# dilht/sacco-voice-frontend architecture

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

- Interactive diagram: https://gitdiagram.com/dilht/sacco-voice-frontend
- Repository: https://github.com/dilht/sacco-voice-frontend

## Overview

This is a Next.js starter for real-time voice and text interaction with LiveKit Agents. A visitor starts from the welcome view; the app creates a LiveKit session from a token source, provides session state and audio playback, then switches to a session view with chat, media tiles, and controls. The token route is an optional development credential path. Camera and screen sharing, five visualizer styles, virtual avatars, and theme customization are documented capabilities. Some capability modules were not sampled, so only documented or indexed relationships are shown.

Main entry points: [`components/app/app.tsx`](https://github.com/dilht/sacco-voice-frontend/blob/main/components/app/app.tsx) (Session setup), [`components/agents-ui/blocks/agent-session-view-01/components/audio-visualizer.tsx`](https://github.com/dilht/sacco-voice-frontend/blob/main/components/agents-ui/blocks/agent-session-view-01/components/audio-visualizer.tsx) (Visualizer styles), [`components/app/view-controller.tsx`](https://github.com/dilht/sacco-voice-frontend/blob/main/components/app/view-controller.tsx) (View controller), [`components/agents-ui/blocks/agent-session-view-01/components/agent-session-block.tsx`](https://github.com/dilht/sacco-voice-frontend/blob/main/components/agents-ui/blocks/agent-session-view-01/components/agent-session-block.tsx) (Session block)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_application["Application flow"]
  node_app_entry["App entry<br/>[page.tsx]"]
  node_app_shell["Session setup<br/>[app.tsx]"]
  node_session_provider["Session provider"]
  node_view_controller["View controller"]
  node_welcome_view["Welcome view<br/>[welcome-view.tsx]"]
  node_session_errors["Agent errors<br/>[useAgentErrors.tsx]"]
  node_theme["Theme controls<br/>[theme-provider.tsx]"]
end

subgraph group_session_ui["Session experience"]
  node_session_view["Session block"]
  node_tile_layout["Media tiles<br/>[tile-view.tsx]"]
  node_visualizer_router["Visualizer styles"]
  node_aura_visualizer["Aura visualizer"]
  node_bar_visualizer["Bar visualizer"]
  node_grid_visualizer["Grid visualizer"]
  node_radial_visualizer["Radial visualizer"]
  node_wave_visualizer["Wave visualizer"]
  node_transcript["Chat transcript"]
  node_avatar_support["Virtual avatars<br/>[tile-view.tsx]"]
end

subgraph group_media_controls["Media and controls"]
  node_control_bar["Control bar"]
  node_track_control["Track controls"]
  node_track_toggle["Track toggles"]
  node_camera_screen["Camera and sharing"]
end

subgraph group_access_tokens["Access and tokens"]
  node_token_route["Token endpoint<br/>[route.ts]"]
  node_access_check["Access check<br/>[access.ts]"]
end

node_visitor(("Visitor"))
node_livekit{{"LiveKit service"}}

node_visitor -->|"opens app"| node_app_entry
node_app_entry -->|"renders"| node_app_shell
node_app_shell -->|"provides session"| node_session_provider
node_app_shell -->|"renders"| node_view_controller
node_view_controller -->|"shows disconnected"| node_welcome_view
node_view_controller -->|"shows connected"| node_session_view
node_session_view -->|"renders"| node_transcript
node_session_view -->|"renders"| node_control_bar
node_session_view -->|"renders"| node_tile_layout
node_tile_layout -->|"renders"| node_visualizer_router
node_visualizer_router -->|"selects style"| node_aura_visualizer
node_visualizer_router -->|"selects style"| node_bar_visualizer
node_visualizer_router -->|"selects style"| node_grid_visualizer
node_visualizer_router -->|"selects style"| node_radial_visualizer
node_visualizer_router -->|"selects style"| node_wave_visualizer
node_control_bar -->|"renders"| node_track_control
node_control_bar -->|"renders"| node_track_toggle
node_app_shell -->|"monitors session"| node_session_errors
node_welcome_view -.->|"requests token"| node_token_route
node_token_route -->|"checks access"| node_access_check
node_token_route -->|"signs participant token"| node_livekit
node_app_shell -->|"connects session"| node_livekit
node_view_controller -->|"enables inputs"| node_camera_screen
node_tile_layout -.->|"supports avatars"| node_avatar_support
node_app_shell -->|"uses theme"| node_theme

click node_app_entry "https://github.com/dilht/sacco-voice-frontend/blob/main/app/page.tsx"
click node_app_shell "https://github.com/dilht/sacco-voice-frontend/blob/main/components/app/app.tsx"
click node_session_provider "https://github.com/dilht/sacco-voice-frontend/blob/main/components/agents-ui/agent-session-provider.tsx"
click node_view_controller "https://github.com/dilht/sacco-voice-frontend/blob/main/components/app/view-controller.tsx"
click node_welcome_view "https://github.com/dilht/sacco-voice-frontend/blob/main/components/app/welcome-view.tsx"
click node_session_view "https://github.com/dilht/sacco-voice-frontend/blob/main/components/agents-ui/blocks/agent-session-view-01/components/agent-session-block.tsx"
click node_tile_layout "https://github.com/dilht/sacco-voice-frontend/blob/main/components/agents-ui/blocks/agent-session-view-01/components/tile-view.tsx"
click node_visualizer_router "https://github.com/dilht/sacco-voice-frontend/blob/main/components/agents-ui/blocks/agent-session-view-01/components/audio-visualizer.tsx"
click node_aura_visualizer "https://github.com/dilht/sacco-voice-frontend/blob/main/components/agents-ui/agent-audio-visualizer-aura.tsx"
click node_bar_visualizer "https://github.com/dilht/sacco-voice-frontend/blob/main/components/agents-ui/agent-audio-visualizer-bar.tsx"
click node_grid_visualizer "https://github.com/dilht/sacco-voice-frontend/blob/main/components/agents-ui/agent-audio-visualizer-grid.tsx"
click node_radial_visualizer "https://github.com/dilht/sacco-voice-frontend/blob/main/components/agents-ui/agent-audio-visualizer-radial.tsx"
click node_wave_visualizer "https://github.com/dilht/sacco-voice-frontend/blob/main/components/agents-ui/agent-audio-visualizer-wave.tsx"
click node_transcript "https://github.com/dilht/sacco-voice-frontend/blob/main/components/agents-ui/agent-chat-transcript.tsx"
click node_control_bar "https://github.com/dilht/sacco-voice-frontend/blob/main/components/agents-ui/agent-control-bar.tsx"
click node_track_control "https://github.com/dilht/sacco-voice-frontend/blob/main/components/agents-ui/agent-track-control.tsx"
click node_track_toggle "https://github.com/dilht/sacco-voice-frontend/blob/main/components/agents-ui/agent-track-toggle.tsx"
click node_session_errors "https://github.com/dilht/sacco-voice-frontend/blob/main/hooks/useAgentErrors.tsx"
click node_token_route "https://github.com/dilht/sacco-voice-frontend/blob/main/app/api/token/route.ts"
click node_access_check "https://github.com/dilht/sacco-voice-frontend/blob/main/lib/access.ts"
click node_theme "https://github.com/dilht/sacco-voice-frontend/blob/main/components/app/theme-provider.tsx"
click node_camera_screen "https://github.com/dilht/sacco-voice-frontend/blob/main/components/agents-ui/agent-control-bar.tsx"
click node_avatar_support "https://github.com/dilht/sacco-voice-frontend/blob/main/components/agents-ui/blocks/agent-session-view-01/components/tile-view.tsx"

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_entry,node_app_shell,node_session_provider,node_view_controller,node_welcome_view,node_session_errors,node_theme toneBlue
class node_session_view,node_tile_layout,node_visualizer_router,node_aura_visualizer,node_bar_visualizer,node_grid_visualizer,node_radial_visualizer,node_wave_visualizer,node_transcript,node_avatar_support toneAmber
class node_control_bar,node_track_control,node_track_toggle,node_camera_screen toneMint
class node_token_route,node_access_check toneRose
class node_visitor,node_livekit toneIndigo
```

## Components

### Application flow

- [App entry](https://github.com/dilht/sacco-voice-frontend/blob/main/app/page.tsx): `app/page.tsx`
- [Session setup](https://github.com/dilht/sacco-voice-frontend/blob/main/components/app/app.tsx): `components/app/app.tsx`
- [Session provider](https://github.com/dilht/sacco-voice-frontend/blob/main/components/agents-ui/agent-session-provider.tsx): `components/agents-ui/agent-session-provider.tsx`
- [View controller](https://github.com/dilht/sacco-voice-frontend/blob/main/components/app/view-controller.tsx): `components/app/view-controller.tsx`
- [Welcome view](https://github.com/dilht/sacco-voice-frontend/blob/main/components/app/welcome-view.tsx): `components/app/welcome-view.tsx`
- [Agent errors](https://github.com/dilht/sacco-voice-frontend/blob/main/hooks/useAgentErrors.tsx): `hooks/useAgentErrors.tsx`
- [Theme controls](https://github.com/dilht/sacco-voice-frontend/blob/main/components/app/theme-provider.tsx): `components/app/theme-provider.tsx`

### Session experience

- [Session block](https://github.com/dilht/sacco-voice-frontend/blob/main/components/agents-ui/blocks/agent-session-view-01/components/agent-session-block.tsx): `components/agents-ui/blocks/agent-session-view-01/components/agent-session-block.tsx`
- [Media tiles](https://github.com/dilht/sacco-voice-frontend/blob/main/components/agents-ui/blocks/agent-session-view-01/components/tile-view.tsx): `components/agents-ui/blocks/agent-session-view-01/components/tile-view.tsx`
- [Visualizer styles](https://github.com/dilht/sacco-voice-frontend/blob/main/components/agents-ui/blocks/agent-session-view-01/components/audio-visualizer.tsx): `components/agents-ui/blocks/agent-session-view-01/components/audio-visualizer.tsx`
- [Aura visualizer](https://github.com/dilht/sacco-voice-frontend/blob/main/components/agents-ui/agent-audio-visualizer-aura.tsx): `components/agents-ui/agent-audio-visualizer-aura.tsx`
- [Bar visualizer](https://github.com/dilht/sacco-voice-frontend/blob/main/components/agents-ui/agent-audio-visualizer-bar.tsx): `components/agents-ui/agent-audio-visualizer-bar.tsx`
- [Grid visualizer](https://github.com/dilht/sacco-voice-frontend/blob/main/components/agents-ui/agent-audio-visualizer-grid.tsx): `components/agents-ui/agent-audio-visualizer-grid.tsx`
- [Radial visualizer](https://github.com/dilht/sacco-voice-frontend/blob/main/components/agents-ui/agent-audio-visualizer-radial.tsx): `components/agents-ui/agent-audio-visualizer-radial.tsx`
- [Wave visualizer](https://github.com/dilht/sacco-voice-frontend/blob/main/components/agents-ui/agent-audio-visualizer-wave.tsx): `components/agents-ui/agent-audio-visualizer-wave.tsx`
- [Chat transcript](https://github.com/dilht/sacco-voice-frontend/blob/main/components/agents-ui/agent-chat-transcript.tsx): `components/agents-ui/agent-chat-transcript.tsx`
- [Virtual avatars](https://github.com/dilht/sacco-voice-frontend/blob/main/components/agents-ui/blocks/agent-session-view-01/components/tile-view.tsx): `components/agents-ui/blocks/agent-session-view-01/components/tile-view.tsx`

### Media and controls

- [Control bar](https://github.com/dilht/sacco-voice-frontend/blob/main/components/agents-ui/agent-control-bar.tsx): `components/agents-ui/agent-control-bar.tsx`
- [Track controls](https://github.com/dilht/sacco-voice-frontend/blob/main/components/agents-ui/agent-track-control.tsx): `components/agents-ui/agent-track-control.tsx`
- [Track toggles](https://github.com/dilht/sacco-voice-frontend/blob/main/components/agents-ui/agent-track-toggle.tsx): `components/agents-ui/agent-track-toggle.tsx`
- [Camera and sharing](https://github.com/dilht/sacco-voice-frontend/blob/main/components/agents-ui/agent-control-bar.tsx): `components/agents-ui/agent-control-bar.tsx`

### Access and tokens

- [Token endpoint](https://github.com/dilht/sacco-voice-frontend/blob/main/app/api/token/route.ts): `app/api/token/route.ts`
- [Access check](https://github.com/dilht/sacco-voice-frontend/blob/main/lib/access.ts): `lib/access.ts`

### Other components

- **Visitor**
- **LiveKit service**

## Connections

- Visitor → App entry: opens app
- App entry → Session setup: renders (evidence: `app/page.tsx`)
- Session setup → Session provider: provides session (evidence: `components/app/app.tsx`)
- Session setup → View controller: renders (evidence: `components/app/app.tsx`)
- View controller → Welcome view: shows disconnected (evidence: `components/app/view-controller.tsx`)
- View controller → Session block: shows connected (evidence: `components/app/view-controller.tsx`)
- Session block → Chat transcript: renders (evidence: `components/agents-ui/blocks/agent-session-view-01/components/agent-session-block.tsx`)
- Session block → Control bar: renders (evidence: `components/agents-ui/blocks/agent-session-view-01/components/agent-session-block.tsx`)
- Session block → Media tiles: renders (evidence: `components/agents-ui/blocks/agent-session-view-01/components/agent-session-block.tsx`)
- Media tiles → Visualizer styles: renders (evidence: `components/agents-ui/blocks/agent-session-view-01/components/tile-view.tsx`)
- Visualizer styles → Aura visualizer: selects style (evidence: `components/agents-ui/blocks/agent-session-view-01/components/audio-visualizer.tsx`)
- Visualizer styles → Bar visualizer: selects style (evidence: `components/agents-ui/blocks/agent-session-view-01/components/audio-visualizer.tsx`)
- Visualizer styles → Grid visualizer: selects style (evidence: `components/agents-ui/blocks/agent-session-view-01/components/audio-visualizer.tsx`)
- Visualizer styles → Radial visualizer: selects style (evidence: `components/agents-ui/blocks/agent-session-view-01/components/audio-visualizer.tsx`)
- Visualizer styles → Wave visualizer: selects style (evidence: `components/agents-ui/blocks/agent-session-view-01/components/audio-visualizer.tsx`)
- Control bar → Track controls: renders (evidence: `components/agents-ui/agent-control-bar.tsx`)
- Control bar → Track toggles: renders (evidence: `components/agents-ui/agent-control-bar.tsx`)
- Session setup → Agent errors: monitors session (evidence: `components/app/app.tsx`)
- Welcome view → Token endpoint: requests token (evidence: `README.md`)
- Token endpoint → Access check: checks access (evidence: `app/api/token/route.ts`)
- Token endpoint → LiveKit service: signs participant token (evidence: `app/api/token/route.ts`)
- Session setup → LiveKit service: connects session (evidence: `README.md`)
- View controller → Camera and sharing: enables inputs (evidence: `components/app/view-controller.tsx`)
- Media tiles → Virtual avatars: supports avatars (evidence: `README.md`)
- Session setup → Theme controls: uses theme
