tinhnguyen0110/shb-digital

1. Purpose and entry points

Digital Expert Guild is a Vietnamese digital-bank workflow system: customers request lending/service assistance through chat; four AI domain specialists assess cases, retrieve bank data/policy, and execute controlled operations. Bank staff supervise approvals, audit, and metrics.

Runtime entry points:

• FastAPI application: backend/app/main.py

• React SPA bootstrap: frontend/src/main.tsx

• Docker deployment: docker-compose.prod.yml

• Benchmark runners: bench/run_single.py, bench/run_multi.py

2. API, identity, and client boundary

The frontend communicates with FastAPI over REST and SSE, with cookie-based JWT authentication. Customer and bank/admin personas are authorization boundaries; APIs expose conversations, approvals, audit, stats, model selection, comparison, and live streams.

Key paths:

• backend/app/api/conversations.py

• backend/app/auth/router.py

• backend/app/api/sse.py

• frontend/src/api/client.ts

• frontend/src/Workspace.tsx

3. Persistent banking state and provenance

PostgreSQL 15 is the system of record for banking entities, conversations/tasks/cards, approvals, audit records, retrieval data, and LLM cost metrics. SQLAlchemy/Alembic own schema evolution; seed modules populate an executable demo/lab dataset. The design deliberately keeps transactional business state and audit/projection state in one database.

Key paths:

• backend/app/db/models.py

• backend/app/db/migrations/versions/

• backend/app/db/seed_from_lab.py

• deploy/seed/shb-132.db

4. Agent orchestration lifecycle

A chat request creates or resumes a durable MAIN agent session. MAIN plans work and dispatches independent role-specific SUB agents asynchronously; the orchestration shell tracks events, role/task state, retries/resumption, and wakes MAIN when work or approval decisions complete. It is not a fixed workflow graph: MAIN determines whether to wait, delegate, or synthesize.

Key paths:

• backend/app/orch/main_session.py

• backend/app/orch/dispatch.py

• backend/app/orch/sub_runner.py

• backend/app/orch/room.py

5. Extensible specialist and retrieval boundary

Specialists are mounted from role directories rather than embedded in the orchestrator. Each supplies a skill prompt and Python business tools; the mount layer supplies schemas, database access, and scoped execution. Shared retrieval combines policy wiki/document lineage, vector notes, and related-entity checks, while numerical assessments use direct database tools.

Key paths:

• backend/app/mount/mount_role.py

• roles/credit/SKILL.md

• roles/credit/functions.py

• roles/_retrieval/functions.py

• deploy/seed/wiki/

6. Controlled action and approval gate

Sensitive actions, notably disbursement, cross a server-side tool gate rather than relying on prompts. The gate normalizes payloads, creates or checks approval tickets, atomically claims approved actions, performs the underlying operation, and records a receipt in one transaction. Ownership checks and assessment verdicts can further deny or escalate actions. Admin decisions re-enter the orchestration lifecycle.

Key paths:

• backend/app/orch/gated.py

• backend/app/orch/disburse_guard.py

• backend/app/orch/verdict.py

• backend/app/api/approvals.py

7. Observability and presentation flow

Agents emit messages, task changes, thinking/tool-call traces, cards, and approvals through an SSE bus; a single redaction boundary protects secrets before client delivery. The SPA renders chat, source-backed cards, a 3D specialist lobby, and the admin Control Tower. Audit is append-only; notifications can be in-app and optional Gmail email.

Key paths:

• backend/app/sse/bus.py

• backend/app/sse/redact.py

• backend/app/orch/audit_emit.py

• frontend/src/components/ControlTower.tsx

• frontend/src/components/cards/CardRenderer.tsx

8. Runtime infrastructure and model providers

Backend is Python 3.11/FastAPI/uvicorn; frontend is React 19/Vite/TypeScript, served/proxied by nginx in production. Docker Compose runs PostgreSQL, backend, and frontend; cloudflared is part of deployed access. The agent runtime uses Claude Agent SDK with per-session provider configuration for Claude, GLM, GPT gateway, or local Ollama; provider keys remain server-side.

Key paths:

• backend/pyproject.toml

• configs/providers.yaml

• backend/Dockerfile

• frontend/Dockerfile

• frontend/nginx.conf