# rudrao2/stratum architecture

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

- Interactive diagram: https://gitdiagram.com/rudrao2/stratum
- Repository: https://github.com/rudrao2/stratum

## Overview

Stratum is a local-first document intelligence workbench for CMPDI and Coal India. Users add documents to the Library; ingestion parses and stores evidence, then extracts and validates traceable facts. From the workbench they can ask evidence-grounded questions, build parliamentary replies or reports, explore topics, review flagged facts, and inspect quality metrics. The plugin mediates workbench interactions and local model routing; the Python backend provides domain services over SQLite. Edges cite excerpts or README statements; some product branches are documented but their implementation was not sampled.

Main entry points: [`backend/stratum/ask/service.py`](https://github.com/rudrao2/stratum/blob/main/backend/stratum/ask/service.py) (Ask service), [`backend/stratum/ingest/pipeline.py`](https://github.com/rudrao2/stratum/blob/main/backend/stratum/ingest/pipeline.py) (Document pipeline), [`backend/stratum/metrics/service.py`](https://github.com/rudrao2/stratum/blob/main/backend/stratum/metrics/service.py) (Quality metrics), [`backend/stratum/facts/service.py`](https://github.com/rudrao2/stratum/blob/main/backend/stratum/facts/service.py) (Fact review)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workbench["Workbench plugin"]
  node_plugin["Harness integration<br/>[index.js]"]
  node_tools["Stratum tools<br/>[stratum-tools.js]"]
  node_backend_client["Backend client<br/>[client.js]"]
  node_router["Model dispatch<br/>[dispatch.js]"]
  node_scoring["Route scoring<br/>[score.js]"]
  node_fleet["Model registry<br/>[loader.js]"]
  node_provider["Local model provider<br/>[local-provider.js]"]
  node_turn_trace["Turn trace<br/>[turn.js]"]
end

subgraph group_ingestion["Library ingestion"]
  node_ingest["Document pipeline<br/>[pipeline.py]"]
  node_parser["Document parsing<br/>[docling_parse.py]"]
  node_chunker["Evidence chunking<br/>[chunker.py]"]
end

subgraph group_facts["Facts and review"]
  node_mapper["Fact mapping<br/>[mapper.py]"]
  node_extract["Verbatim extraction<br/>[extract.py]"]
  node_validation["Fact checks<br/>[validate.py]"]
  node_fact_service["Fact review<br/>[service.py]"]
end

subgraph group_answers["Evidence products"]
  node_ask_intent["Question intent<br/>[intent.py]"]
  node_ask_service["Ask service<br/>[service.py]"]
  node_sql["Fact query compiler<br/>[sql.py]"]
  node_hybrid["Hybrid retrieval<br/>[hybrid.py]"]
  node_embed["Text embeddings<br/>[embed.py]"]
  node_pq["PQ reply builder<br/>[service.py]"]
  node_reports["Report generator<br/>[service.py]"]
  node_topics["Topic analysis<br/>[service.py]"]
  node_metrics["Quality metrics<br/>[service.py]"]
end

subgraph group_runtime["Backend runtime"]
  node_api["FastAPI service<br/>[api.py]"]
  node_domain["Coal domain rules<br/>[__init__.py]"]
  node_db[("SQLite evidence store<br/>[db.py]")]
  node_llm_client["Local LLM client<br/>[llm.py]"]
  node_docx["Word output<br/>[docx_out.py]"]
end

node_user(("Workbench user"))
node_llama["llama-swap models"]

node_user -->|"uses workbench"| node_plugin
node_plugin -->|"registers tools"| node_tools
node_tools -->|"calls backend"| node_backend_client
node_backend_client -->|"HTTP requests"| node_api
node_plugin -->|"routes turns"| node_router
node_router -->|"scores routes"| node_scoring
node_router -->|"selects model"| node_fleet
node_plugin -->|"registers provider"| node_provider
node_provider -->|"records images"| node_turn_trace
node_api -.->|"accepts library documents"| node_ingest
node_ingest -->|"parses documents"| node_parser
node_ingest -->|"creates chunks"| node_chunker
node_ingest -->|"maps tables"| node_mapper
node_ingest -->|"extracts values"| node_extract
node_ingest -->|"checks facts"| node_validation
node_ingest -->|"persists evidence"| node_db
node_mapper -.->|"requests mapping"| node_llm_client
node_fact_service -->|"recomputes checks"| node_validation
node_fact_service -->|"reads and reviews"| node_db
node_user -->|"asks question"| node_ask_service
node_api -.->|"serves questions"| node_ask_service
node_ask_service -->|"parses intent"| node_ask_intent
node_ask_service -->|"queries facts"| node_sql
node_ask_service -->|"retrieves passages"| node_hybrid
node_ask_service -.->|"composes answer"| node_llm_client
node_sql -->|"looks up facts"| node_fact_service
node_hybrid -->|"embeds query"| node_embed
node_ask_intent -->|"normalizes terms"| node_domain
node_sql -->|"uses domain rules"| node_domain
node_hybrid -->|"reads chunks"| node_db
node_embed -.->|"uses local embedding model"| node_llm_client
node_llm_client -->|"sends local requests"| node_llama
node_user -->|"builds PQ reply"| node_pq
node_pq -->|"gets answer evidence"| node_ask_service
node_pq -->|"writes Word reply"| node_docx
node_user -->|"generates report"| node_reports
node_reports -->|"uses answer services"| node_ask_service
node_reports -->|"writes report"| node_docx
node_user -->|"explores topics"| node_topics
node_topics -->|"uses embeddings"| node_embed
node_topics -->|"reads library"| node_db
node_user -->|"reviews flagged facts"| node_fact_service
node_user -->|"views measurements"| node_metrics
node_metrics -->|"reads answer records"| node_db
node_metrics -->|"measures routing"| node_ask_intent
node_metrics -->|"measures correctness"| node_sql
node_metrics -->|"measures extraction"| node_fact_service

click node_plugin "https://github.com/rudrao2/stratum/blob/main/plugins/stratum-ui/lib/index.js"
click node_tools "https://github.com/rudrao2/stratum/blob/main/plugins/stratum-ui/lib/tools/stratum-tools.js"
click node_backend_client "https://github.com/rudrao2/stratum/blob/main/plugins/stratum-ui/lib/backend/client.js"
click node_router "https://github.com/rudrao2/stratum/blob/main/plugins/stratum-ui/lib/router/dispatch.js"
click node_scoring "https://github.com/rudrao2/stratum/blob/main/plugins/stratum-ui/lib/router/score.js"
click node_fleet "https://github.com/rudrao2/stratum/blob/main/plugins/stratum-ui/lib/registry/loader.js"
click node_provider "https://github.com/rudrao2/stratum/blob/main/plugins/stratum-ui/lib/model-plane/local-provider.js"
click node_turn_trace "https://github.com/rudrao2/stratum/blob/main/plugins/stratum-ui/lib/trace/turn.js"
click node_api "https://github.com/rudrao2/stratum/blob/main/backend/stratum/api.py"
click node_ingest "https://github.com/rudrao2/stratum/blob/main/backend/stratum/ingest/pipeline.py"
click node_parser "https://github.com/rudrao2/stratum/blob/main/backend/stratum/ingest/docling_parse.py"
click node_chunker "https://github.com/rudrao2/stratum/blob/main/backend/stratum/ingest/chunker.py"
click node_mapper "https://github.com/rudrao2/stratum/blob/main/backend/stratum/facts/mapper.py"
click node_extract "https://github.com/rudrao2/stratum/blob/main/backend/stratum/facts/extract.py"
click node_validation "https://github.com/rudrao2/stratum/blob/main/backend/stratum/facts/validate.py"
click node_fact_service "https://github.com/rudrao2/stratum/blob/main/backend/stratum/facts/service.py"
click node_ask_intent "https://github.com/rudrao2/stratum/blob/main/backend/stratum/ask/intent.py"
click node_ask_service "https://github.com/rudrao2/stratum/blob/main/backend/stratum/ask/service.py"
click node_sql "https://github.com/rudrao2/stratum/blob/main/backend/stratum/ask/sql.py"
click node_hybrid "https://github.com/rudrao2/stratum/blob/main/backend/stratum/search/hybrid.py"
click node_embed "https://github.com/rudrao2/stratum/blob/main/backend/stratum/search/embed.py"
click node_pq "https://github.com/rudrao2/stratum/blob/main/backend/stratum/pq/service.py"
click node_reports "https://github.com/rudrao2/stratum/blob/main/backend/stratum/reports/service.py"
click node_topics "https://github.com/rudrao2/stratum/blob/main/backend/stratum/topics/service.py"
click node_metrics "https://github.com/rudrao2/stratum/blob/main/backend/stratum/metrics/service.py"
click node_domain "https://github.com/rudrao2/stratum/blob/main/backend/stratum/domain/__init__.py"
click node_db "https://github.com/rudrao2/stratum/blob/main/backend/stratum/db.py"
click node_llm_client "https://github.com/rudrao2/stratum/blob/main/backend/stratum/llm.py"
click node_docx "https://github.com/rudrao2/stratum/blob/main/backend/stratum/docx_out.py"

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_plugin,node_tools,node_backend_client,node_router,node_scoring,node_fleet,node_provider,node_turn_trace,node_user toneBlue
class node_ingest,node_parser,node_chunker toneAmber
class node_mapper,node_extract,node_validation,node_fact_service toneMint
class node_ask_intent,node_ask_service,node_sql,node_hybrid,node_embed,node_pq,node_reports,node_topics,node_metrics toneRose
class node_api,node_domain,node_db,node_llm_client,node_docx,node_llama toneIndigo
```

## Components

### Workbench plugin

- [Harness integration](https://github.com/rudrao2/stratum/blob/main/plugins/stratum-ui/lib/index.js): `plugins/stratum-ui/lib/index.js`
- [Stratum tools](https://github.com/rudrao2/stratum/blob/main/plugins/stratum-ui/lib/tools/stratum-tools.js): `plugins/stratum-ui/lib/tools/stratum-tools.js`
- [Backend client](https://github.com/rudrao2/stratum/blob/main/plugins/stratum-ui/lib/backend/client.js): `plugins/stratum-ui/lib/backend/client.js`
- [Model dispatch](https://github.com/rudrao2/stratum/blob/main/plugins/stratum-ui/lib/router/dispatch.js): `plugins/stratum-ui/lib/router/dispatch.js`
- [Route scoring](https://github.com/rudrao2/stratum/blob/main/plugins/stratum-ui/lib/router/score.js): `plugins/stratum-ui/lib/router/score.js`
- [Model registry](https://github.com/rudrao2/stratum/blob/main/plugins/stratum-ui/lib/registry/loader.js): `plugins/stratum-ui/lib/registry/loader.js`
- [Local model provider](https://github.com/rudrao2/stratum/blob/main/plugins/stratum-ui/lib/model-plane/local-provider.js): `plugins/stratum-ui/lib/model-plane/local-provider.js`
- [Turn trace](https://github.com/rudrao2/stratum/blob/main/plugins/stratum-ui/lib/trace/turn.js): `plugins/stratum-ui/lib/trace/turn.js`

### Library ingestion

- [Document pipeline](https://github.com/rudrao2/stratum/blob/main/backend/stratum/ingest/pipeline.py): `backend/stratum/ingest/pipeline.py`
- [Document parsing](https://github.com/rudrao2/stratum/blob/main/backend/stratum/ingest/docling_parse.py): `backend/stratum/ingest/docling_parse.py`
- [Evidence chunking](https://github.com/rudrao2/stratum/blob/main/backend/stratum/ingest/chunker.py): `backend/stratum/ingest/chunker.py`

### Facts and review

- [Fact mapping](https://github.com/rudrao2/stratum/blob/main/backend/stratum/facts/mapper.py): `backend/stratum/facts/mapper.py`
- [Verbatim extraction](https://github.com/rudrao2/stratum/blob/main/backend/stratum/facts/extract.py): `backend/stratum/facts/extract.py`
- [Fact checks](https://github.com/rudrao2/stratum/blob/main/backend/stratum/facts/validate.py): `backend/stratum/facts/validate.py`
- [Fact review](https://github.com/rudrao2/stratum/blob/main/backend/stratum/facts/service.py): `backend/stratum/facts/service.py`

### Evidence products

- [Question intent](https://github.com/rudrao2/stratum/blob/main/backend/stratum/ask/intent.py): `backend/stratum/ask/intent.py`
- [Ask service](https://github.com/rudrao2/stratum/blob/main/backend/stratum/ask/service.py): `backend/stratum/ask/service.py`
- [Fact query compiler](https://github.com/rudrao2/stratum/blob/main/backend/stratum/ask/sql.py): `backend/stratum/ask/sql.py`
- [Hybrid retrieval](https://github.com/rudrao2/stratum/blob/main/backend/stratum/search/hybrid.py): `backend/stratum/search/hybrid.py`
- [Text embeddings](https://github.com/rudrao2/stratum/blob/main/backend/stratum/search/embed.py): `backend/stratum/search/embed.py`
- [PQ reply builder](https://github.com/rudrao2/stratum/blob/main/backend/stratum/pq/service.py): `backend/stratum/pq/service.py`
- [Report generator](https://github.com/rudrao2/stratum/blob/main/backend/stratum/reports/service.py): `backend/stratum/reports/service.py`
- [Topic analysis](https://github.com/rudrao2/stratum/blob/main/backend/stratum/topics/service.py): `backend/stratum/topics/service.py`
- [Quality metrics](https://github.com/rudrao2/stratum/blob/main/backend/stratum/metrics/service.py): `backend/stratum/metrics/service.py`

### Backend runtime

- [FastAPI service](https://github.com/rudrao2/stratum/blob/main/backend/stratum/api.py): `backend/stratum/api.py`
- [Coal domain rules](https://github.com/rudrao2/stratum/blob/main/backend/stratum/domain/__init__.py): `backend/stratum/domain/__init__.py`
- [SQLite evidence store](https://github.com/rudrao2/stratum/blob/main/backend/stratum/db.py): `backend/stratum/db.py`
- [Local LLM client](https://github.com/rudrao2/stratum/blob/main/backend/stratum/llm.py): `backend/stratum/llm.py`
- [Word output](https://github.com/rudrao2/stratum/blob/main/backend/stratum/docx_out.py): `backend/stratum/docx_out.py`

### Other components

- **Workbench user**
- **llama-swap models**

## Connections

- Workbench user → Harness integration: uses workbench
- Harness integration → Stratum tools: registers tools (evidence: `plugins/stratum-ui/lib/index.js`)
- Stratum tools → Backend client: calls backend (evidence: `plugins/stratum-ui/lib/tools/stratum-tools.js`)
- Backend client → FastAPI service: HTTP requests (evidence: `plugins/stratum-ui/lib/backend/client.js`)
- Harness integration → Model dispatch: routes turns (evidence: `plugins/stratum-ui/lib/index.js`)
- Model dispatch → Route scoring: scores routes (evidence: `plugins/stratum-ui/lib/router/dispatch.js`)
- Model dispatch → Model registry: selects model (evidence: `plugins/stratum-ui/lib/model-plane/llm-adapter.js`)
- Harness integration → Local model provider: registers provider
- Local model provider → Turn trace: records images
- FastAPI service → Document pipeline: accepts library documents
- Document pipeline → Document parsing: parses documents (evidence: `backend/stratum/ingest/pipeline.py`)
- Document pipeline → Evidence chunking: creates chunks (evidence: `backend/stratum/ingest/pipeline.py`)
- Document pipeline → Fact mapping: maps tables (evidence: `backend/stratum/ingest/pipeline.py`)
- Document pipeline → Verbatim extraction: extracts values (evidence: `backend/stratum/ingest/pipeline.py`)
- Document pipeline → Fact checks: checks facts (evidence: `backend/stratum/ingest/pipeline.py`)
- Document pipeline → SQLite evidence store: persists evidence (evidence: `backend/stratum/ingest/pipeline.py`)
- Fact mapping → Local LLM client: requests mapping
- Fact review → Fact checks: recomputes checks (evidence: `backend/stratum/facts/service.py`)
- Fact review → SQLite evidence store: reads and reviews (evidence: `backend/stratum/facts/service.py`)
- Workbench user → Ask service: asks question
- FastAPI service → Ask service: serves questions
- Ask service → Question intent: parses intent (evidence: `backend/stratum/ask/service.py`)
- Ask service → Fact query compiler: queries facts (evidence: `backend/stratum/ask/service.py`)
- Ask service → Hybrid retrieval: retrieves passages (evidence: `backend/stratum/ask/service.py`)
- Ask service → Local LLM client: composes answer (evidence: `backend/stratum/ask/service.py`)
- Fact query compiler → Fact review: looks up facts (evidence: `backend/stratum/ask/sql.py`)
- Hybrid retrieval → Text embeddings: embeds query (evidence: `backend/stratum/search/hybrid.py`)
- Question intent → Coal domain rules: normalizes terms (evidence: `backend/stratum/ask/intent.py`)
- Fact query compiler → Coal domain rules: uses domain rules (evidence: `backend/stratum/ask/sql.py`)
- Hybrid retrieval → SQLite evidence store: reads chunks (evidence: `backend/stratum/search/hybrid.py`)
- Text embeddings → Local LLM client: uses local embedding model
- Local LLM client → llama-swap models: sends local requests (evidence: `backend/stratum/llm.py`)
- Workbench user → PQ reply builder: builds PQ reply
- PQ reply builder → Ask service: gets answer evidence (evidence: `backend/stratum/pq/service.py`)
- PQ reply builder → Word output: writes Word reply (evidence: `backend/stratum/pq/service.py`)
- Workbench user → Report generator: generates report
- Report generator → Ask service: uses answer services (evidence: `backend/stratum/reports/service.py`)
- Report generator → Word output: writes report (evidence: `backend/stratum/reports/service.py`)
- Workbench user → Topic analysis: explores topics
- Topic analysis → Text embeddings: uses embeddings (evidence: `backend/stratum/topics/service.py`)
- Topic analysis → SQLite evidence store: reads library (evidence: `backend/stratum/topics/service.py`)
- Workbench user → Fact review: reviews flagged facts
- Workbench user → Quality metrics: views measurements
- Quality metrics → SQLite evidence store: reads answer records (evidence: `backend/stratum/metrics/service.py`)
- Quality metrics → Question intent: measures routing (evidence: `backend/stratum/metrics/service.py`)
- Quality metrics → Fact query compiler: measures correctness (evidence: `backend/stratum/metrics/service.py`)
- Quality metrics → Fact review: measures extraction (evidence: `backend/stratum/metrics/service.py`)