# mohammadmassaf/groundedforge architecture

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

- Interactive diagram: https://gitdiagram.com/mohammadmassaf/groundedforge
- Repository: https://github.com/mohammadmassaf/groundedforge

## Overview

Grounded Forge ingests user corpora, retrieves cited evidence, generates study or job-mode artifacts, and applies an independent cite-or-strike Critic before rendering results. Its README also describes evaluation of retrieval recall, grounding, and adversarial traps. The excerpts show ingestion dispatch, vector and keyword retrieval, and critique-loop behavior; several other subsystem links are documented in the README or indicated by the source index, so unsampled internals are represented at subsystem level.

Main entry points: [`main.py`](https://github.com/mohammadmassaf/groundedforge/blob/main/main.py) (CLI commands), [`critic/loop.py`](https://github.com/mohammadmassaf/groundedforge/blob/main/critic/loop.py) (Critic-refiner loop), [`retrieve/query.py`](https://github.com/mohammadmassaf/groundedforge/blob/main/retrieve/query.py) (Vector search), [`ingest/pipeline.py`](https://github.com/mohammadmassaf/groundedforge/blob/main/ingest/pipeline.py) (Ingest orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Corpus ingestion"]
  node_corpus_config["Corpus configuration<br/>[corpus_config.py]"]
  node_ingest_pipeline["Ingest orchestration<br/>[pipeline.py]"]
  node_adapters["Source adapters"]
  node_chunking["Chunk preparation<br/>[chunker.py]"]
  node_chunks["Chunk corpus"]
end

subgraph group_retrieval["Evidence retrieval"]
  node_index_store[("Vector index<br/>[store.py]")]
  node_vector_search["Vector search<br/>[query.py]"]
  node_keyword_search["BM25 search<br/>[keyword.py]"]
  node_hybrid_search["Hybrid ranking<br/>[hybrid.py]"]
  node_star_evidence["STAR evidence pools<br/>[star_evidence.py]"]
end

subgraph group_artifacts["Artifact generation"]
  node_generator["Artifact generator<br/>[generator.py]"]
  node_schemas["Output schemas<br/>[schema.py]"]
  node_renderer["Artifact renderer<br/>[renderer.py]"]
end

subgraph group_verification["Verification and evaluation"]
  node_critic_loop["Critic-refiner loop<br/>[loop.py]"]
  node_critic["Independent Critic<br/>[critic.py]"]
  node_quantity_guard["Quantity guard<br/>[quant.py]"]
  node_trace["Run trace<br/>[trace.py]"]
  node_evaluation["Evaluation harness<br/>[run_eval.py]"]
  node_strike_analysis["Strike analysis<br/>[strikes.py]"]
end

node_user(("Corpus user"))
node_cli["CLI commands<br/>[main.py]"]
node_app["Gradio interface<br/>[app.py]"]
node_llm{{"Groq model service"}}

node_user -->|"runs commands"| node_cli
node_user -->|"uses interface"| node_app
node_cli -->|"ingests corpus"| node_ingest_pipeline
node_ingest_pipeline -->|"loads sources"| node_corpus_config
node_ingest_pipeline -->|"dispatches sources"| node_adapters
node_adapters -.->|"prepares chunks"| node_chunking
node_ingest_pipeline -->|"writes chunks"| node_chunks
node_cli -->|"builds index"| node_index_store
node_index_store -->|"reads chunks"| node_chunks
node_cli -->|"queries corpus"| node_vector_search
node_app -->|"queries corpus"| node_vector_search
node_vector_search -->|"searches vectors"| node_index_store
node_hybrid_search -->|"combines results"| node_vector_search
node_hybrid_search -->|"combines results"| node_keyword_search
node_star_evidence -->|"gathers evidence"| node_hybrid_search
node_cli -->|"retrieves context"| node_hybrid_search
node_cli -->|"gathers STAR evidence"| node_star_evidence
node_cli -->|"runs artifact loop"| node_critic_loop
node_app -->|"runs artifact loop"| node_critic_loop
node_critic_loop -->|"generates candidates"| node_generator
node_generator -->|"validates output"| node_schemas
node_critic_loop -->|"checks claims"| node_critic
node_critic_loop -->|"checks quantities"| node_quantity_guard
node_critic_loop -->|"records verdicts"| node_trace
node_cli -->|"renders artifact"| node_renderer
node_critic_loop -.->|"returns kept items"| node_renderer
node_generator -->|"requests generation"| node_llm
node_critic -->|"requests verdict"| node_llm
node_cli -->|"runs evaluation"| node_evaluation
node_evaluation -->|"measures grounding"| node_critic_loop
node_evaluation -->|"measures recall"| node_vector_search
node_cli -->|"reports strikes"| node_strike_analysis
node_evaluation -.->|"analyzes strikes"| node_strike_analysis

click node_cli "https://github.com/mohammadmassaf/groundedforge/blob/main/main.py"
click node_app "https://github.com/mohammadmassaf/groundedforge/blob/main/app.py"
click node_corpus_config "https://github.com/mohammadmassaf/groundedforge/blob/main/ingest/corpus_config.py"
click node_ingest_pipeline "https://github.com/mohammadmassaf/groundedforge/blob/main/ingest/pipeline.py"
click node_adapters "https://github.com/mohammadmassaf/groundedforge/tree/main/ingest/adapters"
click node_chunking "https://github.com/mohammadmassaf/groundedforge/blob/main/ingest/chunker.py"
click node_chunks "https://github.com/mohammadmassaf/groundedforge/tree/main/chunks"
click node_index_store "https://github.com/mohammadmassaf/groundedforge/blob/main/retrieve/store.py"
click node_vector_search "https://github.com/mohammadmassaf/groundedforge/blob/main/retrieve/query.py"
click node_keyword_search "https://github.com/mohammadmassaf/groundedforge/blob/main/retrieve/keyword.py"
click node_hybrid_search "https://github.com/mohammadmassaf/groundedforge/blob/main/retrieve/hybrid.py"
click node_star_evidence "https://github.com/mohammadmassaf/groundedforge/blob/main/retrieve/star_evidence.py"
click node_generator "https://github.com/mohammadmassaf/groundedforge/blob/main/generate/generator.py"
click node_schemas "https://github.com/mohammadmassaf/groundedforge/blob/main/generate/schema.py"
click node_critic_loop "https://github.com/mohammadmassaf/groundedforge/blob/main/critic/loop.py"
click node_critic "https://github.com/mohammadmassaf/groundedforge/blob/main/critic/critic.py"
click node_quantity_guard "https://github.com/mohammadmassaf/groundedforge/blob/main/critic/quant.py"
click node_trace "https://github.com/mohammadmassaf/groundedforge/blob/main/critic/trace.py"
click node_renderer "https://github.com/mohammadmassaf/groundedforge/blob/main/generate/renderer.py"
click node_evaluation "https://github.com/mohammadmassaf/groundedforge/blob/main/eval/run_eval.py"
click node_strike_analysis "https://github.com/mohammadmassaf/groundedforge/blob/main/eval/strikes.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_corpus_config,node_ingest_pipeline,node_adapters,node_chunking,node_chunks,node_user toneBlue
class node_index_store,node_vector_search,node_keyword_search,node_hybrid_search,node_star_evidence toneAmber
class node_generator,node_schemas,node_renderer toneMint
class node_critic_loop,node_critic,node_quantity_guard,node_trace,node_evaluation,node_strike_analysis toneRose
class node_cli,node_app toneTeal
class node_llm toneIndigo
```

## Components

### Corpus ingestion

- [Corpus configuration](https://github.com/mohammadmassaf/groundedforge/blob/main/ingest/corpus_config.py): `ingest/corpus_config.py`
- [Ingest orchestration](https://github.com/mohammadmassaf/groundedforge/blob/main/ingest/pipeline.py): `ingest/pipeline.py`
- [Source adapters](https://github.com/mohammadmassaf/groundedforge/tree/main/ingest/adapters): `ingest/adapters`
- [Chunk preparation](https://github.com/mohammadmassaf/groundedforge/blob/main/ingest/chunker.py): `ingest/chunker.py`
- [Chunk corpus](https://github.com/mohammadmassaf/groundedforge/tree/main/chunks): `chunks`

### Evidence retrieval

- [Vector index](https://github.com/mohammadmassaf/groundedforge/blob/main/retrieve/store.py): `retrieve/store.py`
- [Vector search](https://github.com/mohammadmassaf/groundedforge/blob/main/retrieve/query.py): `retrieve/query.py`
- [BM25 search](https://github.com/mohammadmassaf/groundedforge/blob/main/retrieve/keyword.py): `retrieve/keyword.py`
- [Hybrid ranking](https://github.com/mohammadmassaf/groundedforge/blob/main/retrieve/hybrid.py): `retrieve/hybrid.py`
- [STAR evidence pools](https://github.com/mohammadmassaf/groundedforge/blob/main/retrieve/star_evidence.py): `retrieve/star_evidence.py`

### Artifact generation

- [Artifact generator](https://github.com/mohammadmassaf/groundedforge/blob/main/generate/generator.py): `generate/generator.py`
- [Output schemas](https://github.com/mohammadmassaf/groundedforge/blob/main/generate/schema.py): `generate/schema.py`
- [Artifact renderer](https://github.com/mohammadmassaf/groundedforge/blob/main/generate/renderer.py): `generate/renderer.py`

### Verification and evaluation

- [Critic-refiner loop](https://github.com/mohammadmassaf/groundedforge/blob/main/critic/loop.py): `critic/loop.py`
- [Independent Critic](https://github.com/mohammadmassaf/groundedforge/blob/main/critic/critic.py): `critic/critic.py`
- [Quantity guard](https://github.com/mohammadmassaf/groundedforge/blob/main/critic/quant.py): `critic/quant.py`
- [Run trace](https://github.com/mohammadmassaf/groundedforge/blob/main/critic/trace.py): `critic/trace.py`
- [Evaluation harness](https://github.com/mohammadmassaf/groundedforge/blob/main/eval/run_eval.py): `eval/run_eval.py`
- [Strike analysis](https://github.com/mohammadmassaf/groundedforge/blob/main/eval/strikes.py): `eval/strikes.py`

### Other components

- **Corpus user**
- [CLI commands](https://github.com/mohammadmassaf/groundedforge/blob/main/main.py): `main.py`
- [Gradio interface](https://github.com/mohammadmassaf/groundedforge/blob/main/app.py): `app.py`
- **Groq model service**

## Connections

- Corpus user → CLI commands: runs commands (evidence: `README.md`)
- Corpus user → Gradio interface: uses interface (evidence: `README.md`)
- CLI commands → Ingest orchestration: ingests corpus (evidence: `README.md`)
- Ingest orchestration → Corpus configuration: loads sources (evidence: `ingest/pipeline.py`)
- Ingest orchestration → Source adapters: dispatches sources (evidence: `ingest/pipeline.py`)
- Source adapters → Chunk preparation: prepares chunks (evidence: `ingest/adapters/files_adapter.py`)
- Ingest orchestration → Chunk corpus: writes chunks (evidence: `ingest/pipeline.py`)
- CLI commands → Vector index: builds index (evidence: `README.md`)
- Vector index → Chunk corpus: reads chunks (evidence: `retrieve/store.py`)
- CLI commands → Vector search: queries corpus (evidence: `main.py`)
- Gradio interface → Vector search: queries corpus (evidence: `app.py`)
- Vector search → Vector index: searches vectors (evidence: `retrieve/query.py`)
- Hybrid ranking → Vector search: combines results (evidence: `retrieve/hybrid.py`)
- Hybrid ranking → BM25 search: combines results (evidence: `retrieve/hybrid.py`)
- STAR evidence pools → Hybrid ranking: gathers evidence (evidence: `retrieve/star_evidence.py`)
- CLI commands → Hybrid ranking: retrieves context (evidence: `main.py`)
- CLI commands → STAR evidence pools: gathers STAR evidence (evidence: `main.py`)
- CLI commands → Critic-refiner loop: runs artifact loop (evidence: `main.py`)
- Gradio interface → Critic-refiner loop: runs artifact loop (evidence: `app.py`)
- Critic-refiner loop → Artifact generator: generates candidates (evidence: `critic/loop.py`)
- Artifact generator → Output schemas: validates output (evidence: `generate/schema.py`)
- Critic-refiner loop → Independent Critic: checks claims (evidence: `critic/loop.py`)
- Critic-refiner loop → Quantity guard: checks quantities (evidence: `critic/loop.py`)
- Critic-refiner loop → Run trace: records verdicts (evidence: `critic/loop.py`)
- CLI commands → Artifact renderer: renders artifact (evidence: `main.py`)
- Critic-refiner loop → Artifact renderer: returns kept items
- Artifact generator → Groq model service: requests generation (evidence: `README.md`)
- Independent Critic → Groq model service: requests verdict (evidence: `README.md`)
- CLI commands → Evaluation harness: runs evaluation (evidence: `main.py`)
- Evaluation harness → Critic-refiner loop: measures grounding (evidence: `eval/run_eval.py`)
- Evaluation harness → Vector search: measures recall (evidence: `eval/run_eval.py`)
- CLI commands → Strike analysis: reports strikes (evidence: `main.py`)
- Evaluation harness → Strike analysis: analyzes strikes
