ISO-20022 Combo Flow

A visual workflow builder for composing multi-step financial transactions that combine ISO-20022 banking messages with DLT (Distributed Ledger Technology) operations. Think of it as combining Venmo, your bank, and a crypto exchange into one easy-to-use interface.

🎯 Overview

This system enables users to build complex financial workflows by:

• Dragging and dropping financial steps (borrow, swap, repay, pay)
• Combining DeFi protocols with traditional banking rails
• Executing multi-step transactions atomically using 2PC (Two-Phase Commit)
• Ensuring compliance with LEI/DID/KYC/AML requirements
• Providing real-time execution monitoring and audit trails

🚀 Deployment Models

The system supports three deployment models:

• Web App (Hosted): For approved parties (enterprise clients, financial institutions)

  • Azure AD authentication, RBAC, IP whitelisting
  • Full compliance features and audit logs

• PWA (Mobile): Progressive Web App for mobile users

  • Offline support, push notifications, installable
  • Same backend with mobile-optimized UI

• DApp (Public): Decentralized app for general public

  • Wallet-based authentication (MetaMask, WalletConnect)
  • Open access, public plan templates

See Deployment Architecture for details.

🏗️ Architecture

CurrenciCombo/
├── webapp/           # Next.js 14 frontend application
├── orchestrator/     # Backend orchestrator service (TypeScript/Express)
├── contracts/        # Smart contracts (Solidity)
└── docs/            # Documentation and specifications

✨ Features

Frontend

• 🎨 Drag-and-drop workflow builder
• 🔄 Real-time execution monitoring via SSE
• ✅ Compliance status dashboard (LEI/DID/KYC/AML)
• 🧪 Optional simulation panel for advanced users
• 🔐 Multi-wallet Web3 integration
• 📊 Step dependency visualization

Backend

• 🔄 2PC (Two-Phase Commit) execution coordination
• 📝 ISO-20022 message generation (pacs.008, camt.052/053, camt.056)
• 🏦 Multi-bank connector support (SWIFT, SEPA, FedNow)
• 🔒 Compliance engine integration
• 📋 Notary service for immutable audit trails
• 🎫 Receipt generation and aggregation

Smart Contracts

• ⚡ Atomic execution handler
• 📜 Adapter registry with whitelist/blacklist
• 🔐 Notary registry for codehash tracking
• 🔌 Example adapters (Uniswap, Aave, ISO-20022 Pay)

🚀 Quick Start

Prerequisites

• Node.js 18+
• npm or yarn
• Git
• Docker (optional, for local PostgreSQL)

Installation

1. Clone the repository

   git clone https://github.com/your-org/CurrenciCombo.git
   cd CurrenciCombo
   

2. Install dependencies

   # Frontend
   cd webapp
   npm install
   
   # Backend
   cd ../orchestrator
   npm install
   
   # Smart Contracts
   cd ../contracts
   npm install
   

3. Set up environment variables

   # Frontend - Create webapp/.env.local
   NEXT_PUBLIC_ORCH_URL=http://localhost:8080
   NEXTAUTH_SECRET=dev-secret-change-in-production-min-32-chars
   
   # Backend - Create orchestrator/.env
   PORT=8080
   NODE_ENV=development
   SESSION_SECRET=dev-session-secret-minimum-32-characters-long
   

4. Set up database (optional for development)

   # Using Docker (recommended)
   docker run --name combo-postgres `
     -e POSTGRES_PASSWORD=postgres `
     -e POSTGRES_DB=comboflow `
     -p 5432:5432 `
     -d postgres:15
   
   # Update orchestrator/.env
   DATABASE_URL=postgresql://postgres:postgres@localhost:5432/comboflow
   RUN_MIGRATIONS=true
   
   # Run migrations
   cd orchestrator
   npm run migrate
   

Development

Quick Start (First Time Setup)

# Complete setup (installs dependencies, creates env files, sets up database)
./scripts/setup-complete.sh

# Verify everything (runs all verification tests)
./scripts/verify-all.sh

# Start all services
./scripts/start-all.sh

Start all services (WSL/Ubuntu)

./scripts/start-all.sh

Or start individually:

Frontend (Next.js)

cd webapp
npm run dev
# Open http://localhost:3000
# Wait 10-30 seconds for Next.js to compile

Orchestrator Service

cd orchestrator
npm run dev
# Runs on http://localhost:8080
# Health check: http://localhost:8080/health

Smart Contracts

cd contracts
npm run compile
npm run test

Troubleshooting

Frontend not loading?

./scripts/fix-frontend.sh

Check service status:

./scripts/check-status.sh

Run functionality tests:

./scripts/test-curl.sh

Note: This project uses WSL/Ubuntu for development. See WSL Setup Guide for setup instructions.

See Frontend Troubleshooting for more help.

📚 Documentation

Getting Started

• Developer Onboarding
• Development Setup
• Frontend Troubleshooting
• Database Options - Local vs Azure

Architecture & Design

• Deployment Architecture - Web App, PWA, DApp
• Engineering Ticket Breakdown
• UI/UX Specification
• Smart Contract Interfaces
• Adapter Architecture
• Compliance Integration
• Architecture Decision Records

