docs: Update CHANGELOG and README for deployment models and troubleshooting
- Added multi-platform deployment architecture details (Web App, PWA, DApp) to README.md. - Included comprehensive troubleshooting guides and fix scripts in README.md. - Enhanced CHANGELOG.md with new features, fixes, and improvements, including TypeScript error resolutions and updated documentation structure. - Revised development setup instructions in DEV_SETUP.md to reflect changes in script usage and environment variable setup.
This commit is contained in:
defiQUG
394
docs/DEPLOYMENT_ARCHITECTURE.md
Normal file
394
docs/DEPLOYMENT_ARCHITECTURE.md
Normal file
@@ -0,0 +1,394 @@
|
||||
# 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
|
||||
|
||||
Reference in New Issue
Block a user