hf/README_HF.md

---
title: BankBot AI
emoji: 🏦
colorFrom: blue
colorTo: green
sdk: docker
pinned: true
license: mit
short_description: AI-Native Financial Operating System — real-time streaming, fraud detection, forecasting
---

<div align="center">

# 🏦 BankBot AI

### AI-Native Financial Operating System

[![FastAPI](https://img.shields.io/badge/FastAPI-009688?style=flat-square&logo=fastapi&logoColor=white)](https://fastapi.tiangolo.com)
[![Next.js](https://img.shields.io/badge/Next.js_14-black?style=flat-square&logo=next.js&logoColor=white)](https://nextjs.org)
[![Python](https://img.shields.io/badge/Python_3.11-3776AB?style=flat-square&logo=python&logoColor=white)](https://python.org)
[![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?style=flat-square&logo=typescript&logoColor=white)](https://typescriptlang.org)
[![Docker](https://img.shields.io/badge/Docker-2496ED?style=flat-square&logo=docker&logoColor=white)](https://docker.com)
[![OpenAI](https://img.shields.io/badge/OpenAI-412991?style=flat-square&logo=openai&logoColor=white)](https://openai.com)

**A production-grade AI fintech platform** with real-time WebSocket streaming, multi-provider AI fallback, fraud detection, financial forecasting, and a premium glassmorphism UI.

</div>

---

## 🚀 Demo

**Login with the demo account:**
```
Email:    alex@bankbot.dev
Password: BankBot2026!
```

The demo account includes:
- **$59,637** across 3 accounts (checking · savings · investment)
- **301 transactions** across 6 months
- **1 fraud alert** (Tech Store NYC, $847, 78% risk score)
- **4 financial goals** (Emergency Fund · Vacation · MacBook · Down Payment)
- **4 investments** (S&P 500 · AAPL · BTC · Treasury Bonds)
- **6 notifications** (3 unread)

---

## ✨ Features

### 🤖 AI Financial Twin
- **Contextual chat** — AI knows your real balance, goals, investments, and spending patterns
- **4-tier AI fallback**: OpenAI → Groq → Ollama → Rule-based (always responds)
- **Real-time streaming** via WebSocket — character-by-character with auto-reconnect

### 📊 Financial Intelligence
- **Health Score** — 100-point composite across 6 dimensions
- **What-If Simulator** — 6 sliders, instant 36-month projection
- **Spending Heatmap** — weekly behavioral patterns
- **Category Intelligence** — AI insights per spending category

### 🛡️ Fraud Detection
- **Real-time scoring** — amount spikes, timing anomalies, rapid-fire, duplicates
- **Risk levels** — verified / suspicious / flagged
- **Live alerts** — notification panel with unread count

### ⚡ Performance
- Dashboard: **65ms cold, 10ms cached**
- Cache-aside: Redis → in-memory fallback (automatic)
- All data endpoints: **< 20ms** warm

### 🔍 Observability
- Live metrics at `/api/metrics`
- System Status page at `/status`
- Structured JSON logging with request tracing

---

## 🏗️ Architecture

```
Browser (port 7860)
    │
    ▼
Nginx (port 7860) — single entry point
    │                    │
    ▼                    ▼
Next.js (3000)      FastAPI (8000)
    │                    │
    └────────────────────┤
                         │
              ┌──────────┴──────────┐
              │                     │
         SQLite/PostgreSQL      Redis/Memory
         (auto-fallback)        (auto-fallback)
                         │
              ┌──────────┴──────────┐
              │          │          │
           OpenAI      Groq      Ollama
           (P1)        (P2)      (P3)
                              Rule-based (P4)
```

---

## ⚙️ Configuration (HF Secrets)

Set these in your Space's **Settings → Repository secrets**:

| Secret | Required | Description |
|--------|----------|-------------|
| `OPENAI_API_KEY` | Optional* | OpenAI GPT-4o-mini |
| `GROQ_API_KEY` | Optional* | Groq llama-3.3-70b (free) |
| `JWT_SECRET_KEY` | Recommended | JWT signing secret |
| `DATABASE_URL` | Optional | External PostgreSQL (Neon/Supabase) |
| `REDIS_URL` | Optional | External Redis |

*At least one AI key recommended. Without any key, the app uses rule-based responses from your actual financial data.

**Get a free Groq key:** https://console.groq.com/keys

---

## 🗄️ Database Options

### Option 1: SQLite (Default — works out of the box)
No configuration needed. Data resets on Space restart (fine for demo).

### Option 2: Neon PostgreSQL (Persistent)
1. Create free DB at https://neon.tech
2. Set `DATABASE_URL` secret: `postgresql://user:pass@ep-xxx.neon.tech/bankbot?sslmode=require`

### Option 3: Supabase PostgreSQL (Persistent)
1. Create project at https://supabase.com
2. Set `DATABASE_URL` from Settings → Database → Connection string

---

## 📡 API Endpoints

```
GET  /health                    Health check
GET  /api/status                Runtime info
GET  /api/metrics               Live observability
GET  /docs                      Interactive API docs

POST /api/auth/login            Login → JWT
POST /api/auth/register         Register
GET  /api/dashboard/overview    Full dashboard (65ms)
GET  /api/transactions/         Transaction history
GET  /api/notifications/        Notifications
GET  /api/ai/coaching/score     Health score
GET  /api/ai/fraud/analysis     Fraud alerts
POST /api/ai/chat               HTTP chat
WS   /api/ai/chat/ws            Streaming chat
```

---

## 🛠️ Tech Stack

| Layer | Technology |
|-------|-----------|
| Frontend | Next.js 14, TypeScript, Tailwind CSS |
| Animation | Framer Motion |
| Charts | Recharts |
| State | Zustand |
| Backend | FastAPI, Python 3.11 |
| Database | PostgreSQL / SQLite fallback |
| Cache | Redis / in-memory fallback |
| Auth | JWT (python-jose), bcrypt |
| AI | OpenAI / Groq / Ollama / Rule-based |
| Container | Docker (single container) |
| Proxy | Nginx (port 7860) |

---

## 📁 Source Code

Full source: [GitHub Repository](https://github.com/your-username/bankbot-ai)

Documentation:
- [Architecture](./docs/ARCHITECTURE.md)
- [API Reference](./docs/API_DOCUMENTATION.md)
- [Deployment Guide](./docs/DEPLOYMENT_GUIDE.md)
- [ER Diagram](./docs/ER_DIAGRAM.md)