docs/ARCHITECTURE.md

# Senti AI — Architecture

## Overview

Senti AI is a **Kenya-focused financial intelligence platform** that combines deterministic Rust computation with AI-powered language understanding. It answers financial questions, performs tax calculations, manages budgets, and provides financial advice — all in English and Swahili.

**Core principle**: Financial math is never delegated to the LLM. All calculations go through a deterministic Rust engine. The LLM is used only for language understanding and response formatting.

## Architecture Diagram

```
┌─────────────┐    ┌─────────────┐    ┌─────────────────────────────┐
│  Frontend   │───▶│  FastAPI     │───▶│  Pipeline Router            │
│  (React)    │    │  Backend     │    │  (core/pipeline/router.py)  │
└─────────────┘    └─────────────┘    └──────────┬──────────────────┘
                                                  │
                          ┌───────────────────────┼───────────────────────┐
                          │                       │                       │
                    ┌─────▼─────┐          ┌──────▼──────┐         ┌─────▼─────┐
                    │  Safety    │          │  Intent     │         │  Tier     │
                    │  Check     │          │  Classify   │         │  Route    │
                    │  (empathy) │          │  (determin.)│         │  (A/B/C)  │
                    └───────────┘          └──────┬──────┘         └───────────┘
                                                  │
                    ┌─────────────────────────────┼─────────────────────────┐
                    │                             │                         │
              ┌─────▼─────┐              ┌───────▼───────┐          ┌──────▼──────┐
              │    CAG     │              │     MoE       │          │    KAG      │
              │  (context  │              │   (expert     │          │  (knowledge │
              │   packing) │              │    routing)   │          │    graph)   │
              └───────────┘              └───────┬───────┘          └─────────────┘
                                                 │
                    ┌────────────────────────────┼────────────────────────┐
                    │                            │                        │
              ┌─────▼─────┐              ┌──────▼──────┐          ┌──────▼──────┐
              │   Compute  │              │  Inference  │          │    RAG      │
              │  (Rust     │              │   Engine    │          │  (vector    │
              │   engine)  │              │  (3 levels) │          │   search)   │
              └─────┬─────┘              └──────┬──────┘          └─────────────┘
                    │                            │
                    │                    ┌───────▼───────┐
                    │                    │   LLM Layer   │
                    │                    │  (formatting) │
                    │                    └───────┬───────┘
                    │                            │
                    └────────────┬───────────────┘
                           ┌────▼────┐
                           │Validator│
                           │(output  │
                           │ check)  │
                           └────┬────┘
                                │
                           ┌────▼────┐
                           │  Audit  │
                           │  Log    │
                           └─────────┘
```

## Module Map

### `core/` — Domain Logic

| Module | Path | Purpose |
|---|---|---|
| **Auth** | `core/auth.py` | JWT authentication, password hashing |
| **Intent Classifier** | `core/brain/routing/intent_classifier.py` | Deterministic intent detection (rules + keywords) |
| **MoE Router** | `core/brain/moe/router.py` | Routes to specialist experts (Tax, Investment, Credit, Planning, Safety, Language) |
| **CAG** | `core/brain/memory/cag.py` | Context-Augmented Generation — warm context packing |
| **RAG** | `core/brain/retrieval/rag.py` | Retrieval-Augmented Generation — vector/keyword search |
| **KAG** | `core/brain/knowledge_graph/` | Knowledge graph reasoning (`finance_kg`) |
| **Inference Engine** | `core/brain/inference/engine.py` | 3-level reasoning depth (fast/standard/deep) |
| **Safety** | `core/brain/safety/empathy_interceptor.py` | Crisis/distress detection with helpline referral |
| **Output Validator** | `core/brain/llm/validator.py` | Verifies LLM output matches Rust computation |
| **Memory Agent** | `core/brain/memory/agent.py` | MemGPT-inspired user memory (core + archival) |
| **Compute Engine** | `core/pipeline/compute.py` | Bridge to Rust `senti_calc` formulas |
| **Pipeline Router** | `core/pipeline/router.py` | Main orchestrator — the "brain" |
| **Formula Registry** | `core/engines/formulas/registry.py` | Single source of truth for all finance math |
| **Scheduler** | `core/workflow/scheduler.py` | APScheduler-based recurring jobs |

### `backend/` — API and Infrastructure

| Module | Path | Purpose |
|---|---|---|
| **API** | `backend/api/main.py` | FastAPI app, routes, middleware |
| **Config** | `backend/config/settings.py` | Environment-driven configuration |
| **Postgres** | `backend/database/postgres/` | SQLAlchemy models, session management |
| **Redis** | `backend/database/redis/` | Cache, rate limiting, sessions |
| **Qdrant** | `backend/database/vector/` | Vector store for RAG |
| **Hermes** | `backend/api/hermes/` | Payment intelligence endpoints |
| **Institutional** | `backend/api/institutional/` | Enterprise/tenant API |

### `senti_calc/` — Rust Math Engine

PyO3 Rust extension for deterministic financial calculations. Compiles to a Python `.pyd` module. Includes:
- Kenya PAYE 2024 brackets
- Turnover Tax (TOT)
- VAT, NSSF, SHA, Housing Levy
- Loan EMI (reducing balance)
- NPV, IRR, CAGR, ROI
- Monte Carlo simulation (10,000 scenarios in <1s)
- Business valuation, working capital, breakeven

### `frontend/` — React UI

Vite + React + TypeScript with Tailwind CSS. Features:
- Chat-centric interface
- 3-pane institutional dashboard
- Context-aware right panel

## Request Flow

1. **HTTP Request** → FastAPI endpoint
2. **Auth** → JWT validation via `get_current_user`
3. **Safety Check** → `EmpathyInterceptor` (crisis/distress/illegal detection)
4. **Intent Classification** → Deterministic rules-based classifier
5. **Tier Routing** → A (fast), B (standard), C (RAG-augmented)
6. **CAG** → Pack warm context (user profile, financial state)
7. **MoE** → Select specialist expert(s)
8. **Compute** → Dispatch to Rust engine for calculations
9. **Inference** → Level 1/2/3 reasoning depth
10. **LLM** → Format response (if `USE_LM=true`)
11. **Validator** → Check numbers match, add disclaimers
12. **Audit** → Log request/response to `AuditLog`
13. **Memory** → Update core memory with new facts
14. **Response** → Return to user

## Data Flow

```
                    Financial Truth
                    ──────────────
User Query ──▶ Rust Engine ──▶ Numbers (deterministic)
                                    │
                                    ▼
                              LLM Formatting ──▶ Natural Language Response
                                    │
                              Validator Check ──▶ Numbers in response match Rust?
```

**Rule**: The LLM never invents financial numbers. All numbers must originate from the Rust engine.