CurrenciCombo/README.md

# 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**
   ```bash
   git clone https://github.com/your-org/CurrenciCombo.git
   cd CurrenciCombo
   ```

2. **Install frontend dependencies**
   ```bash
   cd webapp
   npm install
   ```

3. **Install orchestrator dependencies**
   ```bash
   cd ../orchestrator
   npm install
   ```

4. **Install contract dependencies**
   ```bash
   cd ../contracts
   npm install
   ```

### Development

**Frontend (Next.js)**
```bash
cd webapp
npm run dev
# Open http://localhost:3000
```

**Orchestrator Service**
```bash
cd orchestrator
npm run dev
# Runs on http://localhost:8080
```

**Smart Contracts**
```bash
cd contracts
npm run compile
npm run test
```

## 📚 Documentation

- [Engineering Ticket Breakdown](./docs/Engineering_Ticket_Breakdown.md)
- [UI/UX Specification](./docs/UI_UX_Specification_Builder_V2.md)
- [Smart Contract Interfaces](./docs/Smart_Contract_Interfaces.md)
- [Adapter Architecture](./docs/Adapter_Architecture_Spec.md)
- [Compliance Integration](./docs/Compliance_Integration_Spec.md)
- [OpenAPI Specification](./docs/Orchestrator_OpenAPI_Spec.yaml)
- [Final Implementation Summary](./docs/FINAL_IMPLEMENTATION_SUMMARY.md)

## 🧪 Testing

### E2E Tests (Playwright)
```bash
cd webapp
npm run test:e2e
```

### Smart Contract Tests (Hardhat)
```bash
cd contracts
npm run test
```

## 🔧 Configuration

### Environment Variables

**Frontend** (`webapp/.env.local`):
```env
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`):
```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](.github/CONTRIBUTING.md) for guidelines.

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🔗 Links

- [Documentation](./docs/)
- [Issue Tracker](https://github.com/your-org/CurrenciCombo/issues)
- [Discussions](https://github.com/your-org/CurrenciCombo/discussions)

## 👥 Authors

- Your Organization

---

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