Start here. Every document in this repository is listed below with its audience and a short description of what it covers.
New to the project? Read the Product Overview first, then the Glossary, then the entry point for the area you're working in (backend or frontend).
| Document | Audience | What it covers |
|---|---|---|
| Product Overview | Everyone | What the tool does, who uses it (PMRA reviewers), how it was tested, SME evaluation results |
| Glossary | Everyone | Plain-language definitions for all Azure services, tools, and project-specific terms |
| Document | Audience | What it covers |
|---|---|---|
| Backend TDD — Entry Point | Engineers | Master index for the full backend technical design; start here for anything backend |
| 01 — Architecture | Engineers | Service boundaries, package responsibilities, five major data flows, dependency direction |
| 02 — API Surface | Engineers | All 14 routers documented with every endpoint, request/response shapes, auth, and exceptions |
| 03 — Data Models | Engineers | All 13 ORM models with field-level types, constraints, indexes, and migration notes |
| 04 — Schemas | Engineers | All Pydantic request/response schemas with design notes |
| 05 — Document Processing | Engineers | Upload, SHA-256 deduplication, parser selection, Azure DI and Docling pipelines, blob storage, bounding boxes |
| 06 — LLM Layer | Engineers | All 7 provider clients, dispatch table, timeout budgets, structured output handling, cost tracking |
| 07 — Extraction Flow | Engineers | Entity extraction end-to-end: concurrency model, provider dispatch, reference/bbox matching, session persistence |
| 08 — Evaluation Flow | Engineers | G-Eval scoring, combined JSON parsing, background job lifecycle, cancellation, cost tracking |
| 09 — Sessions, Sharing & Groups | Engineers | Session lifecycle, restore-view construction, group membership rules, shared session read path |
| 10 — Template System | Engineers | Template CRUD, version snapshots, fork, scope change, access-control algorithms, folder operations |
| 11 — Auth, Security & Observability | Engineers | Better Auth session validation, auth proxy, CORS, secrets loading, structlog, Prometheus, OpenTelemetry, CostTracker |
| Document | What it covers |
|---|---|
| API Endpoint Index | Compact table of every route — method, path, purpose |
| Class Index | All backend classes organised by package |
| Class Reference | Field-level reference for ORM models, Pydantic schemas, and service classes |
| Data Flow Diagrams | 15 text-format diagrams covering every major request flow |
| Risks, Assumptions & Testing | Runtime/data/provider assumptions, risk table with mitigations, 13-category test strategy, 12-step smoke test |
| Document | Audience | What it covers |
|---|---|---|
| Frontend TDD — Entry Point | Engineers | Tech stack, page map, workflow diagram, architecture overview |
| 01 — App Shell | Engineers | App.tsx — DocumentData interface, step routing, onComplete() pattern, session persistence, navigation guards |
| 02 — Auth | Engineers | LoginPage, AuthCallback, authUtils.ts — OAuth flow, token lifecycle, authenticatedFetch(), visibility refresh |
| 03 — Upload | Engineers | Workflow step 1 — file upload, SHA-256 deduplication, auto-processing, parser selection |
| 04 — Processing | Engineers | Workflow step 2 — parsed content inspection, re-processing, PDF bounding box viewer |
| 05 — Study Config | Engineers | Workflow step 3 — study type, entity editor, template loading, model selection |
| 06 — Extraction | Engineers | Workflow step 4 — concurrent entity extraction, PDF reference highlighting, multi-model comparison, in-place editing |
| 07 — Evaluation | Engineers | Workflow step 5 — G-Eval metrics, background jobs, human score overrides, Excel export |
| 08 — Simplified Flow | Engineers | One-click pipeline, useSimplifiedPipeline hook, batched extraction, stage progression |
| 09 — Chat | Engineers | Freeform document Q&A, multi-document context, message ratings |
| 10 — Session History | Engineers | Browse, restore, share, and delete sessions; shared sessions (read-only) |
| 11 — Templates | Engineers | Template CRUD, version history, fork, scope change, folder organisation |
| 12 — Groups | Engineers | Group lifecycle, member roles, add/remove members, user search |
| 13 — Executive Mode | Engineers | Standalone summary generation without structured entity review |
| 14 — Batch Results | Engineers | Cross-file results table, fuzzy search, column visibility, Excel export |
| Document | What it covers |
|---|---|
| Component Index | All shared components with props and usage |
| Hooks & Contexts | All custom hooks and ThemeContext with exported APIs |
| Types & Interfaces | Key TypeScript interfaces: DocumentData, Entity, Template, Group, and more |
| Document | Audience | What it covers |
|---|---|---|
| GitHub Auth Setup | DevOps | 10-step guide to configuring GitHub Enterprise Cloud OAuth |
| Migration Guide | Engineers | Supabase → Azure Postgres + Better Auth migration history |
| Deployment Plan | DevOps | Azure Container Apps architecture, CI/CD pipeline, provisioning record |
| Logging Stack | DevOps | LGTM stack setup: Grafana, Loki, Tempo, Prometheus; NSG firewall rules |