# ninimu0326/arknightagent architecture

> Architecture diagram of the GitHub repository ninimu0326/arknightagent, 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/ninimu0326/arknightagent
- Repository: https://github.com/ninimu0326/arknightagent

## Overview

Arknights Agent is a web-based Arknights question-answering product. A user asks in the chat UI; the backend streams an Agent response while the LLM selects local knowledge, graph, structured-data, stage-wave, web-search, or optional PRTS MCP tools. Retrieved evidence returns to the Agent for a final streamed answer, with source and image display handled by the frontend. The README documents the major capabilities; sampled source confirms selected retrieval, GraphRAG, storage, and context-compression details, so unsampled internal wiring is omitted where uncertain.

Main entry points: [`backend/main.py`](https://github.com/ninimu0326/arknightagent/blob/master/backend/main.py) (HTTP and SSE API), [`backend/agent/tool_implementations.py`](https://github.com/ninimu0326/arknightagent/blob/master/backend/agent/tool_implementations.py) (Local tool execution), [`backend/agent/core.py`](https://github.com/ninimu0326/arknightagent/blob/master/backend/agent/core.py) (Agent loop), [`backend/rag/retrievers.py`](https://github.com/ninimu0326/arknightagent/blob/master/backend/rag/retrievers.py) (Hybrid retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_chat["Chat view<br/>[ChatView.vue]"]
  node_api_client["API client<br/>[api.js]"]
  node_graph_view["Graph explorer<br/>[GraphView.vue]"]
  node_admin_view["Admin dashboard<br/>[AdminView.vue]"]
end

subgraph group_runtime["Agent runtime"]
  node_backend_api["HTTP and SSE API<br/>[main.py]"]
  node_agent_core["Agent loop<br/>[core.py]"]
  node_context["Context engine<br/>[context_engine.py]"]
  node_tool_registry["Tool registry<br/>[tools.py]"]
  node_tool_impl["Local tool execution"]
  node_llm_factory["LLM client factory<br/>[llm_factory.py]"]
end

subgraph group_knowledge["Knowledge retrieval"]
  node_retrievers["Hybrid retrieval<br/>[retrievers.py]"]
  node_faiss[("FAISS indexes<br/>[faiss_client.py]")]
  node_bm25[("BM25 search<br/>[bm25_index.py]")]
  node_reranker["Cross-encoder reranker<br/>[reranker.py]"]
  node_parent_docs["Parent expansion<br/>[parent_document.py]"]
  node_graph_query["GraphRAG query<br/>[query.py]"]
end

subgraph group_integrations["Data integrations"]
  node_structured["Structured SQL"]
  node_stage_waves["Stage wave parsing<br/>[stage_waves.py]"]
  node_web_search["Web search<br/>[web_search.py]"]
  node_mcp["PRTS MCP client<br/>[mcp_client.py]"]
end

subgraph group_state["State and insight"]
  node_session_store[("SQLite sessions<br/>[db.py]")]
  node_tracing["Trace service<br/>[tracing.py]"]
  node_quick_questions["Quick questions<br/>[quick_questions.py]"]
end

node_user(("Questioner"))
node_llm(("LLM provider"))
node_web(("Web sources"))
node_prts(("PRTS MCP service"))

node_user -->|"asks"| node_chat
node_chat -->|"submits"| node_api_client
node_api_client -->|"calls API"| node_backend_api
node_backend_api -->|"dispatches"| node_agent_core
node_agent_core -->|"builds context"| node_context
node_context -->|"reads and writes"| node_session_store
node_agent_core -->|"requests completion"| node_llm_factory
node_llm_factory -->|"calls"| node_llm
node_agent_core -->|"dispatches tools"| node_tool_registry
node_tool_registry -->|"runs local tools"| node_tool_impl
node_tool_impl -->|"searches"| node_retrievers
node_retrievers -->|"vector search"| node_faiss
node_retrievers -->|"keyword search"| node_bm25
node_retrievers -->|"reranks"| node_reranker
node_retrievers -->|"expands documents"| node_parent_docs
node_tool_impl -->|"queries graph"| node_graph_query
node_tool_impl -->|"queries values"| node_structured
node_tool_impl -->|"parses waves"| node_stage_waves
node_tool_impl -->|"searches web"| node_web_search
node_web_search -->|"queries"| node_web
node_backend_api -.->|"registers tools"| node_mcp
node_tool_registry -.->|"dispatches optional tools"| node_mcp
node_mcp -.->|"calls tools"| node_prts
node_agent_core -->|"streams events"| node_backend_api
node_backend_api -->|"streams response"| node_chat
node_backend_api -->|"records traces"| node_tracing
node_admin_view -->|"requests admin data"| node_api_client
node_graph_view -->|"requests graph data"| node_api_client
node_graph_view -->|"loads graph"| node_backend_api
node_chat -->|"requests suggestions"| node_quick_questions

click node_chat "https://github.com/ninimu0326/arknightagent/blob/master/frontend/src/views/ChatView.vue"
click node_api_client "https://github.com/ninimu0326/arknightagent/blob/master/frontend/src/api.js"
click node_graph_view "https://github.com/ninimu0326/arknightagent/blob/master/frontend/src/views/GraphView.vue"
click node_admin_view "https://github.com/ninimu0326/arknightagent/blob/master/frontend/src/views/AdminView.vue"
click node_backend_api "https://github.com/ninimu0326/arknightagent/blob/master/backend/main.py"
click node_agent_core "https://github.com/ninimu0326/arknightagent/blob/master/backend/agent/core.py"
click node_context "https://github.com/ninimu0326/arknightagent/blob/master/backend/agent/context_engine.py"
click node_tool_registry "https://github.com/ninimu0326/arknightagent/blob/master/backend/agent/tools.py"
click node_tool_impl "https://github.com/ninimu0326/arknightagent/blob/master/backend/agent/tool_implementations.py"
click node_llm_factory "https://github.com/ninimu0326/arknightagent/blob/master/backend/api/llm_factory.py"
click node_retrievers "https://github.com/ninimu0326/arknightagent/blob/master/backend/rag/retrievers.py"
click node_faiss "https://github.com/ninimu0326/arknightagent/blob/master/backend/storage/faiss_client.py"
click node_bm25 "https://github.com/ninimu0326/arknightagent/blob/master/backend/data/bm25_index.py"
click node_reranker "https://github.com/ninimu0326/arknightagent/blob/master/backend/lc/reranker.py"
click node_parent_docs "https://github.com/ninimu0326/arknightagent/blob/master/backend/rag/parent_document.py"
click node_graph_query "https://github.com/ninimu0326/arknightagent/blob/master/backend/rag/graphrag/query.py"
click node_structured "https://github.com/ninimu0326/arknightagent/blob/master/backend/agent/structured_query.py"
click node_stage_waves "https://github.com/ninimu0326/arknightagent/blob/master/backend/agent/stage_waves.py"
click node_web_search "https://github.com/ninimu0326/arknightagent/blob/master/backend/api/web_search.py"
click node_mcp "https://github.com/ninimu0326/arknightagent/blob/master/backend/agent/mcp_client.py"
click node_session_store "https://github.com/ninimu0326/arknightagent/blob/master/backend/db.py"
click node_tracing "https://github.com/ninimu0326/arknightagent/blob/master/backend/observability/tracing.py"
click node_quick_questions "https://github.com/ninimu0326/arknightagent/blob/master/backend/quick_questions.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_chat,node_api_client,node_graph_view,node_admin_view toneBlue
class node_backend_api,node_agent_core,node_context,node_tool_registry,node_tool_impl,node_llm_factory toneAmber
class node_retrievers,node_faiss,node_bm25,node_reranker,node_parent_docs,node_graph_query toneMint
class node_structured,node_stage_waves,node_web_search,node_mcp toneRose
class node_session_store,node_tracing,node_quick_questions,node_user,node_llm,node_web,node_prts toneIndigo
```

## Components

### Web client

- [Chat view](https://github.com/ninimu0326/arknightagent/blob/master/frontend/src/views/ChatView.vue): `frontend/src/views/ChatView.vue`
- [API client](https://github.com/ninimu0326/arknightagent/blob/master/frontend/src/api.js): `frontend/src/api.js`
- [Graph explorer](https://github.com/ninimu0326/arknightagent/blob/master/frontend/src/views/GraphView.vue): `frontend/src/views/GraphView.vue`
- [Admin dashboard](https://github.com/ninimu0326/arknightagent/blob/master/frontend/src/views/AdminView.vue): `frontend/src/views/AdminView.vue`

### Agent runtime

- [HTTP and SSE API](https://github.com/ninimu0326/arknightagent/blob/master/backend/main.py): `backend/main.py`
- [Agent loop](https://github.com/ninimu0326/arknightagent/blob/master/backend/agent/core.py): `backend/agent/core.py`
- [Context engine](https://github.com/ninimu0326/arknightagent/blob/master/backend/agent/context_engine.py): `backend/agent/context_engine.py`
- [Tool registry](https://github.com/ninimu0326/arknightagent/blob/master/backend/agent/tools.py): `backend/agent/tools.py`
- [Local tool execution](https://github.com/ninimu0326/arknightagent/blob/master/backend/agent/tool_implementations.py): `backend/agent/tool_implementations.py`
- [LLM client factory](https://github.com/ninimu0326/arknightagent/blob/master/backend/api/llm_factory.py): `backend/api/llm_factory.py`

### Knowledge retrieval

- [Hybrid retrieval](https://github.com/ninimu0326/arknightagent/blob/master/backend/rag/retrievers.py): `backend/rag/retrievers.py`
- [FAISS indexes](https://github.com/ninimu0326/arknightagent/blob/master/backend/storage/faiss_client.py): `backend/storage/faiss_client.py`
- [BM25 search](https://github.com/ninimu0326/arknightagent/blob/master/backend/data/bm25_index.py): `backend/data/bm25_index.py`
- [Cross-encoder reranker](https://github.com/ninimu0326/arknightagent/blob/master/backend/lc/reranker.py): `backend/lc/reranker.py`
- [Parent expansion](https://github.com/ninimu0326/arknightagent/blob/master/backend/rag/parent_document.py): `backend/rag/parent_document.py`
- [GraphRAG query](https://github.com/ninimu0326/arknightagent/blob/master/backend/rag/graphrag/query.py): `backend/rag/graphrag/query.py`

### Data integrations

- [Structured SQL](https://github.com/ninimu0326/arknightagent/blob/master/backend/agent/structured_query.py): `backend/agent/structured_query.py`
- [Stage wave parsing](https://github.com/ninimu0326/arknightagent/blob/master/backend/agent/stage_waves.py): `backend/agent/stage_waves.py`
- [Web search](https://github.com/ninimu0326/arknightagent/blob/master/backend/api/web_search.py): `backend/api/web_search.py`
- [PRTS MCP client](https://github.com/ninimu0326/arknightagent/blob/master/backend/agent/mcp_client.py): `backend/agent/mcp_client.py`

### State and insight

- [SQLite sessions](https://github.com/ninimu0326/arknightagent/blob/master/backend/db.py): `backend/db.py`
- [Trace service](https://github.com/ninimu0326/arknightagent/blob/master/backend/observability/tracing.py): `backend/observability/tracing.py`
- [Quick questions](https://github.com/ninimu0326/arknightagent/blob/master/backend/quick_questions.py): `backend/quick_questions.py`

### Other components

- **Questioner**
- **LLM provider**
- **Web sources**
- **PRTS MCP service**

## Connections

- Questioner → Chat view: asks
- Chat view → API client: submits
- API client → HTTP and SSE API: calls API
- HTTP and SSE API → Agent loop: dispatches
- Agent loop → Context engine: builds context
- Context engine → SQLite sessions: reads and writes
- Agent loop → LLM client factory: requests completion
- LLM client factory → LLM provider: calls
- Agent loop → Tool registry: dispatches tools
- Tool registry → Local tool execution: runs local tools
- Local tool execution → Hybrid retrieval: searches
- Hybrid retrieval → FAISS indexes: vector search
- Hybrid retrieval → BM25 search: keyword search
- Hybrid retrieval → Cross-encoder reranker: reranks
- Hybrid retrieval → Parent expansion: expands documents
- Local tool execution → GraphRAG query: queries graph
- Local tool execution → Structured SQL: queries values
- Local tool execution → Stage wave parsing: parses waves
- Local tool execution → Web search: searches web
- Web search → Web sources: queries
- HTTP and SSE API → PRTS MCP client: registers tools
- Tool registry → PRTS MCP client: dispatches optional tools
- PRTS MCP client → PRTS MCP service: calls tools
- Agent loop → HTTP and SSE API: streams events
- HTTP and SSE API → Chat view: streams response
- HTTP and SSE API → Trace service: records traces
- Admin dashboard → API client: requests admin data
- Graph explorer → API client: requests graph data
- Graph explorer → HTTP and SSE API: loads graph
- Chat view → Quick questions: requests suggestions