# zhyese/grid-qa architecture

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

- Interactive diagram: https://gitdiagram.com/zhyese/grid-qa
- Repository: https://github.com/zhyese/grid-qa

## Overview

This is a grid-operations RAG question-answering product with a Vue interface and FastAPI backend. Its primary workflow routes an operator’s question, searches and filters operational knowledge, corrects/augments evidence, and streams a cited answer; feedback and evidence gaps feed knowledge improvement. The README also documents document management, governance, operational workflows, graph knowledge, and real-time twin capabilities. Some subsystem links reflect README descriptions because their implementation was not sampled.

Main entry points: [`backend/app/services/qa_service.py`](https://github.com/zhyese/grid-qa/blob/main/backend/app/services/qa_service.py) (Answer orchestration), [`backend/app/main.py`](https://github.com/zhyese/grid-qa/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/services/retrieval_service.py`](https://github.com/zhyese/grid-qa/blob/main/backend/app/services/retrieval_service.py) (Hybrid retrieval), [`frontend/src/App.vue`](https://github.com/zhyese/grid-qa/blob/main/frontend/src/App.vue) (Vue application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_web["Vue application<br/>[App.vue]"]
  node_api["FastAPI application<br/>[main.py]"]
end

subgraph group_qa["Question answering"]
  node_qa_routes["QA endpoints<br/>[qa.py]"]
  node_qa_service["Answer orchestration<br/>[qa_service.py]"]
  node_query_router["Query routing"]
  node_retrieval["Hybrid retrieval"]
  node_query_plan["Complex query planning"]
  node_rag["RAG correction and citations"]
  node_llm["LLM providers and fallback<br/>[llm_router.py]"]
  node_cache["Answer and semantic caches"]
end

subgraph group_knowledge["Knowledge lifecycle"]
  node_documents["Document ingestion and collaboration"]
  node_governance["Knowledge governance"]
  node_evolution["Knowledge evolution"]
  node_feedback["Answer feedback"]
  node_kg["Knowledge graph<br/>[kg_service.py]"]
end

subgraph group_operations["Operations tools"]
  node_ops["Operations and diagnosis"]
  node_workflow["Workflow execution<br/>[workflow_engine.py]"]
  node_twin["Digital twin events<br/>[twin_service.py]"]
end

subgraph group_platform["Platform integrations"]
  node_stores[("Knowledge stores")]
  node_ws["Real-time delivery<br/>[ws_manager.py]"]
  node_mcp["MCP tool server<br/>[server.py]"]
  node_llm_suite["LLM evaluation console<br/>[main.py]"]
end

node_operator(("Grid operator"))

node_operator -->|"asks question"| node_web
node_web -->|"sends request"| node_api
node_api -->|"dispatches"| node_qa_routes
node_qa_routes -->|"invokes"| node_qa_service
node_qa_service -->|"checks cache"| node_cache
node_qa_service -->|"classifies query"| node_query_router
node_qa_service -->|"requests evidence"| node_retrieval
node_qa_service -.->|"plans complex query"| node_query_plan
node_query_plan -->|"retrieves subqueries"| node_retrieval
node_retrieval -->|"searches knowledge"| node_stores
node_retrieval -->|"filters results"| node_governance
node_qa_service -->|"corrects and cites"| node_rag
node_rag -.->|"adds graph context"| node_kg
node_qa_service -->|"generates answer"| node_llm
node_llm -->|"streams response"| node_web
node_documents -->|"indexes documents"| node_stores
node_operator -->|"rates answer"| node_feedback
node_feedback -->|"informs improvement"| node_evolution
node_evolution -->|"proposes knowledge"| node_documents
node_api -->|"serves operations"| node_ops
node_api -->|"serves workflows"| node_workflow
node_api -->|"serves twin data"| node_twin
node_twin -->|"publishes events"| node_ws
node_api -->|"exposes tools"| node_mcp

click node_web "https://github.com/zhyese/grid-qa/blob/main/frontend/src/App.vue"
click node_api "https://github.com/zhyese/grid-qa/blob/main/backend/app/main.py"
click node_qa_routes "https://github.com/zhyese/grid-qa/blob/main/backend/app/routers/qa.py"
click node_qa_service "https://github.com/zhyese/grid-qa/blob/main/backend/app/services/qa_service.py"
click node_query_router "https://github.com/zhyese/grid-qa/blob/main/backend/app/routing/query_classifier.py"
click node_retrieval "https://github.com/zhyese/grid-qa/blob/main/backend/app/services/retrieval_service.py"
click node_query_plan "https://github.com/zhyese/grid-qa/blob/main/backend/app/services/query_plan_service.py"
click node_rag "https://github.com/zhyese/grid-qa/tree/main/backend/app/rag"
click node_llm "https://github.com/zhyese/grid-qa/blob/main/backend/app/providers/llm_router.py"
click node_stores "https://github.com/zhyese/grid-qa/tree/main/backend/app/clients"
click node_documents "https://github.com/zhyese/grid-qa/blob/main/backend/app/services/document_service.py"
click node_governance "https://github.com/zhyese/grid-qa/blob/main/backend/app/services/knowledge_governance_service.py"
click node_evolution "https://github.com/zhyese/grid-qa/blob/main/backend/app/services/knowledge_evolution_service.py"
click node_feedback "https://github.com/zhyese/grid-qa/blob/main/backend/app/services/feedback_service.py"
click node_kg "https://github.com/zhyese/grid-qa/blob/main/backend/app/services/kg_service.py"
click node_workflow "https://github.com/zhyese/grid-qa/blob/main/backend/app/services/workflow_engine.py"
click node_twin "https://github.com/zhyese/grid-qa/blob/main/backend/app/services/twin_service.py"
click node_ws "https://github.com/zhyese/grid-qa/blob/main/backend/app/core/ws_manager.py"
click node_mcp "https://github.com/zhyese/grid-qa/blob/main/backend/app/mcp/server.py"
click node_llm_suite "https://github.com/zhyese/grid-qa/blob/main/llm-user-suite/llm_user_suite/main.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_web,node_api toneBlue
class node_qa_routes,node_qa_service,node_query_router,node_retrieval,node_query_plan,node_rag,node_llm,node_cache toneAmber
class node_documents,node_governance,node_evolution,node_feedback,node_kg toneMint
class node_ops,node_workflow,node_twin toneRose
class node_stores,node_ws,node_mcp,node_llm_suite,node_operator toneIndigo
```

## Components

### User experience

- [Vue application](https://github.com/zhyese/grid-qa/blob/main/frontend/src/App.vue): `frontend/src/App.vue`
- [FastAPI application](https://github.com/zhyese/grid-qa/blob/main/backend/app/main.py): `backend/app/main.py`

### Question answering

- [QA endpoints](https://github.com/zhyese/grid-qa/blob/main/backend/app/routers/qa.py): `backend/app/routers/qa.py`
- [Answer orchestration](https://github.com/zhyese/grid-qa/blob/main/backend/app/services/qa_service.py): `backend/app/services/qa_service.py`
- [Query routing](https://github.com/zhyese/grid-qa/blob/main/backend/app/routing/query_classifier.py): `backend/app/routing/query_classifier.py`
- [Hybrid retrieval](https://github.com/zhyese/grid-qa/blob/main/backend/app/services/retrieval_service.py): `backend/app/services/retrieval_service.py`
- [Complex query planning](https://github.com/zhyese/grid-qa/blob/main/backend/app/services/query_plan_service.py): `backend/app/services/query_plan_service.py`
- [RAG correction and citations](https://github.com/zhyese/grid-qa/tree/main/backend/app/rag): `backend/app/rag`
- [LLM providers and fallback](https://github.com/zhyese/grid-qa/blob/main/backend/app/providers/llm_router.py): `backend/app/providers/llm_router.py`
- **Answer and semantic caches**

### Knowledge lifecycle

- [Document ingestion and collaboration](https://github.com/zhyese/grid-qa/blob/main/backend/app/services/document_service.py): `backend/app/services/document_service.py`
- [Knowledge governance](https://github.com/zhyese/grid-qa/blob/main/backend/app/services/knowledge_governance_service.py): `backend/app/services/knowledge_governance_service.py`
- [Knowledge evolution](https://github.com/zhyese/grid-qa/blob/main/backend/app/services/knowledge_evolution_service.py): `backend/app/services/knowledge_evolution_service.py`
- [Answer feedback](https://github.com/zhyese/grid-qa/blob/main/backend/app/services/feedback_service.py): `backend/app/services/feedback_service.py`
- [Knowledge graph](https://github.com/zhyese/grid-qa/blob/main/backend/app/services/kg_service.py): `backend/app/services/kg_service.py`

### Operations tools

- **Operations and diagnosis**
- [Workflow execution](https://github.com/zhyese/grid-qa/blob/main/backend/app/services/workflow_engine.py): `backend/app/services/workflow_engine.py`
- [Digital twin events](https://github.com/zhyese/grid-qa/blob/main/backend/app/services/twin_service.py): `backend/app/services/twin_service.py`

### Platform integrations

- [Knowledge stores](https://github.com/zhyese/grid-qa/tree/main/backend/app/clients): `backend/app/clients`
- [Real-time delivery](https://github.com/zhyese/grid-qa/blob/main/backend/app/core/ws_manager.py): `backend/app/core/ws_manager.py`
- [MCP tool server](https://github.com/zhyese/grid-qa/blob/main/backend/app/mcp/server.py): `backend/app/mcp/server.py`
- [LLM evaluation console](https://github.com/zhyese/grid-qa/blob/main/llm-user-suite/llm_user_suite/main.py): `llm-user-suite/llm_user_suite/main.py`

### Other components

- **Grid operator**

## Connections

- Grid operator → Vue application: asks question
- Vue application → FastAPI application: sends request
- FastAPI application → QA endpoints: dispatches
- QA endpoints → Answer orchestration: invokes
- Answer orchestration → Answer and semantic caches: checks cache
- Answer orchestration → Query routing: classifies query
- Answer orchestration → Hybrid retrieval: requests evidence
- Answer orchestration → Complex query planning: plans complex query
- Complex query planning → Hybrid retrieval: retrieves subqueries
- Hybrid retrieval → Knowledge stores: searches knowledge
- Hybrid retrieval → Knowledge governance: filters results
- Answer orchestration → RAG correction and citations: corrects and cites
- RAG correction and citations → Knowledge graph: adds graph context
- Answer orchestration → LLM providers and fallback: generates answer
- LLM providers and fallback → Vue application: streams response
- Document ingestion and collaboration → Knowledge stores: indexes documents
- Grid operator → Answer feedback: rates answer
- Answer feedback → Knowledge evolution: informs improvement
- Knowledge evolution → Document ingestion and collaboration: proposes knowledge
- FastAPI application → Operations and diagnosis: serves operations
- FastAPI application → Workflow execution: serves workflows
- FastAPI application → Digital twin events: serves twin data
- Digital twin events → Real-time delivery: publishes events
- FastAPI application → MCP tool server: exposes tools