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:**
```powershell
# 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:**
```dockerfile
# 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:**
```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):**
```javascript
// 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:**
```typescript
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:**
```typescript
"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)**
```bash
# 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:**
```typescript
// 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