ARCHITECTURE.md

# تبيان الطبي — Architecture

## System Overview

Tebyan Medical is a production-grade Arabic medical report analysis platform. Users upload lab reports (PDF or image), the system extracts findings, generates a clinical interpretation in Arabic, and provides an interactive voice-enabled chat assistant.

```
Frontend (Next.js 15)          Backend (FastAPI)              External Services
─────────────────────          ─────────────────              ─────────────────
Upload → /api/analyze ────────► AgentCoordinator              Groq (LLM/STT)
Chat   → /api/chat   ────────► RAG + LLM streaming            Supabase (pgvector)
Voice  → /api/voice  ────────► WhisperSTT / TTS               Cohere (rerank)
Risk   → /api/risk   ────────► RiskEngine                     Google Vision/TTS
```

---

## Backend Layer

### Entry Point

`backend/main.py` — FastAPI application. Registers all routes, mounts middleware, and wires dependency-injected singletons via `@lru_cache`.

### Multi-Agent Pipeline (`services/agents/`)

Replaces the flat `services/agent/pipeline.py` (kept for backward compat) with a structured agent graph:

```
AgentCoordinator
├── OCRAgent           — PDF (fitz + EasyOCR) + Image (Google Vision fallback)
├── ExtractionAgent    — regex parse → LLM fallback → physiological bounds filter
├── ClassificationAgent — panel detection (CBC, Thyroid, Liver, Kidney, Lipid, Diabetes)
├── MedicalReasoningAgent — RAG retrieval + panel-specific LLM prompt
└── SafetyAgent        — PDPL/NDMO compliance filter + emergency detection
```

Each agent extends `AgentBase` which provides retry-with-backoff and structured logging via `AgentContext`.

### RAG Stack (`services/rag/`, `services/search/`)

- **Embedding**: `intfloat/multilingual-e5-large` (1024-dim, via HuggingFace)
- **Vector store**: Supabase pgvector (`match_documents` RPC, 2834+ medical chunks)
- **Query expansion**: Groq LLM generates 3 alternate queries; `query_parser.py` adds Arabic synonym expansions
- **Retrieval**: BM25 fallback + Cohere `rerank-v3.5` cross-encoder
- **Cache**: 5-minute TTL in-memory LRU (`services/cache.py`) prevents redundant embedding calls

### Risk Engine (`services/risk/`)

Evidence-based clinical threshold scoring for 6 conditions. `FeatureExtractor` normalises findings into a 35-feature vector; each scorer (`_score_diabetes`, `_score_cardiovascular`, etc.) applies WHO/ADA/ACC clinical cutoffs. ML `.pkl` model files in `services/risk/models/` override rule-based scores when present.

### Voice (`services/voice/`)

- **STT**: `WhisperSTT` wraps Groq `whisper-large-v3`. Accepts WebM/MP4/OGG/WAV (25 MB max).
- **TTS**: Provider chain — Google Cloud TTS (Wavenet-A) → gTTS (free fallback) → ElevenLabs.

### LLM Router (`services/llm/router.py`)

`LLMRouter` wraps a primary provider (`GroqProvider`) and optional fallback (`HuggingFaceProvider`). Model selection: `llama-3.3-70b-versatile` for analysis, `llama-3.1-8b-instant` for chat.

### Security (`middleware/`)

- **`AuditMiddleware`**: Writes one JSON record per request to rotating log files (`logs/audit/audit.jsonl`). Marks PDPL-sensitive paths. Skips health/docs endpoints.
- **`validate_upload`**: Magic-byte sniffing (anti-MIME-spoofing), 20 MB size limit, extension blocklist.
- **`sanitize_text`**: Strips HTML tags, null bytes, XSS patterns, and SQL injection signatures from all user text inputs.

### Rate Limiting (`services/ratelimit.py`)

In-memory sliding window (no external dependency). Limits: analyze=5/min, chat=30/min, search=60/min. Uses `X-Forwarded-For` for IP detection behind proxies.

---

## Frontend Layer

**Next.js 15 App Router**, RTL Arabic, Tailwind CSS v4, Framer Motion.

| Component | Purpose |
|---|---|
| `upload-section.tsx` | File picker + `/api/analyze` call + loading state |
| `analysis-history.tsx` | Saved analyses list + semantic search + health trend chart |
| `health-trend-chart.tsx` | Recharts line chart — tracks lab values over time with alerts |
| `risk-dashboard.tsx` | Calls `/api/risk` + renders 6 radial gauge cards (collapsible) |
| `chat-bot.tsx` | Floating chat panel — streaming SSE + voice input/output |
| `voice-recorder.tsx` | MediaRecorder → `/api/voice/transcribe` + TTS playback |
| `compare-analyses.tsx` | Side-by-side analysis diff |

---

## Data Flow — Analysis Request

```
1. User uploads PDF/image
2. validate_upload() — size + MIME + magic bytes
3. AgentCoordinator.run()
   a. OCRAgent       → raw_text
   b. ExtractionAgent → findings[] (with impossible-value filter)
   c. ClassificationAgent → panel_code
   d. MedicalReasoningAgent → RAG context + LLM report
   e. SafetyAgent    → filtered report
4. Response: { findings, summary, report }
5. Frontend saves to Supabase via /api/analyses/save
6. RiskDashboard calls /api/risk with findings
```

---

## Key Design Decisions

- **No streaming for analysis**: Analysis takes 8–15 s; streaming a partial JSON would be malformed. Response is returned in full after all agents complete.
- **RAG cache before agent**: MedicalReasoningAgent checks `rag_cache` before calling pgvector — avoids redundant 300 ms embedding round-trips on identical queries.
- **Agents over monolith**: Each agent is independently retryable and observable via `AgentContext.logs`. Failures degrade gracefully — OCR failure sets `raw_text=""`, downstream agents handle empty input without crashing.
- **Rule-based risk scoring**: ML `.pkl` models are optional overrides. The platform is useful immediately without training data.
- **In-memory rate limiter**: Avoids Redis dependency for MVP. Replace with Redis-backed limiter for multi-process deployments.