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

## 🚀 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](./docs/DEPLOYMENT_ARCHITECTURE.md) 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**
   ```bash
   git clone https://github.com/your-org/CurrenciCombo.git
   cd CurrenciCombo
   ```

2. **Install dependencies**
   ```bash
   # Frontend
   cd webapp
   npm install
   
   # Backend
   cd ../orchestrator
   npm install
   
   # Smart Contracts
   cd ../contracts
   npm install
   ```

3. **Set up environment variables**
   ```bash
   # 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)**
   ```bash
   # 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)**
```bash
# 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)**
```bash
./scripts/start-all.sh
```

**Or start individually:**

**Frontend (Next.js)**
```bash
cd webapp
npm run dev
# Open http://localhost:3000
# Wait 10-30 seconds for Next.js to compile
```

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

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

### Troubleshooting

**Frontend not loading?**
```bash
./scripts/fix-frontend.sh
```

**Check service status:**
```bash
./scripts/check-status.sh
```

**Run functionality tests:**
```bash
./scripts/test-curl.sh
```

**Note**: This project uses WSL/Ubuntu for development. See [WSL Setup Guide](./docs/WSL_SETUP.md) for setup instructions.

See [Frontend Troubleshooting](./docs/FRONTEND_TROUBLESHOOTING.md) for more help.

## 📚 Documentation

### Getting Started
- [Developer Onboarding](./docs/DEVELOPER_ONBOARDING.md)
- [Development Setup](./docs/DEV_SETUP.md)
- [Frontend Troubleshooting](./docs/FRONTEND_TROUBLESHOOTING.md)
- [Database Options](./docs/DATABASE_OPTIONS.md) - Local vs Azure

### Architecture & Design
- [Deployment Architecture](./docs/DEPLOYMENT_ARCHITECTURE.md) - Web App, PWA, DApp
- [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)
- [Architecture Decision Records](./docs/ADRs/ADR-001-Architecture-Decisions.md)

### Operations
- [Deployment Runbook](./docs/DEPLOYMENT_RUNBOOK.md)
- [Troubleshooting Guide](./docs/TROUBLESHOOTING.md)
- [Production Checklist](./docs/PRODUCTION_CHECKLIST.md)
- [API Deprecation Policy](./docs/API_DEPRECATION_POLICY.md)

### Testing & Status
- [CURL Test Summary](./docs/CURL_TEST_SUMMARY.md)
- [Full Status Check](./docs/FULL_STATUS_CHECK.md)
- [Services Status](./docs/SERVICES_RUNNING.md)

### Specifications
- [OpenAPI Specification](./docs/Orchestrator_OpenAPI_Spec.yaml)
- [ISO Message Samples](./docs/ISO_Message_Samples.md)
- [Error Handling & Rollback](./docs/Error_Handling_Rollback_Spec.md)
- [Simulation Engine](./docs/Simulation_Engine_Spec.md)

### User Guides
- [User Guide](./docs/USER_GUIDE.md)
- [Postman Collection](./docs/POSTMAN_COLLECTION.md)

### Project Status
- [Final Implementation Summary](./docs/FINAL_IMPLEMENTATION_SUMMARY.md)
- [Completion Report](./docs/COMPLETION_REPORT.md)
- [Answers Summary](./docs/ANSWERS_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
# 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`):
```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](./docs/DATABASE_OPTIONS.md) 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)
```bash
cd webapp
npm run test:e2e
```

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

### Functionality Tests
```bash
# Test all endpoints with curl
./scripts/test-curl.sh

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

## 🗄️ Database Setup

### Local Development (Recommended)
```bash
# 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](./docs/DATABASE_OPTIONS.md) 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](./docs/DEPLOYMENT_ARCHITECTURE.md) for details.

## 🤝 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

---

## 📊 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