# huyanxius/qunxue architecture

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

- Interactive diagram: https://gitdiagram.com/huyanxius/qunxue
- Repository: https://github.com/huyanxius/qunxue

## Overview

群学致知 is a sociology research-discovery and design workbench. Its documented user journey moves from a phenomenon or research material through Agent-supported exploration, knowledge review, researcher-led theory judgment, and a revisable research framework. The graph combines that documented journey with the visible application entry points, research-task API, persistence, and delivery interactions. Some major capabilities are documented but their implementation was not sampled, so those links are documented rather than inferred from module names.

Main entry points: [`frontend/src/app/App.tsx`](https://github.com/huyanxius/qunxue/blob/main/frontend/src/app/App.tsx) (Web application), [`frontend/src/app/research-workspace/M5ResearchDeliveryController.tsx`](https://github.com/huyanxius/qunxue/blob/main/frontend/src/app/research-workspace/M5ResearchDeliveryController.tsx) (Research delivery), [`frontend/src/app/research/ResearchMaterialsPage.tsx`](https://github.com/huyanxius/qunxue/blob/main/frontend/src/app/research/ResearchMaterialsPage.tsx) (Materials library), [`backend/src/qunxue_api/application/theory_matching.py`](https://github.com/huyanxius/qunxue/blob/main/backend/src/qunxue_api/application/theory_matching.py) (Theory matching)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web workbench"]
  node_webapp["Web application<br/>[App.tsx]"]
  node_newresearch["New research"]
  node_workspace["Research workspace"]
  node_materialsui["Materials library"]
  node_knowledgeui["Knowledge exploration"]
  node_deliveryapi["Delivery API client"]
  node_agentclient["Agent client<br/>[index.ts]"]
end

subgraph group_research["Research workflow"]
  node_phenomenon["Phenomenon intake<br/>[service.py]"]
  node_agent["Research Agent"]
  node_theory["Theory matching<br/>[theory_matching.py]"]
  node_framework["Research framework<br/>[proposals.py]"]
  node_delivery["Research delivery"]
end

subgraph group_knowledge["Knowledge and analysis"]
  node_knowledge["Versioned knowledge<br/>[public.py]"]
  node_frontier["Frontier knowledge"]
  node_qualanalysis["Qualitative analysis<br/>[service.py]"]
  node_materials["Research materials<br/>[service.py]"]
end

subgraph group_platform["API and persistence"]
  node_taskapi["Research task API<br/>[research_tasks.py]"]
  node_taskdomain["Task domain<br/>[service.py]"]
  node_analysisrepo["Analysis repository"]
  node_materialrepo["Material repository"]
  node_sqlite[("SQLite database<br/>[base.py]")]
end

node_researcher(("Researcher"))

node_researcher -->|"uses"| node_webapp
node_webapp -->|"routes to"| node_newresearch
node_webapp -->|"routes to"| node_workspace
node_webapp -->|"routes to"| node_materialsui
node_webapp -->|"routes to"| node_knowledgeui
node_researcher -->|"describes phenomenon"| node_phenomenon
node_phenomenon -.->|"continues with"| node_agent
node_agent -->|"uses knowledge tools"| node_knowledge
node_knowledge -->|"informs comparison"| node_theory
node_researcher -->|"chooses theory"| node_theory
node_theory -->|"organizes judgment"| node_framework
node_researcher -->|"reviews materials"| node_materialsui
node_materialsui -.->|"accesses"| node_materials
node_knowledgeui -.->|"explores"| node_knowledge
node_researcher -->|"explores frontier"| node_frontier
node_researcher -.->|"analyzes research"| node_qualanalysis
node_workspace -->|"hosts delivery"| node_delivery
node_delivery -->|"loads and mutates"| node_deliveryapi
node_delivery -->|"streams agent turn"| node_agentclient
node_taskapi -->|"calls service"| node_taskdomain
node_analysisrepo -->|"executes writes"| node_sqlite
node_materialrepo -->|"reads and writes"| node_sqlite

click node_webapp "https://github.com/huyanxius/qunxue/blob/main/frontend/src/app/App.tsx"
click node_newresearch "https://github.com/huyanxius/qunxue/blob/main/frontend/src/app/agent/NewResearchWorkspacePage.tsx"
click node_workspace "https://github.com/huyanxius/qunxue/blob/main/frontend/src/app/research-workspace/ResearchProjectWorkspacePage.tsx"
click node_materialsui "https://github.com/huyanxius/qunxue/blob/main/frontend/src/app/research/ResearchMaterialsPage.tsx"
click node_knowledgeui "https://github.com/huyanxius/qunxue/blob/main/frontend/src/app/KnowledgeGraphIntegration.tsx"
click node_phenomenon "https://github.com/huyanxius/qunxue/blob/main/backend/src/qunxue_api/modules/research_intake/service.py"
click node_agent "https://github.com/huyanxius/qunxue/blob/main/backend/src/qunxue_api/application/agent_research_workflow.py"
click node_theory "https://github.com/huyanxius/qunxue/blob/main/backend/src/qunxue_api/application/theory_matching.py"
click node_framework "https://github.com/huyanxius/qunxue/blob/main/backend/src/qunxue_api/modules/research_framework/proposals.py"
click node_delivery "https://github.com/huyanxius/qunxue/blob/main/frontend/src/app/research-workspace/M5ResearchDeliveryController.tsx"
click node_knowledge "https://github.com/huyanxius/qunxue/blob/main/backend/src/qunxue_api/modules/knowledge_catalog/public.py"
click node_frontier "https://github.com/huyanxius/qunxue/blob/main/backend/src/qunxue_api/application/frontier_pipeline.py"
click node_qualanalysis "https://github.com/huyanxius/qunxue/blob/main/backend/src/qunxue_api/modules/research_analysis/service.py"
click node_materials "https://github.com/huyanxius/qunxue/blob/main/backend/src/qunxue_api/modules/research_materials/service.py"
click node_taskapi "https://github.com/huyanxius/qunxue/blob/main/backend/src/qunxue_api/api/routes/research_tasks.py"
click node_taskdomain "https://github.com/huyanxius/qunxue/blob/main/backend/src/qunxue_api/modules/research_intake/service.py"
click node_analysisrepo "https://github.com/huyanxius/qunxue/blob/main/backend/src/qunxue_api/adapters/sqlite/research_analysis_repository.py"
click node_materialrepo "https://github.com/huyanxius/qunxue/blob/main/backend/src/qunxue_api/adapters/sqlite/research_material_repository.py"
click node_sqlite "https://github.com/huyanxius/qunxue/blob/main/backend/src/qunxue_api/adapters/sqlite/base.py"
click node_deliveryapi "https://github.com/huyanxius/qunxue/blob/main/frontend/src/api/m5ResearchDelivery.ts"
click node_agentclient "https://github.com/huyanxius/qunxue/blob/main/frontend/src/modules/research-agent/index.ts"

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_webapp,node_newresearch,node_workspace,node_materialsui,node_knowledgeui,node_deliveryapi,node_agentclient toneBlue
class node_phenomenon,node_agent,node_theory,node_framework,node_delivery toneAmber
class node_knowledge,node_frontier,node_qualanalysis,node_materials toneMint
class node_taskapi,node_taskdomain,node_analysisrepo,node_materialrepo,node_sqlite toneRose
class node_researcher toneIndigo
```

## Components

### Web workbench

- [Web application](https://github.com/huyanxius/qunxue/blob/main/frontend/src/app/App.tsx): `frontend/src/app/App.tsx`
- [New research](https://github.com/huyanxius/qunxue/blob/main/frontend/src/app/agent/NewResearchWorkspacePage.tsx): `frontend/src/app/agent/NewResearchWorkspacePage.tsx`
- [Research workspace](https://github.com/huyanxius/qunxue/blob/main/frontend/src/app/research-workspace/ResearchProjectWorkspacePage.tsx): `frontend/src/app/research-workspace/ResearchProjectWorkspacePage.tsx`
- [Materials library](https://github.com/huyanxius/qunxue/blob/main/frontend/src/app/research/ResearchMaterialsPage.tsx): `frontend/src/app/research/ResearchMaterialsPage.tsx`
- [Knowledge exploration](https://github.com/huyanxius/qunxue/blob/main/frontend/src/app/KnowledgeGraphIntegration.tsx): `frontend/src/app/KnowledgeGraphIntegration.tsx`
- [Delivery API client](https://github.com/huyanxius/qunxue/blob/main/frontend/src/api/m5ResearchDelivery.ts): `frontend/src/api/m5ResearchDelivery.ts`
- [Agent client](https://github.com/huyanxius/qunxue/blob/main/frontend/src/modules/research-agent/index.ts): `frontend/src/modules/research-agent/index.ts`

### Research workflow

- [Phenomenon intake](https://github.com/huyanxius/qunxue/blob/main/backend/src/qunxue_api/modules/research_intake/service.py): `backend/src/qunxue_api/modules/research_intake/service.py`
- [Research Agent](https://github.com/huyanxius/qunxue/blob/main/backend/src/qunxue_api/application/agent_research_workflow.py): `backend/src/qunxue_api/application/agent_research_workflow.py`
- [Theory matching](https://github.com/huyanxius/qunxue/blob/main/backend/src/qunxue_api/application/theory_matching.py): `backend/src/qunxue_api/application/theory_matching.py`
- [Research framework](https://github.com/huyanxius/qunxue/blob/main/backend/src/qunxue_api/modules/research_framework/proposals.py): `backend/src/qunxue_api/modules/research_framework/proposals.py`
- [Research delivery](https://github.com/huyanxius/qunxue/blob/main/frontend/src/app/research-workspace/M5ResearchDeliveryController.tsx): `frontend/src/app/research-workspace/M5ResearchDeliveryController.tsx`

### Knowledge and analysis

- [Versioned knowledge](https://github.com/huyanxius/qunxue/blob/main/backend/src/qunxue_api/modules/knowledge_catalog/public.py): `backend/src/qunxue_api/modules/knowledge_catalog/public.py`
- [Frontier knowledge](https://github.com/huyanxius/qunxue/blob/main/backend/src/qunxue_api/application/frontier_pipeline.py): `backend/src/qunxue_api/application/frontier_pipeline.py`
- [Qualitative analysis](https://github.com/huyanxius/qunxue/blob/main/backend/src/qunxue_api/modules/research_analysis/service.py): `backend/src/qunxue_api/modules/research_analysis/service.py`
- [Research materials](https://github.com/huyanxius/qunxue/blob/main/backend/src/qunxue_api/modules/research_materials/service.py): `backend/src/qunxue_api/modules/research_materials/service.py`

### API and persistence

- [Research task API](https://github.com/huyanxius/qunxue/blob/main/backend/src/qunxue_api/api/routes/research_tasks.py): `backend/src/qunxue_api/api/routes/research_tasks.py`
- [Task domain](https://github.com/huyanxius/qunxue/blob/main/backend/src/qunxue_api/modules/research_intake/service.py): `backend/src/qunxue_api/modules/research_intake/service.py`
- [Analysis repository](https://github.com/huyanxius/qunxue/blob/main/backend/src/qunxue_api/adapters/sqlite/research_analysis_repository.py): `backend/src/qunxue_api/adapters/sqlite/research_analysis_repository.py`
- [Material repository](https://github.com/huyanxius/qunxue/blob/main/backend/src/qunxue_api/adapters/sqlite/research_material_repository.py): `backend/src/qunxue_api/adapters/sqlite/research_material_repository.py`
- [SQLite database](https://github.com/huyanxius/qunxue/blob/main/backend/src/qunxue_api/adapters/sqlite/base.py): `backend/src/qunxue_api/adapters/sqlite/base.py`

### Other components

- **Researcher**

## Connections

- Researcher → Web application: uses (evidence: `README.md`)
- Web application → New research: routes to (evidence: `frontend/src/app/App.tsx`)
- Web application → Research workspace: routes to (evidence: `frontend/src/app/App.tsx`)
- Web application → Materials library: routes to (evidence: `frontend/src/app/App.tsx`)
- Web application → Knowledge exploration: routes to (evidence: `frontend/src/app/App.tsx`)
- Researcher → Phenomenon intake: describes phenomenon (evidence: `README.md`)
- Phenomenon intake → Research Agent: continues with
- Research Agent → Versioned knowledge: uses knowledge tools (evidence: `README.md`)
- Versioned knowledge → Theory matching: informs comparison (evidence: `README.md`)
- Researcher → Theory matching: chooses theory (evidence: `README.md`)
- Theory matching → Research framework: organizes judgment (evidence: `README.md`)
- Researcher → Materials library: reviews materials (evidence: `README.md`)
- Materials library → Research materials: accesses
- Knowledge exploration → Versioned knowledge: explores
- Researcher → Frontier knowledge: explores frontier (evidence: `README.md`)
- Researcher → Qualitative analysis: analyzes research
- Research workspace → Research delivery: hosts delivery (evidence: `README.md`)
- Research delivery → Delivery API client: loads and mutates (evidence: `frontend/src/app/research-workspace/M5ResearchDeliveryController.tsx`)
- Research delivery → Agent client: streams agent turn (evidence: `frontend/src/app/research-workspace/M5ResearchDeliveryController.tsx`)
- Research task API → Task domain: calls service (evidence: `backend/src/qunxue_api/api/routes/research_tasks.py`)
- Analysis repository → SQLite database: executes writes (evidence: `backend/src/qunxue_api/adapters/sqlite/research_analysis_repository.py`)
- Material repository → SQLite database: reads and writes (evidence: `backend/src/qunxue_api/adapters/sqlite/research_material_repository.py`)