# ki-zore/voice-based-coding-assistant architecture

> Architecture diagram of the GitHub repository ki-zore/voice-based-coding-assistant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ki-zore/voice-based-coding-assistant
- Repository: https://github.com/ki-zore/voice-based-coding-assistant

## Overview

#### Purpose and entry points
This is a Vite-powered React/TypeScript single-page voice coding assistant for visually impaired developers. It accepts spoken commands, generates or explains code through Gemini, and presents accessible transcript/editor feedback. Browser startup is `src/main.tsx`; application composition and state coordination begin in `src/App.tsx`.

#### Application shell and orchestration
`src/App.tsx` is the central UI/controller boundary: it assembles the voice, transcript, command-processing, editor, explanation, and session-facing components. `src/index.css` provides the shared presentation layer. There is no Express server in the supplied tree; external AI and persistence calls appear to be made from the client-side library modules.

#### Voice I/O pipeline
Speech capture is encapsulated by `src/hooks/useSpeechRecognition.ts` and surfaced through `src/components/VoiceInput.tsx`. Recognized speech is forwarded as text into the command/transcript flow. Spoken output is isolated in `src/hooks/useSpeechSynthesis.ts`, allowing generated responses and UI feedback to be read aloud without coupling speech APIs to AI or editor logic.

#### Command and AI generation boundary
`src/components/CommandProcessor.tsx` interprets user text as coding requests and coordinates generation behavior. The Gemini service boundary is `src/lib/gemini.ts`; this module should own requests, API configuration, and response normalization so UI components do not directly depend on the GenAI API. Generated code and explanations are then routed to presentation components.

#### Code and explanation workspace
`src/components/CodeEditor.tsx` is the generated-code display/editing surface. `src/components/ExplanationPanel.tsx` presents explanatory output separately from code, preserving a distinction between executable/editable artifacts and natural-language guidance. `src/components/TranscriptBox.tsx` exposes the conversational record, serving as the user-visible history of voice input and assistant output.

#### Session persistence
`src/components/SessionTracker.tsx` represents session lifecycle/history behavior. Its backend integration boundary is `src/lib/supabase.ts`, with schema ownership in `supabase/migrations/20251013162434_create_voco_sessions_table.sql`. The intended flow is UI/session events → Supabase client → persisted `voco_sessions` records; database details should remain outside voice and AI components.

#### Runtime and external dependencies
The frontend runs in the browser via Vite (`src/main.tsx`, `vite.config.ts`) and React. Material external services are Gemini for generative AI (`src/lib/gemini.ts`) and Supabase for session storage (`src/lib/supabase.ts`, `supabase/migrations/20251013162434_create_voco_sessions_table.sql`). Browser speech-recognition and speech-synthesis capabilities are core runtime dependencies, wrapped by the hooks rather than accessed throughout the UI.

