# freger-ucu/ai-tutor architecture

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

- Interactive diagram: https://gitdiagram.com/freger-ucu/ai-tutor
- Repository: https://github.com/freger-ucu/ai-tutor

## Overview

AI Tutor is a React/FastAPI learning platform: students request answer feedback and learning support, while teachers generate notes, tests, and recommendations adapted to student performance. The backend exposes role-based APIs and LangGraph learning flows, with textbook-grounded retrieval and configurable LLM access. The frontend presents role-specific pages and keeps some materials and recommendations in browser storage. The tree and excerpts support the main subsystems; some endpoint-to-flow wiring is inferred only at the documented product-capability level, so uncertain internal links are omitted.

Main entry points: [`backend/app/rag/utils/llm_client.py`](https://github.com/freger-ucu/ai-tutor/blob/main/backend/app/rag/utils/llm_client.py) (LLM client), [`frontend/src/pages`](https://github.com/freger-ucu/ai-tutor/tree/main/frontend/src/pages) (Teacher pages), [`backend/app/api/v1/student.py`](https://github.com/freger-ucu/ai-tutor/blob/main/backend/app/api/v1/student.py) (Student endpoints), [`frontend/src/App.tsx`](https://github.com/freger-ucu/ai-tutor/blob/main/frontend/src/App.tsx) (Web application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Learning interface"]
  node_webapp["Web application<br/>[App.tsx]"]
  node_studentpages["Student pages"]
  node_teacherpages["Teacher pages"]
  node_frontendapi["Role API clients"]
  node_httpclient["HTTP client<br/>[client.ts]"]
end

subgraph group_api["Application API"]
  node_backend["FastAPI application<br/>[main.py]"]
  node_apirouter["API router<br/>[router.py]"]
  node_studentapi["Student endpoints<br/>[student.py]"]
  node_teacherapi["Teacher endpoints<br/>[teacher.py]"]
end

subgraph group_learning["Learning workflows"]
  node_checkflow["Answer checking<br/>[check_answer.py]"]
  node_feedbackflow["Answer feedback<br/>[feedback.py]"]
  node_notesflow["Note generation<br/>[notes.py]"]
  node_recommendflow["Recommendations<br/>[recommendation.py]"]
  node_solver["Test solving<br/>[solver.py]"]
end

subgraph group_knowledge["Knowledge and AI"]
  node_ragshared["Workflow retrieval<br/>[rag_node.py]"]
  node_ragagent["Agentic retrieval<br/>[graph.py]"]
  node_smartretrieve["Smart retrieval<br/>[smart_retrieve.py]"]
  node_retrievaltools["Retrieval components"]
  node_llm["LLM client<br/>[llm_client.py]"]
  node_textbooks[("Textbook embeddings")]
end

subgraph group_state["Learning data"]
  node_browserdata[("Browser storage")]
  node_materials["Materials storage"]
  node_recommendations["Recommendation storage"]
  node_studentdata[("Student performance data")]
end

node_student(("Student"))
node_teacher(("Teacher"))
node_llmproviders{{"LLM providers"}}

node_student -->|"uses"| node_webapp
node_teacher -->|"uses"| node_webapp
node_webapp -->|"routes to"| node_studentpages
node_webapp -->|"routes to"| node_teacherpages
node_studentpages -->|"requests"| node_frontendapi
node_teacherpages -->|"requests"| node_frontendapi
node_frontendapi -->|"calls"| node_httpclient
node_httpclient -->|"HTTP requests"| node_backend
node_backend -->|"mounts"| node_apirouter
node_apirouter -->|"dispatches"| node_studentapi
node_apirouter -->|"dispatches"| node_teacherapi
node_studentapi -->|"runs checking"| node_checkflow
node_studentapi -->|"requests feedback"| node_feedbackflow
node_studentapi -->|"requests analysis"| node_solver
node_teacherapi -->|"generates notes"| node_notesflow
node_teacherapi -->|"generates recommendations"| node_recommendflow
node_checkflow -->|"retrieves context"| node_ragshared
node_feedbackflow -->|"retrieves context"| node_ragshared
node_notesflow -->|"retrieves context"| node_ragshared
node_ragshared -->|"searches"| node_retrievaltools
node_ragagent -->|"dispatches retrieval"| node_smartretrieve
node_smartretrieve -->|"uses"| node_retrievaltools
node_retrievaltools -->|"reads embeddings"| node_textbooks
node_checkflow -->|"requests generation"| node_llm
node_feedbackflow -->|"requests generation"| node_llm
node_notesflow -->|"requests generation"| node_llm
node_recommendflow -->|"requests generation"| node_llm
node_llm -->|"calls"| node_llmproviders
node_teacherpages -->|"manages materials"| node_materials
node_studentpages -->|"reads assigned materials"| node_materials
node_teacherpages -->|"saves recommendations"| node_recommendations
node_materials -->|"reads and writes"| node_browserdata
node_recommendations -->|"reads and writes"| node_browserdata
node_recommendflow -->|"uses performance data"| node_studentdata

click node_webapp "https://github.com/freger-ucu/ai-tutor/blob/main/frontend/src/App.tsx"
click node_studentpages "https://github.com/freger-ucu/ai-tutor/tree/main/frontend/src/pages"
click node_teacherpages "https://github.com/freger-ucu/ai-tutor/tree/main/frontend/src/pages"
click node_frontendapi "https://github.com/freger-ucu/ai-tutor/tree/main/frontend/src/api"
click node_httpclient "https://github.com/freger-ucu/ai-tutor/blob/main/frontend/src/api/client.ts"
click node_backend "https://github.com/freger-ucu/ai-tutor/blob/main/backend/app/main.py"
click node_apirouter "https://github.com/freger-ucu/ai-tutor/blob/main/backend/app/api/v1/router.py"
click node_studentapi "https://github.com/freger-ucu/ai-tutor/blob/main/backend/app/api/v1/student.py"
click node_teacherapi "https://github.com/freger-ucu/ai-tutor/blob/main/backend/app/api/v1/teacher.py"
click node_checkflow "https://github.com/freger-ucu/ai-tutor/blob/main/backend/app/graph/flows/check_answer.py"
click node_feedbackflow "https://github.com/freger-ucu/ai-tutor/blob/main/backend/app/graph/flows/feedback.py"
click node_notesflow "https://github.com/freger-ucu/ai-tutor/blob/main/backend/app/graph/flows/notes.py"
click node_recommendflow "https://github.com/freger-ucu/ai-tutor/blob/main/backend/app/graph/flows/recommendation.py"
click node_solver "https://github.com/freger-ucu/ai-tutor/blob/main/backend/app/services/solver.py"
click node_ragshared "https://github.com/freger-ucu/ai-tutor/blob/main/backend/app/graph/shared/rag_node.py"
click node_ragagent "https://github.com/freger-ucu/ai-tutor/blob/main/backend/app/rag/graph.py"
click node_smartretrieve "https://github.com/freger-ucu/ai-tutor/blob/main/backend/app/rag/nodes/smart_retrieve.py"
click node_retrievaltools "https://github.com/freger-ucu/ai-tutor/tree/main/backend/app/rag/utils"
click node_llm "https://github.com/freger-ucu/ai-tutor/blob/main/backend/app/rag/utils/llm_client.py"
click node_textbooks "https://github.com/freger-ucu/ai-tutor/tree/main/backend/app/rag"
click node_materials "https://github.com/freger-ucu/ai-tutor/blob/main/frontend/src/data/materialsStorage.ts"
click node_recommendations "https://github.com/freger-ucu/ai-tutor/blob/main/frontend/src/data/recommendationsStorage.ts"
click node_studentdata "https://github.com/freger-ucu/ai-tutor/tree/main/backend/app/services"

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_studentpages,node_teacherpages,node_frontendapi,node_httpclient toneBlue
class node_backend,node_apirouter,node_studentapi,node_teacherapi toneAmber
class node_checkflow,node_feedbackflow,node_notesflow,node_recommendflow,node_solver toneMint
class node_ragshared,node_ragagent,node_smartretrieve,node_retrievaltools,node_llm,node_textbooks toneRose
class node_browserdata,node_materials,node_recommendations,node_studentdata,node_student,node_teacher,node_llmproviders toneIndigo
```

## Components

### Learning interface

- [Web application](https://github.com/freger-ucu/ai-tutor/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Student pages](https://github.com/freger-ucu/ai-tutor/tree/main/frontend/src/pages): `frontend/src/pages`
- [Teacher pages](https://github.com/freger-ucu/ai-tutor/tree/main/frontend/src/pages): `frontend/src/pages`
- [Role API clients](https://github.com/freger-ucu/ai-tutor/tree/main/frontend/src/api): `frontend/src/api`
- [HTTP client](https://github.com/freger-ucu/ai-tutor/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`

### Application API

- [FastAPI application](https://github.com/freger-ucu/ai-tutor/blob/main/backend/app/main.py): `backend/app/main.py`
- [API router](https://github.com/freger-ucu/ai-tutor/blob/main/backend/app/api/v1/router.py): `backend/app/api/v1/router.py`
- [Student endpoints](https://github.com/freger-ucu/ai-tutor/blob/main/backend/app/api/v1/student.py): `backend/app/api/v1/student.py`
- [Teacher endpoints](https://github.com/freger-ucu/ai-tutor/blob/main/backend/app/api/v1/teacher.py): `backend/app/api/v1/teacher.py`

### Learning workflows

- [Answer checking](https://github.com/freger-ucu/ai-tutor/blob/main/backend/app/graph/flows/check_answer.py): `backend/app/graph/flows/check_answer.py`
- [Answer feedback](https://github.com/freger-ucu/ai-tutor/blob/main/backend/app/graph/flows/feedback.py): `backend/app/graph/flows/feedback.py`
- [Note generation](https://github.com/freger-ucu/ai-tutor/blob/main/backend/app/graph/flows/notes.py): `backend/app/graph/flows/notes.py`
- [Recommendations](https://github.com/freger-ucu/ai-tutor/blob/main/backend/app/graph/flows/recommendation.py): `backend/app/graph/flows/recommendation.py`
- [Test solving](https://github.com/freger-ucu/ai-tutor/blob/main/backend/app/services/solver.py): `backend/app/services/solver.py`

### Knowledge and AI

- [Workflow retrieval](https://github.com/freger-ucu/ai-tutor/blob/main/backend/app/graph/shared/rag_node.py): `backend/app/graph/shared/rag_node.py`
- [Agentic retrieval](https://github.com/freger-ucu/ai-tutor/blob/main/backend/app/rag/graph.py): `backend/app/rag/graph.py`
- [Smart retrieval](https://github.com/freger-ucu/ai-tutor/blob/main/backend/app/rag/nodes/smart_retrieve.py): `backend/app/rag/nodes/smart_retrieve.py`
- [Retrieval components](https://github.com/freger-ucu/ai-tutor/tree/main/backend/app/rag/utils): `backend/app/rag/utils`
- [LLM client](https://github.com/freger-ucu/ai-tutor/blob/main/backend/app/rag/utils/llm_client.py): `backend/app/rag/utils/llm_client.py`
- [Textbook embeddings](https://github.com/freger-ucu/ai-tutor/tree/main/backend/app/rag): `backend/app/rag`

### Learning data

- **Browser storage**
- [Materials storage](https://github.com/freger-ucu/ai-tutor/blob/main/frontend/src/data/materialsStorage.ts): `frontend/src/data/materialsStorage.ts`
- [Recommendation storage](https://github.com/freger-ucu/ai-tutor/blob/main/frontend/src/data/recommendationsStorage.ts): `frontend/src/data/recommendationsStorage.ts`
- [Student performance data](https://github.com/freger-ucu/ai-tutor/tree/main/backend/app/services): `backend/app/services`

### Other components

- **Student**
- **Teacher**
- **LLM providers**

## Connections

- Student → Web application: uses
- Teacher → Web application: uses
- Web application → Student pages: routes to
- Web application → Teacher pages: routes to
- Student pages → Role API clients: requests
- Teacher pages → Role API clients: requests
- Role API clients → HTTP client: calls
- HTTP client → FastAPI application: HTTP requests
- FastAPI application → API router: mounts
- API router → Student endpoints: dispatches
- API router → Teacher endpoints: dispatches
- Student endpoints → Answer checking: runs checking
- Student endpoints → Answer feedback: requests feedback
- Student endpoints → Test solving: requests analysis
- Teacher endpoints → Note generation: generates notes
- Teacher endpoints → Recommendations: generates recommendations
- Answer checking → Workflow retrieval: retrieves context
- Answer feedback → Workflow retrieval: retrieves context
- Note generation → Workflow retrieval: retrieves context
- Workflow retrieval → Retrieval components: searches
- Agentic retrieval → Smart retrieval: dispatches retrieval
- Smart retrieval → Retrieval components: uses
- Retrieval components → Textbook embeddings: reads embeddings
- Answer checking → LLM client: requests generation
- Answer feedback → LLM client: requests generation
- Note generation → LLM client: requests generation
- Recommendations → LLM client: requests generation
- LLM client → LLM providers: calls
- Teacher pages → Materials storage: manages materials
- Student pages → Materials storage: reads assigned materials
- Teacher pages → Recommendation storage: saves recommendations
- Materials storage → Browser storage: reads and writes
- Recommendation storage → Browser storage: reads and writes
- Recommendations → Student performance data: uses performance data