# gui-bertoso/maya architecture

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

- Interactive diagram: https://gitdiagram.com/gui-bertoso/maya
- Repository: https://github.com/gui-bertoso/maya

## Overview

Maya is a local-first desktop voice assistant. The main workflow captures speech, recognizes a command, processes it asynchronously, and presents a response through the overlay and speech output. Command handling also covers routines, memory and vocabulary, plus desktop, web, music, and workspace automation. The graph includes major documented capabilities and substantial indexed modules. Some connections are documented or inferred rather than visible in sampled call sites; those are dashed and unverified. Paths identify source implementations, not every data file they may use.

Main entry points: [`core/process.py`](https://github.com/gui-bertoso/maya/blob/before-AI/core/process.py) (Command processing), [`app.py`](https://github.com/gui-bertoso/maya/blob/before-AI/app.py) (Desktop lifecycle), [`output/renderer.py`](https://github.com/gui-bertoso/maya/blob/before-AI/output/renderer.py) (Overlay and UI), [`core/memory.py`](https://github.com/gui-bertoso/maya/blob/before-AI/core/memory.py) (Conversation memory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Input and experience"]
  node_voice["Voice recognition<br/>[voice.py]"]
  node_clap["Clap detection<br/>[clap_detector.py]"]
  node_app["Desktop lifecycle<br/>[app.py]"]
  node_renderer["Overlay and UI<br/>[renderer.py]"]
  node_speaker["Speech output<br/>[speaker.py]"]
  node_showcase["Window showcase<br/>[window_showcase.py]"]
end

subgraph group_orchestration["Command orchestration"]
  node_pipeline["Async input pipeline<br/>[input_pipeline.py]"]
  node_assistant["Command processing<br/>[process.py]"]
end

subgraph group_personal["Personal state"]
  node_memory["Conversation memory<br/>[memory.py]"]
  node_knowledge["Knowledge base<br/>[knowledge_base.py]"]
  node_vocabulary["Vocabulary manager"]
  node_routine["Routine scheduling<br/>[routine_manager.py]"]
  node_localdata[("Local JSON state")]
end

subgraph group_automation["Automation"]
  node_launcher["App launcher<br/>[app_launcher.py]"]
  node_web["Web assistant<br/>[web_assistant.py]"]
  node_spotify["Spotify assistant"]
  node_dev["Developer workspace<br/>[dev_assistant.py]"]
  node_workspace["Workspace tools<br/>[dev_workspace.py]"]
  node_thoughtful["Thoughtful workspace"]
end

subgraph group_platform["Runtime support"]
  node_backup["Safe persistence<br/>[backup_manager.py]"]
  node_i18n["Localization<br/>[i18n.py]"]
  node_config["Runtime configuration<br/>[config.py]"]
end

node_user(("Person"))
node_desktop(("Desktop environment"))
node_webservice(("Web services"))
node_spotifyservice(("Spotify client"))

node_user -->|"speaks to"| node_voice
node_voice -->|"delivers transcripts"| node_app
node_clap -->|"signals wake"| node_app
node_app -.->|"submits work"| node_pipeline
node_pipeline -.->|"runs callback"| node_assistant
node_app -.->|"processes commands"| node_assistant
node_assistant -->|"dispatches UI events"| node_app
node_app -.->|"updates interface"| node_renderer
node_app -->|"speaks responses"| node_speaker
node_assistant -->|"records conversation"| node_memory
node_assistant -->|"uses knowledge"| node_knowledge
node_assistant -->|"uses vocabulary"| node_vocabulary
node_assistant -->|"handles routines"| node_routine
node_memory -->|"loads and saves"| node_backup
node_vocabulary -->|"loads and saves"| node_backup
node_routine -.->|"persists progress"| node_localdata
node_memory -.->|"persists memory"| node_localdata
node_vocabulary -.->|"persists vocabulary"| node_localdata
node_assistant -.->|"dispatches automation"| node_launcher
node_assistant -.->|"dispatches web tasks"| node_web
node_assistant -.->|"dispatches music tasks"| node_spotify
node_assistant -.->|"dispatches dev tasks"| node_dev
node_assistant -.->|"delegates workspace"| node_workspace
node_assistant -.->|"dispatches workspace"| node_thoughtful
node_launcher -.->|"launches apps"| node_desktop
node_web -.->|"uses online services"| node_webservice
node_spotify -.->|"opens and searches"| node_spotifyservice
node_renderer -->|"uses window tools"| node_showcase
node_renderer -->|"uses workspace tools"| node_workspace
node_renderer -->|"uses workspace tools"| node_thoughtful
node_renderer -->|"localizes interface"| node_i18n
node_assistant -.->|"reads settings"| node_config
node_memory -->|"resolves storage path"| node_config
node_routine -->|"resolves storage path"| node_config
node_voice -->|"reads audio settings"| node_config

click node_voice "https://github.com/gui-bertoso/maya/blob/before-AI/input/voice.py"
click node_clap "https://github.com/gui-bertoso/maya/blob/before-AI/input/clap_detector.py"
click node_app "https://github.com/gui-bertoso/maya/blob/before-AI/app.py"
click node_pipeline "https://github.com/gui-bertoso/maya/blob/before-AI/core/input_pipeline.py"
click node_assistant "https://github.com/gui-bertoso/maya/blob/before-AI/core/process.py"
click node_renderer "https://github.com/gui-bertoso/maya/blob/before-AI/output/renderer.py"
click node_speaker "https://github.com/gui-bertoso/maya/blob/before-AI/output/speaker.py"
click node_memory "https://github.com/gui-bertoso/maya/blob/before-AI/core/memory.py"
click node_knowledge "https://github.com/gui-bertoso/maya/blob/before-AI/core/knowledge_base.py"
click node_vocabulary "https://github.com/gui-bertoso/maya/blob/before-AI/core/vocabulary_manager.py"
click node_routine "https://github.com/gui-bertoso/maya/blob/before-AI/core/routine_manager.py"
click node_localdata "https://github.com/gui-bertoso/maya/tree/before-AI/data"
click node_backup "https://github.com/gui-bertoso/maya/blob/before-AI/helpers/backup_manager.py"
click node_launcher "https://github.com/gui-bertoso/maya/blob/before-AI/helpers/app_launcher.py"
click node_web "https://github.com/gui-bertoso/maya/blob/before-AI/helpers/web_assistant.py"
click node_spotify "https://github.com/gui-bertoso/maya/blob/before-AI/helpers/spotify_assistant.py"
click node_dev "https://github.com/gui-bertoso/maya/blob/before-AI/helpers/dev_assistant.py"
click node_workspace "https://github.com/gui-bertoso/maya/blob/before-AI/helpers/dev_workspace.py"
click node_thoughtful "https://github.com/gui-bertoso/maya/blob/before-AI/helpers/thoughtful_workspace.py"
click node_showcase "https://github.com/gui-bertoso/maya/blob/before-AI/helpers/window_showcase.py"
click node_i18n "https://github.com/gui-bertoso/maya/blob/before-AI/helpers/i18n.py"
click node_config "https://github.com/gui-bertoso/maya/blob/before-AI/helpers/config.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_voice,node_clap,node_app,node_renderer,node_speaker,node_showcase,node_spotifyservice toneBlue
class node_pipeline,node_assistant toneAmber
class node_memory,node_knowledge,node_vocabulary,node_routine,node_localdata toneMint
class node_launcher,node_web,node_spotify,node_dev,node_workspace,node_thoughtful toneRose
class node_backup,node_i18n,node_config,node_user,node_desktop,node_webservice toneIndigo
```

## Components

### Input and experience

- [Voice recognition](https://github.com/gui-bertoso/maya/blob/before-AI/input/voice.py): `input/voice.py`
- [Clap detection](https://github.com/gui-bertoso/maya/blob/before-AI/input/clap_detector.py): `input/clap_detector.py`
- [Desktop lifecycle](https://github.com/gui-bertoso/maya/blob/before-AI/app.py): `app.py`
- [Overlay and UI](https://github.com/gui-bertoso/maya/blob/before-AI/output/renderer.py): `output/renderer.py`
- [Speech output](https://github.com/gui-bertoso/maya/blob/before-AI/output/speaker.py): `output/speaker.py`
- [Window showcase](https://github.com/gui-bertoso/maya/blob/before-AI/helpers/window_showcase.py): `helpers/window_showcase.py`

### Command orchestration

- [Async input pipeline](https://github.com/gui-bertoso/maya/blob/before-AI/core/input_pipeline.py): `core/input_pipeline.py`
- [Command processing](https://github.com/gui-bertoso/maya/blob/before-AI/core/process.py): `core/process.py`

### Personal state

- [Conversation memory](https://github.com/gui-bertoso/maya/blob/before-AI/core/memory.py): `core/memory.py`
- [Knowledge base](https://github.com/gui-bertoso/maya/blob/before-AI/core/knowledge_base.py): `core/knowledge_base.py`
- [Vocabulary manager](https://github.com/gui-bertoso/maya/blob/before-AI/core/vocabulary_manager.py): `core/vocabulary_manager.py`
- [Routine scheduling](https://github.com/gui-bertoso/maya/blob/before-AI/core/routine_manager.py): `core/routine_manager.py`
- [Local JSON state](https://github.com/gui-bertoso/maya/tree/before-AI/data): `data`

### Automation

- [App launcher](https://github.com/gui-bertoso/maya/blob/before-AI/helpers/app_launcher.py): `helpers/app_launcher.py`
- [Web assistant](https://github.com/gui-bertoso/maya/blob/before-AI/helpers/web_assistant.py): `helpers/web_assistant.py`
- [Spotify assistant](https://github.com/gui-bertoso/maya/blob/before-AI/helpers/spotify_assistant.py): `helpers/spotify_assistant.py`
- [Developer workspace](https://github.com/gui-bertoso/maya/blob/before-AI/helpers/dev_assistant.py): `helpers/dev_assistant.py`
- [Workspace tools](https://github.com/gui-bertoso/maya/blob/before-AI/helpers/dev_workspace.py): `helpers/dev_workspace.py`
- [Thoughtful workspace](https://github.com/gui-bertoso/maya/blob/before-AI/helpers/thoughtful_workspace.py): `helpers/thoughtful_workspace.py`

### Runtime support

- [Safe persistence](https://github.com/gui-bertoso/maya/blob/before-AI/helpers/backup_manager.py): `helpers/backup_manager.py`
- [Localization](https://github.com/gui-bertoso/maya/blob/before-AI/helpers/i18n.py): `helpers/i18n.py`
- [Runtime configuration](https://github.com/gui-bertoso/maya/blob/before-AI/helpers/config.py): `helpers/config.py`

### Other components

- **Person**
- **Desktop environment**
- **Web services**
- **Spotify client**

## Connections

- Person → Voice recognition: speaks to (evidence: `README.md`)
- Voice recognition → Desktop lifecycle: delivers transcripts (evidence: `app.py`)
- Clap detection → Desktop lifecycle: signals wake (evidence: `app.py`)
- Desktop lifecycle → Async input pipeline: submits work (evidence: `app.py`)
- Async input pipeline → Command processing: runs callback
- Desktop lifecycle → Command processing: processes commands (evidence: `app.py`)
- Command processing → Desktop lifecycle: dispatches UI events (evidence: `core/process.py`)
- Desktop lifecycle → Overlay and UI: updates interface (evidence: `app.py`)
- Desktop lifecycle → Speech output: speaks responses (evidence: `app.py`)
- Command processing → Conversation memory: records conversation (evidence: `core/process.py`)
- Command processing → Knowledge base: uses knowledge (evidence: `core/process.py`)
- Command processing → Vocabulary manager: uses vocabulary (evidence: `core/process.py`)
- Command processing → Routine scheduling: handles routines (evidence: `core/process.py`)
- Conversation memory → Safe persistence: loads and saves (evidence: `core/memory.py`)
- Vocabulary manager → Safe persistence: loads and saves (evidence: `core/vocabulary_manager.py`)
- Routine scheduling → Local JSON state: persists progress
- Conversation memory → Local JSON state: persists memory
- Vocabulary manager → Local JSON state: persists vocabulary
- Command processing → App launcher: dispatches automation
- Command processing → Web assistant: dispatches web tasks
- Command processing → Spotify assistant: dispatches music tasks
- Command processing → Developer workspace: dispatches dev tasks
- Command processing → Workspace tools: delegates workspace
- Command processing → Thoughtful workspace: dispatches workspace
- App launcher → Desktop environment: launches apps
- Web assistant → Web services: uses online services
- Spotify assistant → Spotify client: opens and searches
- Overlay and UI → Window showcase: uses window tools (evidence: `output/renderer.py`)
- Overlay and UI → Workspace tools: uses workspace tools (evidence: `output/renderer.py`)
- Overlay and UI → Thoughtful workspace: uses workspace tools (evidence: `output/renderer.py`)
- Overlay and UI → Localization: localizes interface (evidence: `output/renderer.py`)
- Command processing → Runtime configuration: reads settings (evidence: `core/process.py`)
- Conversation memory → Runtime configuration: resolves storage path (evidence: `core/memory.py`)
- Routine scheduling → Runtime configuration: resolves storage path (evidence: `core/routine_manager.py`)
- Voice recognition → Runtime configuration: reads audio settings (evidence: `input/voice.py`)