docs/ARCHITECTURE.md

🏛️ SaulGPT — System Architecture & Component Specification

Document Version: 2.2.0
Status: Active Production
Hosting Architecture: Hugging Face Spaces (ZeroGPU Backend) + Supabase Managed PostgreSQL + Firebase Hosting (Web SPA)

---

1. High-Level Architecture Overview

SaulGPT is an AI-powered Indian Legal Intelligence platform operating on a Two-Tier Neuro-Symbolic Architecture:

1. The Multi-Agent Workflow Layer (UX & Client Lifecycle): Omni-Box Routing $\rightarrow$ 3-Phase Virtual Counsel (Discovery $\rightarrow$ Strategy $\rightarrow$ Execution) $\rightarrow$ Pre-Trial Studio & Moot Court Arena.
2. The 6-Layer Deterministic Substantive Legal Engine: 6-Layer RAG $\rightarrow$ Actor-Critic Process Reward Model $\rightarrow$ 4-Family Document Drafter $\rightarrow$ Supabase PostgreSQL Cloud Persistence.

┌────────────────────────────────────────────────────────────────────────┐
│                    Frontend (React 18 + Vite 5 SPA)                    │
│  Hosted at: https://legalgpt-india.web.app (Firebase Hosting)          │
│                                                                        │
│  ├── App.jsx                   Core Omni-Box chat & session state      │
│  ├── AuthPage.jsx              JWT Auth & Guest Session Manager        │
│  ├── ConversationsSidebar.jsx  Multi-Device Supabase chat history      │
│  ├── TrialStudio.jsx           Pre-Trial Moot Court & Cross-Examiner   │
│  ├── EvidenceUploader.jsx      Sec 63 BSA Digital Evidence Processor   │
│  ├── TriageCards.jsx           Strategic SWOT Option Cards             │
│  ├── VetoCard.jsx              Scrutiny Gatekeeper & Limitation Alert  │
│  ├── BNSCorrectionNotice.jsx   2024 Transition Warnings (BNS/BNSS/BSA) │
│  ├── JurisdictionBadge.jsx     Court Pecuniary / Territorial Badging   │
│  ├── UrgencyBanner.jsx         Statutory Limitation Countdown          │
│  ├── ApiKeyModal.jsx           BYOK Groq API Key Management            │
│  └── usePDF.js                 Browser-Side Vector PDF Generator       │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │ HTTPS REST (port 443 / 7860)
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│             Backend API Server (Hugging Face Spaces ZeroGPU)           │
│  Hosted at: https://lvvbaaal-legalgpt-api.hf.space                    │
│                                                                        │
│  ┌──────────────────────────────────────────────────────────────────┐  │
│  │ app.py (ZeroGPU Gradio 5.20 + FastAPI Unification)              │  │
│  │  - demo.launch(server_port=7860, prevent_thread_lock=True)       │  │
│  │  - server_app.include_router(fastapi_app.router)                 │  │
│  │  - demo.block_thread() keeps server active                       │  │
│  └─────────────────────────────────┬────────────────────────────────┘  │
│                                    │                                   │
│  ┌─────────────────────────────────▼────────────────────────────────┐  │
│  │ api_server.py (Core Dispatcher & Route Handlers)                 │  │
│  │  - Omni-Box Autonomous Intent Routing (Layer 1)                  │  │
│  │  - 3-Phase Discovery State Machine (triage_state.py)             │  │
│  │  - 4-Family Document Drafting Engine (interview_state.py)       │  │
│  │  - Adversarial IRAC Advocate Mode (irac_agent.py)                │  │
│  │  - Pre-Trial Moot Court & Precedent Engine (trial_studio/)       │  │
│  │  - Sec 63 BSA Electronic Certificate Generator                  │  │
│  │  - Contract Risk Evaluator (layer6_evaluator.py)                 │  │
│  │  - Actor-Critic Fine-Grained PRM (actor_critic.py)               │  │
│  └─────────────────────────────────┬────────────────────────────────┘  │
└────────────────────────────────────┼───────────────────────────────────┘
                                     │
         ┌───────────────────────────┴───────────────────────────┐
         ▼                                                       ▼
┌────────────────────────────────────────┐  ┌────────────────────────────────────────┐
│   SUPABASE POSTGRESQL CLOUD DATABASE   │  │         LOCAL CHROMADB VECTOR STORE    │
│  Host: aws-0-ap-southeast-1.pooler...  │  │  Path: 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. The 3-Phase Virtual Counsel Workflow

