# kal51411/alicia architecture

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

- Interactive diagram: https://gitdiagram.com/kal51411/alicia
- Repository: https://github.com/kal51411/alicia

## Overview

Alicia is a personal voice assistant with CLI and desktop entry modes. The principal workflow accepts typed or spoken input, transcribes speech when needed, dispatches commands to AI, search, memory, or system capabilities, then presents a response with optional speech. Its major internal layers include voice processing, command/AI logic, system tools, configuration, and local persistence. The README documents VAD and SQLite, while the tree and sampled storage code show JSON-backed persistence; VAD wiring and some integration details are not established by the excerpts.

Main entry points: [`src/core/cmd/action.py`](https://github.com/kal51411/alicia/blob/main/src/core/cmd/action.py) (Command Dispatcher), [`src/cli.py`](https://github.com/kal51411/alicia/blob/main/src/cli.py) (Terminal Assistant), [`src/gui/mainwindow.py`](https://github.com/kal51411/alicia/blob/main/src/gui/mainwindow.py) (Desktop Window), [`src/gui/thread.py`](https://github.com/kal51411/alicia/blob/main/src/gui/thread.py) (GUI Workers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_entry["Application Entry<br/>[main.py]"]
  node_cli["Terminal Assistant<br/>[cli.py]"]
  node_gui["Desktop Window<br/>[mainwindow.py]"]
  node_workers["GUI Workers<br/>[thread.py]"]
end

subgraph group_voice["Voice Processing"]
  node_vad["Voice Activity Detection<br/>[vad.py]"]
  node_stt["Speech Recognition<br/>[stt.py]"]
  node_wake["Wake Word Matching<br/>[fuzz.py]"]
  node_tts["Speech Synthesis<br/>[tts.py]"]
end

subgraph group_intelligence["Command Intelligence"]
  node_router["Command Dispatcher<br/>[action.py]"]
  node_model["Gemini Conversation<br/>[model.py]"]
  node_summary["Text Summarization<br/>[summary.py]"]
  node_vision["Vision Logic<br/>[vision.py]"]
  node_search["Web Search<br/>[search.py]"]
end

subgraph group_platform["Platform and State"]
  node_system["System Commands<br/>[system.py]"]
  node_crossplatform["Cross-platform Actions<br/>[crossplatform.py]"]
  node_crosspath["Path Utilities<br/>[crosspath.py]"]
  node_settings["Application Settings<br/>[settings.py]"]
  node_database[("JSON Persistence<br/>[manager.py]")]
end

node_user(("User"))
node_google(("Google Gemini"))
node_hf(("Hugging Face"))
node_web(("Web Services"))
node_os(("Operating System"))
node_localdata[("Local JSON Files")]

node_user -->|"starts"| node_entry
node_entry -->|"launches default"| node_cli
node_entry -->|"launches GUI"| node_gui
node_gui -->|"falls back"| node_cli
node_user -->|"types or speaks"| node_cli
node_user -->|"interacts"| node_gui
node_cli -->|"transcribes input"| node_stt
node_workers -->|"captures speech"| node_stt
node_workers -->|"checks phrase"| node_wake
node_cli -->|"checks wake word"| node_wake
node_gui -->|"starts workers"| node_workers
node_cli -->|"dispatches command"| node_router
node_workers -->|"executes command"| node_router
node_router -->|"requests response"| node_model
node_model -->|"sends prompt"| node_google
node_router -->|"summarizes text"| node_summary
node_summary -->|"uses fallback"| node_model
node_summary -.->|"requests summary"| node_hf
node_router -->|"delegates vision"| node_vision
node_router -->|"delegates search"| node_search
node_search -.->|"queries web"| node_web
node_router -->|"runs system action"| node_system
node_workers -->|"samples metrics"| node_system
node_system -->|"reads or controls"| node_os
node_router -->|"opens target"| node_crossplatform
node_system -->|"uses platform helper"| node_crossplatform
node_gui -->|"uses path helper"| node_crosspath
node_router -->|"stores and reads notes"| node_database
node_cli -->|"reads user data"| node_database
node_gui -->|"reads user data"| node_database
node_database -->|"reads and writes"| node_localdata
node_cli -->|"speaks response"| node_tts
node_workers -->|"uses speech output"| node_tts
node_gui -->|"uses speech output"| node_tts
node_stt -->|"reads voice options"| node_settings
node_tts -->|"reads voice options"| node_settings
node_model -->|"reads AI options"| node_settings
node_database -->|"uses database paths"| node_settings
node_vad -.->|"speech gating"| node_stt

click node_entry "https://github.com/kal51411/alicia/blob/main/src/main.py"
click node_cli "https://github.com/kal51411/alicia/blob/main/src/cli.py"
click node_gui "https://github.com/kal51411/alicia/blob/main/src/gui/mainwindow.py"
click node_workers "https://github.com/kal51411/alicia/blob/main/src/gui/thread.py"
click node_vad "https://github.com/kal51411/alicia/blob/main/src/core/voice/vad.py"
click node_stt "https://github.com/kal51411/alicia/blob/main/src/core/voice/stt.py"
click node_wake "https://github.com/kal51411/alicia/blob/main/src/core/voice/fuzz.py"
click node_tts "https://github.com/kal51411/alicia/blob/main/src/core/voice/tts.py"
click node_router "https://github.com/kal51411/alicia/blob/main/src/core/cmd/action.py"
click node_model "https://github.com/kal51411/alicia/blob/main/src/core/logic/model.py"
click node_summary "https://github.com/kal51411/alicia/blob/main/src/core/logic/summary.py"
click node_vision "https://github.com/kal51411/alicia/blob/main/src/core/logic/vision.py"
click node_search "https://github.com/kal51411/alicia/blob/main/src/core/cmd/search.py"
click node_system "https://github.com/kal51411/alicia/blob/main/src/core/cmd/system.py"
click node_crossplatform "https://github.com/kal51411/alicia/blob/main/src/core/utils/crossplatform.py"
click node_crosspath "https://github.com/kal51411/alicia/blob/main/src/core/utils/crosspath.py"
click node_settings "https://github.com/kal51411/alicia/blob/main/config/settings.py"
click node_database "https://github.com/kal51411/alicia/blob/main/database/manager.py"

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_entry,node_cli,node_gui,node_workers,node_user toneBlue
class node_vad,node_stt,node_wake,node_tts,node_localdata toneAmber
class node_router,node_model,node_summary,node_vision,node_search toneMint
class node_system,node_crossplatform,node_crosspath,node_settings,node_database toneRose
class node_google,node_hf,node_web,node_os toneIndigo
```

## Components

### User Interfaces

- [Application Entry](https://github.com/kal51411/alicia/blob/main/src/main.py): `src/main.py`
- [Terminal Assistant](https://github.com/kal51411/alicia/blob/main/src/cli.py): `src/cli.py`
- [Desktop Window](https://github.com/kal51411/alicia/blob/main/src/gui/mainwindow.py): `src/gui/mainwindow.py`
- [GUI Workers](https://github.com/kal51411/alicia/blob/main/src/gui/thread.py): `src/gui/thread.py`

### Voice Processing

- [Voice Activity Detection](https://github.com/kal51411/alicia/blob/main/src/core/voice/vad.py): `src/core/voice/vad.py`
- [Speech Recognition](https://github.com/kal51411/alicia/blob/main/src/core/voice/stt.py): `src/core/voice/stt.py`
- [Wake Word Matching](https://github.com/kal51411/alicia/blob/main/src/core/voice/fuzz.py): `src/core/voice/fuzz.py`
- [Speech Synthesis](https://github.com/kal51411/alicia/blob/main/src/core/voice/tts.py): `src/core/voice/tts.py`

### Command Intelligence

- [Command Dispatcher](https://github.com/kal51411/alicia/blob/main/src/core/cmd/action.py): `src/core/cmd/action.py`
- [Gemini Conversation](https://github.com/kal51411/alicia/blob/main/src/core/logic/model.py): `src/core/logic/model.py`
- [Text Summarization](https://github.com/kal51411/alicia/blob/main/src/core/logic/summary.py): `src/core/logic/summary.py`
- [Vision Logic](https://github.com/kal51411/alicia/blob/main/src/core/logic/vision.py): `src/core/logic/vision.py`
- [Web Search](https://github.com/kal51411/alicia/blob/main/src/core/cmd/search.py): `src/core/cmd/search.py`

### Platform and State

- [System Commands](https://github.com/kal51411/alicia/blob/main/src/core/cmd/system.py): `src/core/cmd/system.py`
- [Cross-platform Actions](https://github.com/kal51411/alicia/blob/main/src/core/utils/crossplatform.py): `src/core/utils/crossplatform.py`
- [Path Utilities](https://github.com/kal51411/alicia/blob/main/src/core/utils/crosspath.py): `src/core/utils/crosspath.py`
- [Application Settings](https://github.com/kal51411/alicia/blob/main/config/settings.py): `config/settings.py`
- [JSON Persistence](https://github.com/kal51411/alicia/blob/main/database/manager.py): `database/manager.py`

### Other components

- **User**
- **Google Gemini**
- **Hugging Face**
- **Web Services**
- **Operating System**
- **Local JSON Files**

## Connections

- User → Application Entry: starts (evidence: `README.md`)
- Application Entry → Terminal Assistant: launches default (evidence: `src/main.py`)
- Application Entry → Desktop Window: launches GUI (evidence: `src/main.py`)
- Desktop Window → Terminal Assistant: falls back (evidence: `src/main.py`)
- User → Terminal Assistant: types or speaks (evidence: `src/cli.py`)
- User → Desktop Window: interacts (evidence: `src/gui/mainwindow.py`)
- Terminal Assistant → Speech Recognition: transcribes input (evidence: `src/cli.py`)
- GUI Workers → Speech Recognition: captures speech (evidence: `src/gui/thread.py`)
- GUI Workers → Wake Word Matching: checks phrase (evidence: `src/gui/thread.py`)
- Terminal Assistant → Wake Word Matching: checks wake word (evidence: `src/cli.py`)
- Desktop Window → GUI Workers: starts workers (evidence: `src/gui/mainwindow.py`)
- Terminal Assistant → Command Dispatcher: dispatches command (evidence: `src/cli.py`)
- GUI Workers → Command Dispatcher: executes command (evidence: `src/gui/thread.py`)
- Command Dispatcher → Gemini Conversation: requests response (evidence: `src/core/cmd/action.py`)
- Gemini Conversation → Google Gemini: sends prompt (evidence: `src/core/logic/model.py`)
- Command Dispatcher → Text Summarization: summarizes text (evidence: `src/core/cmd/action.py`)
- Text Summarization → Gemini Conversation: uses fallback (evidence: `src/core/logic/summary.py`)
- Text Summarization → Hugging Face: requests summary
- Command Dispatcher → Vision Logic: delegates vision (evidence: `src/core/cmd/action.py`)
- Command Dispatcher → Web Search: delegates search (evidence: `src/core/cmd/action.py`)
- Web Search → Web Services: queries web
- Command Dispatcher → System Commands: runs system action (evidence: `src/core/cmd/action.py`)
- GUI Workers → System Commands: samples metrics (evidence: `src/gui/thread.py`)
- System Commands → Operating System: reads or controls (evidence: `src/core/cmd/system.py`)
- Command Dispatcher → Cross-platform Actions: opens target (evidence: `src/core/cmd/action.py`)
- System Commands → Cross-platform Actions: uses platform helper (evidence: `src/core/cmd/system.py`)
- Desktop Window → Path Utilities: uses path helper (evidence: `src/gui/mainwindow.py`)
- Command Dispatcher → JSON Persistence: stores and reads notes (evidence: `src/core/cmd/action.py`)
- Terminal Assistant → JSON Persistence: reads user data (evidence: `src/cli.py`)
- Desktop Window → JSON Persistence: reads user data (evidence: `src/gui/mainwindow.py`)
- JSON Persistence → Local JSON Files: reads and writes (evidence: `database/manager.py`)
- Terminal Assistant → Speech Synthesis: speaks response (evidence: `src/cli.py`)
- GUI Workers → Speech Synthesis: uses speech output (evidence: `src/gui/thread.py`)
- Desktop Window → Speech Synthesis: uses speech output (evidence: `src/gui/mainwindow.py`)
- Speech Recognition → Application Settings: reads voice options (evidence: `src/core/voice/stt.py`)
- Speech Synthesis → Application Settings: reads voice options (evidence: `src/core/voice/tts.py`)
- Gemini Conversation → Application Settings: reads AI options (evidence: `src/core/logic/model.py`)
- JSON Persistence → Application Settings: uses database paths (evidence: `database/manager.py`)
- Voice Activity Detection → Speech Recognition: speech gating
