# priyanshu2705-hub/ustaad-ai-teacher architecture

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

- Interactive diagram: https://gitdiagram.com/priyanshu2705-hub/ustaad-ai-teacher
- Repository: https://github.com/priyanshu2705-hub/ustaad-ai-teacher

## Overview

This is a browser-based AI learning app: a learner supplies a topic or study material, receives an interactive lesson, answers questions, and can ask follow-up doubts. The frontend also provides spoken interaction, voice selection, an animated avatar, and visual renderers. Flask serves the page and exposes a generation endpoint that calls Gemini with model fallbacks. The frontend and backend excerpts support the main request path; detailed links for some lesson interactions are not visible in the partial JavaScript excerpt.

Main entry points: [`static/app.js`](https://github.com/priyanshu2705-hub/ustaad-ai-teacher/blob/main/static/app.js) (Lesson controller), [`app.py`](https://github.com/priyanshu2705-hub/ustaad-ai-teacher/blob/main/app.py) (Flask routes), [`templates/index.html`](https://github.com/priyanshu2705-hub/ustaad-ai-teacher/blob/main/templates/index.html) (Learning page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_learning["Learning experience"]
  node_page["Learning page<br/>[index.html]"]
  node_lesson["Lesson controller<br/>[app.js]"]
  node_visuals["Visual renderers<br/>[app.js]"]
end

subgraph group_server["Generation backend"]
  node_flask["Flask routes<br/>[app.py]"]
  node_generator["Gemini generation<br/>[app.py]"]
end

subgraph group_interaction["Speech and visuals"]
  node_voice["Voice controller<br/>[app.js]"]
  node_listening["Speech recognition<br/>[app.js]"]
  node_avatar["Animated avatar<br/>[app.js]"]
end

node_learner(("Learner"))
node_gemini{{"Gemini API"}}

node_learner -->|"uses"| node_page
node_flask -->|"renders"| node_page
node_learner -->|"provides input"| node_lesson
node_lesson -->|"POSTs generation"| node_flask
node_flask -->|"dispatches request"| node_generator
node_generator -->|"requests content"| node_gemini
node_lesson -->|"renders visuals"| node_visuals
node_lesson -->|"speaks lesson"| node_voice
node_lesson -->|"starts recognition"| node_listening
node_voice -->|"animates speech"| node_avatar

click node_page "https://github.com/priyanshu2705-hub/ustaad-ai-teacher/blob/main/templates/index.html"
click node_lesson "https://github.com/priyanshu2705-hub/ustaad-ai-teacher/blob/main/static/app.js"
click node_visuals "https://github.com/priyanshu2705-hub/ustaad-ai-teacher/blob/main/static/app.js"
click node_voice "https://github.com/priyanshu2705-hub/ustaad-ai-teacher/blob/main/static/app.js"
click node_listening "https://github.com/priyanshu2705-hub/ustaad-ai-teacher/blob/main/static/app.js"
click node_avatar "https://github.com/priyanshu2705-hub/ustaad-ai-teacher/blob/main/static/app.js"
click node_flask "https://github.com/priyanshu2705-hub/ustaad-ai-teacher/blob/main/app.py"
click node_generator "https://github.com/priyanshu2705-hub/ustaad-ai-teacher/blob/main/app.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_page,node_lesson,node_visuals toneBlue
class node_flask,node_generator toneAmber
class node_voice,node_listening,node_avatar,node_gemini toneMint
class node_learner toneIndigo
```

## Components

### Learning experience

- [Learning page](https://github.com/priyanshu2705-hub/ustaad-ai-teacher/blob/main/templates/index.html): `templates/index.html`
- [Lesson controller](https://github.com/priyanshu2705-hub/ustaad-ai-teacher/blob/main/static/app.js): `static/app.js`
- [Visual renderers](https://github.com/priyanshu2705-hub/ustaad-ai-teacher/blob/main/static/app.js): `static/app.js`

### Generation backend

- [Flask routes](https://github.com/priyanshu2705-hub/ustaad-ai-teacher/blob/main/app.py): `app.py`
- [Gemini generation](https://github.com/priyanshu2705-hub/ustaad-ai-teacher/blob/main/app.py): `app.py`

### Speech and visuals

- [Voice controller](https://github.com/priyanshu2705-hub/ustaad-ai-teacher/blob/main/static/app.js): `static/app.js`
- [Speech recognition](https://github.com/priyanshu2705-hub/ustaad-ai-teacher/blob/main/static/app.js): `static/app.js`
- [Animated avatar](https://github.com/priyanshu2705-hub/ustaad-ai-teacher/blob/main/static/app.js): `static/app.js`

### Other components

- **Learner**
- **Gemini API**

## Connections

- Learner → Learning page: uses
- Flask routes → Learning page: renders (evidence: `app.py`)
- Learner → Lesson controller: provides input
- Lesson controller → Flask routes: POSTs generation (evidence: `static/app.js`)
- Flask routes → Gemini generation: dispatches request (evidence: `app.py`)
- Gemini generation → Gemini API: requests content (evidence: `app.py`)
- Lesson controller → Visual renderers: renders visuals (evidence: `static/app.js`)
- Lesson controller → Voice controller: speaks lesson (evidence: `static/app.js`)
- Lesson controller → Speech recognition: starts recognition (evidence: `static/app.js`)
- Voice controller → Animated avatar: animates speech (evidence: `static/app.js`)
