ARCH.md

🏛️ SaulGPT Architecture & Systems Specification (Quick Reference)

Document Version: 2.2.0
Target Release: Production Cloud (Hugging Face Spaces + Supabase + Firebase)
System Classification: Neuro-Symbolic Indian Legal Intelligence Platform

For exhaustive documentation, refer to:

• 👉 Comprehensive Architecture Document — In-depth architectural specification and pipeline flows.
• 👉 Technical Design Document (TDD) — Infrastructure, schemas, CPU pinning, and PRM token budgeting.
• 👉 Functional Design Document (FDD) — User journeys, 4 document families, and constitutional guardrails.
• 👉 Architectural Decision Records (ADRs) — All 30 ADRs (ADR-001 through ADR-030).
• 👉 Complete Feature Breakdown — Deep dive into all 10 core system modules.
• 👉 REST API Reference — All HTTP endpoints, schemas, and request/response models.
• 👉 Deployment Guide — Production deployment steps for HF Spaces, Supabase, and Firebase.
• 👉 Setup & Developer Guide — Local development, testing, and environment setup.

---

1. High-Level Cloud Topology

┌────────────────────────────────────────────────────────────────────────┐
│                        CLIENT LAYER (Web Browser)                     │
│  Hosted at: https://legalgpt-india.web.app (Firebase Hosting)          │
│  Stack: React 18, Vite 5, Axios Interceptors, jsPDF A4 Engine          │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │ HTTPS REST + CORS (Port 443)
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│             BACKEND API LAYER (Hugging Face Spaces - ZeroGPU)          │
│  Hosted at: https://lvvbaaal-legalgpt-api.hf.space                    │
│  Hardware: zero-a10g (16 GB VRAM, Dynamic GPU Allocation)              │
│  Server: FastAPI mounted inside Gradio 5.20 ASGI Server (Port 7860)   │
│                                                                        │
│  ┌──────────────────────────────────────────────────────────────────┐  │
│  │ app.py (ZeroGPU Entrypoint)                                      │  │
│  │ ├─ demo.launch(server_port=7860, prevent_thread_lock=True)       │  │
│  │ ├─ server_app.include_router(fastapi_app.router)                 │  │
│  │ └─ demo.block_thread() keeps container alive                     │  │
│  └─────────────────────────────────┬────────────────────────────────┘  │
│                                    │                                   │
│  ┌─────────────────────────────────▼────────────────────────────────┐  │
│  │ api_server.py (Core Controller & Pipeline Dispatcher)            │  │
│  │ ├─ Omni-Box Autonomous Routing & Devanagari Hindi HyDE (Layer 1) │  │
│  │ ├─ 3-Phase Discovery State Machine (triage_state.py)             │  │
│  │ ├─ 4-Family Document Factory & Fallback Engine (interview_state) │  │
│  │ ├─ IRAC Advocate Mode & Courtroom Simulator (irac_agent.py)      │  │
│  │ ├─ Pre-Trial Studio & Precedent Engine (trial_studio/)           │  │
│  │ ├─ Sec 63 BSA Digital Evidence Processor (evidence_processor.py) │  │
│  │ ├─ Contract Risk Evaluator (layer6_evaluator.py, 25K chars)      │  │
│  │ └─ Actor-Critic FG-PRM Token Budgeting (actor_critic.py)         │  │
│  └─────────────────────────────────┬────────────────────────────────┘  │
└────────────────────────────────────┼───────────────────────────────────┘
                                     │
         ┌───────────────────────────┴───────────────────────────┐
         ▼                                                       ▼
┌────────────────────────────────────────┐  ┌────────────────────────────────────────┐
│    SUPABASE MANAGED POSTGRESQL CLOUD   │  │         LOCAL CHROMADB VECTOR STORE    │
│  Host: aws-0-ap-southeast-1.pooler...  │  │  Storage: data/vector_db/              │
│  Port: 5432 (Session) / 6543 (Tx)      │  │  Model: all-MiniLM-L6-v2 (CPU-pinned)  │
│  Tables: users, conversations, messages│  │  Collections: saulgpt_indian_laws,     │
│  Engine: IPv4 Connection Pooler        │  │               landmark_precedents      │
└────────────────────────────────────────┘  └────────────────────────────────────────┘

---

2. Core Subsystems & Components

Subsystem	Primary Implementation	Architectural Highlights
Omni-Box & Routing	backend/layer1_understanding.py, backend/api_server.py	Eliminates manual mode dropdowns; classifies intent across Q&A, Grievance, Drafter, Reviewer, and Studio. Devanagari Hindi cross-lingual HyDE.
Virtual Counsel	backend/triage_state.py, backend/discovery_agent.py, backend/strategy_agent.py	3-Phase grievance workflow (Discovery $\rightarrow$ Strategy $\rightarrow$ Execution) capped at 3 turns with SWOT analysis and 4 action paths.
6-Layer RAG Engine	backend/pipeline_orchestrator.py, backend/layer[1-6]*.py	Dense vector retrieval (2,449+ chunks) + BM25 Okapi + Cross-Encoder reranking + PyTorch TransE/RotatE GNN ($\mathbb{R}^{64}$) + SC Struck-Down Firewall.
Actor-Critic FG-PRM	backend/actor_critic.py, backend/layer4_validation.py	Fine-Grained Process Reward Model evaluating factuality, legal soundness, and tone. Token budget strictly capped at max_tokens=800 to avoid Groq OTPM rate limits.
4-Family Document Drafter	backend/interview_state.py, backend/document_generator.py	Generates .docx and .pdf across 4 families (letter, pleading, affidavit, agreement). 100% prompt sanitization, canonical Indian legal formatting, and deterministic fallback spec engine.
Pre-Trial Studio	backend/trial_studio/, saulgpt-ui/src/TrialStudio.jsx	2-column judicial chamber: Hostile Sec 146 BSA cross-examination vs. confidential Corner Coach tactical counsel. Indexed over 50,000 SC/HC precedents.
Sec 63 BSA Evidence	backend/evidence_processor.py, saulgpt-ui/src/EvidenceUploader.jsx	Cryptographic SHA-256 digital certificate generation, cheque OCR extraction, and debtor voice admission limitation extension under S.18 Limitation Act.
Contract Risk Evaluator	backend/layer6_evaluator.py	Single-pass evaluation of full agreements up to 25,000 characters against Indian Contract Act 1872 (Sections 27, 28, 74).
Persistence Engine	backend/database.py, Supabase PostgreSQL	Supabase PostgreSQL IPv4 pooler (:5432) for zero-connection-drop cloud deployment across mobile/desktop, with local SQLite WAL fallback.
Security & BYOK	backend/api_server.py, saulgpt-ui/src/ApiKeyModal.jsx	User Groq API keys (gsk_...) stored client-side in localStorage, injected per-request via X-Groq-Api-Key headers; zero server-side key logging.

---

3. Environment & Configuration Reference

# Core LLM API
GROQ_API_KEY=gsk_...
GROQ_MODEL=llama-3.1-8b-instant

# Cloud Database (Supabase IPv4 Pooler)
DATABASE_URL=postgresql://postgres.lxnrfznxvnjlpginivob:PASSWORD@aws-0-ap-southeast-1.pooler.supabase.com:5432/postgres

# JWT Security
JWT_SECRET=super-secret-jwt-key-change-in-production

# Public API URL for Document Downloads
PUBLIC_API_URL=https://lvvbaaal-legalgpt-api.hf.space