Main entry points: [`src/App.tsx`](https://github.com/ki-zore/voice-based-coding-assistant/blob/main/src/App.tsx) (App controller), [`src/components/CommandProcessor.tsx`](https://github.com/ki-zore/voice-based-coding-assistant/blob/main/src/components/CommandProcessor.tsx) (Command processor), [`src/lib/gemini.ts`](https://github.com/ki-zore/voice-based-coding-assistant/blob/main/src/lib/gemini.ts) (Gemini client), [`src/main.tsx`](https://github.com/ki-zore/voice-based-coding-assistant/blob/main/src/main.tsx) (Browser entry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser application"]
  node_vite{{"Vite runtime<br/>build runtime<br/>[vite.config.ts]"}}
  node_main["Browser entry<br/>React bootstrap<br/>[main.tsx]"]
  node_app["App controller<br/>UI orchestration<br/>[App.tsx]"]
  node_styles["Shared styles<br/>CSS<br/>[index.css]"]
  node_editor["Code editor<br/>React component<br/>[CodeEditor.tsx]"]
  node_explanation["Explanation panel<br/>React component"]
  node_transcript["Transcript box<br/>React component<br/>[TranscriptBox.tsx]"]
end

subgraph group_voice["Voice I/O"]
  node_voice_input["Voice input<br/>React component<br/>[VoiceInput.tsx]"]
  node_recognition["Speech recognition<br/>browser speech hook"]
  node_synthesis["Speech synthesis<br/>browser speech hook"]
end

subgraph group_ai["AI generation"]
  node_command["Command processor<br/>React component"]
  node_gemini{{"Gemini client<br/>AI service client<br/>[gemini.ts]"}}
  node_gemini_api(("Gemini API<br/>external AI service"))
end

subgraph group_session["Session persistence"]
  node_session_tracker["Session tracker<br/>React component<br/>[SessionTracker.tsx]"]
  node_supabase{{"Supabase client<br/>persistence client<br/>[supabase.ts]"}}
  node_sessions_table[("voco_sessions<br/>database table")]
end

node_vite -->|"serves"| node_main
node_main -->|"mounts"| node_app
node_app -->|"uses"| node_styles
node_app -->|"assembles"| node_voice_input
node_app -->|"assembles"| node_command
node_app -->|"updates"| node_editor
node_app -->|"updates"| node_explanation
node_app -->|"shows history in"| node_transcript
node_app -->|"coordinates"| node_session_tracker
node_voice_input -->|"captures speech through"| node_recognition
node_recognition -->|"recognized text"| node_command
node_command -->|"coding requests"| node_gemini
node_gemini -->|"generates via"| node_gemini_api
node_gemini -->|"generated code"| node_editor
node_gemini -->|"explanations"| node_explanation
node_command -->|"conversation events"| node_transcript
node_command -->|"responses for speech"| node_synthesis
node_session_tracker -->|"session events"| node_supabase
node_supabase -->|"stores"| node_sessions_table

click node_vite "https://github.com/ki-zore/voice-based-coding-assistant/blob/main/vite.config.ts"
click node_main "https://github.com/ki-zore/voice-based-coding-assistant/blob/main/src/main.tsx"
click node_app "https://github.com/ki-zore/voice-based-coding-assistant/blob/main/src/App.tsx"
click node_styles "https://github.com/ki-zore/voice-based-coding-assistant/blob/main/src/index.css"
click node_voice_input "https://github.com/ki-zore/voice-based-coding-assistant/blob/main/src/components/VoiceInput.tsx"
click node_recognition "https://github.com/ki-zore/voice-based-coding-assistant/blob/main/src/hooks/useSpeechRecognition.ts"
click node_synthesis "https://github.com/ki-zore/voice-based-coding-assistant/blob/main/src/hooks/useSpeechSynthesis.ts"
click node_command "https://github.com/ki-zore/voice-based-coding-assistant/blob/main/src/components/CommandProcessor.tsx"
click node_gemini "https://github.com/ki-zore/voice-based-coding-assistant/blob/main/src/lib/gemini.ts"
click node_editor "https://github.com/ki-zore/voice-based-coding-assistant/blob/main/src/components/CodeEditor.tsx"
click node_explanation "https://github.com/ki-zore/voice-based-coding-assistant/blob/main/src/components/ExplanationPanel.tsx"
click node_transcript "https://github.com/ki-zore/voice-based-coding-assistant/blob/main/src/components/TranscriptBox.tsx"
click node_session_tracker "https://github.com/ki-zore/voice-based-coding-assistant/blob/main/src/components/SessionTracker.tsx"
click node_supabase "https://github.com/ki-zore/voice-based-coding-assistant/blob/main/src/lib/supabase.ts"
click node_sessions_table "https://github.com/ki-zore/voice-based-coding-assistant/blob/main/supabase/migrations/20251013162434_create_voco_sessions_table.sql"

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_vite,node_main,node_app,node_styles,node_editor,node_explanation,node_transcript toneBlue
class node_voice_input,node_recognition,node_synthesis toneAmber
class node_command,node_gemini,node_gemini_api toneMint
class node_session_tracker,node_supabase,node_sessions_table toneRose
```

## Components

### Browser application

Vite-hosted React single-page application.

- [Vite runtime](https://github.com/ki-zore/voice-based-coding-assistant/blob/main/vite.config.ts): build runtime · `vite.config.ts`
- [Browser entry](https://github.com/ki-zore/voice-based-coding-assistant/blob/main/src/main.tsx): React bootstrap · `src/main.tsx`
- [App controller](https://github.com/ki-zore/voice-based-coding-assistant/blob/main/src/App.tsx): UI orchestration · Composes workspace state and feature components. · `src/App.tsx`
- [Shared styles](https://github.com/ki-zore/voice-based-coding-assistant/blob/main/src/index.css): CSS · `src/index.css`
- [Code editor](https://github.com/ki-zore/voice-based-coding-assistant/blob/main/src/components/CodeEditor.tsx): React component · Displays and edits generated code. · `src/components/CodeEditor.tsx`
- [Explanation panel](https://github.com/ki-zore/voice-based-coding-assistant/blob/main/src/components/ExplanationPanel.tsx): React component · Presents natural-language guidance separately from code. · `src/components/ExplanationPanel.tsx`
- [Transcript box](https://github.com/ki-zore/voice-based-coding-assistant/blob/main/src/components/TranscriptBox.tsx): React component · Shows conversational voice and assistant history. · `src/components/TranscriptBox.tsx`

### Voice I/O

Browser speech APIs are isolated behind hooks.

- [Voice input](https://github.com/ki-zore/voice-based-coding-assistant/blob/main/src/components/VoiceInput.tsx): React component · `src/components/VoiceInput.tsx`
- [Speech recognition](https://github.com/ki-zore/voice-based-coding-assistant/blob/main/src/hooks/useSpeechRecognition.ts): browser speech hook · Wraps browser speech capture and recognition. · `src/hooks/useSpeechRecognition.ts`
- [Speech synthesis](https://github.com/ki-zore/voice-based-coding-assistant/blob/main/src/hooks/useSpeechSynthesis.ts): browser speech hook · Reads generated responses and UI feedback aloud. · `src/hooks/useSpeechSynthesis.ts`

### AI generation

Client-side Gemini request boundary.

- [Command processor](https://github.com/ki-zore/voice-based-coding-assistant/blob/main/src/components/CommandProcessor.tsx): React component · Interprets recognized text as coding requests. · `src/components/CommandProcessor.tsx`
- [Gemini client](https://github.com/ki-zore/voice-based-coding-assistant/blob/main/src/lib/gemini.ts): AI service client · Owns API requests and response normalization. · `src/lib/gemini.ts`
- **Gemini API**: external AI service

### Session persistence

Session UI persists records through Supabase.

- [Session tracker](https://github.com/ki-zore/voice-based-coding-assistant/blob/main/src/components/SessionTracker.tsx): React component · Handles session lifecycle and history events. · `src/components/SessionTracker.tsx`
- [Supabase client](https://github.com/ki-zore/voice-based-coding-assistant/blob/main/src/lib/supabase.ts): persistence client · `src/lib/supabase.ts`
- [voco_sessions](https://github.com/ki-zore/voice-based-coding-assistant/blob/main/supabase/migrations/20251013162434_create_voco_sessions_table.sql): database table · Persisted session records. · `supabase/migrations/20251013162434_create_voco_sessions_table.sql`

## Connections

- Vite runtime → Browser entry: serves
- Browser entry → App controller: mounts
- App controller → Shared styles: uses
- App controller → Voice input: assembles
- App controller → Command processor: assembles
- App controller → Code editor: updates
- App controller → Explanation panel: updates
- App controller → Transcript box: shows history in
- App controller → Session tracker: coordinates
- Voice input → Speech recognition: captures speech through
- Speech recognition → Command processor: recognized text
- Command processor → Gemini client: coding requests
- Gemini client → Gemini API: generates via
- Gemini client → Code editor: generated code
- Gemini client → Explanation panel: explanations
- Command processor → Transcript box: conversation events
- Command processor → Speech synthesis: responses for speech
- Session tracker → Supabase client: session events
- Supabase client → voco_sessions: stores