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

🏗️ 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

Installation

1. Clone the repository

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

2. Install frontend dependencies

   cd webapp
   npm install
   

3. Install orchestrator dependencies

   cd ../orchestrator
   npm install
   

4. Install contract dependencies

   cd ../contracts
   npm install
   

Development

Frontend (Next.js)

cd webapp
npm run dev
# Open http://localhost:3000

Orchestrator Service

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

Smart Contracts

cd contracts
npm run compile
npm run test

📚 Documentation

• Engineering Ticket Breakdown
• UI/UX Specification
• Smart Contract Interfaces
• Adapter Architecture
• Compliance Integration
• OpenAPI Specification
• Final Implementation 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):

NEXT_PUBLIC_ORCH_URL=http://localhost:8080
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=your-secret-key
AZURE_AD_CLIENT_ID=your-azure-ad-client-id
AZURE_AD_CLIENT_SECRET=your-azure-ad-client-secret

Orchestrator (orchestrator/.env):

PORT=8080
DATABASE_URL=postgresql://user:pass@localhost:5432/comboflow
NODE_ENV=development

📦 Project Structure

.
├── webapp/                    # Next.js frontend
│   ├── src/
│   │   ├── app/              # App router pages
│   │   ├── 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
│   │   └── db/              # Database layer
│
├── contracts/                 # Smart contracts
│   ├── ComboHandler.sol      # Main handler
│   ├── NotaryRegistry.sol    # Notary registry
│   ├── AdapterRegistry.sol   # Adapter registry
│   └── adapters/            # Protocol adapters
│
└── docs/                      # Documentation

🤝 Contributing

See CONTRIBUTING.md for guidelines.

📄 License

MIT License - see LICENSE file for details.

🔗 Links

• Documentation
• Issue Tracker
• Discussions

👥 Authors

• Your Organization

---

Status: ✅ All 28 engineering tickets completed | Ready for integration testing