[User Input] ──► Phase 1: Discovery (Max 3 Turns)
                      │
                      ├── Turn 1: Story & Relationship
                      ├── Turn 2: Key Evidence & Dates
                      └── Turn 3: Primary Desired Outcome
                      │
                      ▼
                 Phase 2: Strategy (SWOT Matrix)
                      │
                      ├── 4 Action Paths (path_a .. path_d)
                      ├── Success Probability & Time Horizon
                      └── Counsel Override for Exceptional Cases
                      │
                      ▼
                 Phase 3: Execution
                      ├── Document Factory (.docx & .pdf)
                      ├── Procedural Pathfinder Roadmap
                      └── Pre-Trial Moot Court Rehearsal

---

3. The 6-Layer Deterministic RAG Pipeline

Layer	Component	File	Key Capabilities & Device Pinning
0	Conversational Memory	pipeline_orchestrator.py	Sliding window of 6 verbatim turns; older turns compressed.
1	Query Understanding	layer1_understanding.py	SpaCy NER, Devanagari Hindi HyDE translation, blank model fallback.
2	Hybrid Retrieval	layer2_retrieval.py	Dense ChromaDB (2,449+ chunks) + BM25 + CrossEncoder (device="cpu").
3	Big Model Reasoning	layer3_reasoning.py	Groq qwen/qwen3.8-27b & openai/gpt-oss-120b synthesis.
4	Validation & Guardrails	layer4_validation.py, actor_critic.py	NLI DeBERTa (device="cpu"), Actor-Critic FG-PRM (max_tokens=800), 2024 Transition concordance, SC Struck-Down Firewall.
5	External Search & Triplifier	layer5_external.py, auto_triplifier.py	Live DuckDuckGo & IndianKanoon scraping; real-time $(h, r, t)$ ingestion.
6	Evaluator & Relational GNN	layer6_evaluator.py, gnn_engine.py	25K character contract review (ICA 1872), PyTorch GNN TransE/RotatE ($\mathbb{R}^{64}$).

---

4. Court-Grade Document Factory (4 Families)

The document drafting engine (backend/document_generator.py and backend/interview_state.py) implements a 4-Family Architecture:

                  DOCUMENT FACTORY
                         │
      ┌──────────────┬───┴──────────┬──────────────┐
      ▼              ▼              ▼              ▼
   LETTER        PLEADING       AFFIDAVIT      AGREEMENT
(Legal Notice, (Order VII CPC (Sworn Deponent (Commercial
 S.138 NIA,     Plaints, Civil Declarations,   Leases, SLAs,
 Demand RPAD)  Petitions)     Stamp Margin)    NDAs)

Key Technical Guardrails:

1. Dynamic Prompt Sanitization: Strips all [User Goal: document] tags and conversational instruction artifacts before document generation.
2. Deterministic Fallback Spec Engine (build_fallback_spec): Automatically activated if LLM generation fails or times out. Synthesizes an authentic legal document with formal statutory clauses.
3. Notice Elements: RPAD header, Sender FROM: block with Date, Recipient TO: block, formal heading under Section 138 NIA / relevant Act, numbered factual recitals, statutory 15-day demand clause, enclosures, and advocate signature.
4. Order VII Rule 11 CPC Triad of Survival: Mandatory limitation clause, jurisdiction clause, and court valuation clause for plaints.
5. Dual Cloud Storage & Delivery: Cached in-memory in SESSION_DOCUMENTS and on disk in ./generated_docs/{session_id}.docx. Delivered via Axios blob stream and browser jsPDF.

---

5. Persistence Architecture: Supabase Cloud PostgreSQL

To support high-concurrency cloud deployments across mobile and desktop clients without file lock errors, SaulGPT utilizes Supabase Managed PostgreSQL alongside local SQLite:

• Connection Pooler: Routed through aws-0-ap-southeast-1.pooler.supabase.com:5432 (Session Mode) via IPv4, ensuring container accessibility without IPv6 requirements.
• Relational Tables:
  • users: User registration, bcrypt password hashes, timestamps.
  • conversations: Chat sessions with titles, linked to user_id.
  • messages: Multi-turn user and assistant messages with structured metadata JSON.
• Failover & Safety: Automatic fallback to SQLite if PostgreSQL credentials are unset in local test environments.

---

6. Security, Key Isolation, & Rate Limiting

• Bring Your Own Key (BYOK): Users provide personal Groq API keys (gsk_...), stored client-side in localStorage. Injected per-request via X-Groq-Api-Key headers.
• Token Budget Guardrails: Critic PRM calls calibrated to max_tokens=800 to prevent Groq free-tier 1000 OTPM rate limit exceptions (429 rate_limit_exceeded).
• Memory Stability: Pre-initialized PyTorch and spaCy pipelines strictly isolated on CPU outside ZeroGPU calls, ensuring 0% OOM crashes.