# 522blackcat/knowledgeops-console architecture

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

- Interactive diagram: https://gitdiagram.com/522blackcat/knowledgeops-console
- Repository: https://github.com/522blackcat/knowledgeops-console

## Overview

KnowledgeOps Console is a web console and backend for configuring Agents, managing knowledge bases, running conversations, approving risky actions, and evaluating retrieval. A user works through the Vue console and FastAPI routes; Agent and RAG workers perform long-running tasks separately. PostgreSQL holds durable business state, Redis coordinates notifications and queues, and Qdrant stores vectors. The graph preserves the documented evaluation and administration branches. Some route and worker internals were not excerpted, so connections without direct evidence are omitted.

Main entry points: [`app/main.py`](https://github.com/522blackcat/knowledgeops-console/blob/main/app/main.py) (FastAPI app), [`agent/worker.py`](https://github.com/522blackcat/knowledgeops-console/blob/main/agent/worker.py) (Agent worker), [`rag/retrieval.py`](https://github.com/522blackcat/knowledgeops-console/blob/main/rag/retrieval.py) (Hybrid retrieval), [`rag/worker.py`](https://github.com/522blackcat/knowledgeops-console/blob/main/rag/worker.py) (Ingest worker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_console["Console and API"]
  node_frontend["Vue console<br/>[App.vue]"]
  node_api["FastAPI app<br/>[main.py]"]
  node_auth["Authentication<br/>[auth_api.py]"]
  node_admin["Admin APIs<br/>[admin_api.py]"]
  node_agentapi["Agent APIs<br/>[agent_api.py]"]
  node_runapi["Run APIs<br/>[run_api.py]"]
  node_approvalapi["Approval APIs<br/>[approval_api.py]"]
  node_sse["Run event stream<br/>[sse_api.py]"]
end

subgraph group_agent["Agent runtime"]
  node_agentworker["Agent worker<br/>[worker.py]"]
  node_agentgraph["Agent graph<br/>[graph.py]"]
  node_completion["Run completion<br/>[completion.py]"]
  node_approval["Approval logic<br/>[approval.py]"]
end

subgraph group_knowledge["Knowledge and RAG"]
  node_knowledgeapi["Knowledge APIs<br/>[knowledge_api.py]"]
  node_evalapi["RAG eval API<br/>[rag_eval_api.py]"]
  node_evalrunner["Eval runner<br/>[rag_eval_runner.py]"]
  node_ragworker["Ingest worker<br/>[worker.py]"]
  node_parser["Document parser<br/>[parser.py]"]
  node_storage["Upload storage<br/>[storage.py]"]
  node_chunking["Chunking<br/>[chunking.py]"]
  node_retrieval["Hybrid retrieval<br/>[retrieval.py]"]
  node_bm25["BM25 search<br/>[bm25.py]"]
  node_vectorstore[("Qdrant vector store<br/>[vector_store.py]")]
  node_embedding["Embeddings<br/>[embedding.py]"]
  node_reranker["Reranker<br/>[reranker.py]"]
end

subgraph group_state["State and memory"]
  node_database[("PostgreSQL<br/>[database.py]")]
  node_models["Domain records<br/>[models.py]"]
  node_redis["Redis coordination<br/>[redis_client.py]"]
  node_memory["Conversation memory<br/>[context.py]"]
  node_summary["Incremental summaries<br/>[summary.py]"]
end

subgraph group_integrations["Tools and models"]
  node_tools["Tool execution<br/>[execution.py]"]
  node_registry["Tool registry<br/>[registry.py]"]
  node_builtin["Built-in tools<br/>[builtin.py]"]
  node_mcp["MCP tools<br/>[mcp_registry.py]"]
end

node_user(("Console user"))

node_user -->|"uses"| node_frontend
node_frontend -.->|"accesses"| node_api
node_api -->|"registers"| node_auth
node_api -->|"registers"| node_admin
node_api -->|"registers"| node_agentapi
node_api -->|"registers"| node_runapi
node_api -->|"registers"| node_approvalapi
node_api -->|"registers"| node_sse
node_api -->|"registers"| node_knowledgeapi
node_api -->|"registers"| node_evalapi
node_agentworker -->|"invokes"| node_agentgraph
node_agentworker -->|"uses"| node_completion
node_agentworker -->|"uses"| node_approval
node_agentworker -->|"builds context"| node_memory
node_agentworker -->|"retrieves evidence"| node_retrieval
node_agentgraph -->|"executes tools"| node_tools
node_agentgraph -->|"loads tools"| node_registry
node_agentworker -->|"checks cancellation"| node_redis
node_agentworker -->|"claims tasks"| node_database
node_ragworker -->|"parses documents"| node_parser
node_ragworker -->|"prepares chunks"| node_chunking
node_ragworker -->|"uses upload storage"| node_storage
node_ragworker -->|"indexes vectors"| node_vectorstore
node_evalapi -->|"runs hybrid search"| node_retrieval
node_evalapi -->|"runs lexical search"| node_bm25
node_retrieval -->|"searches chunks"| node_bm25
node_retrieval -->|"embeds query"| node_embedding
node_retrieval -->|"searches vectors"| node_vectorstore
node_retrieval -->|"reranks hits"| node_reranker
node_memory -->|"loads summaries"| node_summary
node_memory -->|"reads memory"| node_database
node_summary -->|"stores versions"| node_database
node_summary -->|"uses records"| node_models
node_tools -->|"validates tools"| node_registry
node_builtin -->|"searches knowledge"| node_retrieval
node_agentgraph -->|"loads MCP tools"| node_mcp
node_evalrunner -.->|"evaluates retrieval"| node_retrieval
node_database -->|"maps records"| node_models
node_agentworker -.->|"coordinates work"| node_redis

click node_frontend "https://github.com/522blackcat/knowledgeops-console/blob/main/frontend/src/App.vue"
click node_api "https://github.com/522blackcat/knowledgeops-console/blob/main/app/main.py"
click node_auth "https://github.com/522blackcat/knowledgeops-console/blob/main/app/auth_api.py"
click node_admin "https://github.com/522blackcat/knowledgeops-console/blob/main/app/admin_api.py"
click node_agentapi "https://github.com/522blackcat/knowledgeops-console/blob/main/app/agent_api.py"
click node_runapi "https://github.com/522blackcat/knowledgeops-console/blob/main/app/run_api.py"
click node_approvalapi "https://github.com/522blackcat/knowledgeops-console/blob/main/app/approval_api.py"
click node_sse "https://github.com/522blackcat/knowledgeops-console/blob/main/app/sse_api.py"
click node_knowledgeapi "https://github.com/522blackcat/knowledgeops-console/blob/main/app/knowledge_api.py"
click node_evalapi "https://github.com/522blackcat/knowledgeops-console/blob/main/app/rag_eval_api.py"
click node_evalrunner "https://github.com/522blackcat/knowledgeops-console/blob/main/evaluation/rag_eval_runner.py"
click node_agentworker "https://github.com/522blackcat/knowledgeops-console/blob/main/agent/worker.py"
click node_agentgraph "https://github.com/522blackcat/knowledgeops-console/blob/main/agent/graph.py"
click node_completion "https://github.com/522blackcat/knowledgeops-console/blob/main/agent/completion.py"
click node_approval "https://github.com/522blackcat/knowledgeops-console/blob/main/agent/approval.py"
click node_ragworker "https://github.com/522blackcat/knowledgeops-console/blob/main/rag/worker.py"
click node_parser "https://github.com/522blackcat/knowledgeops-console/blob/main/rag/parser.py"
click node_storage "https://github.com/522blackcat/knowledgeops-console/blob/main/rag/storage.py"
click node_chunking "https://github.com/522blackcat/knowledgeops-console/blob/main/rag/chunking.py"
click node_retrieval "https://github.com/522blackcat/knowledgeops-console/blob/main/rag/retrieval.py"
click node_bm25 "https://github.com/522blackcat/knowledgeops-console/blob/main/rag/bm25.py"
click node_vectorstore "https://github.com/522blackcat/knowledgeops-console/blob/main/rag/vector_store.py"
click node_embedding "https://github.com/522blackcat/knowledgeops-console/blob/main/rag/embedding.py"
click node_reranker "https://github.com/522blackcat/knowledgeops-console/blob/main/rag/reranker.py"
click node_database "https://github.com/522blackcat/knowledgeops-console/blob/main/infrastructure/database.py"
click node_models "https://github.com/522blackcat/knowledgeops-console/blob/main/infrastructure/models.py"
click node_redis "https://github.com/522blackcat/knowledgeops-console/blob/main/infrastructure/redis_client.py"
click node_memory "https://github.com/522blackcat/knowledgeops-console/blob/main/memory/context.py"
click node_summary "https://github.com/522blackcat/knowledgeops-console/blob/main/memory/summary.py"
click node_tools "https://github.com/522blackcat/knowledgeops-console/blob/main/tools/execution.py"
click node_registry "https://github.com/522blackcat/knowledgeops-console/blob/main/tools/registry.py"
click node_builtin "https://github.com/522blackcat/knowledgeops-console/blob/main/tools/builtin.py"
click node_mcp "https://github.com/522blackcat/knowledgeops-console/blob/main/tools/mcp_registry.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_frontend,node_api,node_auth,node_admin,node_agentapi,node_runapi,node_approvalapi,node_sse,node_user toneBlue
class node_agentworker,node_agentgraph,node_completion,node_approval toneAmber
class node_knowledgeapi,node_evalapi,node_evalrunner,node_ragworker,node_parser,node_storage,node_chunking,node_retrieval,node_bm25,node_vectorstore,node_embedding,node_reranker toneMint
class node_database,node_models,node_redis,node_memory,node_summary toneRose
class node_tools,node_registry,node_builtin,node_mcp toneIndigo
```

## Components

### Console and API

- [Vue console](https://github.com/522blackcat/knowledgeops-console/blob/main/frontend/src/App.vue): `frontend/src/App.vue`
- [FastAPI app](https://github.com/522blackcat/knowledgeops-console/blob/main/app/main.py): `app/main.py`
- [Authentication](https://github.com/522blackcat/knowledgeops-console/blob/main/app/auth_api.py): `app/auth_api.py`
- [Admin APIs](https://github.com/522blackcat/knowledgeops-console/blob/main/app/admin_api.py): `app/admin_api.py`
- [Agent APIs](https://github.com/522blackcat/knowledgeops-console/blob/main/app/agent_api.py): `app/agent_api.py`
- [Run APIs](https://github.com/522blackcat/knowledgeops-console/blob/main/app/run_api.py): `app/run_api.py`
- [Approval APIs](https://github.com/522blackcat/knowledgeops-console/blob/main/app/approval_api.py): `app/approval_api.py`
- [Run event stream](https://github.com/522blackcat/knowledgeops-console/blob/main/app/sse_api.py): `app/sse_api.py`

### Agent runtime

- [Agent worker](https://github.com/522blackcat/knowledgeops-console/blob/main/agent/worker.py): `agent/worker.py`
- [Agent graph](https://github.com/522blackcat/knowledgeops-console/blob/main/agent/graph.py): `agent/graph.py`
- [Run completion](https://github.com/522blackcat/knowledgeops-console/blob/main/agent/completion.py): `agent/completion.py`
- [Approval logic](https://github.com/522blackcat/knowledgeops-console/blob/main/agent/approval.py): `agent/approval.py`

### Knowledge and RAG

- [Knowledge APIs](https://github.com/522blackcat/knowledgeops-console/blob/main/app/knowledge_api.py): `app/knowledge_api.py`
- [RAG eval API](https://github.com/522blackcat/knowledgeops-console/blob/main/app/rag_eval_api.py): `app/rag_eval_api.py`
- [Eval runner](https://github.com/522blackcat/knowledgeops-console/blob/main/evaluation/rag_eval_runner.py): `evaluation/rag_eval_runner.py`
- [Ingest worker](https://github.com/522blackcat/knowledgeops-console/blob/main/rag/worker.py): `rag/worker.py`
- [Document parser](https://github.com/522blackcat/knowledgeops-console/blob/main/rag/parser.py): `rag/parser.py`
- [Upload storage](https://github.com/522blackcat/knowledgeops-console/blob/main/rag/storage.py): `rag/storage.py`
- [Chunking](https://github.com/522blackcat/knowledgeops-console/blob/main/rag/chunking.py): `rag/chunking.py`
- [Hybrid retrieval](https://github.com/522blackcat/knowledgeops-console/blob/main/rag/retrieval.py): `rag/retrieval.py`
- [BM25 search](https://github.com/522blackcat/knowledgeops-console/blob/main/rag/bm25.py): `rag/bm25.py`
- [Qdrant vector store](https://github.com/522blackcat/knowledgeops-console/blob/main/rag/vector_store.py): `rag/vector_store.py`
- [Embeddings](https://github.com/522blackcat/knowledgeops-console/blob/main/rag/embedding.py): `rag/embedding.py`
- [Reranker](https://github.com/522blackcat/knowledgeops-console/blob/main/rag/reranker.py): `rag/reranker.py`

### State and memory

- [PostgreSQL](https://github.com/522blackcat/knowledgeops-console/blob/main/infrastructure/database.py): `infrastructure/database.py`
- [Domain records](https://github.com/522blackcat/knowledgeops-console/blob/main/infrastructure/models.py): `infrastructure/models.py`
- [Redis coordination](https://github.com/522blackcat/knowledgeops-console/blob/main/infrastructure/redis_client.py): `infrastructure/redis_client.py`
- [Conversation memory](https://github.com/522blackcat/knowledgeops-console/blob/main/memory/context.py): `memory/context.py`
- [Incremental summaries](https://github.com/522blackcat/knowledgeops-console/blob/main/memory/summary.py): `memory/summary.py`

### Tools and models

- [Tool execution](https://github.com/522blackcat/knowledgeops-console/blob/main/tools/execution.py): `tools/execution.py`
- [Tool registry](https://github.com/522blackcat/knowledgeops-console/blob/main/tools/registry.py): `tools/registry.py`
- [Built-in tools](https://github.com/522blackcat/knowledgeops-console/blob/main/tools/builtin.py): `tools/builtin.py`
- [MCP tools](https://github.com/522blackcat/knowledgeops-console/blob/main/tools/mcp_registry.py): `tools/mcp_registry.py`

### Other components

- **Console user**

## Connections

- Console user → Vue console: uses (evidence: `README.md`)
- Vue console → FastAPI app: accesses (evidence: `README.md`)
- FastAPI app → Authentication: registers (evidence: `app/main.py`)
- FastAPI app → Admin APIs: registers (evidence: `app/main.py`)
- FastAPI app → Agent APIs: registers (evidence: `app/main.py`)
- FastAPI app → Run APIs: registers (evidence: `app/main.py`)
- FastAPI app → Approval APIs: registers (evidence: `app/main.py`)
- FastAPI app → Run event stream: registers (evidence: `app/main.py`)
- FastAPI app → Knowledge APIs: registers (evidence: `app/main.py`)
- FastAPI app → RAG eval API: registers (evidence: `app/main.py`)
- Agent worker → Agent graph: invokes (evidence: `agent/worker.py`)
- Agent worker → Run completion: uses (evidence: `agent/worker.py`)
- Agent worker → Approval logic: uses (evidence: `agent/worker.py`)
- Agent worker → Conversation memory: builds context (evidence: `agent/worker.py`)
- Agent worker → Hybrid retrieval: retrieves evidence (evidence: `agent/worker.py`)
- Agent graph → Tool execution: executes tools (evidence: `agent/graph.py`)
- Agent graph → Tool registry: loads tools (evidence: `agent/graph.py`)
- Agent worker → Redis coordination: checks cancellation (evidence: `agent/worker.py`)
- Agent worker → PostgreSQL: claims tasks (evidence: `agent/worker.py`)
- Ingest worker → Document parser: parses documents (evidence: `rag/worker.py`)
- Ingest worker → Chunking: prepares chunks (evidence: `rag/worker.py`)
- Ingest worker → Upload storage: uses upload storage (evidence: `rag/worker.py`)
- Ingest worker → Qdrant vector store: indexes vectors (evidence: `rag/worker.py`)
- RAG eval API → Hybrid retrieval: runs hybrid search (evidence: `app/rag_eval_api.py`)
- RAG eval API → BM25 search: runs lexical search (evidence: `app/rag_eval_api.py`)
- Hybrid retrieval → BM25 search: searches chunks (evidence: `rag/retrieval.py`)
- Hybrid retrieval → Embeddings: embeds query (evidence: `rag/retrieval.py`)
- Hybrid retrieval → Qdrant vector store: searches vectors (evidence: `rag/retrieval.py`)
- Hybrid retrieval → Reranker: reranks hits (evidence: `rag/retrieval.py`)
- Conversation memory → Incremental summaries: loads summaries (evidence: `memory/context.py`)
- Conversation memory → PostgreSQL: reads memory (evidence: `memory/context.py`)
- Incremental summaries → PostgreSQL: stores versions (evidence: `memory/summary.py`)
- Incremental summaries → Domain records: uses records (evidence: `memory/summary.py`)
- Tool execution → Tool registry: validates tools (evidence: `tools/execution.py`)
- Built-in tools → Hybrid retrieval: searches knowledge (evidence: `tools/builtin.py`)
- Agent graph → MCP tools: loads MCP tools (evidence: `agent/worker.py`)
- Eval runner → Hybrid retrieval: evaluates retrieval (evidence: `README.md`)
- PostgreSQL → Domain records: maps records (evidence: `infrastructure/models.py`)
- Agent worker → Redis coordination: coordinates work (evidence: `README.md`)
