# shivanissingh/conversai architecture

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

- Interactive diagram: https://gitdiagram.com/shivanissingh/conversai
- Repository: https://github.com/shivanissingh/conversai

## Overview

ConversAI turns user text or a topic into an educational explanation with narration, timed visuals, and optional avatar cues, then presents it in a synchronized playback UI. The graph follows the evidenced frontend request flow and backend aggregation stages. The README documents provider and observability capabilities that are not fully shown in sampled source; those links are marked optional where implementation connections are unverified.

Main entry points: [`conversai-backend/src/engines/aggregation/composer.py`](https://github.com/shivanissingh/conversai/blob/main/conversai-backend/src/engines/aggregation/composer.py) (Aggregation Composer), [`conversai-frontend/src/App.jsx`](https://github.com/shivanissingh/conversai/blob/main/conversai-frontend/src/App.jsx) (Application Flow), [`conversai-frontend/src/components/PlaybackView/PlaybackView.jsx`](https://github.com/shivanissingh/conversai/blob/main/conversai-frontend/src/components/PlaybackView/PlaybackView.jsx) (Playback View), [`conversai-backend/src/api/routes/explanation.py`](https://github.com/shivanissingh/conversai/blob/main/conversai-backend/src/api/routes/explanation.py) (Explanation Routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Learner Experience"]
  node_app["Application Flow<br/>[App.jsx]"]
  node_input["Text and Topic Input<br/>[InputSection.jsx]"]
  node_speech["Speech Recognition"]
  node_api_client["API Client<br/>[api.js]"]
  node_history["Explanation History<br/>[history.js]"]
end

subgraph group_api["Request API"]
  node_api_routes["Explanation Routes<br/>[explanation.py]"]
  node_text_controller["Text Controller"]
  node_topic_controller["Topic Controller"]
end

subgraph group_engines["Content Engines"]
  node_aggregation["Aggregation Composer<br/>[composer.py]"]
  node_explanation["Explanation Engine"]
  node_visual["Visual Engine"]
  node_voice["Voice and Avatar Engine"]
end

subgraph group_presentation["Playback Presentation"]
  node_playback["Playback View<br/>[PlaybackView.jsx]"]
  node_playback_hook["Playback Synchronization<br/>[usePlayback.js]"]
  node_audio["Audio Playback<br/>[useAudio.js]"]
  node_avatar_sync["Avatar Synchronization<br/>[useAvatarSync.js]"]
  node_avatar_ui["Avatar Display"]
  node_visual_ui["Visual Display<br/>[VisualDisplay.jsx]"]
  node_talkinghead["Talkinghead Runtime<br/>[talkinghead.mjs]"]
end

subgraph group_telemetry["Observability"]
  node_observability["Telemetry Recorder<br/>[recorder.py]"]
  node_sqlite[("SQLite Telemetry<br/>[database.py]")]
end

node_learner(("Learner"))
node_gemini["Gemini Topic Expansion"]

node_learner -->|"uses"| node_app
node_app -->|"renders"| node_input
node_input -->|"uses"| node_speech
node_app -->|"requests explanation"| node_api_client
node_app -->|"saves results"| node_history
node_api_client -.->|"sends requests"| node_api_routes
node_api_routes -->|"routes text requests"| node_text_controller
node_api_routes -->|"routes topic requests"| node_topic_controller
node_text_controller -->|"calls aggregate"| node_aggregation
node_topic_controller -->|"expands topic"| node_gemini
node_topic_controller -->|"calls aggregate"| node_aggregation
node_aggregation -->|"generates explanation"| node_explanation
node_aggregation -->|"generates visuals"| node_visual
node_aggregation -->|"synthesizes narration"| node_voice
node_aggregation -->|"records pipeline data"| node_observability
node_observability -.->|"stores telemetry"| node_sqlite
node_app -->|"shows result"| node_playback
node_playback -->|"uses"| node_playback_hook
node_playback_hook -->|"controls audio"| node_audio
node_playback_hook -->|"synchronizes avatar"| node_avatar_sync
node_playback -->|"renders"| node_avatar_ui
node_playback -->|"renders"| node_visual_ui
node_avatar_ui -.->|"may use runtime"| node_talkinghead

click node_app "https://github.com/shivanissingh/conversai/blob/main/conversai-frontend/src/App.jsx"
click node_input "https://github.com/shivanissingh/conversai/blob/main/conversai-frontend/src/components/InputSection/InputSection.jsx"
click node_speech "https://github.com/shivanissingh/conversai/blob/main/conversai-frontend/src/hooks/useSpeechRecognition.js"
click node_api_client "https://github.com/shivanissingh/conversai/blob/main/conversai-frontend/src/services/api.js"
click node_history "https://github.com/shivanissingh/conversai/blob/main/conversai-frontend/src/utils/history.js"
click node_api_routes "https://github.com/shivanissingh/conversai/blob/main/conversai-backend/src/api/routes/explanation.py"
click node_text_controller "https://github.com/shivanissingh/conversai/blob/main/conversai-backend/src/api/controllers/explanation_controller.py"
click node_topic_controller "https://github.com/shivanissingh/conversai/blob/main/conversai-backend/src/api/controllers/topic_controller.py"
click node_aggregation "https://github.com/shivanissingh/conversai/blob/main/conversai-backend/src/engines/aggregation/composer.py"
click node_explanation "https://github.com/shivanissingh/conversai/tree/main/conversai-backend/src/engines/explanation"
click node_visual "https://github.com/shivanissingh/conversai/tree/main/conversai-backend/src/engines/visual"
click node_voice "https://github.com/shivanissingh/conversai/tree/main/conversai-backend/src/engines/voice"
click node_observability "https://github.com/shivanissingh/conversai/blob/main/conversai-backend/src/observability/recorder.py"
click node_sqlite "https://github.com/shivanissingh/conversai/blob/main/conversai-backend/src/observability/database.py"
click node_playback "https://github.com/shivanissingh/conversai/blob/main/conversai-frontend/src/components/PlaybackView/PlaybackView.jsx"
click node_playback_hook "https://github.com/shivanissingh/conversai/blob/main/conversai-frontend/src/hooks/usePlayback.js"
click node_audio "https://github.com/shivanissingh/conversai/blob/main/conversai-frontend/src/hooks/useAudio.js"
click node_avatar_sync "https://github.com/shivanissingh/conversai/blob/main/conversai-frontend/src/hooks/useAvatarSync.js"
click node_avatar_ui "https://github.com/shivanissingh/conversai/blob/main/conversai-frontend/src/components/Avatar/AvatarComponent.jsx"
click node_visual_ui "https://github.com/shivanissingh/conversai/blob/main/conversai-frontend/src/components/VisualDisplay/VisualDisplay.jsx"
click node_talkinghead "https://github.com/shivanissingh/conversai/blob/main/conversai-frontend/public/talkinghead/talkinghead.mjs"

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_input,node_speech,node_api_client,node_history toneBlue
class node_api_routes,node_text_controller,node_topic_controller toneAmber
class node_aggregation,node_explanation,node_visual,node_voice toneMint
class node_playback,node_playback_hook,node_audio,node_avatar_sync,node_avatar_ui,node_visual_ui,node_talkinghead toneRose
class node_observability,node_sqlite,node_learner,node_gemini toneIndigo
```

## Components

### Learner Experience

- [Application Flow](https://github.com/shivanissingh/conversai/blob/main/conversai-frontend/src/App.jsx): `conversai-frontend/src/App.jsx`
- [Text and Topic Input](https://github.com/shivanissingh/conversai/blob/main/conversai-frontend/src/components/InputSection/InputSection.jsx): `conversai-frontend/src/components/InputSection/InputSection.jsx`
- [Speech Recognition](https://github.com/shivanissingh/conversai/blob/main/conversai-frontend/src/hooks/useSpeechRecognition.js): `conversai-frontend/src/hooks/useSpeechRecognition.js`
- [API Client](https://github.com/shivanissingh/conversai/blob/main/conversai-frontend/src/services/api.js): `conversai-frontend/src/services/api.js`
- [Explanation History](https://github.com/shivanissingh/conversai/blob/main/conversai-frontend/src/utils/history.js): `conversai-frontend/src/utils/history.js`

### Request API

- [Explanation Routes](https://github.com/shivanissingh/conversai/blob/main/conversai-backend/src/api/routes/explanation.py): `conversai-backend/src/api/routes/explanation.py`
- [Text Controller](https://github.com/shivanissingh/conversai/blob/main/conversai-backend/src/api/controllers/explanation_controller.py): `conversai-backend/src/api/controllers/explanation_controller.py`
- [Topic Controller](https://github.com/shivanissingh/conversai/blob/main/conversai-backend/src/api/controllers/topic_controller.py): `conversai-backend/src/api/controllers/topic_controller.py`

### Content Engines

- [Aggregation Composer](https://github.com/shivanissingh/conversai/blob/main/conversai-backend/src/engines/aggregation/composer.py): `conversai-backend/src/engines/aggregation/composer.py`
- [Explanation Engine](https://github.com/shivanissingh/conversai/tree/main/conversai-backend/src/engines/explanation): `conversai-backend/src/engines/explanation`
- [Visual Engine](https://github.com/shivanissingh/conversai/tree/main/conversai-backend/src/engines/visual): `conversai-backend/src/engines/visual`
- [Voice and Avatar Engine](https://github.com/shivanissingh/conversai/tree/main/conversai-backend/src/engines/voice): `conversai-backend/src/engines/voice`

### Playback Presentation

- [Playback View](https://github.com/shivanissingh/conversai/blob/main/conversai-frontend/src/components/PlaybackView/PlaybackView.jsx): `conversai-frontend/src/components/PlaybackView/PlaybackView.jsx`
- [Playback Synchronization](https://github.com/shivanissingh/conversai/blob/main/conversai-frontend/src/hooks/usePlayback.js): `conversai-frontend/src/hooks/usePlayback.js`
- [Audio Playback](https://github.com/shivanissingh/conversai/blob/main/conversai-frontend/src/hooks/useAudio.js): `conversai-frontend/src/hooks/useAudio.js`
- [Avatar Synchronization](https://github.com/shivanissingh/conversai/blob/main/conversai-frontend/src/hooks/useAvatarSync.js): `conversai-frontend/src/hooks/useAvatarSync.js`
- [Avatar Display](https://github.com/shivanissingh/conversai/blob/main/conversai-frontend/src/components/Avatar/AvatarComponent.jsx): `conversai-frontend/src/components/Avatar/AvatarComponent.jsx`
- [Visual Display](https://github.com/shivanissingh/conversai/blob/main/conversai-frontend/src/components/VisualDisplay/VisualDisplay.jsx): `conversai-frontend/src/components/VisualDisplay/VisualDisplay.jsx`
- [Talkinghead Runtime](https://github.com/shivanissingh/conversai/blob/main/conversai-frontend/public/talkinghead/talkinghead.mjs): `conversai-frontend/public/talkinghead/talkinghead.mjs`

### Observability

- [Telemetry Recorder](https://github.com/shivanissingh/conversai/blob/main/conversai-backend/src/observability/recorder.py): `conversai-backend/src/observability/recorder.py`
- [SQLite Telemetry](https://github.com/shivanissingh/conversai/blob/main/conversai-backend/src/observability/database.py): `conversai-backend/src/observability/database.py`

### Other components

- **Learner**
- **Gemini Topic Expansion**

## Connections

- Learner → Application Flow: uses (evidence: `conversai-frontend/src/App.jsx`)
- Application Flow → Text and Topic Input: renders (evidence: `conversai-frontend/src/App.jsx`)
- Text and Topic Input → Speech Recognition: uses (evidence: `conversai-frontend/src/components/InputSection/InputSection.jsx`)
- Application Flow → API Client: requests explanation (evidence: `conversai-frontend/src/App.jsx`)
- Application Flow → Explanation History: saves results (evidence: `conversai-frontend/src/App.jsx`)
- API Client → Explanation Routes: sends requests
- Explanation Routes → Text Controller: routes text requests (evidence: `conversai-backend/src/api/routes/explanation.py`)
- Explanation Routes → Topic Controller: routes topic requests (evidence: `conversai-backend/src/api/routes/explanation.py`)
- Text Controller → Aggregation Composer: calls aggregate (evidence: `conversai-backend/src/api/controllers/explanation_controller.py`)
- Topic Controller → Gemini Topic Expansion: expands topic (evidence: `conversai-backend/src/api/controllers/topic_controller.py`)
- Topic Controller → Aggregation Composer: calls aggregate (evidence: `conversai-backend/src/api/controllers/topic_controller.py`)
- Aggregation Composer → Explanation Engine: generates explanation (evidence: `conversai-backend/src/engines/aggregation/composer.py`)
- Aggregation Composer → Visual Engine: generates visuals (evidence: `conversai-backend/src/engines/aggregation/composer.py`)
- Aggregation Composer → Voice and Avatar Engine: synthesizes narration (evidence: `conversai-backend/src/engines/aggregation/composer.py`)
- Aggregation Composer → Telemetry Recorder: records pipeline data (evidence: `conversai-backend/src/engines/aggregation/composer.py`)
- Telemetry Recorder → SQLite Telemetry: stores telemetry
- Application Flow → Playback View: shows result (evidence: `conversai-frontend/src/App.jsx`)
- Playback View → Playback Synchronization: uses (evidence: `conversai-frontend/src/components/PlaybackView/PlaybackView.jsx`)
- Playback Synchronization → Audio Playback: controls audio (evidence: `conversai-frontend/src/hooks/usePlayback.js`)
- Playback Synchronization → Avatar Synchronization: synchronizes avatar (evidence: `conversai-frontend/src/hooks/usePlayback.js`)
- Playback View → Avatar Display: renders (evidence: `conversai-frontend/src/components/PlaybackView/PlaybackView.jsx`)
- Playback View → Visual Display: renders (evidence: `conversai-frontend/src/components/PlaybackView/PlaybackView.jsx`)
- Avatar Display → Talkinghead Runtime: may use runtime