# ahmedmalik07/labsaathi architecture

> Architecture diagram of the GitHub repository ahmedmalik07/labsaathi, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ahmedmalik07/labsaathi
- Repository: https://github.com/ahmedmalik07/labsaathi

## Overview

Samjho turns a CityLab lab report into cited, rule-based result classifications and a plain-language explanation, with English and Roman Urdu support. The main path is report submission, deterministic parsing (with model extraction only when parsing finds no tests), rules-based classification, explanation checks or template fallback, and a signed report-bound session. Follow-up chat uses that session and a privacy check. The README documents these behaviors; source excerpts show the analyze and chat wiring. UI wiring and several secondary routes were not sampled, so their connections are not inferred.

Main entry points: [`src/lib/pipeline.ts`](https://github.com/ahmedmalik07/labsaathi/blob/main/src/lib/pipeline.ts) (Analysis pipeline), [`src/lib/explain.ts`](https://github.com/ahmedmalik07/labsaathi/blob/main/src/lib/explain.ts) (Explanation writer), [`src/lib/chat.ts`](https://github.com/ahmedmalik07/labsaathi/blob/main/src/lib/chat.ts) (Follow-up chat), [`src/lib/kb.ts`](https://github.com/ahmedmalik07/labsaathi/blob/main/src/lib/kb.ts) (Knowledge access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Report experience"]
  node_app["Samjho interface<br/>[SamjhoApp.tsx]"]
end

subgraph group_api["API entry points"]
  node_analyze_route["Analyze endpoint<br/>[route.ts]"]
  node_chat_route["Chat endpoint<br/>[route.ts]"]
  node_explain_route["Explain endpoint<br/>[route.ts]"]
  node_transcribe_route["Transcription endpoint<br/>[route.ts]"]
  node_reference_route["Reference endpoint<br/>[route.ts]"]
  node_evals_route["Evaluation endpoint<br/>[route.ts]"]
end

subgraph group_analysis["Report analysis"]
  node_pipeline["Analysis pipeline<br/>[pipeline.ts]"]
  node_cleaner["Report cleaner<br/>[cleaner.ts]"]
  node_parser["Report parser<br/>[parser.ts]"]
  node_extractor["Fallback extraction<br/>[extract.ts]"]
  node_analyze["Analysis coordinator<br/>[analyze.ts]"]
  node_engine["Rules engine<br/>[engine.ts]"]
  node_reference_data[("Reference tables<br/>[reference.ts]")]
  node_knowledge["Knowledge access<br/>[kb.ts]"]
  node_evals["Evaluation logic<br/>[evals.ts]"]
end

subgraph group_explanation["Explanation and privacy"]
  node_facts["Engine facts<br/>[facts.ts]"]
  node_explainer["Explanation writer<br/>[explain.ts]"]
  node_guard["Text guard<br/>[guard.ts]"]
  node_template["Fallback template<br/>[template.ts]"]
  node_groq["Groq model client<br/>[groq.ts]"]
  node_session["Signed sessions<br/>[session.ts]"]
  node_chat["Follow-up chat<br/>[chat.ts]"]
  node_privacy["Privacy checks<br/>[privacy.ts]"]
end

node_patient(("Report submitter"))

node_patient -->|"submits report"| node_analyze_route
node_analyze_route -->|"runs pipeline"| node_pipeline
node_pipeline -->|"parses report"| node_parser
node_pipeline -->|"extracts if needed"| node_extractor
node_parser -->|"cleans text"| node_cleaner
node_pipeline -->|"analyzes parsed data"| node_analyze
node_analyze -->|"classifies results"| node_engine
node_engine -->|"uses references"| node_knowledge
node_knowledge -->|"exposes tables"| node_reference_data
node_pipeline -->|"builds facts"| node_facts
node_pipeline -->|"requests explanation"| node_explainer
node_explainer -->|"requests model text"| node_groq
node_explainer -->|"checks text"| node_guard
node_explainer -->|"falls back"| node_template
node_pipeline -->|"creates session"| node_session
node_chat_route -->|"verifies token"| node_session
node_chat_route -->|"requests answer"| node_chat
node_chat -->|"checks message"| node_privacy
node_chat -->|"requests answer"| node_groq
node_explain_route -->|"loads facts"| node_session
node_explain_route -->|"re-explains"| node_explainer
node_reference_route -->|"reads tables"| node_knowledge
node_evals_route -->|"serves evaluations"| node_evals

click node_app "https://github.com/ahmedmalik07/labsaathi/blob/main/src/components/SamjhoApp.tsx"
click node_analyze_route "https://github.com/ahmedmalik07/labsaathi/blob/main/src/app/api/analyze/route.ts"
click node_chat_route "https://github.com/ahmedmalik07/labsaathi/blob/main/src/app/api/chat/route.ts"
click node_explain_route "https://github.com/ahmedmalik07/labsaathi/blob/main/src/app/api/explain/route.ts"
click node_transcribe_route "https://github.com/ahmedmalik07/labsaathi/blob/main/src/app/api/transcribe/route.ts"
click node_reference_route "https://github.com/ahmedmalik07/labsaathi/blob/main/src/app/api/reference/route.ts"
click node_evals_route "https://github.com/ahmedmalik07/labsaathi/blob/main/src/app/api/evals/route.ts"
click node_pipeline "https://github.com/ahmedmalik07/labsaathi/blob/main/src/lib/pipeline.ts"
click node_cleaner "https://github.com/ahmedmalik07/labsaathi/blob/main/src/lib/cleaner.ts"
click node_parser "https://github.com/ahmedmalik07/labsaathi/blob/main/src/lib/parser.ts"
click node_extractor "https://github.com/ahmedmalik07/labsaathi/blob/main/src/lib/extract.ts"
click node_analyze "https://github.com/ahmedmalik07/labsaathi/blob/main/src/lib/analyze.ts"
click node_engine "https://github.com/ahmedmalik07/labsaathi/blob/main/src/lib/engine.ts"
click node_reference_data "https://github.com/ahmedmalik07/labsaathi/blob/main/src/lib/reference.ts"
click node_knowledge "https://github.com/ahmedmalik07/labsaathi/blob/main/src/lib/kb.ts"
click node_facts "https://github.com/ahmedmalik07/labsaathi/blob/main/src/lib/facts.ts"
click node_explainer "https://github.com/ahmedmalik07/labsaathi/blob/main/src/lib/explain.ts"
click node_guard "https://github.com/ahmedmalik07/labsaathi/blob/main/src/lib/guard.ts"
click node_template "https://github.com/ahmedmalik07/labsaathi/blob/main/src/lib/template.ts"
click node_groq "https://github.com/ahmedmalik07/labsaathi/blob/main/src/lib/llm/groq.ts"
click node_session "https://github.com/ahmedmalik07/labsaathi/blob/main/src/lib/session.ts"
click node_chat "https://github.com/ahmedmalik07/labsaathi/blob/main/src/lib/chat.ts"
click node_privacy "https://github.com/ahmedmalik07/labsaathi/blob/main/src/lib/privacy.ts"
click node_evals "https://github.com/ahmedmalik07/labsaathi/blob/main/src/lib/evals.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app toneBlue
class node_analyze_route,node_chat_route,node_explain_route,node_transcribe_route,node_reference_route,node_evals_route toneAmber
class node_pipeline,node_cleaner,node_parser,node_extractor,node_analyze,node_engine,node_reference_data,node_knowledge,node_evals toneMint
class node_facts,node_explainer,node_guard,node_template,node_groq,node_session,node_chat,node_privacy toneRose
class node_patient toneIndigo
```

## Components

### Report experience

- [Samjho interface](https://github.com/ahmedmalik07/labsaathi/blob/main/src/components/SamjhoApp.tsx): `src/components/SamjhoApp.tsx`

### API entry points

- [Analyze endpoint](https://github.com/ahmedmalik07/labsaathi/blob/main/src/app/api/analyze/route.ts): `src/app/api/analyze/route.ts`
- [Chat endpoint](https://github.com/ahmedmalik07/labsaathi/blob/main/src/app/api/chat/route.ts): `src/app/api/chat/route.ts`
- [Explain endpoint](https://github.com/ahmedmalik07/labsaathi/blob/main/src/app/api/explain/route.ts): `src/app/api/explain/route.ts`
- [Transcription endpoint](https://github.com/ahmedmalik07/labsaathi/blob/main/src/app/api/transcribe/route.ts): `src/app/api/transcribe/route.ts`
- [Reference endpoint](https://github.com/ahmedmalik07/labsaathi/blob/main/src/app/api/reference/route.ts): `src/app/api/reference/route.ts`
- [Evaluation endpoint](https://github.com/ahmedmalik07/labsaathi/blob/main/src/app/api/evals/route.ts): `src/app/api/evals/route.ts`

### Report analysis

- [Analysis pipeline](https://github.com/ahmedmalik07/labsaathi/blob/main/src/lib/pipeline.ts): `src/lib/pipeline.ts`
- [Report cleaner](https://github.com/ahmedmalik07/labsaathi/blob/main/src/lib/cleaner.ts): `src/lib/cleaner.ts`
- [Report parser](https://github.com/ahmedmalik07/labsaathi/blob/main/src/lib/parser.ts): `src/lib/parser.ts`
- [Fallback extraction](https://github.com/ahmedmalik07/labsaathi/blob/main/src/lib/extract.ts): `src/lib/extract.ts`
- [Analysis coordinator](https://github.com/ahmedmalik07/labsaathi/blob/main/src/lib/analyze.ts): `src/lib/analyze.ts`
- [Rules engine](https://github.com/ahmedmalik07/labsaathi/blob/main/src/lib/engine.ts): `src/lib/engine.ts`
- [Reference tables](https://github.com/ahmedmalik07/labsaathi/blob/main/src/lib/reference.ts): `src/lib/reference.ts`
- [Knowledge access](https://github.com/ahmedmalik07/labsaathi/blob/main/src/lib/kb.ts): `src/lib/kb.ts`
- [Evaluation logic](https://github.com/ahmedmalik07/labsaathi/blob/main/src/lib/evals.ts): `src/lib/evals.ts`

### Explanation and privacy

- [Engine facts](https://github.com/ahmedmalik07/labsaathi/blob/main/src/lib/facts.ts): `src/lib/facts.ts`
- [Explanation writer](https://github.com/ahmedmalik07/labsaathi/blob/main/src/lib/explain.ts): `src/lib/explain.ts`
- [Text guard](https://github.com/ahmedmalik07/labsaathi/blob/main/src/lib/guard.ts): `src/lib/guard.ts`
- [Fallback template](https://github.com/ahmedmalik07/labsaathi/blob/main/src/lib/template.ts): `src/lib/template.ts`
- [Groq model client](https://github.com/ahmedmalik07/labsaathi/blob/main/src/lib/llm/groq.ts): `src/lib/llm/groq.ts`
- [Signed sessions](https://github.com/ahmedmalik07/labsaathi/blob/main/src/lib/session.ts): `src/lib/session.ts`
- [Follow-up chat](https://github.com/ahmedmalik07/labsaathi/blob/main/src/lib/chat.ts): `src/lib/chat.ts`
- [Privacy checks](https://github.com/ahmedmalik07/labsaathi/blob/main/src/lib/privacy.ts): `src/lib/privacy.ts`

### Other components

- **Report submitter**

## Connections

- Report submitter → Analyze endpoint: submits report
- Analyze endpoint → Analysis pipeline: runs pipeline (evidence: `src/app/api/analyze/route.ts`)
- Analysis pipeline → Report parser: parses report (evidence: `src/lib/pipeline.ts`)
- Analysis pipeline → Fallback extraction: extracts if needed (evidence: `src/lib/pipeline.ts`)
- Report parser → Report cleaner: cleans text (evidence: `src/lib/parser.ts`)
- Analysis pipeline → Analysis coordinator: analyzes parsed data (evidence: `src/lib/pipeline.ts`)
- Analysis coordinator → Rules engine: classifies results (evidence: `src/lib/analyze.ts`)
- Rules engine → Knowledge access: uses references (evidence: `src/lib/kb.ts`)
- Knowledge access → Reference tables: exposes tables (evidence: `src/lib/kb.ts`)
- Analysis pipeline → Engine facts: builds facts (evidence: `src/lib/pipeline.ts`)
- Analysis pipeline → Explanation writer: requests explanation (evidence: `src/lib/pipeline.ts`)
- Explanation writer → Groq model client: requests model text (evidence: `src/lib/explain.ts`)
- Explanation writer → Text guard: checks text (evidence: `src/lib/explain.ts`)
- Explanation writer → Fallback template: falls back (evidence: `src/lib/explain.ts`)
- Analysis pipeline → Signed sessions: creates session (evidence: `src/lib/pipeline.ts`)
- Chat endpoint → Signed sessions: verifies token (evidence: `src/app/api/chat/route.ts`)
- Chat endpoint → Follow-up chat: requests answer (evidence: `src/app/api/chat/route.ts`)
- Follow-up chat → Privacy checks: checks message (evidence: `src/lib/chat.ts`)
- Follow-up chat → Groq model client: requests answer (evidence: `src/lib/chat.ts`)
- Explain endpoint → Signed sessions: loads facts (evidence: `src/app/api/explain/route.ts`)
- Explain endpoint → Explanation writer: re-explains (evidence: `src/app/api/explain/route.ts`)
- Reference endpoint → Knowledge access: reads tables (evidence: `src/app/api/reference/route.ts`)
- Evaluation endpoint → Evaluation logic: serves evaluations (evidence: `src/app/api/evals/route.ts`)