Add full monorepo: virtual-banker, backend, frontend, docs, scripts, deployment

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-10 11:32:49 -08:00
commit b4753cef7e
81 changed files with 9255 additions and 0 deletions
--- a/docs/DEPLOYMENT.md
+++ b/docs/DEPLOYMENT.md
@@ -0,0 +1,213 @@
+# Deployment Guide
+
+## Prerequisites
+
+- Docker and Docker Compose
+- PostgreSQL 16+ with pgvector extension
+- Redis 7+
+- (Optional) Kubernetes cluster for production
+
+## Development Deployment
+
+### 1. Database Setup
+
+Run migrations:
+
+```bash
+cd virtual-banker/database
+psql -U explorer -d explorer -f migrations/001_sessions.up.sql
+psql -U explorer -d explorer -f migrations/002_conversations.up.sql
+psql -U explorer -d explorer -f migrations/003_tenants.up.sql
+psql -U explorer -d explorer -f migrations/004_vector_extension.up.sql
+```
+
+### 2. Start Services
+
+Using the main docker-compose.yml:
+
+```bash
+cd deployment
+docker-compose up -d virtual-banker-api virtual-banker-widget
+```
+
+Or using the virtual-banker specific compose file:
+
+```bash
+cd virtual-banker/deployment
+docker-compose up -d
+```
+
+### 3. Verify
+
+Check health:
+
+```bash
+curl http://localhost:8081/health
+```
+
+Access widget:
+
+```
+http://localhost:8082
+```
+
+## Production Deployment
+
+### Environment Variables
+
+**Backend API:**
+```bash
+DATABASE_URL=postgres://user:pass@host:5432/db
+REDIS_URL=redis://host:6379
+PORT=8081
+```
+
+**Widget CDN:**
+- Deploy to CDN (Cloudflare, AWS CloudFront, etc.)
+- Configure CORS headers
+- Enable gzip compression
+
+### Docker Compose Production
+
+```yaml
+services:
+  virtual-banker-api:
+    image: your-registry/virtual-banker-api:latest
+    environment:
+      - DATABASE_URL=${DATABASE_URL}
+      - REDIS_URL=${REDIS_URL}
+    deploy:
+      replicas: 3
+      resources:
+        limits:
+          cpus: '2'
+          memory: 2G
+```
+
+### Kubernetes Deployment
+
+Example deployment:
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: virtual-banker-api
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      app: virtual-banker-api
+  template:
+    metadata:
+      labels:
+        app: virtual-banker-api
+    spec:
+      containers:
+      - name: api
+        image: your-registry/virtual-banker-api:latest
+        env:
+        - name: DATABASE_URL
+          valueFrom:
+            secretKeyRef:
+              name: virtual-banker-secrets
+              key: database-url
+        ports:
+        - containerPort: 8081
+        resources:
+          requests:
+            memory: "1Gi"
+            cpu: "1"
+          limits:
+            memory: "2Gi"
+            cpu: "2"
+```
+
+## Scaling
+
+### Horizontal Scaling
+
+- **API Service**: Stateless, scale horizontally
+- **Widget CDN**: Use CDN for global distribution
+- **Avatar Renderer**: GPU-bound, scale based on concurrent sessions
+
+### Vertical Scaling
+
+- **Database**: Increase connection pool, add read replicas
+- **Redis**: Use Redis Cluster for high availability
+- **Avatar Renderer**: Allocate more GPU resources
+
+## Monitoring
+
+### Health Checks
+
+- API: `GET /health`
+- Widget: `GET /health` (nginx)
+
+### Metrics
+
+- Session creation rate
+- Active sessions
+- API latency
+- Error rates
+- Avatar render queue
+
+### Logging
+
+- Structured logging (JSON)
+- Log aggregation (ELK, Loki, etc.)
+- Audit logs for compliance
+
+## Security
+
+### Network
+
+- Use internal networks for service communication
+- Expose only necessary ports
+- Use TLS for external communication
+
+### Secrets
+
+- Store secrets in secret management (Vault, AWS Secrets Manager)
+- Rotate tokens regularly
+- Use ephemeral tokens for sessions
+
+### Compliance
+
+- Enable audit logging
+- Implement data retention policies
+- PII redaction in logs
+- Encryption at rest and in transit
+
+## Backup & Recovery
+
+### Database
+
+- Regular PostgreSQL backups
+- Point-in-time recovery
+- Test restore procedures
+
+### Redis
+
+- Enable persistence (AOF/RDB)
+- Regular snapshots
+
+## Troubleshooting
+
+### Common Issues
+
+**Session creation fails:**
+- Check database connection
+- Verify tenant exists
+- Check JWT validation
+
+**Widget not loading:**
+- Check CORS configuration
+- Verify CDN is accessible
+- Check browser console for errors
+
+**Avatar not displaying:**
+- Verify WebRTC connection
+- Check avatar renderer service
+- Verify GPU resources available
+