Spaces:
Build error
Build error
BankBot AI — System Architecture
1. High-Level Architecture
┌─────────────────────────────────┐
│ CLIENT BROWSER │
│ Next.js 14 (React, TypeScript) │
│ │
│ Pages: │
│ / Dashboard │
│ /chat AI Assistant (WS) │
│ /analytics Spending Intel │
│ /simulator What-If Engine │
│ /transactions History │
│ /status Observability │
└──────────────┬───────────────────┘
│ HTTPS / WSS
┌──────────────▼───────────────────┐
│ NGINX REVERSE PROXY │
│ • TLS termination │
│ • Rate limiting (30r/m API) │
│ • Auth rate limit (10r/m) │
│ • WebSocket upgrade proxy │
│ • Static asset caching │
└──────────┬────────────┬──────────┘
│ │
┌────────────────────▼──┐ ┌──────▼──────────────────┐
│ FastAPI Backend │ │ Next.js Standalone │
│ Python 3.11 │ │ Node.js 20 │
│ Uvicorn (2 workers) │ │ Port 3000 │
│ Port 8000 │ └──────────────────────────┘
│ │
│ Routers: │
│ /api/auth │
│ /api/dashboard │
│ /api/ai/* │
│ /api/ai/chat/ws (WS) │
│ /api/transactions │
│ /api/notifications │
│ /api/metrics │
└──────┬────────┬────────┘
│ │
┌────────────▼──┐ ┌──▼──────────────┐
│ PostgreSQL 15 │ │ Redis 7 │
│ (Primary DB) │ │ (Cache Layer) │
│ │ │ │
│ Tables: │ │ Keys: │
│ users │ │ dashboard:* │
│ accounts │ │ ai:coaching:* │
│ transactions │ │ ai:behavior:* │
│ goals │ │ ai:twin:* │
│ investments │ │ ai:subs:* │
│ subscriptions │ │ │
│ notifications │ │ TTLs: │
│ fraud_logs │ │ dashboard: 2min │
│ ai_insights │ │ score: 10min │
│ analytics_ │ │ briefing: 1hr │
│ snapshots │ └──────────────────┘
└────────────────┘
│
┌────────────▼──────────────────────────┐
│ AI ORCHESTRATION LAYER │
│ │
│ Priority Chain: │
│ 1. OpenAI (gpt-4o-mini) ← fastest │
│ ↓ if unavailable │
│ 2. Groq (llama-3.3-70b) ← free tier │
│ ↓ if unavailable │
│ 3. Ollama (llama3:latest) ← local │
│ ↓ if unavailable │
│ 4. Rule-based fallback ← always on │
│ │
│ Modules: │
│ • chat.py — contextual chat │
│ • coaching.py — health score │
│ • forecasting.py — balance prediction │
│ • simulation.py — what-if engine │
│ • fraud.py — anomaly detection │
│ • behavior.py — spending patterns │
│ • subscriptions.py — sub optimization │
└─────────────────────────────────────────┘
2. Data Flow — Dashboard Load
Browser Next.js FastAPI DB/Cache
│ │ │ │
│── GET / │ │ │
│ │── fetch /api/ │ │
│ │ dashboard/ │ │
│ │ overview │ │
│ │ │── check cache ──► │
│ │ │◄── cache miss ── │
│ │ │── query accounts │
│ │ │── query txns │
│ │── JSON response ◄──│── query fraud │
│◄── render dashboard ──│ │── set cache(2min) │
│ │ │ │
│ [2nd request] │ │ │
│ │── fetch /api/ │ │
│ │ dashboard/ │ │
│ │ overview │ │
│ │ │── check cache ──► │
│ │ │◄── cache HIT ─── │
│◄── render (22ms) ─────│◄── JSON (22ms) ────│ │
3. Data Flow — WebSocket Chat
Browser FastAPI AI Backend
│ │ │
│── WS connect ─────────► │
│◄── WS accepted ────────│ │
│ │ │
│── { type: "chat", │ │
│ message: "..." } ──►│ │
│ │── build context ──►│
│ │ (user profile, │
│ │ history, goals) │
│ │ │── stream tokens
│◄── { type: "chat_start" } │
│◄── { type: "chat_chunk", content: "He" } │
│◄── { type: "chat_chunk", content: "re" } │
│◄── { type: "chat_chunk", content: " is" } │
│ ... (streaming) │
│◄── { type: "chat_end" } │
│ │ │
│── { type: "ping" } ───►│ (heartbeat 25s) │
│◄── { type: "pong" } ───│ │
4. AI Context Construction
Every chat message is enriched with full user financial context:
system_prompt = f"""
You are BankBot, an elite AI Financial Analyst.
CURRENT USER PORTFOLIO:
- Name: {user.name}
- Financial Personality: {user.financial_personality}
- Health Score: {score}/100
- Total Balance: ${total_balance:,.2f}
- Accounts: {account_details}
- Goals: {goals_details}
- Investments: {investments_details}
- Subscriptions: {subs_details}
- Behavioral Insights: {behavior_insights}
PRINCIPLES:
1. Never give generic advice — use real numbers
2. Respond like a Bloomberg Terminal analyst
3. Keep answers brief, actionable, financially meaningful
"""
5. Fraud Detection Algorithm
Transaction received
│
▼
┌───────────────────────────────┐
│ Load last 30 transactions │
│ for this user │
└───────────────┬───────────────┘
│
┌───────▼────────┐
│ Amount spike? │ > 3.5x avg → +40 pts
│ │ > 2.0x avg → +20 pts
└───────┬────────┘
│
┌───────▼────────┐
│ Timing anomaly?│ 11PM–4AM → +25 pts
└───────┬────────┘
│
┌───────▼────────┐
│ Rapid fire? │ < 3 min gap → +20 pts
└───────┬────────┘
│
┌───────▼────────┐
│ Duplicate? │ Same merchant+amount
│ │ within 10 min → +30 pts
└───────┬────────┘
│
┌───────▼────────┐
│ Score ≥ 30? │ → Log to fraud_logs
│ Score ≥ 50? │ → Status: "flagged"
│ Score < 30? │ → Status: "verified"
└────────────────┘
6. Caching Strategy
| Data | Cache Key | TTL | Reason |
|---|---|---|---|
| Dashboard overview | dashboard:overview:{uid} |
2 min | High-frequency, DB-heavy |
| AI health score | ai:coaching:score:{uid} |
10 min | AI call expensive |
| AI daily briefing | ai:coaching:briefing:{uid} |
1 hr | LLM cost control |
| Behavior insights | ai:behavior:insights:{uid} |
10 min | Computation heavy |
| Twin prediction | ai:twin:predict:{uid} |
5 min | Moderate cost |
| Subscriptions | ai:subs:optimize:{uid} |
10 min | Stable data |
Cache backend: Redis → in-memory dict fallback (automatic, no config needed).
7. Security Architecture
Request → Nginx (rate limit) → FastAPI middleware stack:
1. Rate limiter (120 req/min per IP)
2. Security headers (X-Frame-Options, CSP, etc.)
3. Request logger (structured JSON)
4. Process time header
5. CORS validation
6. Route handler
└── JWT validation (if protected route)
└── Business logic
└── DB query / AI call / Cache lookup
JWT Flow:
Login → access_token (60min) + refresh_token (7 days)
│
▼
Request with Authorization: Bearer {access_token}
│
▼
Token expired? → POST /api/auth/refresh with refresh_token
│
▼
New access_token issued (refresh_token unchanged)
│
▼
Logout → client clears tokens (stateless)
8. Deployment Architecture
Internet
│
▼
Cloudflare (DNS + DDoS protection)
│
▼
Nginx (SSL termination, rate limiting)
│
├──► Next.js Frontend (Vercel / Docker port 3000)
│
└──► FastAPI Backend (Render / Docker port 8000)
│
├──► PostgreSQL (Render managed / Docker)
├──► Redis (Render managed / Docker)
└──► AI Provider (OpenAI API / Groq API)