# dedinsaf/parentai architecture

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

- Interactive diagram: https://gitdiagram.com/dedinsaf/parentai
- Repository: https://github.com/dedinsaf/parentai

## Overview

ParentAI is a localhost homework-help application combining a browser avatar/camera with Python services. The main workflow captures a parent profile and voice sample, then listens for a child’s question, transcribes it, manages tutoring turns, and presents a spoken, lip-synced reply. The graph includes documented avatar construction, presence/listening, and voice options. Some implementation details are unsampled; those subsystem links are omitted or marked unverified rather than inferred from names alone.

Main entry points: [`web/app.js`](https://github.com/dedinsaf/parentai/blob/main/web/app.js) (Lesson UI), [`server.py`](https://github.com/dedinsaf/parentai/blob/main/server.py) (HTTP API), [`runtime.py`](https://github.com/dedinsaf/parentai/blob/main/runtime.py) (Profile and local state), [`dialogue.py`](https://github.com/dedinsaf/parentai/blob/main/dialogue.py) (Dialogue sessions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser experience"]
  node_browser_ui["Lesson UI<br/>[app.js]"]
  node_web_core["Scan and audio utilities<br/>[core.mjs]"]
  node_listener["Speech gate<br/>[listening.mjs]"]
  node_avatar_geometry["Head and body geometry<br/>[head-geometry.mjs]"]
  node_face_atlas["Face texture atlas<br/>[face-atlas.mjs]"]
end

subgraph group_server["Local application"]
  node_api["HTTP API<br/>[server.py]"]
  node_launcher["Application launcher<br/>[run_app.py]"]
  node_profile[("Profile and local state<br/>[runtime.py]")]
  node_asset_download["Camera assets<br/>[download_assets.py]"]
end

subgraph group_conversation["Tutoring and speech"]
  node_dialogues["Dialogue sessions<br/>[dialogue.py]"]
  node_tutor["Homework tutor<br/>[tutor.py]"]
  node_speech["Speech recognition<br/>[speech.py]"]
end

subgraph group_voice["Voice generation"]
  node_voice_setup["Voice profile generation<br/>[voice.py]"]
  node_voice_engine["XTTS engine<br/>[voice_engine.py]"]
  node_voice_worker["XTTS worker<br/>[voice_worker.py]"]
  node_lipsync["Lip-sync timeline<br/>[lipsync.py]"]
end

node_parent(("Parent / child"))
node_speechkit["Yandex SpeechKit"]
node_yandexgpt["YandexGPT"]

node_parent -->|"uses"| node_browser_ui
node_browser_ui -->|"calls API"| node_api
node_browser_ui -->|"uses scan/audio"| node_web_core
node_browser_ui -->|"uses speech gate"| node_listener
node_browser_ui -->|"builds avatar"| node_avatar_geometry
node_browser_ui -->|"uses atlas"| node_face_atlas
node_launcher -->|"creates runtime"| node_profile
node_launcher -->|"starts server"| node_api
node_api -->|"reads profile"| node_profile
node_api -->|"routes dialogue"| node_dialogues
node_api -->|"configures tutor"| node_tutor
node_api -->|"configures speech"| node_speech
node_profile -->|"starts asset setup"| node_asset_download
node_profile -->|"starts voice setup"| node_voice_setup
node_profile -->|"warms XTTS"| node_voice_engine
node_speech -.->|"transcribes audio"| node_speechkit
node_dialogues -->|"requests answer"| node_tutor
node_tutor -->|"generates reply"| node_yandexgpt
node_dialogues -->|"synthesizes reply"| node_voice_engine
node_voice_engine -.->|"dispatches work"| node_voice_worker
node_dialogues -->|"builds cues"| node_lipsync

click node_browser_ui "https://github.com/dedinsaf/parentai/blob/main/web/app.js"
click node_web_core "https://github.com/dedinsaf/parentai/blob/main/web/core.mjs"
click node_listener "https://github.com/dedinsaf/parentai/blob/main/web/listening.mjs"
click node_avatar_geometry "https://github.com/dedinsaf/parentai/blob/main/web/head-geometry.mjs"
click node_face_atlas "https://github.com/dedinsaf/parentai/blob/main/web/face-atlas.mjs"
click node_api "https://github.com/dedinsaf/parentai/blob/main/server.py"
click node_launcher "https://github.com/dedinsaf/parentai/blob/main/run_app.py"
click node_profile "https://github.com/dedinsaf/parentai/blob/main/runtime.py"
click node_asset_download "https://github.com/dedinsaf/parentai/blob/main/download_assets.py"
click node_dialogues "https://github.com/dedinsaf/parentai/blob/main/dialogue.py"
click node_tutor "https://github.com/dedinsaf/parentai/blob/main/tutor.py"
click node_speech "https://github.com/dedinsaf/parentai/blob/main/speech.py"
click node_voice_setup "https://github.com/dedinsaf/parentai/blob/main/voice.py"
click node_voice_engine "https://github.com/dedinsaf/parentai/blob/main/voice_engine.py"
click node_voice_worker "https://github.com/dedinsaf/parentai/blob/main/voice_worker.py"
click node_lipsync "https://github.com/dedinsaf/parentai/blob/main/lipsync.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_browser_ui,node_web_core,node_listener,node_avatar_geometry,node_face_atlas toneBlue
class node_api,node_launcher,node_profile,node_asset_download toneAmber
class node_dialogues,node_tutor,node_speech toneMint
class node_voice_setup,node_voice_engine,node_voice_worker,node_lipsync toneRose
class node_parent,node_speechkit,node_yandexgpt toneIndigo
```

## Components

### Browser experience

- [Lesson UI](https://github.com/dedinsaf/parentai/blob/main/web/app.js): `web/app.js`
- [Scan and audio utilities](https://github.com/dedinsaf/parentai/blob/main/web/core.mjs): `web/core.mjs`
- [Speech gate](https://github.com/dedinsaf/parentai/blob/main/web/listening.mjs): `web/listening.mjs`
- [Head and body geometry](https://github.com/dedinsaf/parentai/blob/main/web/head-geometry.mjs): `web/head-geometry.mjs`
- [Face texture atlas](https://github.com/dedinsaf/parentai/blob/main/web/face-atlas.mjs): `web/face-atlas.mjs`

### Local application

- [HTTP API](https://github.com/dedinsaf/parentai/blob/main/server.py): `server.py`
- [Application launcher](https://github.com/dedinsaf/parentai/blob/main/run_app.py): `run_app.py`
- [Profile and local state](https://github.com/dedinsaf/parentai/blob/main/runtime.py): `runtime.py`
- [Camera assets](https://github.com/dedinsaf/parentai/blob/main/download_assets.py): `download_assets.py`

### Tutoring and speech

- [Dialogue sessions](https://github.com/dedinsaf/parentai/blob/main/dialogue.py): `dialogue.py`
- [Homework tutor](https://github.com/dedinsaf/parentai/blob/main/tutor.py): `tutor.py`
- [Speech recognition](https://github.com/dedinsaf/parentai/blob/main/speech.py): `speech.py`

### Voice generation

- [Voice profile generation](https://github.com/dedinsaf/parentai/blob/main/voice.py): `voice.py`
- [XTTS engine](https://github.com/dedinsaf/parentai/blob/main/voice_engine.py): `voice_engine.py`
- [XTTS worker](https://github.com/dedinsaf/parentai/blob/main/voice_worker.py): `voice_worker.py`
- [Lip-sync timeline](https://github.com/dedinsaf/parentai/blob/main/lipsync.py): `lipsync.py`

### Other components

- **Parent / child**
- **Yandex SpeechKit**
- **YandexGPT**

## Connections

- Parent / child → Lesson UI: uses (evidence: `README.md`)
- Lesson UI → HTTP API: calls API (evidence: `README.md`)
- Lesson UI → Scan and audio utilities: uses scan/audio (evidence: `web/app.js`)
- Lesson UI → Speech gate: uses speech gate (evidence: `web/app.js`)
- Lesson UI → Head and body geometry: builds avatar (evidence: `web/app.js`)
- Lesson UI → Face texture atlas: uses atlas (evidence: `web/app.js`)
- Application launcher → Profile and local state: creates runtime (evidence: `run_app.py`)
- Application launcher → HTTP API: starts server (evidence: `run_app.py`)
- HTTP API → Profile and local state: reads profile (evidence: `server.py`)
- HTTP API → Dialogue sessions: routes dialogue (evidence: `server.py`)
- HTTP API → Homework tutor: configures tutor (evidence: `server.py`)
- HTTP API → Speech recognition: configures speech (evidence: `server.py`)
- Profile and local state → Camera assets: starts asset setup (evidence: `runtime.py`)
- Profile and local state → Voice profile generation: starts voice setup (evidence: `runtime.py`)
- Profile and local state → XTTS engine: warms XTTS (evidence: `runtime.py`)
- Speech recognition → Yandex SpeechKit: transcribes audio (evidence: `README.md`)
- Dialogue sessions → Homework tutor: requests answer (evidence: `dialogue.py`)
- Homework tutor → YandexGPT: generates reply (evidence: `README.md`)
- Dialogue sessions → XTTS engine: synthesizes reply (evidence: `dialogue.py`)
- XTTS engine → XTTS worker: dispatches work
- Dialogue sessions → Lip-sync timeline: builds cues (evidence: `dialogue.py`)
