# aricommits/corpusrag architecture

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

- Interactive diagram: https://gitdiagram.com/aricommits/corpusrag
- Repository: https://github.com/aricommits/corpusrag

## Overview

CorpusRAG is a document knowledge base: users ingest files or text into named collections, then retrieve grounded answers and generate study materials. The map covers RAG ingestion and retrieval, model/database services, MCP and web interfaces, plus video and handwriting ingestion and lecture orchestration. The README documents summaries, flashcards, and quizzes; their implementation paths are represented, but internal calls are not inferred where source was not shown. Edges are limited to relationships explicit in excerpts, the source index, or README.

Main entry points: [`src/kernel.py`](https://github.com/aricommits/corpusrag/blob/main/src/kernel.py) (Corpus facade), [`src/tools/rag/ingest.py`](https://github.com/aricommits/corpusrag/blob/main/src/tools/rag/ingest.py) (RAG ingestion), [`src/orchestrations/lecture_pipeline.py`](https://github.com/aricommits/corpusrag/blob/main/src/orchestrations/lecture_pipeline.py) (Lecture orchestrator), [`src/tools/rag/retriever.py`](https://github.com/aricommits/corpusrag/blob/main/src/tools/rag/retriever.py) (Retriever)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["User interfaces"]
  node_cli["CLI<br/>[cli.py]"]
  node_web["Web UI<br/>[app.py]"]
  node_mcp["MCP server<br/>[server.py]"]
  node_mcp_profiles["Tool profiles<br/>[profiles.py]"]
  node_mcp_video["Video tools<br/>[video.py]"]
end

subgraph group_rag["Knowledge base"]
  node_kernel["Corpus facade<br/>[kernel.py]"]
  node_rag_ingest["RAG ingestion<br/>[ingest.py]"]
  node_rag_split["Adaptive chunking"]
  node_rag_retrieval["Retrieval strategies"]
  node_rag_retriever["Retriever<br/>[retriever.py]"]
  node_rag_agent["RAG agent<br/>[agent.py]"]
end

subgraph group_services["Core services"]
  node_config["Configuration<br/>[base.py]"]
  node_db["Database backend<br/>[base.py]"]
  node_chroma[("ChromaDB<br/>[chroma.py]")]
  node_llm["LLM backend<br/>[backend.py]"]
end

subgraph group_media["Media ingestion"]
  node_video_ingest["Visual OCR ingest<br/>[ingest.py]"]
  node_audio_video["Audio transcription"]
  node_handwriting["Handwriting OCR"]
end

subgraph group_study["Study workflows"]
  node_lecture["Lecture orchestrator"]
  node_summaries["Summaries<br/>[generator.py]"]
  node_flashcards["Flashcards<br/>[generator.py]"]
  node_quizzes["Quizzes<br/>[generator.py]"]
end

node_user(("User"))
node_editors(("MCP clients"))

node_user -->|"uses"| node_cli
node_user -->|"uses"| node_web
node_editors -->|"connects"| node_mcp
node_cli -->|"dispatches"| node_kernel
node_web -->|"calls"| node_kernel
node_mcp -->|"loads profiles"| node_mcp_profiles
node_mcp_profiles -->|"registers tools"| node_mcp_video
node_mcp_video -->|"runs OCR"| node_video_ingest
node_kernel -->|"ingests paths"| node_rag_ingest
node_kernel -->|"asks questions"| node_rag_agent
node_kernel -->|"generates summaries"| node_summaries
node_rag_ingest -->|"chunks documents"| node_rag_split
node_rag_ingest -->|"stores documents"| node_db
node_rag_agent -->|"retrieves context"| node_rag_retriever
node_rag_retriever -->|"selects strategy"| node_rag_retrieval
node_rag_retriever -->|"searches"| node_db
node_rag_agent -->|"generates answer"| node_llm
node_chroma -->|"implements"| node_db
node_rag_ingest -->|"uses settings"| node_config
node_video_ingest -.->|"distinct audio path"| node_audio_video
node_handwriting -.->|"ingests into RAG"| node_rag_ingest
node_lecture -->|"generates"| node_summaries
node_lecture -->|"generates"| node_flashcards
node_lecture -->|"generates"| node_quizzes
node_lecture -->|"transcribes video"| node_audio_video

click node_cli "https://github.com/aricommits/corpusrag/blob/main/src/cli.py"
click node_web "https://github.com/aricommits/corpusrag/blob/main/src/web_ui/app.py"
click node_mcp "https://github.com/aricommits/corpusrag/blob/main/src/mcp_server/server.py"
click node_mcp_profiles "https://github.com/aricommits/corpusrag/blob/main/src/mcp_server/profiles.py"
click node_mcp_video "https://github.com/aricommits/corpusrag/blob/main/src/mcp_server/tools/video.py"
click node_kernel "https://github.com/aricommits/corpusrag/blob/main/src/kernel.py"
click node_rag_ingest "https://github.com/aricommits/corpusrag/blob/main/src/tools/rag/ingest.py"
click node_rag_split "https://github.com/aricommits/corpusrag/blob/main/src/tools/rag/pipeline/adaptive_splitter.py"
click node_rag_retrieval "https://github.com/aricommits/corpusrag/tree/main/src/tools/rag/strategies"
click node_rag_retriever "https://github.com/aricommits/corpusrag/blob/main/src/tools/rag/retriever.py"
click node_rag_agent "https://github.com/aricommits/corpusrag/blob/main/src/tools/rag/agent.py"
click node_config "https://github.com/aricommits/corpusrag/blob/main/src/config/base.py"
click node_db "https://github.com/aricommits/corpusrag/blob/main/src/db/base.py"
click node_chroma "https://github.com/aricommits/corpusrag/blob/main/src/db/chroma.py"
click node_llm "https://github.com/aricommits/corpusrag/blob/main/src/llm/backend.py"
click node_video_ingest "https://github.com/aricommits/corpusrag/blob/main/src/tools/video/ingest.py"
click node_audio_video "https://github.com/aricommits/corpusrag/tree/main/src/tools/video"
click node_handwriting "https://github.com/aricommits/corpusrag/blob/main/src/tools/handwriting/ingest_handwriting.py"
click node_lecture "https://github.com/aricommits/corpusrag/blob/main/src/orchestrations/lecture_pipeline.py"
click node_summaries "https://github.com/aricommits/corpusrag/blob/main/src/tools/summaries/generator.py"
click node_flashcards "https://github.com/aricommits/corpusrag/blob/main/src/tools/flashcards/generator.py"
click node_quizzes "https://github.com/aricommits/corpusrag/blob/main/src/tools/quizzes/generator.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_cli,node_web,node_mcp,node_mcp_profiles,node_mcp_video,node_user,node_editors toneBlue
class node_kernel,node_rag_ingest,node_rag_split,node_rag_retrieval,node_rag_retriever,node_rag_agent toneAmber
class node_config,node_db,node_chroma,node_llm toneMint
class node_video_ingest,node_audio_video,node_handwriting toneRose
class node_lecture,node_summaries,node_flashcards,node_quizzes toneIndigo
```

## Components

### User interfaces

- [CLI](https://github.com/aricommits/corpusrag/blob/main/src/cli.py): `src/cli.py`
- [Web UI](https://github.com/aricommits/corpusrag/blob/main/src/web_ui/app.py): `src/web_ui/app.py`
- [MCP server](https://github.com/aricommits/corpusrag/blob/main/src/mcp_server/server.py): `src/mcp_server/server.py`
- [Tool profiles](https://github.com/aricommits/corpusrag/blob/main/src/mcp_server/profiles.py): `src/mcp_server/profiles.py`
- [Video tools](https://github.com/aricommits/corpusrag/blob/main/src/mcp_server/tools/video.py): `src/mcp_server/tools/video.py`

### Knowledge base

- [Corpus facade](https://github.com/aricommits/corpusrag/blob/main/src/kernel.py): `src/kernel.py`
- [RAG ingestion](https://github.com/aricommits/corpusrag/blob/main/src/tools/rag/ingest.py): `src/tools/rag/ingest.py`
- [Adaptive chunking](https://github.com/aricommits/corpusrag/blob/main/src/tools/rag/pipeline/adaptive_splitter.py): `src/tools/rag/pipeline/adaptive_splitter.py`
- [Retrieval strategies](https://github.com/aricommits/corpusrag/tree/main/src/tools/rag/strategies): `src/tools/rag/strategies`
- [Retriever](https://github.com/aricommits/corpusrag/blob/main/src/tools/rag/retriever.py): `src/tools/rag/retriever.py`
- [RAG agent](https://github.com/aricommits/corpusrag/blob/main/src/tools/rag/agent.py): `src/tools/rag/agent.py`

### Core services

- [Configuration](https://github.com/aricommits/corpusrag/blob/main/src/config/base.py): `src/config/base.py`
- [Database backend](https://github.com/aricommits/corpusrag/blob/main/src/db/base.py): `src/db/base.py`
- [ChromaDB](https://github.com/aricommits/corpusrag/blob/main/src/db/chroma.py): `src/db/chroma.py`
- [LLM backend](https://github.com/aricommits/corpusrag/blob/main/src/llm/backend.py): `src/llm/backend.py`

### Media ingestion

- [Visual OCR ingest](https://github.com/aricommits/corpusrag/blob/main/src/tools/video/ingest.py): `src/tools/video/ingest.py`
- [Audio transcription](https://github.com/aricommits/corpusrag/tree/main/src/tools/video): `src/tools/video`
- [Handwriting OCR](https://github.com/aricommits/corpusrag/blob/main/src/tools/handwriting/ingest_handwriting.py): `src/tools/handwriting/ingest_handwriting.py`

### Study workflows

- [Lecture orchestrator](https://github.com/aricommits/corpusrag/blob/main/src/orchestrations/lecture_pipeline.py): `src/orchestrations/lecture_pipeline.py`
- [Summaries](https://github.com/aricommits/corpusrag/blob/main/src/tools/summaries/generator.py): `src/tools/summaries/generator.py`
- [Flashcards](https://github.com/aricommits/corpusrag/blob/main/src/tools/flashcards/generator.py): `src/tools/flashcards/generator.py`
- [Quizzes](https://github.com/aricommits/corpusrag/blob/main/src/tools/quizzes/generator.py): `src/tools/quizzes/generator.py`

### Other components

- **User**
- **MCP clients**

## Connections

- User → CLI: uses (evidence: `README.md`)
- User → Web UI: uses (evidence: `README.md`)
- MCP clients → MCP server: connects (evidence: `README.md`)
- CLI → Corpus facade: dispatches (evidence: `src/cli.py`)
- Web UI → Corpus facade: calls (evidence: `src/web_ui/app.py`)
- MCP server → Tool profiles: loads profiles (evidence: `src/mcp_server/server.py`)
- Tool profiles → Video tools: registers tools (evidence: `src/mcp_server/profiles.py`)
- Video tools → Visual OCR ingest: runs OCR (evidence: `src/mcp_server/tools/video.py`)
- Corpus facade → RAG ingestion: ingests paths (evidence: `src/kernel.py`)
- Corpus facade → RAG agent: asks questions (evidence: `src/kernel.py`)
- Corpus facade → Summaries: generates summaries (evidence: `src/kernel.py`)
- RAG ingestion → Adaptive chunking: chunks documents (evidence: `src/tools/rag/ingest.py`)
- RAG ingestion → Database backend: stores documents (evidence: `src/tools/rag/ingest.py`)
- RAG agent → Retriever: retrieves context (evidence: `src/tools/rag/agent.py`)
- Retriever → Retrieval strategies: selects strategy (evidence: `src/tools/rag/retriever.py`)
- Retriever → Database backend: searches (evidence: `src/tools/rag/retriever.py`)
- RAG agent → LLM backend: generates answer (evidence: `src/tools/rag/agent.py`)
- ChromaDB → Database backend: implements (evidence: `src/db/chroma.py`)
- RAG ingestion → Configuration: uses settings (evidence: `src/tools/rag/ingest.py`)
- Visual OCR ingest → Audio transcription: distinct audio path (evidence: `README.md`)
- Handwriting OCR → RAG ingestion: ingests into RAG (evidence: `README.md`)
- Lecture orchestrator → Summaries: generates (evidence: `README.md`)
- Lecture orchestrator → Flashcards: generates (evidence: `README.md`)
- Lecture orchestrator → Quizzes: generates (evidence: `README.md`)
- Lecture orchestrator → Audio transcription: transcribes video (evidence: `src/orchestrations/lecture_pipeline.py`)
