How shivanissingh/conversai works
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: composer.py Aggregation Composer · App.jsx Application Flow · PlaybackView.jsx Playback View · explanation.py Explanation Routes
Components 23
Learner Experience
- Application Flow
conversai-frontend/src/App.jsx - Text and Topic Input
conversai-frontend/src/components/InputSection/InputSection.jsx - Speech Recognition
conversai-frontend/src/hooks/useSpeechRecognition.js - API Client
conversai-frontend/src/services/api.js - Explanation History
conversai-frontend/src/utils/history.js
Request API
- Explanation Routes
conversai-backend/src/api/routes/explanation.py - Text Controller
conversai-backend/src/api/controllers/explanation_controller.py - Topic Controller
conversai-backend/src/api/controllers/topic_controller.py
Content Engines
- Aggregation Composer
conversai-backend/src/engines/aggregation/composer.py - Explanation Engine
conversai-backend/src/engines/explanation - Visual Engine
conversai-backend/src/engines/visual - Voice and Avatar Engine
conversai-backend/src/engines/voice
Playback Presentation
- Playback View
conversai-frontend/src/components/PlaybackView/PlaybackView.jsx - Playback Synchronization
conversai-frontend/src/hooks/usePlayback.js - Audio Playback
conversai-frontend/src/hooks/useAudio.js - Avatar Synchronization
conversai-frontend/src/hooks/useAvatarSync.js - Avatar Display
conversai-frontend/src/components/Avatar/AvatarComponent.jsx - Visual Display
conversai-frontend/src/components/VisualDisplay/VisualDisplay.jsx - Talkinghead Runtime
conversai-frontend/public/talkinghead/talkinghead.mjs
Observability
- Telemetry Recorder
conversai-backend/src/observability/recorder.py - SQLite Telemetry
conversai-backend/src/observability/database.py
Other components
- Learner
- Gemini Topic Expansion
Connections 23
- Learner → Application Flow: uses
conversai-frontend/src/App.jsx - Application Flow → Text and Topic Input: renders
conversai-frontend/src/App.jsx - Text and Topic Input → Speech Recognition: uses
conversai-frontend/src/components/InputSection/InputSection.jsx - Application Flow → API Client: requests explanation
conversai-frontend/src/App.jsx - Application Flow → Explanation History: saves results
conversai-frontend/src/App.jsx - API Client → Explanation Routes: sends requests
- Explanation Routes → Text Controller: routes text requests
conversai-backend/src/api/routes/explanation.py - Explanation Routes → Topic Controller: routes topic requests
conversai-backend/src/api/routes/explanation.py - Text Controller → Aggregation Composer: calls aggregate
conversai-backend/src/api/controllers/explanation_controller.py - Topic Controller → Gemini Topic Expansion: expands topic
conversai-backend/src/api/controllers/topic_controller.py - Topic Controller → Aggregation Composer: calls aggregate
conversai-backend/src/api/controllers/topic_controller.py - Aggregation Composer → Explanation Engine: generates explanation
conversai-backend/src/engines/aggregation/composer.py - Aggregation Composer → Visual Engine: generates visuals
conversai-backend/src/engines/aggregation/composer.py - Aggregation Composer → Voice and Avatar Engine: synthesizes narration
conversai-backend/src/engines/aggregation/composer.py - Aggregation Composer → Telemetry Recorder: records pipeline data
conversai-backend/src/engines/aggregation/composer.py - Telemetry Recorder → SQLite Telemetry: stores telemetry
- Application Flow → Playback View: shows result
conversai-frontend/src/App.jsx - Playback View → Playback Synchronization: uses
conversai-frontend/src/components/PlaybackView/PlaybackView.jsx - Playback Synchronization → Audio Playback: controls audio
conversai-frontend/src/hooks/usePlayback.js - Playback Synchronization → Avatar Synchronization: synchronizes avatar
conversai-frontend/src/hooks/usePlayback.js - Playback View → Avatar Display: renders
conversai-frontend/src/components/PlaybackView/PlaybackView.jsx - Playback View → Visual Display: renders
conversai-frontend/src/components/PlaybackView/PlaybackView.jsx - Avatar Display → Talkinghead Runtime: may use runtime