# magnusinst84-sudo/edutrace architecture

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

- Interactive diagram: https://gitdiagram.com/magnusinst84-sudo/edutrace
- Repository: https://github.com/magnusinst84-sudo/edutrace

## Overview

EduTrace is an adaptive learning-path agent: learners choose a topic, complete a diagnostic, receive a level-tailored roadmap, then learn through stateful chat and week-end quizzes. The React client calls the authenticated FastAPI session API; agent handlers coordinate Gemini prompts, roadmap context, world state, and Firestore persistence. The README documents progress views, PDF export, teaching styles, and pacing as product capabilities. Some frontend and integration details are unsampled, so the graph shows only documented or excerpt-supported links.

Main entry points: [`backend/agent/handlers.py`](https://github.com/magnusinst84-sudo/edutrace/blob/main/backend/agent/handlers.py) (Learning handlers), [`frontend/src/api/client.js`](https://github.com/magnusinst84-sudo/edutrace/blob/main/frontend/src/api/client.js) (API client), [`backend/routes/session.py`](https://github.com/magnusinst84-sudo/edutrace/blob/main/backend/routes/session.py) (Session routes), [`frontend/src/pages/Chat.jsx`](https://github.com/magnusinst84-sudo/edutrace/blob/main/frontend/src/pages/Chat.jsx) (Learning chat)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Learner experience"]
  node_app["App routes<br/>[App.jsx]"]
  node_authui["Auth context<br/>[AuthContext.jsx]"]
  node_firebaseui["Firebase client<br/>[firebase.js]"]
  node_topic["Topic dashboard<br/>[Landing.jsx]"]
  node_chat["Learning chat<br/>[Chat.jsx]"]
  node_quizui["Quiz panel<br/>[QuizPanel.jsx]"]
  node_progress["Progress view<br/>[Progress.jsx]"]
  node_pdf["Roadmap PDF export"]
  node_http["API client<br/>[client.js]"]
end

subgraph group_api["Session API"]
  node_backend["FastAPI app<br/>[main.py]"]
  node_routes["Session routes<br/>[session.py]"]
  node_auth["Token verification<br/>[auth.py]"]
  node_sanitize["Input validation<br/>[sanitize.py]"]
end

subgraph group_agent["Learning agent"]
  node_handlers["Learning handlers<br/>[handlers.py]"]
  node_state["World state<br/>[state.py]"]
  node_prompts["Prompt templates<br/>[prompts.py]"]
  node_roadmapdata["Roadmap context<br/>[loader.py]"]
  node_gemini["Gemini models<br/>[gemini.py]"]
end

subgraph group_services["Identity and persistence"]
  node_firebaseinit["Firebase initialization<br/>[firebase_init.py]"]
  node_sessions[("Session persistence<br/>[sessions.py]")]
  node_firestore[("Firestore")]
  node_firebaseauth["Firebase Auth"]
end

node_learner(("Learner"))

node_learner -->|"uses"| node_app
node_app -->|"provides auth"| node_authui
node_authui -->|"observes sign-in"| node_firebaseui
node_firebaseui -.->|"authenticates"| node_firebaseauth
node_learner -->|"chooses topic"| node_topic
node_topic -->|"starts session"| node_http
node_chat -->|"calls API"| node_http
node_quizui -->|"submits quiz"| node_http
node_progress -->|"loads progress"| node_http
node_chat -->|"renders"| node_quizui
node_chat -->|"exports roadmap"| node_pdf
node_http -.->|"HTTP requests"| node_backend
node_http -->|"gets ID token"| node_firebaseauth
node_backend -->|"initializes"| node_firebaseinit
node_backend -->|"mounts routes"| node_routes
node_routes -->|"verifies user"| node_auth
node_routes -->|"validates topic"| node_sanitize
node_routes -->|"dispatches learning"| node_handlers
node_handlers -->|"sanitizes messages"| node_sanitize
node_handlers -->|"hydrates state"| node_state
node_handlers -->|"builds prompts"| node_prompts
node_handlers -->|"loads grounding"| node_roadmapdata
node_handlers -->|"requests generation"| node_gemini
node_handlers -->|"loads and saves"| node_sessions
node_routes -->|"persists sessions"| node_sessions
node_sessions -->|"reads and writes"| node_firestore
node_firebaseinit -.->|"initializes SDK"| node_firebaseauth
node_firebaseinit -.->|"initializes SDK"| node_firestore
node_learner -->|"learns and adapts"| node_chat
node_learner -->|"reviews weeks"| node_progress

click node_app "https://github.com/magnusinst84-sudo/edutrace/blob/main/frontend/src/App.jsx"
click node_authui "https://github.com/magnusinst84-sudo/edutrace/blob/main/frontend/src/context/AuthContext.jsx"
click node_firebaseui "https://github.com/magnusinst84-sudo/edutrace/blob/main/frontend/src/firebase.js"
click node_topic "https://github.com/magnusinst84-sudo/edutrace/blob/main/frontend/src/pages/Landing.jsx"
click node_chat "https://github.com/magnusinst84-sudo/edutrace/blob/main/frontend/src/pages/Chat.jsx"
click node_quizui "https://github.com/magnusinst84-sudo/edutrace/blob/main/frontend/src/components/QuizPanel.jsx"
click node_progress "https://github.com/magnusinst84-sudo/edutrace/blob/main/frontend/src/pages/Progress.jsx"
click node_pdf "https://github.com/magnusinst84-sudo/edutrace/blob/main/frontend/src/utils/exportRoadmapPDF.js"
click node_http "https://github.com/magnusinst84-sudo/edutrace/blob/main/frontend/src/api/client.js"
click node_backend "https://github.com/magnusinst84-sudo/edutrace/blob/main/backend/main.py"
click node_routes "https://github.com/magnusinst84-sudo/edutrace/blob/main/backend/routes/session.py"
click node_auth "https://github.com/magnusinst84-sudo/edutrace/blob/main/backend/middleware/auth.py"
click node_sanitize "https://github.com/magnusinst84-sudo/edutrace/blob/main/backend/middleware/sanitize.py"
click node_handlers "https://github.com/magnusinst84-sudo/edutrace/blob/main/backend/agent/handlers.py"
click node_state "https://github.com/magnusinst84-sudo/edutrace/blob/main/backend/agent/state.py"
click node_prompts "https://github.com/magnusinst84-sudo/edutrace/blob/main/backend/agent/prompts.py"
click node_roadmapdata "https://github.com/magnusinst84-sudo/edutrace/blob/main/backend/agent/loader.py"
click node_gemini "https://github.com/magnusinst84-sudo/edutrace/blob/main/backend/agent/gemini.py"
click node_firebaseinit "https://github.com/magnusinst84-sudo/edutrace/blob/main/backend/utils/firebase_init.py"
click node_sessions "https://github.com/magnusinst84-sudo/edutrace/blob/main/backend/db/sessions.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_app,node_authui,node_firebaseui,node_topic,node_chat,node_quizui,node_progress,node_pdf,node_http toneBlue
class node_backend,node_routes,node_auth,node_sanitize toneAmber
class node_handlers,node_state,node_prompts,node_roadmapdata,node_gemini toneMint
class node_firebaseinit,node_sessions,node_firestore,node_firebaseauth toneRose
class node_learner toneIndigo
```

## Components

### Learner experience

- [App routes](https://github.com/magnusinst84-sudo/edutrace/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Auth context](https://github.com/magnusinst84-sudo/edutrace/blob/main/frontend/src/context/AuthContext.jsx): `frontend/src/context/AuthContext.jsx`
- [Firebase client](https://github.com/magnusinst84-sudo/edutrace/blob/main/frontend/src/firebase.js): `frontend/src/firebase.js`
- [Topic dashboard](https://github.com/magnusinst84-sudo/edutrace/blob/main/frontend/src/pages/Landing.jsx): `frontend/src/pages/Landing.jsx`
- [Learning chat](https://github.com/magnusinst84-sudo/edutrace/blob/main/frontend/src/pages/Chat.jsx): `frontend/src/pages/Chat.jsx`
- [Quiz panel](https://github.com/magnusinst84-sudo/edutrace/blob/main/frontend/src/components/QuizPanel.jsx): `frontend/src/components/QuizPanel.jsx`
- [Progress view](https://github.com/magnusinst84-sudo/edutrace/blob/main/frontend/src/pages/Progress.jsx): `frontend/src/pages/Progress.jsx`
- [Roadmap PDF export](https://github.com/magnusinst84-sudo/edutrace/blob/main/frontend/src/utils/exportRoadmapPDF.js): `frontend/src/utils/exportRoadmapPDF.js`
- [API client](https://github.com/magnusinst84-sudo/edutrace/blob/main/frontend/src/api/client.js): `frontend/src/api/client.js`

### Session API

- [FastAPI app](https://github.com/magnusinst84-sudo/edutrace/blob/main/backend/main.py): `backend/main.py`
- [Session routes](https://github.com/magnusinst84-sudo/edutrace/blob/main/backend/routes/session.py): `backend/routes/session.py`
- [Token verification](https://github.com/magnusinst84-sudo/edutrace/blob/main/backend/middleware/auth.py): `backend/middleware/auth.py`
- [Input validation](https://github.com/magnusinst84-sudo/edutrace/blob/main/backend/middleware/sanitize.py): `backend/middleware/sanitize.py`

### Learning agent

- [Learning handlers](https://github.com/magnusinst84-sudo/edutrace/blob/main/backend/agent/handlers.py): `backend/agent/handlers.py`
- [World state](https://github.com/magnusinst84-sudo/edutrace/blob/main/backend/agent/state.py): `backend/agent/state.py`
- [Prompt templates](https://github.com/magnusinst84-sudo/edutrace/blob/main/backend/agent/prompts.py): `backend/agent/prompts.py`
- [Roadmap context](https://github.com/magnusinst84-sudo/edutrace/blob/main/backend/agent/loader.py): `backend/agent/loader.py`
- [Gemini models](https://github.com/magnusinst84-sudo/edutrace/blob/main/backend/agent/gemini.py): `backend/agent/gemini.py`

### Identity and persistence

- [Firebase initialization](https://github.com/magnusinst84-sudo/edutrace/blob/main/backend/utils/firebase_init.py): `backend/utils/firebase_init.py`
- [Session persistence](https://github.com/magnusinst84-sudo/edutrace/blob/main/backend/db/sessions.py): `backend/db/sessions.py`
- **Firestore**
- **Firebase Auth**

### Other components

- **Learner**

## Connections

- Learner → App routes: uses (evidence: `frontend/src/App.jsx`)
- App routes → Auth context: provides auth (evidence: `frontend/src/App.jsx`)
- Auth context → Firebase client: observes sign-in (evidence: `frontend/src/context/AuthContext.jsx`)
- Firebase client → Firebase Auth: authenticates
- Learner → Topic dashboard: chooses topic
- Topic dashboard → API client: starts session (evidence: `frontend/src/pages/Landing.jsx`)
- Learning chat → API client: calls API (evidence: `frontend/src/pages/Chat.jsx`)
- Quiz panel → API client: submits quiz (evidence: `frontend/src/components/QuizPanel.jsx`)
- Progress view → API client: loads progress (evidence: `frontend/src/pages/Progress.jsx`)
- Learning chat → Quiz panel: renders (evidence: `frontend/src/pages/Chat.jsx`)
- Learning chat → Roadmap PDF export: exports roadmap (evidence: `frontend/src/pages/Chat.jsx`)
- API client → FastAPI app: HTTP requests
- API client → Firebase Auth: gets ID token (evidence: `frontend/src/api/client.js`)
- FastAPI app → Firebase initialization: initializes (evidence: `backend/main.py`)
- FastAPI app → Session routes: mounts routes (evidence: `backend/main.py`)
- Session routes → Token verification: verifies user (evidence: `backend/routes/session.py`)
- Session routes → Input validation: validates topic (evidence: `backend/routes/session.py`)
- Session routes → Learning handlers: dispatches learning (evidence: `backend/routes/session.py`)
- Learning handlers → Input validation: sanitizes messages (evidence: `backend/agent/handlers.py`)
- Learning handlers → World state: hydrates state (evidence: `backend/agent/handlers.py`)
- Learning handlers → Prompt templates: builds prompts (evidence: `backend/agent/handlers.py`)
- Learning handlers → Roadmap context: loads grounding (evidence: `backend/agent/handlers.py`)
- Learning handlers → Gemini models: requests generation (evidence: `backend/agent/handlers.py`)
- Learning handlers → Session persistence: loads and saves (evidence: `backend/agent/handlers.py`)
- Session routes → Session persistence: persists sessions (evidence: `backend/routes/session.py`)
- Session persistence → Firestore: reads and writes (evidence: `backend/db/sessions.py`)
- Firebase initialization → Firebase Auth: initializes SDK
- Firebase initialization → Firestore: initializes SDK
- Learner → Learning chat: learns and adapts
- Learner → Progress view: reviews weeks
