CurrenciCombo/docs/DEPLOYMENT_ARCHITECTURE.md

Multi-Platform Deployment Architecture

Overview

The ISO-20022 Combo Flow system can be deployed in three distinct ways to serve different user groups:

1. Web App (Hosted) - For approved parties (enterprise users)
2. PWA (Progressive Web App) - Mobile app version
3. DApp (Decentralized App) - For general public (Web3 users)

---

Architecture Diagram

┌─────────────────────────────────────────────────────────────┐
│                    User Access Layer                         │
├──────────────┬──────────────┬──────────────────────────────┤
│  Web App     │     PWA       │          DApp                │
│ (Approved)   │   (Mobile)    │      (Public/Web3)            │
└──────┬───────┴──────┬─────────┴──────────────┬──────────────┘
       │             │                        │
       └─────────────┼────────────────────────┘
                     │
       ┌─────────────▼─────────────┐
       │   Shared Backend API       │
       │   (Orchestrator Service)   │
       └─────────────┬─────────────┘
                     │
       ┌─────────────▼─────────────┐
       │   Smart Contracts (DLT)   │
       └────────────────────────────┘

---

1. Web App (Hosted Product for Approved Parties)

Characteristics

• Target Users: Enterprise clients, financial institutions, approved partners
• Authentication: Azure AD / Entra ID (OIDC)
• Access Control: Role-based (RBAC), IP whitelisting
• Hosting: Azure App Service or Azure Container Apps
• Features: Full feature set, compliance tools, audit logs

Implementation

Frontend

• Next.js application (current webapp/)
• Azure AD authentication
• Enterprise dashboard
• Advanced compliance features

Backend

• Azure App Service or Container Apps
• Azure Database for PostgreSQL
• Azure Key Vault for secrets
• Application Insights for monitoring

Deployment

Azure App Service:

# Create App Service Plan
az appservice plan create `
  --name comboflow-plan `
  --resource-group comboflow-rg `
  --sku B1 `
  --is-linux

# Create Web App
az webapp create `
  --name comboflow-webapp `
  --resource-group comboflow-rg `
  --plan comboflow-plan `
  --runtime "NODE:18-lts"

