# lyonzin/knowledge-rag architecture

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

- Interactive diagram: https://gitdiagram.com/lyonzin/knowledge-rag
- Repository: https://github.com/lyonzin/knowledge-rag

## Overview

knowledge-rag is a local MCP server that indexes documents and code, then returns ranked, source-attributed results to an MCP client. The main workflow is client request → server dispatch → document ingestion (parse, chunk, embed, index) and hybrid retrieval (lexical and vector candidates, fusion, reranking) → results. The README documents these stages and optional FTS5 routing; sampled source confirms key parsing, routing, scope, storage, and security responsibilities. Some retrieval details are documented but not visible in the excerpts, so those links are marked as documented rather than inferred from unsampled code.

Main entry points: [`mcp_server/server.py`](https://github.com/lyonzin/knowledge-rag/blob/master/mcp_server/server.py) (MCP server), [`mcp_server/ingestion.py`](https://github.com/lyonzin/knowledge-rag/blob/master/mcp_server/ingestion.py) (Document parsing), [`mcp_server/skills_cli.py`](https://github.com/lyonzin/knowledge-rag/blob/master/mcp_server/skills_cli.py) (Skills CLI), [`mcp_server/filesystem.py`](https://github.com/lyonzin/knowledge-rag/blob/master/mcp_server/filesystem.py) (Document filesystem)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["MCP runtime"]
  node_server["MCP server<br/>[server.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_health["Health checks<br/>[health.py]"]
  node_metrics["Metrics<br/>[metrics.py]"]
end

subgraph group_ingestion["Ingestion and indexing"]
  node_parser["Document parsing<br/>[ingestion.py]"]
  node_pdf["PDF extraction<br/>[pdf_support.py]"]
  node_filesystem["Document filesystem<br/>[filesystem.py]"]
  node_vector[("Vector indexing<br/>[server.py]")]
end

subgraph group_retrieval["Retrieval"]
  node_bm25[("BM25 retrieval<br/>[server.py]")]
  node_fts5[("FTS5 index<br/>[fts5_index.py]")]
  node_router["Query router<br/>[query_router.py]"]
  node_scope["Search scope<br/>[search_scope.py]"]
  node_candidates["Candidate selection"]
  node_reranker["Cross-encoder reranker<br/>[server.py]"]
end

subgraph group_operations["Operations and safety"]
  node_security["Path and content safety<br/>[security.py]"]
  node_transactions["File transactions"]
  node_preflight["Startup preflight<br/>[preflight.py]"]
  node_locking["Instance lock<br/>[instance_lock.py]"]
  node_logging["Logging setup<br/>[logging_config.py]"]
end

subgraph group_skills["Assistant skills"]
  node_assistants["Assistant detection<br/>[assistants.py]"]
  node_skillscli["Skills CLI<br/>[skills_cli.py]"]
  node_skillsbundle["Skills bundle<br/>[skills_bundle.py]"]
end

node_client(("MCP client"))

node_client -->|"sends requests"| node_server
node_server -->|"returns results"| node_client
node_server -->|"loads settings"| node_config
node_server -->|"indexes documents"| node_parser
node_server -->|"stores embeddings"| node_vector
node_server -->|"runs keyword search"| node_bm25
node_server -->|"classifies queries"| node_router
node_server -.->|"dispatches lexical search"| node_fts5
node_server -->|"filters sources"| node_scope
node_server -.->|"selects candidates"| node_candidates
node_server -->|"reranks candidates"| node_reranker
node_server -->|"serves health"| node_health
node_server -->|"records metrics"| node_metrics
node_server -->|"watches documents"| node_filesystem
node_server -->|"validates paths"| node_security
node_server -->|"stages file changes"| node_transactions
node_server -->|"runs preflight"| node_preflight
node_server -->|"acquires lock"| node_locking
node_server -.->|"configures logging"| node_logging
node_parser -->|"extracts PDF text"| node_pdf
node_parser -->|"walks document paths"| node_filesystem
node_parser -->|"checks input paths"| node_security
node_scope -->|"normalizes paths"| node_filesystem
node_router -.->|"selects lexical path"| node_fts5
node_server -->|"invokes skills CLI"| node_assistants
node_skillscli -->|"detects targets"| node_assistants
node_skillscli -->|"loads bundled skills"| node_skillsbundle
node_skillscli -.->|"updates skill files"| node_transactions

click node_server "https://github.com/lyonzin/knowledge-rag/blob/master/mcp_server/server.py"
click node_config "https://github.com/lyonzin/knowledge-rag/blob/master/mcp_server/config.py"
click node_health "https://github.com/lyonzin/knowledge-rag/blob/master/mcp_server/health.py"
click node_metrics "https://github.com/lyonzin/knowledge-rag/blob/master/mcp_server/metrics.py"
click node_parser "https://github.com/lyonzin/knowledge-rag/blob/master/mcp_server/ingestion.py"
click node_pdf "https://github.com/lyonzin/knowledge-rag/blob/master/mcp_server/pdf_support.py"
click node_filesystem "https://github.com/lyonzin/knowledge-rag/blob/master/mcp_server/filesystem.py"
click node_security "https://github.com/lyonzin/knowledge-rag/blob/master/mcp_server/security.py"
click node_vector "https://github.com/lyonzin/knowledge-rag/blob/master/mcp_server/server.py"
click node_bm25 "https://github.com/lyonzin/knowledge-rag/blob/master/mcp_server/server.py"
click node_fts5 "https://github.com/lyonzin/knowledge-rag/blob/master/mcp_server/fts5_index.py"
click node_router "https://github.com/lyonzin/knowledge-rag/blob/master/mcp_server/query_router.py"
click node_scope "https://github.com/lyonzin/knowledge-rag/blob/master/mcp_server/search_scope.py"
click node_candidates "https://github.com/lyonzin/knowledge-rag/blob/master/mcp_server/search_candidates.py"
click node_reranker "https://github.com/lyonzin/knowledge-rag/blob/master/mcp_server/server.py"
click node_transactions "https://github.com/lyonzin/knowledge-rag/blob/master/mcp_server/file_transaction.py"
click node_preflight "https://github.com/lyonzin/knowledge-rag/blob/master/mcp_server/preflight.py"
click node_locking "https://github.com/lyonzin/knowledge-rag/blob/master/mcp_server/instance_lock.py"
click node_logging "https://github.com/lyonzin/knowledge-rag/blob/master/mcp_server/logging_config.py"
click node_assistants "https://github.com/lyonzin/knowledge-rag/blob/master/mcp_server/assistants.py"
click node_skillscli "https://github.com/lyonzin/knowledge-rag/blob/master/mcp_server/skills_cli.py"
click node_skillsbundle "https://github.com/lyonzin/knowledge-rag/blob/master/mcp_server/skills_bundle.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_server,node_config,node_health,node_metrics,node_client toneBlue
class node_parser,node_pdf,node_filesystem,node_vector toneAmber
class node_bm25,node_fts5,node_router,node_scope,node_candidates,node_reranker toneMint
class node_security,node_transactions,node_preflight,node_locking,node_logging toneRose
class node_assistants,node_skillscli,node_skillsbundle toneIndigo
```

## Components

### MCP runtime

- [MCP server](https://github.com/lyonzin/knowledge-rag/blob/master/mcp_server/server.py): `mcp_server/server.py`
- [Configuration](https://github.com/lyonzin/knowledge-rag/blob/master/mcp_server/config.py): `mcp_server/config.py`
- [Health checks](https://github.com/lyonzin/knowledge-rag/blob/master/mcp_server/health.py): `mcp_server/health.py`
- [Metrics](https://github.com/lyonzin/knowledge-rag/blob/master/mcp_server/metrics.py): `mcp_server/metrics.py`

### Ingestion and indexing

- [Document parsing](https://github.com/lyonzin/knowledge-rag/blob/master/mcp_server/ingestion.py): `mcp_server/ingestion.py`
- [PDF extraction](https://github.com/lyonzin/knowledge-rag/blob/master/mcp_server/pdf_support.py): `mcp_server/pdf_support.py`
- [Document filesystem](https://github.com/lyonzin/knowledge-rag/blob/master/mcp_server/filesystem.py): `mcp_server/filesystem.py`
- [Vector indexing](https://github.com/lyonzin/knowledge-rag/blob/master/mcp_server/server.py): `mcp_server/server.py`

### Retrieval

- [BM25 retrieval](https://github.com/lyonzin/knowledge-rag/blob/master/mcp_server/server.py): `mcp_server/server.py`
- [FTS5 index](https://github.com/lyonzin/knowledge-rag/blob/master/mcp_server/fts5_index.py): `mcp_server/fts5_index.py`
- [Query router](https://github.com/lyonzin/knowledge-rag/blob/master/mcp_server/query_router.py): `mcp_server/query_router.py`
- [Search scope](https://github.com/lyonzin/knowledge-rag/blob/master/mcp_server/search_scope.py): `mcp_server/search_scope.py`
- [Candidate selection](https://github.com/lyonzin/knowledge-rag/blob/master/mcp_server/search_candidates.py): `mcp_server/search_candidates.py`
- [Cross-encoder reranker](https://github.com/lyonzin/knowledge-rag/blob/master/mcp_server/server.py): `mcp_server/server.py`

### Operations and safety

- [Path and content safety](https://github.com/lyonzin/knowledge-rag/blob/master/mcp_server/security.py): `mcp_server/security.py`
- [File transactions](https://github.com/lyonzin/knowledge-rag/blob/master/mcp_server/file_transaction.py): `mcp_server/file_transaction.py`
- [Startup preflight](https://github.com/lyonzin/knowledge-rag/blob/master/mcp_server/preflight.py): `mcp_server/preflight.py`
- [Instance lock](https://github.com/lyonzin/knowledge-rag/blob/master/mcp_server/instance_lock.py): `mcp_server/instance_lock.py`
- [Logging setup](https://github.com/lyonzin/knowledge-rag/blob/master/mcp_server/logging_config.py): `mcp_server/logging_config.py`

### Assistant skills

- [Assistant detection](https://github.com/lyonzin/knowledge-rag/blob/master/mcp_server/assistants.py): `mcp_server/assistants.py`
- [Skills CLI](https://github.com/lyonzin/knowledge-rag/blob/master/mcp_server/skills_cli.py): `mcp_server/skills_cli.py`
- [Skills bundle](https://github.com/lyonzin/knowledge-rag/blob/master/mcp_server/skills_bundle.py): `mcp_server/skills_bundle.py`

### Other components

- **MCP client**

## Connections

- MCP client → MCP server: sends requests (evidence: `README.md`)
- MCP server → MCP client: returns results (evidence: `README.md`)
- MCP server → Configuration: loads settings (evidence: `mcp_server/server.py`)
- MCP server → Document parsing: indexes documents (evidence: `mcp_server/server.py`)
- MCP server → Vector indexing: stores embeddings (evidence: `README.md`)
- MCP server → BM25 retrieval: runs keyword search (evidence: `README.md`)
- MCP server → Query router: classifies queries (evidence: `mcp_server/query_router.py`)
- MCP server → FTS5 index: dispatches lexical search (evidence: `mcp_server/server.py`)
- MCP server → Search scope: filters sources (evidence: `mcp_server/server.py`)
- MCP server → Candidate selection: selects candidates (evidence: `mcp_server/server.py`)
- MCP server → Cross-encoder reranker: reranks candidates (evidence: `README.md`)
- MCP server → Health checks: serves health (evidence: `mcp_server/server.py`)
- MCP server → Metrics: records metrics (evidence: `mcp_server/server.py`)
- MCP server → Document filesystem: watches documents (evidence: `mcp_server/server.py`)
- MCP server → Path and content safety: validates paths (evidence: `mcp_server/server.py`)
- MCP server → File transactions: stages file changes (evidence: `mcp_server/server.py`)
- MCP server → Startup preflight: runs preflight (evidence: `mcp_server/server.py`)
- MCP server → Instance lock: acquires lock (evidence: `mcp_server/server.py`)
- MCP server → Logging setup: configures logging (evidence: `mcp_server/server.py`)
- Document parsing → PDF extraction: extracts PDF text (evidence: `mcp_server/ingestion.py`)
- Document parsing → Document filesystem: walks document paths (evidence: `mcp_server/ingestion.py`)
- Document parsing → Path and content safety: checks input paths (evidence: `mcp_server/ingestion.py`)
- Search scope → Document filesystem: normalizes paths (evidence: `mcp_server/search_scope.py`)
- Query router → FTS5 index: selects lexical path
- MCP server → Assistant detection: invokes skills CLI (evidence: `mcp_server/server.py`)
- Skills CLI → Assistant detection: detects targets (evidence: `mcp_server/skills_cli.py`)
- Skills CLI → Skills bundle: loads bundled skills (evidence: `mcp_server/skills_cli.py`)
- Skills CLI → File transactions: updates skill files
