# akskriitk/100x_aakash_voice_bot architecture

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

- Interactive diagram: https://gitdiagram.com/akskriitk/100x_aakash_voice_bot
- Repository: https://github.com/akskriitk/100x_aakash_voice_bot

## Overview

Aakash AI is a web voice-and-text assistant that responds in Aakash Kumar’s first person. The main workflow runs from the React voice or text interface through FastAPI to conversation processing, where history and persona grounding inform an answer; voice input can be transcribed before this step. Answers return to the client for display and speech playback. The README documents provider alternatives and health and conversation APIs. Some route and service implementations were not sampled, so those connections reflect documented architecture rather than inspected calls.

Main entry points: [`frontend/src/hooks/useVoiceBot.ts`](https://github.com/akskriitk/100x_aakash_voice_bot/blob/main/frontend/src/hooks/useVoiceBot.ts) (Voice bot state), [`frontend/src/services/api.ts`](https://github.com/akskriitk/100x_aakash_voice_bot/blob/main/frontend/src/services/api.ts) (API client), [`backend/app/api/router.py`](https://github.com/akskriitk/100x_aakash_voice_bot/blob/main/backend/app/api/router.py) (API router), [`backend/app/services/agent_workflow.py`](https://github.com/akskriitk/100x_aakash_voice_bot/blob/main/backend/app/services/agent_workflow.py) (Persona workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_app["React app<br/>[App.tsx]"]
  node_voicebot["Voice bot UI<br/>[VoiceBot.tsx]"]
  node_bot_hook["Voice bot state<br/>[useVoiceBot.ts]"]
  node_recorder["Audio recorder"]
  node_speech["Speech playback"]
  node_api_client["API client<br/>[api.ts]"]
  node_local_fallback["Local answers"]
end

subgraph group_api["Backend API"]
  node_server["FastAPI app<br/>[main.py]"]
  node_router["API router<br/>[router.py]"]
  node_chat_routes["Chat routes<br/>[chat.py]"]
  node_voice_routes["Voice routes<br/>[voice.py]"]
  node_tts_routes["TTS routes<br/>[tts.py]"]
  node_health_routes["Health routes<br/>[health.py]"]
end

subgraph group_conversation["Conversation flow"]
  node_conversation_service["Conversation service"]
  node_voice_service["Voice service<br/>[voice_service.py]"]
  node_stt_service["Speech transcription"]
end

subgraph group_grounding["Persona and AI"]
  node_agent["Persona workflow<br/>[agent_workflow.py]"]
  node_rag["Semantic retrieval<br/>[semantic_rag.py]"]
  node_personality["Persona knowledge"]
  node_llm_service["LLM service<br/>[llm_service.py]"]
end

subgraph group_integrations["Storage and providers"]
  node_llm_provider["LLM providers"]
  node_repository["Conversation repository"]
  node_database[("SQL database<br/>[database.py]")]
  node_speech_provider["Speech providers"]
  node_tts_provider["TTS providers"]
end

node_user(("User"))

node_user -->|"uses"| node_app
node_app -->|"renders"| node_voicebot
node_voicebot -->|"uses"| node_bot_hook
node_bot_hook -->|"records"| node_recorder
node_bot_hook -->|"speaks answers"| node_speech
node_bot_hook -->|"requests"| node_api_client
node_bot_hook -.->|"falls back"| node_local_fallback
node_api_client -->|"sends text"| node_chat_routes
node_api_client -->|"sends audio"| node_voice_routes
node_api_client -->|"requests audio"| node_tts_routes
node_api_client -->|"checks health"| node_health_routes
node_server -->|"mounts routes"| node_router
node_router -->|"dispatches"| node_chat_routes
node_router -->|"dispatches"| node_voice_routes
node_router -->|"dispatches"| node_tts_routes
node_router -->|"dispatches"| node_health_routes
node_chat_routes -->|"processes chat"| node_conversation_service
node_voice_routes -->|"processes voice"| node_voice_service
node_voice_service -->|"transcribes audio"| node_stt_service
node_voice_service -->|"dispatches transcript"| node_conversation_service
node_conversation_service -->|"reads and saves"| node_repository
node_conversation_service -->|"runs workflow"| node_agent
node_agent -->|"retrieves context"| node_rag
node_agent -->|"uses grounding"| node_personality
node_agent -->|"generates answer"| node_llm_service
node_llm_service -->|"calls provider"| node_llm_provider
node_stt_service -->|"calls provider"| node_speech_provider
node_tts_routes -->|"generates speech"| node_tts_provider
node_repository -.->|"reads and writes"| node_database

click node_app "https://github.com/akskriitk/100x_aakash_voice_bot/blob/main/frontend/src/App.tsx"
click node_voicebot "https://github.com/akskriitk/100x_aakash_voice_bot/blob/main/frontend/src/components/VoiceBot.tsx"
click node_bot_hook "https://github.com/akskriitk/100x_aakash_voice_bot/blob/main/frontend/src/hooks/useVoiceBot.ts"
click node_recorder "https://github.com/akskriitk/100x_aakash_voice_bot/blob/main/frontend/src/hooks/useAudioRecorder.ts"
click node_speech "https://github.com/akskriitk/100x_aakash_voice_bot/blob/main/frontend/src/hooks/useSpeechSynthesis.ts"
click node_api_client "https://github.com/akskriitk/100x_aakash_voice_bot/blob/main/frontend/src/services/api.ts"
click node_local_fallback "https://github.com/akskriitk/100x_aakash_voice_bot/blob/main/frontend/src/utils/localPersonalityFallback.ts"
click node_server "https://github.com/akskriitk/100x_aakash_voice_bot/blob/main/backend/app/main.py"
click node_router "https://github.com/akskriitk/100x_aakash_voice_bot/blob/main/backend/app/api/router.py"
click node_chat_routes "https://github.com/akskriitk/100x_aakash_voice_bot/blob/main/backend/app/api/v1/chat.py"
click node_voice_routes "https://github.com/akskriitk/100x_aakash_voice_bot/blob/main/backend/app/api/v1/voice.py"
click node_tts_routes "https://github.com/akskriitk/100x_aakash_voice_bot/blob/main/backend/app/api/v1/tts.py"
click node_health_routes "https://github.com/akskriitk/100x_aakash_voice_bot/blob/main/backend/app/api/v1/health.py"
click node_conversation_service "https://github.com/akskriitk/100x_aakash_voice_bot/blob/main/backend/app/services/conversation_service.py"
click node_voice_service "https://github.com/akskriitk/100x_aakash_voice_bot/blob/main/backend/app/services/voice_service.py"
click node_stt_service "https://github.com/akskriitk/100x_aakash_voice_bot/blob/main/backend/app/services/speech_to_text_service.py"
click node_agent "https://github.com/akskriitk/100x_aakash_voice_bot/blob/main/backend/app/services/agent_workflow.py"
click node_rag "https://github.com/akskriitk/100x_aakash_voice_bot/blob/main/backend/app/services/semantic_rag.py"
click node_personality "https://github.com/akskriitk/100x_aakash_voice_bot/tree/main/backend/app/personality"
click node_llm_service "https://github.com/akskriitk/100x_aakash_voice_bot/blob/main/backend/app/services/llm_service.py"
click node_llm_provider "https://github.com/akskriitk/100x_aakash_voice_bot/tree/main/backend/app/providers/llm"
click node_repository "https://github.com/akskriitk/100x_aakash_voice_bot/blob/main/backend/app/repositories/conversation_repository.py"
click node_database "https://github.com/akskriitk/100x_aakash_voice_bot/blob/main/backend/app/db/database.py"
click node_speech_provider "https://github.com/akskriitk/100x_aakash_voice_bot/tree/main/backend/app/providers/speech"
click node_tts_provider "https://github.com/akskriitk/100x_aakash_voice_bot/tree/main/backend/app/providers/tts"

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_voicebot,node_bot_hook,node_recorder,node_speech,node_api_client,node_local_fallback,node_user toneBlue
class node_server,node_router,node_chat_routes,node_voice_routes,node_tts_routes,node_health_routes toneAmber
class node_conversation_service,node_voice_service,node_stt_service toneMint
class node_agent,node_rag,node_personality,node_llm_service toneRose
class node_llm_provider,node_repository,node_database,node_speech_provider,node_tts_provider toneIndigo
```

## Components

### Web client

- [React app](https://github.com/akskriitk/100x_aakash_voice_bot/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Voice bot UI](https://github.com/akskriitk/100x_aakash_voice_bot/blob/main/frontend/src/components/VoiceBot.tsx): `frontend/src/components/VoiceBot.tsx`
- [Voice bot state](https://github.com/akskriitk/100x_aakash_voice_bot/blob/main/frontend/src/hooks/useVoiceBot.ts): `frontend/src/hooks/useVoiceBot.ts`
- [Audio recorder](https://github.com/akskriitk/100x_aakash_voice_bot/blob/main/frontend/src/hooks/useAudioRecorder.ts): `frontend/src/hooks/useAudioRecorder.ts`
- [Speech playback](https://github.com/akskriitk/100x_aakash_voice_bot/blob/main/frontend/src/hooks/useSpeechSynthesis.ts): `frontend/src/hooks/useSpeechSynthesis.ts`
- [API client](https://github.com/akskriitk/100x_aakash_voice_bot/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`
- [Local answers](https://github.com/akskriitk/100x_aakash_voice_bot/blob/main/frontend/src/utils/localPersonalityFallback.ts): `frontend/src/utils/localPersonalityFallback.ts`

### Backend API

- [FastAPI app](https://github.com/akskriitk/100x_aakash_voice_bot/blob/main/backend/app/main.py): `backend/app/main.py`
- [API router](https://github.com/akskriitk/100x_aakash_voice_bot/blob/main/backend/app/api/router.py): `backend/app/api/router.py`
- [Chat routes](https://github.com/akskriitk/100x_aakash_voice_bot/blob/main/backend/app/api/v1/chat.py): `backend/app/api/v1/chat.py`
- [Voice routes](https://github.com/akskriitk/100x_aakash_voice_bot/blob/main/backend/app/api/v1/voice.py): `backend/app/api/v1/voice.py`
- [TTS routes](https://github.com/akskriitk/100x_aakash_voice_bot/blob/main/backend/app/api/v1/tts.py): `backend/app/api/v1/tts.py`
- [Health routes](https://github.com/akskriitk/100x_aakash_voice_bot/blob/main/backend/app/api/v1/health.py): `backend/app/api/v1/health.py`

### Conversation flow

- [Conversation service](https://github.com/akskriitk/100x_aakash_voice_bot/blob/main/backend/app/services/conversation_service.py): `backend/app/services/conversation_service.py`
- [Voice service](https://github.com/akskriitk/100x_aakash_voice_bot/blob/main/backend/app/services/voice_service.py): `backend/app/services/voice_service.py`
- [Speech transcription](https://github.com/akskriitk/100x_aakash_voice_bot/blob/main/backend/app/services/speech_to_text_service.py): `backend/app/services/speech_to_text_service.py`

### Persona and AI

- [Persona workflow](https://github.com/akskriitk/100x_aakash_voice_bot/blob/main/backend/app/services/agent_workflow.py): `backend/app/services/agent_workflow.py`
- [Semantic retrieval](https://github.com/akskriitk/100x_aakash_voice_bot/blob/main/backend/app/services/semantic_rag.py): `backend/app/services/semantic_rag.py`
- [Persona knowledge](https://github.com/akskriitk/100x_aakash_voice_bot/tree/main/backend/app/personality): `backend/app/personality`
- [LLM service](https://github.com/akskriitk/100x_aakash_voice_bot/blob/main/backend/app/services/llm_service.py): `backend/app/services/llm_service.py`

### Storage and providers

- [LLM providers](https://github.com/akskriitk/100x_aakash_voice_bot/tree/main/backend/app/providers/llm): `backend/app/providers/llm`
- [Conversation repository](https://github.com/akskriitk/100x_aakash_voice_bot/blob/main/backend/app/repositories/conversation_repository.py): `backend/app/repositories/conversation_repository.py`
- [SQL database](https://github.com/akskriitk/100x_aakash_voice_bot/blob/main/backend/app/db/database.py): `backend/app/db/database.py`
- [Speech providers](https://github.com/akskriitk/100x_aakash_voice_bot/tree/main/backend/app/providers/speech): `backend/app/providers/speech`
- [TTS providers](https://github.com/akskriitk/100x_aakash_voice_bot/tree/main/backend/app/providers/tts): `backend/app/providers/tts`

### Other components

- **User**

## Connections

- User → React app: uses
- React app → Voice bot UI: renders
- Voice bot UI → Voice bot state: uses
- Voice bot state → Audio recorder: records
- Voice bot state → Speech playback: speaks answers
- Voice bot state → API client: requests
- Voice bot state → Local answers: falls back
- API client → Chat routes: sends text
- API client → Voice routes: sends audio
- API client → TTS routes: requests audio
- API client → Health routes: checks health
- FastAPI app → API router: mounts routes
- API router → Chat routes: dispatches
- API router → Voice routes: dispatches
- API router → TTS routes: dispatches
- API router → Health routes: dispatches
- Chat routes → Conversation service: processes chat
- Voice routes → Voice service: processes voice
- Voice service → Speech transcription: transcribes audio
- Voice service → Conversation service: dispatches transcript
- Conversation service → Conversation repository: reads and saves
- Conversation service → Persona workflow: runs workflow
- Persona workflow → Semantic retrieval: retrieves context
- Persona workflow → Persona knowledge: uses grounding
- Persona workflow → LLM service: generates answer
- LLM service → LLM providers: calls provider
- Speech transcription → Speech providers: calls provider
- TTS routes → TTS providers: generates speech
- Conversation repository → SQL database: reads and writes