# Deploy
az webapp deployment source config-zip `
  --name comboflow-webapp `
  --resource-group comboflow-rg `
  --src webapp.zip

Docker Container:

# Use existing Dockerfile
FROM node:18-alpine
WORKDIR /app
COPY . .
RUN npm install && npm run build
EXPOSE 3000
CMD ["npm", "start"]

Configuration

• Custom domain with SSL
• Azure AD app registration
• IP whitelisting
• Rate limiting
• Compliance reporting

---

2. PWA (Progressive Web App - Mobile)

Characteristics

• Target Users: Mobile users (iOS/Android)
• Authentication: Same as Web App (Azure AD) + Biometric
• Offline Support: Service workers, local caching
• Installation: Add to home screen
• Features: Mobile-optimized UI, push notifications

Implementation

PWA Configuration

webapp/public/manifest.json:

{
  "name": "Combo Flow",
  "short_name": "ComboFlow",
  "description": "ISO-20022 Combo Flow Mobile",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#000000",
  "icons": [
    {
      "src": "/icon-192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "/icon-512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ]
}

Service Worker (webapp/public/sw.js):

// Offline caching strategy
self.addEventListener('fetch', (event) => {
  event.respondWith(
    caches.match(event.request)
      .then(response => response || fetch(event.request))
  );
});

Next.js PWA Setup

next.config.ts:

import withPWA from 'next-pwa';

export default withPWA({
  dest: 'public',
  register: true,
  skipWaiting: true,
  disable: process.env.NODE_ENV === 'development',
})({
  // Next.js config
});

Mobile-Specific Features

• Touch-optimized drag-and-drop
• Biometric authentication (Face ID, Touch ID)
• Push notifications for execution status
• Offline plan viewing
• Camera for QR code scanning

Deployment

• Same backend as Web App
• CDN for static assets
• Service worker caching
• App Store / Play Store (optional wrapper)

---

3. DApp (Decentralized App - General Public)

Characteristics

• Target Users: General public, Web3 users
• Authentication: Wallet-based (MetaMask, WalletConnect)
• Hosting: IPFS, decentralized hosting, or traditional hosting
• Access: Open to all (no approval required)
• Features: Public plan templates, community features

Implementation

Frontend

• Same Next.js base, different authentication
• Wallet connection (Wagmi/Viem)
• Web3 provider integration
• Public plan marketplace

Smart Contract Integration

• Direct interaction with ComboHandler contract
• Plan execution via wallet
• Public adapter registry
• Community governance (optional)

DApp-Specific Features

webapp/src/app/dapp/page.tsx:

"use client";

import { useAccount, useConnect } from 'wagmi';

export default function DAppPage() {
  const { address, isConnected } = useAccount();
  const { connect, connectors } = useConnect();

  return (
    <div>
      {!isConnected ? (
        <button onClick={() => connect({ connector: connectors[0] })}>
          Connect Wallet
        </button>
      ) : (
        <Dashboard address={address} />
      )}
    </div>
  );
}

Hosting Options

Option A: Traditional Hosting (Easier)

• Deploy to Azure/Vercel/Netlify
• Use wallet authentication
• Public access, no approval needed

Option B: IPFS (Fully Decentralized)

# Build static site
npm run build
npm run export

# Deploy to IPFS
npx ipfs-deploy out -p pinata

Option C: ENS Domain

• Register .eth domain
• Point to IPFS hash
• Fully decentralized access

Configuration

• Public API endpoints (rate-limited)
• No Azure AD required
• Wallet-based authentication only
• Public plan templates
• Community features

---

Shared Backend Architecture

API Gateway Pattern

┌─────────────┐
│  API Gateway │ (Azure API Management or Kong)
└──────┬───────┘
       │
       ├─── Web App Routes (Azure AD auth)
       ├─── PWA Routes (Azure AD + Biometric)
       └─── DApp Routes (Wallet auth, public)

Authentication Strategy

Multi-Auth Support:

// orchestrator/src/middleware/auth.ts
export function authenticate(req: Request) {
  // Check Azure AD token
  if (req.headers['authorization']?.startsWith('Bearer ')) {
    return validateAzureADToken(req);
  }
  
  // Check wallet signature
  if (req.headers['x-wallet-address']) {
    return validateWalletSignature(req);
  }
  
  // Public endpoints (DApp)
  if (isPublicEndpoint(req.path)) {
    return { type: 'public' };
  }
  
  throw new Error('Unauthorized');
}

---

Deployment Strategy

Phase 1: Web App (Approved Parties)

1. Deploy to Azure App Service
2. Configure Azure AD
3. Set up IP whitelisting
4. Enable compliance features

Phase 2: PWA (Mobile)

1. Add PWA configuration
2. Implement service workers
3. Mobile UI optimizations
4. Deploy to same backend

Phase 3: DApp (Public)

1. Create public API endpoints
2. Implement wallet authentication
3. Deploy to IPFS or public hosting
4. Enable public features

---

Feature Matrix

Feature	Web App	PWA	DApp
Authentication	Azure AD	Azure AD + Bio	Wallet
Access Control	RBAC	RBAC	Public
Offline Support	No	Yes	Limited
Compliance	Full	Full	Basic
Audit Logs	Yes	Yes	On-chain
Plan Templates	Private	Private	Public
Approval Required	Yes	Yes	No
Hosting	Azure	Azure + CDN	IPFS/Public

---

Code Structure

webapp/
├── src/
│   ├── app/
│   │   ├── (webapp)/          # Web App routes (approved)
│   │   │   ├── dashboard/
│   │   │   └── admin/
│   │   ├── (pwa)/             # PWA routes (mobile)
│   │   │   └── mobile/
│   │   └── (dapp)/            # DApp routes (public)
│   │       ├── dapp/
│   │       └── marketplace/
│   ├── components/
│   │   ├── webapp/            # Web App components
│   │   ├── pwa/               # PWA components
│   │   └── dapp/              # DApp components
│   └── lib/
│       ├── auth-webapp.ts     # Azure AD auth
│       ├── auth-dapp.ts        # Wallet auth
│       └── api.ts              # Shared API client

---

Next Steps

1. Create PWA Configuration

   • Add manifest.json
   • Implement service worker
   • Mobile UI components

2. Create DApp Routes

   • Public dashboard
   • Wallet connection
   • Public plan marketplace

3. Update Backend

   • Multi-auth middleware
   • Public API endpoints
   • Rate limiting for public access

4. Deployment Scripts

   • Web App deployment
   • PWA build and deploy
   • DApp IPFS deployment

---

Last Updated: 2025-01-15