# fengzhenfei/carrel architecture

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

- Interactive diagram: https://gitdiagram.com/fengzhenfei/carrel
- Repository: https://github.com/fengzhenfei/carrel

## Overview

Carrel is a self-hosted agent knowledge base. Document folders are scanned and scheduled for parsing and chunking; outputs feed vector and keyword indexes and, optionally, a source-aware knowledge graph. Agents query the search API, which combines retrieval channels and returns evidence rather than generated answers. The web console manages knowledge bases, configuration, files, graphs, and tasks. The README documents the overall flow; sampled code supports selected parser, indexing, and search details, so uncertain internal dispatch links are omitted.

Main entry points: [`app/kb_pipeline/pipeline/parse_job.py`](https://github.com/fengzhenfei/carrel/blob/main/app/kb_pipeline/pipeline/parse_job.py) (Parse jobs), [`app/kb_pipeline/discovery.py`](https://github.com/fengzhenfei/carrel/blob/main/app/kb_pipeline/discovery.py) (File discovery), [`app/kb_pipeline/pipeline/worker.py`](https://github.com/fengzhenfei/carrel/blob/main/app/kb_pipeline/pipeline/worker.py) (Job worker), [`app/kb_search/service.py`](https://github.com/fengzhenfei/carrel/blob/main/app/kb_search/service.py) (Retrieval orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Ingestion"]
  node_scheduler["Task scheduler<br/>[scheduler.py]"]
  node_discovery["File discovery<br/>[discovery.py]"]
  node_worker["Job worker<br/>[worker.py]"]
  node_parse["Parse jobs<br/>[parse_job.py]"]
  node_parser["Format parsers<br/>[router.py]"]
  node_chunker["Chunking<br/>[chunker.py]"]
end

subgraph group_knowledge["Knowledge indexes"]
  node_embed["Embedding client<br/>[client.py]"]
  node_qdrant[("Vector index<br/>[qdrant.py]")]
  node_fts[("Keyword index<br/>[search_fts.py]")]
  node_graph_build["Graph construction<br/>[build.py]"]
  node_graph_llm["Graph model client<br/>[llm.py]"]
  node_neo4j[("Knowledge graph<br/>[neo4j_import.py]")]
  node_state[("Pipeline state<br/>[db.py]")]
end

subgraph group_retrieve["Retrieval"]
  node_search_api["Search API<br/>[api.py]"]
  node_search_service["Retrieval orchestration<br/>[service.py]"]
  node_channels["Search channels<br/>[channels.py]"]
  node_fusion["Fusion and reranking<br/>[fusion.py]"]
  node_evidence["Evidence assembly<br/>[evidence.py]"]
end

subgraph group_manage["User interfaces"]
  node_console["Web console API<br/>[api.py]"]
  node_console_service["Console service<br/>[service.py]"]
  node_browser["Console UI<br/>[app.js]"]
end

node_folders(("Document folders"))
node_mineru["MinerU service"]
node_embedding_service["Embedding endpoint"]
node_agent(("AI agent"))
node_console_user(("Console user"))

node_folders -->|"scans files"| node_discovery
node_scheduler -->|"schedules scans"| node_discovery
node_discovery -->|"tracks files"| node_state
node_discovery -->|"queues jobs"| node_worker
node_worker -->|"runs parse"| node_parse
node_parse -->|"routes files"| node_parser
node_parser -.->|"parses remotely"| node_mineru
node_parse -->|"chunks content"| node_chunker
node_chunker -->|"embeds chunks"| node_embed
node_embed -->|"requests vectors"| node_embedding_service
node_parse -->|"writes vectors"| node_qdrant
node_worker -->|"syncs keywords"| node_fts
node_fts -->|"reads active points"| node_qdrant
node_parse -.->|"builds graph"| node_graph_build
node_graph_build -->|"extracts facts"| node_graph_llm
node_graph_build -->|"writes graph"| node_neo4j
node_worker -->|"updates jobs"| node_state
node_agent -->|"submits queries"| node_search_api
node_search_api -->|"dispatches search"| node_search_service
node_search_service -->|"runs channels"| node_channels
node_channels -->|"searches vectors"| node_qdrant
node_channels -->|"searches keywords"| node_fts
node_channels -.->|"follows relations"| node_neo4j
node_search_service -->|"fuses candidates"| node_fusion
node_search_service -->|"assembles evidence"| node_evidence
node_evidence -->|"returns evidence"| node_search_api
node_console_user -->|"manages knowledge"| node_browser
node_browser -->|"calls API"| node_console
node_console -->|"delegates operations"| node_console_service
node_console_service -->|"reads and writes"| node_state
node_console_service -->|"configures bases"| node_discovery

click node_scheduler "https://github.com/fengzhenfei/carrel/blob/main/app/kb_pipeline/pipeline/scheduler.py"
click node_discovery "https://github.com/fengzhenfei/carrel/blob/main/app/kb_pipeline/discovery.py"
click node_worker "https://github.com/fengzhenfei/carrel/blob/main/app/kb_pipeline/pipeline/worker.py"
click node_parse "https://github.com/fengzhenfei/carrel/blob/main/app/kb_pipeline/pipeline/parse_job.py"
click node_parser "https://github.com/fengzhenfei/carrel/blob/main/app/kb_pipeline/parsers/router.py"
click node_chunker "https://github.com/fengzhenfei/carrel/blob/main/app/kb_pipeline/chunking/chunker.py"
click node_embed "https://github.com/fengzhenfei/carrel/blob/main/app/kb_pipeline/embedding/client.py"
click node_qdrant "https://github.com/fengzhenfei/carrel/blob/main/app/kb_pipeline/vector/qdrant.py"
click node_fts "https://github.com/fengzhenfei/carrel/blob/main/app/kb_pipeline/search_fts.py"
click node_graph_build "https://github.com/fengzhenfei/carrel/blob/main/app/kb_pipeline/graph/build.py"
click node_graph_llm "https://github.com/fengzhenfei/carrel/blob/main/app/kb_pipeline/graph/llm.py"
click node_neo4j "https://github.com/fengzhenfei/carrel/blob/main/app/kb_pipeline/graph/neo4j_import.py"
click node_state "https://github.com/fengzhenfei/carrel/blob/main/app/kb_pipeline/db.py"
click node_search_api "https://github.com/fengzhenfei/carrel/blob/main/app/kb_search/api.py"
click node_search_service "https://github.com/fengzhenfei/carrel/blob/main/app/kb_search/service.py"
click node_channels "https://github.com/fengzhenfei/carrel/blob/main/app/kb_search/channels.py"
click node_fusion "https://github.com/fengzhenfei/carrel/blob/main/app/kb_search/fusion.py"
click node_evidence "https://github.com/fengzhenfei/carrel/blob/main/app/kb_search/evidence.py"
click node_console "https://github.com/fengzhenfei/carrel/blob/main/app/kb_server/api.py"
click node_console_service "https://github.com/fengzhenfei/carrel/blob/main/app/kb_server/service.py"
click node_browser "https://github.com/fengzhenfei/carrel/blob/main/app/kb_server/static/app.js"

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_scheduler,node_discovery,node_worker,node_parse,node_parser,node_chunker,node_console_user toneBlue
class node_embed,node_qdrant,node_fts,node_graph_build,node_graph_llm,node_neo4j,node_state toneAmber
class node_search_api,node_search_service,node_channels,node_fusion,node_evidence toneMint
class node_console,node_console_service,node_browser toneRose
class node_folders,node_mineru,node_embedding_service,node_agent toneIndigo
```

## Components

### Ingestion

- [Task scheduler](https://github.com/fengzhenfei/carrel/blob/main/app/kb_pipeline/pipeline/scheduler.py): `app/kb_pipeline/pipeline/scheduler.py`
- [File discovery](https://github.com/fengzhenfei/carrel/blob/main/app/kb_pipeline/discovery.py): `app/kb_pipeline/discovery.py`
- [Job worker](https://github.com/fengzhenfei/carrel/blob/main/app/kb_pipeline/pipeline/worker.py): `app/kb_pipeline/pipeline/worker.py`
- [Parse jobs](https://github.com/fengzhenfei/carrel/blob/main/app/kb_pipeline/pipeline/parse_job.py): `app/kb_pipeline/pipeline/parse_job.py`
- [Format parsers](https://github.com/fengzhenfei/carrel/blob/main/app/kb_pipeline/parsers/router.py): `app/kb_pipeline/parsers/router.py`
- [Chunking](https://github.com/fengzhenfei/carrel/blob/main/app/kb_pipeline/chunking/chunker.py): `app/kb_pipeline/chunking/chunker.py`

### Knowledge indexes

- [Embedding client](https://github.com/fengzhenfei/carrel/blob/main/app/kb_pipeline/embedding/client.py): `app/kb_pipeline/embedding/client.py`
- [Vector index](https://github.com/fengzhenfei/carrel/blob/main/app/kb_pipeline/vector/qdrant.py): `app/kb_pipeline/vector/qdrant.py`
- [Keyword index](https://github.com/fengzhenfei/carrel/blob/main/app/kb_pipeline/search_fts.py): `app/kb_pipeline/search_fts.py`
- [Graph construction](https://github.com/fengzhenfei/carrel/blob/main/app/kb_pipeline/graph/build.py): `app/kb_pipeline/graph/build.py`
- [Graph model client](https://github.com/fengzhenfei/carrel/blob/main/app/kb_pipeline/graph/llm.py): `app/kb_pipeline/graph/llm.py`
- [Knowledge graph](https://github.com/fengzhenfei/carrel/blob/main/app/kb_pipeline/graph/neo4j_import.py): `app/kb_pipeline/graph/neo4j_import.py`
- [Pipeline state](https://github.com/fengzhenfei/carrel/blob/main/app/kb_pipeline/db.py): `app/kb_pipeline/db.py`

### Retrieval

- [Search API](https://github.com/fengzhenfei/carrel/blob/main/app/kb_search/api.py): `app/kb_search/api.py`
- [Retrieval orchestration](https://github.com/fengzhenfei/carrel/blob/main/app/kb_search/service.py): `app/kb_search/service.py`
- [Search channels](https://github.com/fengzhenfei/carrel/blob/main/app/kb_search/channels.py): `app/kb_search/channels.py`
- [Fusion and reranking](https://github.com/fengzhenfei/carrel/blob/main/app/kb_search/fusion.py): `app/kb_search/fusion.py`
- [Evidence assembly](https://github.com/fengzhenfei/carrel/blob/main/app/kb_search/evidence.py): `app/kb_search/evidence.py`

### User interfaces

- [Web console API](https://github.com/fengzhenfei/carrel/blob/main/app/kb_server/api.py): `app/kb_server/api.py`
- [Console service](https://github.com/fengzhenfei/carrel/blob/main/app/kb_server/service.py): `app/kb_server/service.py`
- [Console UI](https://github.com/fengzhenfei/carrel/blob/main/app/kb_server/static/app.js): `app/kb_server/static/app.js`

### Other components

- **Document folders**
- **MinerU service**
- **Embedding endpoint**
- **AI agent**
- **Console user**

## Connections

- Document folders → File discovery: scans files
- Task scheduler → File discovery: schedules scans
- File discovery → Pipeline state: tracks files
- File discovery → Job worker: queues jobs
- Job worker → Parse jobs: runs parse
- Parse jobs → Format parsers: routes files
- Format parsers → MinerU service: parses remotely
- Parse jobs → Chunking: chunks content
- Chunking → Embedding client: embeds chunks
- Embedding client → Embedding endpoint: requests vectors
- Parse jobs → Vector index: writes vectors
- Job worker → Keyword index: syncs keywords
- Keyword index → Vector index: reads active points
- Parse jobs → Graph construction: builds graph
- Graph construction → Graph model client: extracts facts
- Graph construction → Knowledge graph: writes graph
- Job worker → Pipeline state: updates jobs
- AI agent → Search API: submits queries
- Search API → Retrieval orchestration: dispatches search
- Retrieval orchestration → Search channels: runs channels
- Search channels → Vector index: searches vectors
- Search channels → Keyword index: searches keywords
- Search channels → Knowledge graph: follows relations
- Retrieval orchestration → Fusion and reranking: fuses candidates
- Retrieval orchestration → Evidence assembly: assembles evidence
- Evidence assembly → Search API: returns evidence
- Console user → Console UI: manages knowledge
- Console UI → Web console API: calls API
- Web console API → Console service: delegates operations
- Console service → Pipeline state: reads and writes
- Console service → File discovery: configures bases