# mattkari/source-grounded-rag architecture

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

- Interactive diagram: https://gitdiagram.com/mattkari/source-grounded-rag
- Repository: https://github.com/mattkari/source-grounded-rag

## Overview

This is a source-grounded scholarly research assistant with a second, substantial workflow for drafting reviewable articles. Researchers ask questions through a web or CLI surface; a shared retrieval-and-generation pipeline returns answers with traceable citations or refuses when evidence is insufficient. Documents can also be ingested or uploaded with layout measurement and review. The article workflow explores sources, drafts and checks sections, then assembles and exports an article. The README documents the product capabilities; some internals are unsampled, so the graph omits uncertain links.

Main entry points: [`ask.py`](https://github.com/mattkari/source-grounded-rag/blob/main/ask.py) (Query pipeline), [`article/pipeline.py`](https://github.com/mattkari/source-grounded-rag/blob/main/article/pipeline.py) (Article pipeline), [`app.py`](https://github.com/mattkari/source-grounded-rag/blob/main/app.py) (Article workspace), [`upload.py`](https://github.com/mattkari/source-grounded-rag/blob/main/upload.py) (Upload workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Research interfaces"]
  node_web["Web chat<br/>[app.py]"]
  node_interactive["Interactive CLI<br/>[main.py]"]
  node_single["Single-query CLI<br/>[ask.py]"]
  node_uploadui["Upload review UI<br/>[app.py]"]
  node_articleui["Article workspace<br/>[app.py]"]
end

subgraph group_corpus["Corpus management"]
  node_upload["Upload workflow<br/>[upload.py]"]
  node_layout["PDF layout profile<br/>[layout.py]"]
  node_identity["Document identity<br/>[identity.py]"]
  node_ingest["Extract and chunk<br/>[ingest.py]"]
  node_canonical["Canonical pages<br/>[pages.jsonl]"]
  node_index[("Passage index")]
end

subgraph group_qa["Grounded Q&amp;A"]
  node_query["Query pipeline<br/>[ask.py]"]
  node_embed["Embedding provider<br/>[embeddings.py]"]
  node_documents["Document profiles<br/>[documents.py]"]
  node_models{{"Model services"}}
end

subgraph group_article["Article workflow"]
  node_explorer["Source exploration<br/>[explorer.py]"]
  node_sources["Article source filter<br/>[sources.py]"]
  node_draft["Article pipeline<br/>[pipeline.py]"]
  node_checks["Article checks<br/>[checks.py]"]
  node_assembly["Article assembly<br/>[assemble.py]"]
  node_export["Article export<br/>[export.py]"]
end

subgraph group_review["Review and records"]
  node_trace["Workflow trace<br/>[trace.py]"]
  node_runs[("Run history<br/>[runs.py]")]
end

node_researcher(("Researcher"))

node_researcher -->|"asks through"| node_web
node_researcher -->|"asks through"| node_interactive
node_researcher -->|"asks through"| node_single
node_researcher -->|"submits document"| node_uploadui
node_web -->|"calls shared pipeline"| node_query
node_interactive -->|"calls shared pipeline"| node_query
node_single -->|"runs query"| node_query
node_uploadui -->|"uses workflow"| node_upload
node_upload -->|"measures PDF"| node_layout
node_upload -->|"proposes identity"| node_identity
node_upload -->|"extracts and chunks"| node_ingest
node_ingest -->|"writes pages"| node_canonical
node_ingest -->|"embeds passages"| node_embed
node_ingest -->|"builds index"| node_index
node_query -->|"embeds question"| node_embed
node_query -->|"retrieves passages"| node_index
node_query -->|"uses document profiles"| node_documents
node_query -->|"requests grounded answer"| node_models
node_query -.->|"records query"| node_runs
node_researcher -->|"drafts article"| node_articleui
node_articleui -.->|"starts exploration"| node_explorer
node_explorer -->|"queries evidence"| node_query
node_articleui -.->|"runs article workflow"| node_draft
node_draft -->|"filters sources"| node_sources
node_draft -->|"drafts sections"| node_query
node_draft -->|"checks outcomes"| node_checks
node_draft -->|"assembles validated draft"| node_assembly
node_draft -->|"saves or exports"| node_export
node_articleui -.->|"shows workflow trace"| node_trace

click node_web "https://github.com/mattkari/source-grounded-rag/blob/main/app.py"
click node_interactive "https://github.com/mattkari/source-grounded-rag/blob/main/main.py"
click node_single "https://github.com/mattkari/source-grounded-rag/blob/main/ask.py"
click node_uploadui "https://github.com/mattkari/source-grounded-rag/blob/main/app.py"
click node_upload "https://github.com/mattkari/source-grounded-rag/blob/main/upload.py"
click node_layout "https://github.com/mattkari/source-grounded-rag/blob/main/layout.py"
click node_identity "https://github.com/mattkari/source-grounded-rag/blob/main/identity.py"
click node_ingest "https://github.com/mattkari/source-grounded-rag/blob/main/ingest.py"
click node_canonical "https://github.com/mattkari/source-grounded-rag/blob/main/data/canonical/pages.jsonl"
click node_index "https://github.com/mattkari/source-grounded-rag/tree/main/index"
click node_query "https://github.com/mattkari/source-grounded-rag/blob/main/ask.py"
click node_embed "https://github.com/mattkari/source-grounded-rag/blob/main/embeddings.py"
click node_documents "https://github.com/mattkari/source-grounded-rag/blob/main/documents.py"
click node_articleui "https://github.com/mattkari/source-grounded-rag/blob/main/app.py"
click node_explorer "https://github.com/mattkari/source-grounded-rag/blob/main/article/explorer.py"
click node_sources "https://github.com/mattkari/source-grounded-rag/blob/main/article/sources.py"
click node_draft "https://github.com/mattkari/source-grounded-rag/blob/main/article/pipeline.py"
click node_checks "https://github.com/mattkari/source-grounded-rag/blob/main/article/checks.py"
click node_assembly "https://github.com/mattkari/source-grounded-rag/blob/main/article/assemble.py"
click node_export "https://github.com/mattkari/source-grounded-rag/blob/main/article/export.py"
click node_trace "https://github.com/mattkari/source-grounded-rag/blob/main/article/trace.py"
click node_runs "https://github.com/mattkari/source-grounded-rag/blob/main/runs.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_web,node_interactive,node_single,node_uploadui,node_articleui toneBlue
class node_upload,node_layout,node_identity,node_ingest,node_canonical,node_index toneAmber
class node_query,node_embed,node_documents,node_models toneMint
class node_explorer,node_sources,node_draft,node_checks,node_assembly,node_export toneRose
class node_trace,node_runs,node_researcher toneIndigo
```

## Components

### Research interfaces

- [Web chat](https://github.com/mattkari/source-grounded-rag/blob/main/app.py): `app.py`
- [Interactive CLI](https://github.com/mattkari/source-grounded-rag/blob/main/main.py): `main.py`
- [Single-query CLI](https://github.com/mattkari/source-grounded-rag/blob/main/ask.py): `ask.py`
- [Upload review UI](https://github.com/mattkari/source-grounded-rag/blob/main/app.py): `app.py`
- [Article workspace](https://github.com/mattkari/source-grounded-rag/blob/main/app.py): `app.py`

### Corpus management

- [Upload workflow](https://github.com/mattkari/source-grounded-rag/blob/main/upload.py): `upload.py`
- [PDF layout profile](https://github.com/mattkari/source-grounded-rag/blob/main/layout.py): `layout.py`
- [Document identity](https://github.com/mattkari/source-grounded-rag/blob/main/identity.py): `identity.py`
- [Extract and chunk](https://github.com/mattkari/source-grounded-rag/blob/main/ingest.py): `ingest.py`
- [Canonical pages](https://github.com/mattkari/source-grounded-rag/blob/main/data/canonical/pages.jsonl): `data/canonical/pages.jsonl`
- [Passage index](https://github.com/mattkari/source-grounded-rag/tree/main/index): `index`

### Grounded Q&A

- [Query pipeline](https://github.com/mattkari/source-grounded-rag/blob/main/ask.py): `ask.py`
- [Embedding provider](https://github.com/mattkari/source-grounded-rag/blob/main/embeddings.py): `embeddings.py`
- [Document profiles](https://github.com/mattkari/source-grounded-rag/blob/main/documents.py): `documents.py`
- **Model services**

### Article workflow

- [Source exploration](https://github.com/mattkari/source-grounded-rag/blob/main/article/explorer.py): `article/explorer.py`
- [Article source filter](https://github.com/mattkari/source-grounded-rag/blob/main/article/sources.py): `article/sources.py`
- [Article pipeline](https://github.com/mattkari/source-grounded-rag/blob/main/article/pipeline.py): `article/pipeline.py`
- [Article checks](https://github.com/mattkari/source-grounded-rag/blob/main/article/checks.py): `article/checks.py`
- [Article assembly](https://github.com/mattkari/source-grounded-rag/blob/main/article/assemble.py): `article/assemble.py`
- [Article export](https://github.com/mattkari/source-grounded-rag/blob/main/article/export.py): `article/export.py`

### Review and records

- [Workflow trace](https://github.com/mattkari/source-grounded-rag/blob/main/article/trace.py): `article/trace.py`
- [Run history](https://github.com/mattkari/source-grounded-rag/blob/main/runs.py): `runs.py`

### Other components

- **Researcher**

## Connections

- Researcher → Web chat: asks through (evidence: `README.md`)
- Researcher → Interactive CLI: asks through (evidence: `README.md`)
- Researcher → Single-query CLI: asks through (evidence: `README.md`)
- Researcher → Upload review UI: submits document (evidence: `README.md`)
- Web chat → Query pipeline: calls shared pipeline (evidence: `README.md`)
- Interactive CLI → Query pipeline: calls shared pipeline (evidence: `README.md`)
- Single-query CLI → Query pipeline: runs query (evidence: `README.md`)
- Upload review UI → Upload workflow: uses workflow (evidence: `app.py`)
- Upload workflow → PDF layout profile: measures PDF (evidence: `upload.py`)
- Upload workflow → Document identity: proposes identity (evidence: `upload.py`)
- Upload workflow → Extract and chunk: extracts and chunks (evidence: `upload.py`)
- Extract and chunk → Canonical pages: writes pages (evidence: `README.md`)
- Extract and chunk → Embedding provider: embeds passages (evidence: `ingest.py`)
- Extract and chunk → Passage index: builds index (evidence: `README.md`)
- Query pipeline → Embedding provider: embeds question (evidence: `ask.py`)
- Query pipeline → Passage index: retrieves passages (evidence: `README.md`)
- Query pipeline → Document profiles: uses document profiles (evidence: `ask.py`)
- Query pipeline → Model services: requests grounded answer (evidence: `README.md`)
- Query pipeline → Run history: records query (evidence: `app.py`)
- Researcher → Article workspace: drafts article (evidence: `README.md`)
- Article workspace → Source exploration: starts exploration (evidence: `app.py`)
- Source exploration → Query pipeline: queries evidence (evidence: `article/explorer.py`)
- Article workspace → Article pipeline: runs article workflow (evidence: `app.py`)
- Article pipeline → Article source filter: filters sources (evidence: `article/pipeline.py`)
- Article pipeline → Query pipeline: drafts sections (evidence: `article/pipeline.py`)
- Article pipeline → Article checks: checks outcomes (evidence: `article/pipeline.py`)
- Article pipeline → Article assembly: assembles validated draft (evidence: `article/pipeline.py`)
- Article pipeline → Article export: saves or exports (evidence: `article/pipeline.py`)
- Article workspace → Workflow trace: shows workflow trace (evidence: `app.py`)
