# firestar3/olanga-desktop-agent architecture

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

- Interactive diagram: https://gitdiagram.com/firestar3/olanga-desktop-agent
- Repository: https://github.com/firestar3/olanga-desktop-agent
- Video tour (about a minute): https://gitdiagram.com/firestar3/olanga-desktop-agent/video

## Overview

Olanga is a Windows desktop voice-and-text assistant. A request enters through the Electron interface, is handled locally when it matches a fast intent or interpreted with Gemini, then dispatches supported desktop, media, timer, or task actions before a reply is presented. Screen-edit workflows add capture, scoped planning, approval, execution, and visible-result review. The README documents Notes, News, Terminal, settings, and the corner status orb as additional capabilities. Source excerpts are partial, so uncertain internal wiring is omitted.

Main entry points: [`js/assistant.js`](https://github.com/firestar3/olanga-desktop-agent/blob/main/js/assistant.js) (Conversation and routing), [`main.js`](https://github.com/firestar3/olanga-desktop-agent/blob/main/main.js) (Electron main process), [`js/core.js`](https://github.com/firestar3/olanga-desktop-agent/blob/main/js/core.js) (UI controller), [`js/tts.js`](https://github.com/firestar3/olanga-desktop-agent/blob/main/js/tts.js) (Speech output)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Assistant interaction"]
  node_ui["Assistant window<br/>[index.html]"]
  node_core["UI controller<br/>[core.js]"]
  node_voice["Voice input<br/>[voice.js]"]
  node_assistant["Conversation and routing<br/>[assistant.js]"]
  node_intents["Fast intents<br/>[fast-intents.js]"]
  node_gemini_request["Gemini request builder<br/>[gemini-request.js]"]
  node_tts["Speech output<br/>[tts.js]"]
end

subgraph group_actions["Desktop actions"]
  node_timer_tasks["Timers and checklist<br/>[timers-tasks.js]"]
  node_desktop_ui["Desktop task workspace"]
  node_plan["Plan validation<br/>[action-plan.js]"]
  node_automation["Desktop automation<br/>[automation.js]"]
  node_desktop_helper["Windows input helper<br/>[input-helper.ps1]"]
  node_media["Spotify and volume"]
  node_media_helper["Windows media helper<br/>[media-helper.ps1]"]
end

subgraph group_workspace["Panels and settings"]
  node_notes["Notepad panel<br/>[notepad.js]"]
  node_news["News panel<br/>[news.js]"]
  node_terminal["Terminal panel<br/>[terminal.js]"]
  node_settings["Settings<br/>[settings.js]"]
end

subgraph group_platform["Electron platform"]
  node_orb_controller["Status orb controller<br/>[status-overlay.js]"]
  node_orb_ui["Status orb interface"]
  node_main["Electron main process<br/>[main.js]"]
  node_preload["Main window bridge<br/>[preload.js]"]
end

node_person(("User"))
node_gemini{{"Gemini service"}}
node_spotify["Spotify app"]
node_windows["Windows desktop"]
node_nvidia{{"NVIDIA Magpie"}}

node_person -->|"types request"| node_ui
node_person -->|"speaks request"| node_voice
node_ui -->|"provides interface"| node_core
node_voice -->|"transcribes input"| node_assistant
node_core -->|"submits request"| node_assistant
node_assistant -->|"matches locally"| node_intents
node_assistant -->|"builds request"| node_gemini_request
node_gemini_request -->|"formats for"| node_gemini
node_assistant -->|"updates timers/tasks"| node_timer_tasks
node_assistant -->|"requests media action"| node_media
node_assistant -->|"starts screen task"| node_desktop_ui
node_desktop_ui -->|"requests capture/run"| node_main
node_desktop_ui -->|"validates proposed plan"| node_plan
node_main -->|"dispatches desktop work"| node_automation
node_automation -->|"validates plan"| node_plan
node_automation -->|"sends input commands"| node_desktop_helper
node_media -->|"sends media request"| node_media_helper
node_media_helper -->|"controls playback"| node_spotify
node_media_helper -->|"controls volume"| node_windows
node_assistant -->|"uses notes panel"| node_notes
node_assistant -->|"requests briefing"| node_news
node_person -->|"uses panel"| node_terminal
node_person -->|"configures assistant"| node_settings
node_main -->|"creates overlay"| node_orb_controller
node_orb_controller -->|"sends snapshots"| node_orb_ui
node_orb_ui -->|"dispatches shortcuts"| node_orb_controller
node_core -->|"uses bridge"| node_preload
node_preload -->|"sends IPC"| node_main
node_assistant -->|"speaks response"| node_tts
node_tts -.->|"synthesizes optionally"| node_nvidia
node_tts -.->|"uses Windows voice"| node_windows

click node_ui "https://github.com/firestar3/olanga-desktop-agent/blob/main/index.html"
click node_core "https://github.com/firestar3/olanga-desktop-agent/blob/main/js/core.js"
click node_voice "https://github.com/firestar3/olanga-desktop-agent/blob/main/js/voice.js"
click node_assistant "https://github.com/firestar3/olanga-desktop-agent/blob/main/js/assistant.js"
click node_intents "https://github.com/firestar3/olanga-desktop-agent/blob/main/shared/fast-intents.js"
click node_gemini_request "https://github.com/firestar3/olanga-desktop-agent/blob/main/shared/gemini-request.js"
click node_tts "https://github.com/firestar3/olanga-desktop-agent/blob/main/js/tts.js"
click node_timer_tasks "https://github.com/firestar3/olanga-desktop-agent/blob/main/js/timers-tasks.js"
click node_desktop_ui "https://github.com/firestar3/olanga-desktop-agent/blob/main/js/desktop-workflows.js"
click node_plan "https://github.com/firestar3/olanga-desktop-agent/blob/main/shared/action-plan.js"
click node_automation "https://github.com/firestar3/olanga-desktop-agent/blob/main/desktop/automation.js"
click node_desktop_helper "https://github.com/firestar3/olanga-desktop-agent/blob/main/desktop/input-helper.ps1"
click node_media "https://github.com/firestar3/olanga-desktop-agent/blob/main/desktop/media-controller.js"
click node_media_helper "https://github.com/firestar3/olanga-desktop-agent/blob/main/desktop/media-helper.ps1"
click node_notes "https://github.com/firestar3/olanga-desktop-agent/blob/main/js/notepad.js"
click node_news "https://github.com/firestar3/olanga-desktop-agent/blob/main/js/news.js"
click node_terminal "https://github.com/firestar3/olanga-desktop-agent/blob/main/js/terminal.js"
click node_settings "https://github.com/firestar3/olanga-desktop-agent/blob/main/js/settings.js"
click node_orb_controller "https://github.com/firestar3/olanga-desktop-agent/blob/main/desktop/status-overlay.js"
click node_orb_ui "https://github.com/firestar3/olanga-desktop-agent/blob/main/status-indicator.js"
click node_main "https://github.com/firestar3/olanga-desktop-agent/blob/main/main.js"
click node_preload "https://github.com/firestar3/olanga-desktop-agent/blob/main/preload.js"

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_ui,node_core,node_voice,node_assistant,node_intents,node_gemini_request,node_tts,node_person toneBlue
class node_timer_tasks,node_desktop_ui,node_plan,node_automation,node_desktop_helper,node_media,node_media_helper toneAmber
class node_notes,node_news,node_terminal,node_settings toneMint
class node_orb_controller,node_orb_ui,node_main,node_preload toneRose
class node_gemini,node_spotify,node_windows,node_nvidia toneIndigo
```

## Components

### Assistant interaction

- [Assistant window](https://github.com/firestar3/olanga-desktop-agent/blob/main/index.html): `index.html`
- [UI controller](https://github.com/firestar3/olanga-desktop-agent/blob/main/js/core.js): `js/core.js`
- [Voice input](https://github.com/firestar3/olanga-desktop-agent/blob/main/js/voice.js): `js/voice.js`
- [Conversation and routing](https://github.com/firestar3/olanga-desktop-agent/blob/main/js/assistant.js): `js/assistant.js`
- [Fast intents](https://github.com/firestar3/olanga-desktop-agent/blob/main/shared/fast-intents.js): `shared/fast-intents.js`
- [Gemini request builder](https://github.com/firestar3/olanga-desktop-agent/blob/main/shared/gemini-request.js): `shared/gemini-request.js`
- [Speech output](https://github.com/firestar3/olanga-desktop-agent/blob/main/js/tts.js): `js/tts.js`

### Desktop actions

- [Timers and checklist](https://github.com/firestar3/olanga-desktop-agent/blob/main/js/timers-tasks.js): `js/timers-tasks.js`
- [Desktop task workspace](https://github.com/firestar3/olanga-desktop-agent/blob/main/js/desktop-workflows.js): `js/desktop-workflows.js`
- [Plan validation](https://github.com/firestar3/olanga-desktop-agent/blob/main/shared/action-plan.js): `shared/action-plan.js`
- [Desktop automation](https://github.com/firestar3/olanga-desktop-agent/blob/main/desktop/automation.js): `desktop/automation.js`
- [Windows input helper](https://github.com/firestar3/olanga-desktop-agent/blob/main/desktop/input-helper.ps1): `desktop/input-helper.ps1`
- [Spotify and volume](https://github.com/firestar3/olanga-desktop-agent/blob/main/desktop/media-controller.js): `desktop/media-controller.js`
- [Windows media helper](https://github.com/firestar3/olanga-desktop-agent/blob/main/desktop/media-helper.ps1): `desktop/media-helper.ps1`

### Panels and settings

- [Notepad panel](https://github.com/firestar3/olanga-desktop-agent/blob/main/js/notepad.js): `js/notepad.js`
- [News panel](https://github.com/firestar3/olanga-desktop-agent/blob/main/js/news.js): `js/news.js`
- [Terminal panel](https://github.com/firestar3/olanga-desktop-agent/blob/main/js/terminal.js): `js/terminal.js`
- [Settings](https://github.com/firestar3/olanga-desktop-agent/blob/main/js/settings.js): `js/settings.js`

### Electron platform

- [Status orb controller](https://github.com/firestar3/olanga-desktop-agent/blob/main/desktop/status-overlay.js): `desktop/status-overlay.js`
- [Status orb interface](https://github.com/firestar3/olanga-desktop-agent/blob/main/status-indicator.js): `status-indicator.js`
- [Electron main process](https://github.com/firestar3/olanga-desktop-agent/blob/main/main.js): `main.js`
- [Main window bridge](https://github.com/firestar3/olanga-desktop-agent/blob/main/preload.js): `preload.js`

### Other components

- **User**
- **Gemini service**
- **Spotify app**
- **Windows desktop**
- **NVIDIA Magpie**

## Connections

- User → Assistant window: types request
- User → Voice input: speaks request
- Assistant window → UI controller: provides interface
- Voice input → Conversation and routing: transcribes input
- UI controller → Conversation and routing: submits request
- Conversation and routing → Fast intents: matches locally
- Conversation and routing → Gemini request builder: builds request
- Gemini request builder → Gemini service: formats for
- Conversation and routing → Timers and checklist: updates timers/tasks
- Conversation and routing → Spotify and volume: requests media action
- Conversation and routing → Desktop task workspace: starts screen task
- Desktop task workspace → Electron main process: requests capture/run
- Desktop task workspace → Plan validation: validates proposed plan
- Electron main process → Desktop automation: dispatches desktop work
- Desktop automation → Plan validation: validates plan
- Desktop automation → Windows input helper: sends input commands
- Spotify and volume → Windows media helper: sends media request
- Windows media helper → Spotify app: controls playback
- Windows media helper → Windows desktop: controls volume
- Conversation and routing → Notepad panel: uses notes panel
- Conversation and routing → News panel: requests briefing
- User → Terminal panel: uses panel
- User → Settings: configures assistant
- Electron main process → Status orb controller: creates overlay
- Status orb controller → Status orb interface: sends snapshots
- Status orb interface → Status orb controller: dispatches shortcuts
- UI controller → Main window bridge: uses bridge
- Main window bridge → Electron main process: sends IPC
- Conversation and routing → Speech output: speaks response
- Speech output → NVIDIA Magpie: synthesizes optionally
- Speech output → Windows desktop: uses Windows voice