Superuserz — Financial Digital Twin

Real-time financial behavioral digital twin system with 10 progressive tiers. Continuously observes financial signals, builds a stateful user twin, predicts risk, simulates futures, generates interventions, and powers adaptive credit decisions.

---

One-Command Startup

# 1. Copy env file and fill in API keys
cp devops/.env.example devops/.env
# Edit devops/.env — at minimum set JWT_SECRET

# 2. Start the full stack (Postgres + Redis + Backend + Dashboard)
make up
# Or manually:
docker compose -f devops/docker-compose.yml up --build -d

# 3. Seed demo data (runs automatically with `make up`, or run manually)
make seed

All services will be healthy within ~60s from a cold start.

---

Services

Service	URL
Dashboard	http://localhost:3000
API	http://localhost:8000/api/v1
API Docs	http://localhost:8000/api/docs
Expo Dev	http://localhost:19006 (manual: npx expo start)

Default demo user

• User ID: user_001
• Phone: +91-9999000001
• Seeded with 90 days of realistic transaction history

---

Make Commands

Command	Action
make up	Build and start all containers, then seed demo data
make down	Stop all containers
make build	Rebuild images without cache
make seed	Re-run the demo data seed (idempotent)
make logs	Tail logs from all services
make ps	Show container status
make shell-be	Shell into the backend container
make shell-db	psql into the Postgres container
make clean	Stop containers and remove all volumes

---

Local Development (without Docker)

# Backend
cd backend
pip install -r requirements.txt
alembic upgrade head
uvicorn main:app --reload --port 8000

# Dashboard
cd frontend-dashboard
npm install
npm run dev   # Vite dev server at http://localhost:5173

# Mobile app
cd frontend-app
npm install
npx expo start

---

Environment Variables

Copy devops/.env.example to devops/.env:

JWT_SECRET=<generate with: openssl rand -hex 32>
KIMI_API_KEY=<your Featherless/Kimi API key — optional for LLM features>
QWEN_API_KEY=<fallback LLM key — optional>

LLM features (narrative, interview, contradictions) gracefully fall back to mock data when no API key is configured. All other features work without API keys.

---

Architecture

See .claude/CLAUDE.md for full architecture, 10-tier system design, agent assignments, NeoPOP design system rules, and coding conventions.