# sampreethg/ai-teacher-hackathon architecture

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

- Interactive diagram: https://gitdiagram.com/sampreethg/ai-teacher-hackathon
- Repository: https://github.com/sampreethg/ai-teacher-hackathon

## Overview

AI Teacher combines a learning studio and classroom with a Python teaching API and a separate live-avatar experience. The student-facing path runs from studio/classroom interaction through lesson, chat, or answer evaluation to the teaching engine’s adaptive response; the avatar path establishes a session and speaks lesson text. The tree and excerpts support key API-to-engine calls and avatar-session wiring, but not every UI-to-API request or persistence mechanism, so those links are omitted rather than inferred.

Main entry points: [`AI_Teacher/AI_Teacher/api/main.py`](https://github.com/sampreethg/ai-teacher-hackathon/blob/master/AI_Teacher/AI_Teacher/api/main.py) (Teaching API), [`app/studio/page.tsx`](https://github.com/sampreethg/ai-teacher-hackathon/blob/master/app/studio/page.tsx) (Lesson studio), [`ai-teacher-avatar/src/App.tsx`](https://github.com/sampreethg/ai-teacher-hackathon/blob/master/ai-teacher-avatar/src/App.tsx) (Avatar experience), [`ai-teacher-avatar/src/services/liveAvatarSession.ts`](https://github.com/sampreethg/ai-teacher-hackathon/blob/master/ai-teacher-avatar/src/services/liveAvatarSession.ts) (Session controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_learning_ui["Learning experience"]
  node_studio["Lesson studio<br/>[page.tsx]"]
  node_classroom["AI classroom<br/>[page.tsx]"]
  node_source_upload["Source upload<br/>[AddSourceModal.tsx]"]
  node_auth["Authentication<br/>[AuthCard.tsx]"]
  node_profile["Profile menu"]
end

subgraph group_teaching_api["Teaching API"]
  node_chat_api["Chat endpoint<br/>[route.ts]"]
  node_lesson_api["Lesson endpoint<br/>[route.ts]"]
  node_upload_api["Upload endpoint<br/>[route.ts]"]
  node_python_api["Teaching API<br/>[main.py]"]
end

subgraph group_teaching_engine["Teaching engine"]
  node_lesson_generation["Lesson generation"]
  node_question_generation["Question generation"]
  node_answer_evaluation["Answer evaluation"]
  node_adaptation["Adaptive decisions<br/>[adaptive_engine.py]"]
end

subgraph group_avatar["Live avatar"]
  node_avatar_ui["Avatar experience<br/>[App.tsx]"]
  node_session_controller["Session controller"]
  node_avatar_client["Avatar API client<br/>[avatarApi.ts]"]
  node_avatar_backend["Avatar routes<br/>[avatar.js]"]
  node_avatar_server["Avatar server<br/>[server.js]"]
  node_voice_config["Voice configuration<br/>[voices.ts]"]
  node_avatar_component["Avatar display"]
end

node_teacher(("Student / teacher"))
node_avatar_provider["LiveAvatar service"]

node_teacher -->|"works in"| node_studio
node_teacher -->|"learns in"| node_classroom
node_teacher -->|"signs in"| node_auth
node_studio -->|"opens"| node_source_upload
node_studio -.-> node_lesson_api
node_studio -.-> node_chat_api
node_classroom -.-> node_python_api
node_source_upload -.-> node_upload_api
node_lesson_api -.-> node_python_api
node_chat_api -.-> node_python_api
node_python_api -->|"generates lesson"| node_lesson_generation
node_python_api -->|"evaluates answer"| node_answer_evaluation
node_python_api -->|"chooses next step"| node_adaptation
node_python_api -->|"generates questions"| node_question_generation
node_avatar_ui -->|"starts and controls"| node_session_controller
node_avatar_ui -->|"renders"| node_avatar_component
node_avatar_ui -.-> node_voice_config
node_session_controller -->|"requests session"| node_avatar_client
node_avatar_client -.-> node_avatar_backend
node_avatar_server -->|"mounts routes"| node_avatar_backend
node_avatar_backend -.-> node_avatar_provider
node_session_controller -->|"starts session"| node_avatar_provider

click node_studio "https://github.com/sampreethg/ai-teacher-hackathon/blob/master/app/studio/page.tsx"
click node_classroom "https://github.com/sampreethg/ai-teacher-hackathon/blob/master/app/classroom/page.tsx"
click node_source_upload "https://github.com/sampreethg/ai-teacher-hackathon/blob/master/components/dashboard/AddSourceModal.tsx"
click node_auth "https://github.com/sampreethg/ai-teacher-hackathon/blob/master/components/AuthCard.tsx"
click node_profile "https://github.com/sampreethg/ai-teacher-hackathon/blob/master/components/navigation/UserProfileMenu.tsx"
click node_chat_api "https://github.com/sampreethg/ai-teacher-hackathon/blob/master/app/api/chat/route.ts"
click node_lesson_api "https://github.com/sampreethg/ai-teacher-hackathon/blob/master/app/api/generate-lesson/route.ts"
click node_upload_api "https://github.com/sampreethg/ai-teacher-hackathon/blob/master/app/api/upload/route.ts"
click node_python_api "https://github.com/sampreethg/ai-teacher-hackathon/blob/master/AI_Teacher/AI_Teacher/api/main.py"
click node_lesson_generation "https://github.com/sampreethg/ai-teacher-hackathon/blob/master/AI_Teacher/AI_Teacher/ai_engine/lesson_generator.py"
click node_question_generation "https://github.com/sampreethg/ai-teacher-hackathon/blob/master/AI_Teacher/AI_Teacher/ai_engine/question_generator.py"
click node_answer_evaluation "https://github.com/sampreethg/ai-teacher-hackathon/blob/master/AI_Teacher/AI_Teacher/ai_engine/answer_evaluator.py"
click node_adaptation "https://github.com/sampreethg/ai-teacher-hackathon/blob/master/AI_Teacher/AI_Teacher/ai_engine/adaptive_engine.py"
click node_avatar_ui "https://github.com/sampreethg/ai-teacher-hackathon/blob/master/ai-teacher-avatar/src/App.tsx"
click node_session_controller "https://github.com/sampreethg/ai-teacher-hackathon/blob/master/ai-teacher-avatar/src/services/liveAvatarSession.ts"
click node_avatar_client "https://github.com/sampreethg/ai-teacher-hackathon/blob/master/ai-teacher-avatar/src/services/avatarApi.ts"
click node_avatar_backend "https://github.com/sampreethg/ai-teacher-hackathon/blob/master/ai-teacher-avatar/backend/routes/avatar.js"
click node_avatar_server "https://github.com/sampreethg/ai-teacher-hackathon/blob/master/ai-teacher-avatar/backend/server.js"
click node_voice_config "https://github.com/sampreethg/ai-teacher-hackathon/blob/master/lib/config/voices.ts"
click node_avatar_component "https://github.com/sampreethg/ai-teacher-hackathon/blob/master/ai-teacher-avatar/src/components/AITeacherAvatar.tsx"

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_studio,node_classroom,node_source_upload,node_auth,node_profile toneBlue
class node_chat_api,node_lesson_api,node_upload_api,node_python_api toneAmber
class node_lesson_generation,node_question_generation,node_answer_evaluation,node_adaptation toneMint
class node_avatar_ui,node_session_controller,node_avatar_client,node_avatar_backend,node_avatar_server,node_voice_config,node_avatar_component toneRose
class node_teacher,node_avatar_provider toneIndigo
```

## Components

### Learning experience

- [Lesson studio](https://github.com/sampreethg/ai-teacher-hackathon/blob/master/app/studio/page.tsx): `app/studio/page.tsx`
- [AI classroom](https://github.com/sampreethg/ai-teacher-hackathon/blob/master/app/classroom/page.tsx): `app/classroom/page.tsx`
- [Source upload](https://github.com/sampreethg/ai-teacher-hackathon/blob/master/components/dashboard/AddSourceModal.tsx): `components/dashboard/AddSourceModal.tsx`
- [Authentication](https://github.com/sampreethg/ai-teacher-hackathon/blob/master/components/AuthCard.tsx): `components/AuthCard.tsx`
- [Profile menu](https://github.com/sampreethg/ai-teacher-hackathon/blob/master/components/navigation/UserProfileMenu.tsx): `components/navigation/UserProfileMenu.tsx`

### Teaching API

- [Chat endpoint](https://github.com/sampreethg/ai-teacher-hackathon/blob/master/app/api/chat/route.ts): `app/api/chat/route.ts`
- [Lesson endpoint](https://github.com/sampreethg/ai-teacher-hackathon/blob/master/app/api/generate-lesson/route.ts): `app/api/generate-lesson/route.ts`
- [Upload endpoint](https://github.com/sampreethg/ai-teacher-hackathon/blob/master/app/api/upload/route.ts): `app/api/upload/route.ts`
- [Teaching API](https://github.com/sampreethg/ai-teacher-hackathon/blob/master/AI_Teacher/AI_Teacher/api/main.py): `AI_Teacher/AI_Teacher/api/main.py`

### Teaching engine

- [Lesson generation](https://github.com/sampreethg/ai-teacher-hackathon/blob/master/AI_Teacher/AI_Teacher/ai_engine/lesson_generator.py): `AI_Teacher/AI_Teacher/ai_engine/lesson_generator.py`
- [Question generation](https://github.com/sampreethg/ai-teacher-hackathon/blob/master/AI_Teacher/AI_Teacher/ai_engine/question_generator.py): `AI_Teacher/AI_Teacher/ai_engine/question_generator.py`
- [Answer evaluation](https://github.com/sampreethg/ai-teacher-hackathon/blob/master/AI_Teacher/AI_Teacher/ai_engine/answer_evaluator.py): `AI_Teacher/AI_Teacher/ai_engine/answer_evaluator.py`
- [Adaptive decisions](https://github.com/sampreethg/ai-teacher-hackathon/blob/master/AI_Teacher/AI_Teacher/ai_engine/adaptive_engine.py): `AI_Teacher/AI_Teacher/ai_engine/adaptive_engine.py`

### Live avatar

- [Avatar experience](https://github.com/sampreethg/ai-teacher-hackathon/blob/master/ai-teacher-avatar/src/App.tsx): `ai-teacher-avatar/src/App.tsx`
- [Session controller](https://github.com/sampreethg/ai-teacher-hackathon/blob/master/ai-teacher-avatar/src/services/liveAvatarSession.ts): `ai-teacher-avatar/src/services/liveAvatarSession.ts`
- [Avatar API client](https://github.com/sampreethg/ai-teacher-hackathon/blob/master/ai-teacher-avatar/src/services/avatarApi.ts): `ai-teacher-avatar/src/services/avatarApi.ts`
- [Avatar routes](https://github.com/sampreethg/ai-teacher-hackathon/blob/master/ai-teacher-avatar/backend/routes/avatar.js): `ai-teacher-avatar/backend/routes/avatar.js`
- [Avatar server](https://github.com/sampreethg/ai-teacher-hackathon/blob/master/ai-teacher-avatar/backend/server.js): `ai-teacher-avatar/backend/server.js`
- [Voice configuration](https://github.com/sampreethg/ai-teacher-hackathon/blob/master/lib/config/voices.ts): `lib/config/voices.ts`
- [Avatar display](https://github.com/sampreethg/ai-teacher-hackathon/blob/master/ai-teacher-avatar/src/components/AITeacherAvatar.tsx): `ai-teacher-avatar/src/components/AITeacherAvatar.tsx`

### Other components

- **Student / teacher**
- **LiveAvatar service**

## Connections

- Student / teacher → Lesson studio: works in (evidence: `app/studio/page.tsx`)
- Student / teacher → AI classroom: learns in (evidence: `app/classroom/page.tsx`)
- Student / teacher → Authentication: signs in (evidence: `components/AuthCard.tsx`)
- Lesson studio → Source upload: opens (evidence: `app/studio/page.tsx`)
- Lesson studio → Lesson endpoint
- Lesson studio → Chat endpoint
- AI classroom → Teaching API
- Source upload → Upload endpoint
- Lesson endpoint → Teaching API
- Chat endpoint → Teaching API
- Teaching API → Lesson generation: generates lesson (evidence: `AI_Teacher/AI_Teacher/api/main.py`)
- Teaching API → Answer evaluation: evaluates answer (evidence: `AI_Teacher/AI_Teacher/api/main.py`)
- Teaching API → Adaptive decisions: chooses next step (evidence: `AI_Teacher/AI_Teacher/api/main.py`)
- Teaching API → Question generation: generates questions (evidence: `AI_Teacher/AI_Teacher/api/main.py`)
- Avatar experience → Session controller: starts and controls (evidence: `ai-teacher-avatar/src/App.tsx`)
- Avatar experience → Avatar display: renders (evidence: `ai-teacher-avatar/src/App.tsx`)
- Avatar experience → Voice configuration
- Session controller → Avatar API client: requests session (evidence: `ai-teacher-avatar/src/services/liveAvatarSession.ts`)
- Avatar API client → Avatar routes
- Avatar server → Avatar routes: mounts routes (evidence: `ai-teacher-avatar/backend/server.js`)
- Avatar routes → LiveAvatar service
- Session controller → LiveAvatar service: starts session (evidence: `ai-teacher-avatar/src/services/liveAvatarSession.ts`)