Operations

• Deployment Runbook
• Troubleshooting Guide
• Production Checklist
• API Deprecation Policy

Testing & Status

• CURL Test Summary
• Full Status Check
• Services Status

Specifications

• OpenAPI Specification
• ISO Message Samples
• Error Handling & Rollback
• Simulation Engine

User Guides

• User Guide
• Postman Collection

Project Status

• Final Implementation Summary
• Completion Report
• Answers Summary

🧪 Testing

E2E Tests (Playwright)

cd webapp
npm run test:e2e

Smart Contract Tests (Hardhat)

cd contracts
npm run test

🔧 Configuration

Environment Variables

Frontend (webapp/.env.local):

# Required
NEXT_PUBLIC_ORCH_URL=http://localhost:8080
NEXTAUTH_SECRET=dev-secret-change-in-production-min-32-chars

# Optional (for Azure AD authentication)
NEXTAUTH_URL=http://localhost:3000
AZURE_AD_CLIENT_ID=your-azure-ad-client-id
AZURE_AD_CLIENT_SECRET=your-azure-ad-client-secret
AZURE_AD_TENANT_ID=common

Orchestrator (orchestrator/.env):

# Required
PORT=8080
NODE_ENV=development
SESSION_SECRET=dev-session-secret-minimum-32-characters-long
JWT_SECRET=dev-jwt-secret-minimum-32-characters-long

# Optional (for database)
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/comboflow
RUN_MIGRATIONS=false

# Optional (for Redis caching)
REDIS_URL=redis://localhost:6379

# Optional (for API authentication)
API_KEYS=dev-key-123
ALLOWED_IPS=127.0.0.1,::1

See Database Options for database setup.

📦 Project Structure

.
├── webapp/                    # Next.js frontend
│   ├── src/
│   │   ├── app/              # App router pages
│   │   │   ├── (webapp)/    # Web App routes (approved parties)
│   │   │   ├── (pwa)/       # PWA routes (mobile)
│   │   │   └── (dapp)/      # DApp routes (public)
│   │   ├── components/       # React components
│   │   ├── lib/              # Utilities
│   │   └── store/            # Zustand state
│   └── tests/e2e/            # Playwright tests
│
├── orchestrator/              # Backend service
│   ├── src/
│   │   ├── api/             # Express routes
│   │   ├── services/         # Business logic
│   │   ├── integrations/    # External integrations
│   │   ├── middleware/       # Security, auth, validation
│   │   ├── db/              # Database layer
│   │   └── config/          # Configuration
│   └── .env                 # Environment variables
│
├── contracts/                 # Smart contracts
│   ├── ComboHandler.sol      # Main handler
│   ├── NotaryRegistry.sol    # Notary registry
│   ├── AdapterRegistry.sol   # Adapter registry
│   └── adapters/            # Protocol adapters
│
├── scripts/                   # Utility scripts (WSL/Ubuntu)
│   ├── start-all.sh         # Start all services
│   ├── check-status.sh      # Check service status
│   ├── test-curl.sh         # Functionality tests
│   └── fix-frontend.sh      # Frontend troubleshooting
│
└── docs/                      # Documentation
    ├── DEPLOYMENT_ARCHITECTURE.md
    ├── DATABASE_OPTIONS.md
    ├── FRONTEND_TROUBLESHOOTING.md
    └── ... (see Documentation section)

🧪 Testing

E2E Tests (Playwright)

cd webapp
npm run test:e2e

Smart Contract Tests (Hardhat)

cd contracts
npm run test

Functionality Tests

# Test all endpoints with curl
./scripts/test-curl.sh

# Check service status
./scripts/check-status.sh

🗄️ Database Setup

Local Development (Recommended)

# Using Docker
docker run --name combo-postgres \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=comboflow \
  -p 5432:5432 \
  -d postgres:15

Azure Production

See Database Options for Azure setup.

🚢 Deployment

Web App (Azure App Service)

• Deploy to Azure App Service
• Configure Azure AD authentication
• Set up IP whitelisting

PWA (Mobile)

• Add PWA configuration
• Deploy to same backend
• Enable offline support

DApp (Public)

• Deploy to IPFS or public hosting
• Enable wallet authentication
• Public API endpoints

See Deployment Architecture for details.

🤝 Contributing

See CONTRIBUTING.md for guidelines.

📄 License

MIT License - see LICENSE file for details.

🔗 Links

• Documentation
• Issue Tracker
• Discussions

👥 Authors

• Your Organization

---

📊 Current Status

✅ Production Ready: All core features implemented

• ✅ Frontend: Next.js app with drag-and-drop builder
• ✅ Backend: Orchestrator service with 2PC execution
• ✅ Smart Contracts: Handler, registry, and adapters
• ✅ Testing: E2E tests, contract tests, functionality tests
• ✅ Documentation: Comprehensive guides and specifications

🚀 Deployment Options:

• ✅ Web App (Approved parties)
• ✅ PWA (Mobile version)
• ✅ DApp (Public version)

📈 Next Steps:

1. Set up local database for development
2. Configure Azure AD for authentication
3. Deploy to Azure for production
4. Enable PWA and DApp features

---

Last Updated: 2025-01-15