# windfall8623/xunke-ai architecture

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

- Interactive diagram: https://gitdiagram.com/windfall8623/xunke-ai
- Repository: https://github.com/windfall8623/xunke-ai

## Overview

Xunke AI is a course-centered self-study agent: learners organize a topic or uploaded material into a course, study lessons, ask evidence-backed questions, practice, and use feedback and review recommendations to continue. The graph includes the documented course, teaching, retrieval, learning, and evaluation capabilities. Relationship evidence is primarily from the README’s architecture and capability descriptions; unsampled implementation details are not inferred.

Main entry points: [`backend/app/rag/pipeline.py`](https://github.com/windfall8623/xunke-ai/blob/main/backend/app/rag/pipeline.py) (Retrieval workflow), [`backend/app/main.py`](https://github.com/windfall8623/xunke-ai/blob/main/backend/app/main.py) (FastAPI application), [`web/src/app/router.tsx`](https://github.com/windfall8623/xunke-ai/blob/main/web/src/app/router.tsx) (Web application), [`backend/app/rag/engine.py`](https://github.com/windfall8623/xunke-ai/blob/main/backend/app/rag/engine.py) (RAG engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Learner experience"]
  node_web["Web application<br/>[router.tsx]"]
  node_web_auth["Session and API client<br/>[AuthProvider.tsx]"]
end

subgraph group_course["Course learning"]
  node_courses["Course services<br/>[course_service.py]"]
  node_teaching["Teaching agent<br/>[graph.py]"]
  node_lesson_learning["Lesson study<br/>[course_read.py]"]
  node_course_checks["Course assessments"]
  node_practice["Practice generation<br/>[pipeline.py]"]
end

subgraph group_knowledge["Knowledge and agents"]
  node_qa["Document Q&amp;A<br/>[pipeline.py]"]
  node_rag_engine["RAG engine<br/>[engine.py]"]
  node_rag_pipeline["Retrieval workflow<br/>[pipeline.py]"]
  node_rag_contracts["Evidence contracts<br/>[contracts.py]"]
  node_rag_budget["Execution budget<br/>[budget.py]"]
  node_rag_context["Context assembly<br/>[context.py]"]
  node_rag_scope["Source scope<br/>[scope.py]"]
  node_model_providers["Model providers"]
end

subgraph group_platform["Learning platform"]
  node_api["FastAPI application<br/>[main.py]"]
  node_learning_records["Learning and review<br/>[review_service.py]"]
  node_task_runtime["Task execution<br/>[job_service.py]"]
  node_mysql[("MySQL records<br/>[db.py]")]
  node_redis[("Redis events<br/>[redis_client.py]")]
end

subgraph group_evaluation["Evaluation workbench"]
  node_eval_ui["Evaluation UI<br/>[RunsPage.tsx]"]
  node_eval_worker["Evaluation worker<br/>[worker.py]"]
  node_eval_contracts["Evaluation contracts<br/>[contracts.py]"]
  node_eval_metrics["Evaluation metrics<br/>[metrics.py]"]
end

node_learner(("Learner"))

node_learner -->|"uses"| node_web
node_web -->|"manages sessions"| node_web_auth
node_web -->|"requests services"| node_api
node_api -->|"routes course work"| node_courses
node_courses -.->|"generates courses"| node_teaching
node_learner -->|"studies lessons"| node_lesson_learning
node_learner -->|"asks questions"| node_qa
node_qa -->|"retrieves evidence"| node_rag_engine
node_rag_engine -->|"runs workflow"| node_rag_pipeline
node_rag_pipeline -->|"exchanges evidence"| node_rag_contracts
node_rag_pipeline -->|"reserves budget"| node_rag_budget
node_rag_pipeline -->|"assembles context"| node_rag_context
node_rag_pipeline -->|"checks scope"| node_rag_scope
node_learner -->|"practices"| node_practice
node_learner -->|"checks outcomes"| node_course_checks
node_practice -.->|"records attempts"| node_learning_records
node_course_checks -.->|"records learning evidence"| node_learning_records
node_api -->|"submits tasks"| node_task_runtime
node_task_runtime -->|"leases and stores"| node_mysql
node_task_runtime -->|"notifies"| node_redis
node_rag_engine -.->|"generates answers"| node_model_providers
node_learner -->|"compares retrieval"| node_eval_ui
node_eval_ui -->|"uses evaluation API"| node_api
node_eval_worker -->|"uses contracts"| node_eval_contracts
node_eval_worker -->|"computes metrics"| node_eval_metrics

click node_web "https://github.com/windfall8623/xunke-ai/blob/main/web/src/app/router.tsx"
click node_web_auth "https://github.com/windfall8623/xunke-ai/blob/main/web/src/app/AuthProvider.tsx"
click node_api "https://github.com/windfall8623/xunke-ai/blob/main/backend/app/main.py"
click node_courses "https://github.com/windfall8623/xunke-ai/blob/main/backend/app/services/course_service.py"
click node_teaching "https://github.com/windfall8623/xunke-ai/blob/main/backend/app/teaching/graph.py"
click node_lesson_learning "https://github.com/windfall8623/xunke-ai/blob/main/backend/app/services/course_read.py"
click node_course_checks "https://github.com/windfall8623/xunke-ai/blob/main/backend/app/services/course_assessment_service.py"
click node_qa "https://github.com/windfall8623/xunke-ai/blob/main/backend/app/qa/pipeline.py"
click node_rag_engine "https://github.com/windfall8623/xunke-ai/blob/main/backend/app/rag/engine.py"
click node_rag_pipeline "https://github.com/windfall8623/xunke-ai/blob/main/backend/app/rag/pipeline.py"
click node_rag_contracts "https://github.com/windfall8623/xunke-ai/blob/main/backend/app/rag/contracts.py"
click node_rag_budget "https://github.com/windfall8623/xunke-ai/blob/main/backend/app/rag/budget.py"
click node_rag_context "https://github.com/windfall8623/xunke-ai/blob/main/backend/app/rag/context.py"
click node_rag_scope "https://github.com/windfall8623/xunke-ai/blob/main/backend/app/rag/scope.py"
click node_practice "https://github.com/windfall8623/xunke-ai/blob/main/backend/app/practice/pipeline.py"
click node_learning_records "https://github.com/windfall8623/xunke-ai/blob/main/backend/app/services/review_service.py"
click node_task_runtime "https://github.com/windfall8623/xunke-ai/blob/main/backend/app/services/job_service.py"
click node_mysql "https://github.com/windfall8623/xunke-ai/blob/main/backend/app/core/db.py"
click node_redis "https://github.com/windfall8623/xunke-ai/blob/main/backend/app/core/redis_client.py"
click node_model_providers "https://github.com/windfall8623/xunke-ai/blob/main/backend/app/llm/langchain_factory.py"
click node_eval_ui "https://github.com/windfall8623/xunke-ai/blob/main/web/src/pages/evaluation/RunsPage.tsx"
click node_eval_worker "https://github.com/windfall8623/xunke-ai/blob/main/evaluation/rag_eval/worker.py"
click node_eval_contracts "https://github.com/windfall8623/xunke-ai/blob/main/evaluation/rag_eval/contracts.py"
click node_eval_metrics "https://github.com/windfall8623/xunke-ai/blob/main/evaluation/rag_eval/metrics.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_web_auth toneBlue
class node_courses,node_teaching,node_lesson_learning,node_course_checks,node_practice toneAmber
class node_qa,node_rag_engine,node_rag_pipeline,node_rag_contracts,node_rag_budget,node_rag_context,node_rag_scope,node_model_providers toneMint
class node_api,node_learning_records,node_task_runtime,node_mysql,node_redis toneRose
class node_eval_ui,node_eval_worker,node_eval_contracts,node_eval_metrics,node_learner toneIndigo
```

## Components

### Learner experience

- [Web application](https://github.com/windfall8623/xunke-ai/blob/main/web/src/app/router.tsx): `web/src/app/router.tsx`
- [Session and API client](https://github.com/windfall8623/xunke-ai/blob/main/web/src/app/AuthProvider.tsx): `web/src/app/AuthProvider.tsx`

### Course learning

- [Course services](https://github.com/windfall8623/xunke-ai/blob/main/backend/app/services/course_service.py): `backend/app/services/course_service.py`
- [Teaching agent](https://github.com/windfall8623/xunke-ai/blob/main/backend/app/teaching/graph.py): `backend/app/teaching/graph.py`
- [Lesson study](https://github.com/windfall8623/xunke-ai/blob/main/backend/app/services/course_read.py): `backend/app/services/course_read.py`
- [Course assessments](https://github.com/windfall8623/xunke-ai/blob/main/backend/app/services/course_assessment_service.py): `backend/app/services/course_assessment_service.py`
- [Practice generation](https://github.com/windfall8623/xunke-ai/blob/main/backend/app/practice/pipeline.py): `backend/app/practice/pipeline.py`

### Knowledge and agents

- [Document Q&A](https://github.com/windfall8623/xunke-ai/blob/main/backend/app/qa/pipeline.py): `backend/app/qa/pipeline.py`
- [RAG engine](https://github.com/windfall8623/xunke-ai/blob/main/backend/app/rag/engine.py): `backend/app/rag/engine.py`
- [Retrieval workflow](https://github.com/windfall8623/xunke-ai/blob/main/backend/app/rag/pipeline.py): `backend/app/rag/pipeline.py`
- [Evidence contracts](https://github.com/windfall8623/xunke-ai/blob/main/backend/app/rag/contracts.py): `backend/app/rag/contracts.py`
- [Execution budget](https://github.com/windfall8623/xunke-ai/blob/main/backend/app/rag/budget.py): `backend/app/rag/budget.py`
- [Context assembly](https://github.com/windfall8623/xunke-ai/blob/main/backend/app/rag/context.py): `backend/app/rag/context.py`
- [Source scope](https://github.com/windfall8623/xunke-ai/blob/main/backend/app/rag/scope.py): `backend/app/rag/scope.py`
- [Model providers](https://github.com/windfall8623/xunke-ai/blob/main/backend/app/llm/langchain_factory.py): `backend/app/llm/langchain_factory.py`

### Learning platform

- [FastAPI application](https://github.com/windfall8623/xunke-ai/blob/main/backend/app/main.py): `backend/app/main.py`
- [Learning and review](https://github.com/windfall8623/xunke-ai/blob/main/backend/app/services/review_service.py): `backend/app/services/review_service.py`
- [Task execution](https://github.com/windfall8623/xunke-ai/blob/main/backend/app/services/job_service.py): `backend/app/services/job_service.py`
- [MySQL records](https://github.com/windfall8623/xunke-ai/blob/main/backend/app/core/db.py): `backend/app/core/db.py`
- [Redis events](https://github.com/windfall8623/xunke-ai/blob/main/backend/app/core/redis_client.py): `backend/app/core/redis_client.py`

### Evaluation workbench

- [Evaluation UI](https://github.com/windfall8623/xunke-ai/blob/main/web/src/pages/evaluation/RunsPage.tsx): `web/src/pages/evaluation/RunsPage.tsx`
- [Evaluation worker](https://github.com/windfall8623/xunke-ai/blob/main/evaluation/rag_eval/worker.py): `evaluation/rag_eval/worker.py`
- [Evaluation contracts](https://github.com/windfall8623/xunke-ai/blob/main/evaluation/rag_eval/contracts.py): `evaluation/rag_eval/contracts.py`
- [Evaluation metrics](https://github.com/windfall8623/xunke-ai/blob/main/evaluation/rag_eval/metrics.py): `evaluation/rag_eval/metrics.py`

### Other components

- **Learner**

## Connections

- Learner → Web application: uses (evidence: `README.md`)
- Web application → Session and API client: manages sessions (evidence: `web/src/app/router.tsx`)
- Web application → FastAPI application: requests services (evidence: `README.md`)
- FastAPI application → Course services: routes course work (evidence: `backend/app/main.py`)
- Course services → Teaching agent: generates courses (evidence: `README.md`)
- Learner → Lesson study: studies lessons (evidence: `README.md`)
- Learner → Document Q&A: asks questions (evidence: `README.md`)
- Document Q&A → RAG engine: retrieves evidence (evidence: `backend/app/rag/engine.py`)
- RAG engine → Retrieval workflow: runs workflow (evidence: `backend/app/rag/engine.py`)
- Retrieval workflow → Evidence contracts: exchanges evidence (evidence: `backend/app/rag/pipeline.py`)
- Retrieval workflow → Execution budget: reserves budget (evidence: `backend/app/rag/pipeline.py`)
- Retrieval workflow → Context assembly: assembles context (evidence: `backend/app/rag/pipeline.py`)
- Retrieval workflow → Source scope: checks scope (evidence: `backend/app/rag/pipeline.py`)
- Learner → Practice generation: practices (evidence: `README.md`)
- Learner → Course assessments: checks outcomes (evidence: `README.md`)
- Practice generation → Learning and review: records attempts (evidence: `README.md`)
- Course assessments → Learning and review: records learning evidence (evidence: `README.md`)
- FastAPI application → Task execution: submits tasks (evidence: `README.md`)
- Task execution → MySQL records: leases and stores (evidence: `README.md`)
- Task execution → Redis events: notifies (evidence: `README.md`)
- RAG engine → Model providers: generates answers (evidence: `README.md`)
- Learner → Evaluation UI: compares retrieval (evidence: `README.md`)
- Evaluation UI → FastAPI application: uses evaluation API (evidence: `README.md`)
- Evaluation worker → Evaluation contracts: uses contracts (evidence: `evaluation/rag_eval/worker.py`)
- Evaluation worker → Evaluation metrics: computes metrics (evidence: `evaluation/rag_eval/worker.py`)