# shamanthhiremath/opencluely architecture

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

- Interactive diagram: https://gitdiagram.com/shamanthhiremath/opencluely
- Repository: https://github.com/shamanthhiremath/opencluely

## Overview

OpenCluely is an Electron desktop interview copilot. The main workflow is voice, chat, or screenshot input → session-aware Gemini reasoning → streamed answers in the overlay and optional chat. The graph also includes documented stealth/window behavior, language and settings controls, and local Whisper support. README-described features are included where relevant, but unsampled implementation details and uncertain call paths are not expanded.

Main entry points: [`main.js`](https://github.com/shamanthhiremath/opencluely/blob/main/main.js) (Application controller), [`src/services/llm.service.js`](https://github.com/shamanthhiremath/opencluely/blob/main/src/services/llm.service.js) (Gemini service), [`src/services/speech.service.js`](https://github.com/shamanthhiremath/opencluely/blob/main/src/services/speech.service.js) (Speech recognition), [`src/managers/window.manager.js`](https://github.com/shamanthhiremath/opencluely/blob/main/src/managers/window.manager.js) (Window manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["App orchestration"]
  node_main["Application controller<br/>[main.js]"]
end

subgraph group_inputs["Question input"]
  node_capture["Screen capture<br/>[capture.service.js]"]
  node_speech["Speech recognition<br/>[speech.service.js]"]
  node_worker["Whisper worker"]
  node_worker_script["Whisper process<br/>[whisper_worker.py]"]
end

subgraph group_reasoning["Context and AI"]
  node_session["Session memory<br/>[session.manager.js]"]
  node_llm["Gemini service<br/>[llm.service.js]"]
  node_prompts["Skill prompts"]
end

subgraph group_interface["Windows and controls"]
  node_windows["Window manager<br/>[window.manager.js]"]
  node_main_ui["Overlay controls<br/>[main-window.js]"]
  node_chat_ui["Chat panel<br/>[chat-window.js]"]
  node_answer_ui["Answer window<br/>[llm-response.html]"]
  node_settings_ui["Settings window<br/>[settings-window.js]"]
end

subgraph group_setup["Configuration"]
  node_config["App configuration<br/>[config.js]"]
  node_onboarding["First-run onboarding<br/>[first-run.js]"]
  node_installer["Whisper setup"]
end

node_user(("User"))
node_microphone(("Microphone"))
node_gemini{{"Google Gemini"}}
node_screen_sharing(("Screen-sharing apps"))

node_user -->|"asks or controls"| node_main_ui
node_user -->|"speaks"| node_microphone
node_microphone -->|"audio"| node_speech
node_main_ui -->|"sends input"| node_main
node_main -->|"requests screenshot"| node_capture
node_capture -->|"returns image"| node_main
node_main -->|"controls capture"| node_speech
node_speech -->|"transcribes locally"| node_worker
node_worker -->|"dispatches requests"| node_worker_script
node_speech -->|"emits transcript"| node_main
node_main -->|"records input"| node_session
node_main -->|"requests answer"| node_llm
node_session -->|"provides history"| node_main
node_main -->|"supplies context"| node_llm
node_llm -->|"loads skill prompts"| node_prompts
node_llm -->|"sends AI request"| node_gemini
node_gemini -->|"streams response"| node_llm
node_main -->|"manages windows"| node_windows
node_windows -->|"dispatches answer"| node_answer_ui
node_windows -->|"manages panel"| node_chat_ui
node_main -->|"reads settings"| node_config
node_settings_ui -->|"saves settings"| node_main
node_main -->|"checks first run"| node_onboarding
node_onboarding -.->|"sets up Whisper"| node_installer
node_screen_sharing -.->|"triggers hiding"| node_windows

click node_main "https://github.com/shamanthhiremath/opencluely/blob/main/main.js"
click node_capture "https://github.com/shamanthhiremath/opencluely/blob/main/src/services/capture.service.js"
click node_speech "https://github.com/shamanthhiremath/opencluely/blob/main/src/services/speech.service.js"
click node_worker "https://github.com/shamanthhiremath/opencluely/blob/main/src/services/whisper-worker.service.js"
click node_worker_script "https://github.com/shamanthhiremath/opencluely/blob/main/scripts/whisper_worker.py"
click node_session "https://github.com/shamanthhiremath/opencluely/blob/main/src/managers/session.manager.js"
click node_llm "https://github.com/shamanthhiremath/opencluely/blob/main/src/services/llm.service.js"
click node_prompts "https://github.com/shamanthhiremath/opencluely/tree/main/prompts"
click node_windows "https://github.com/shamanthhiremath/opencluely/blob/main/src/managers/window.manager.js"
click node_main_ui "https://github.com/shamanthhiremath/opencluely/blob/main/src/ui/main-window.js"
click node_chat_ui "https://github.com/shamanthhiremath/opencluely/blob/main/src/ui/chat-window.js"
click node_answer_ui "https://github.com/shamanthhiremath/opencluely/blob/main/llm-response.html"
click node_settings_ui "https://github.com/shamanthhiremath/opencluely/blob/main/src/ui/settings-window.js"
click node_config "https://github.com/shamanthhiremath/opencluely/blob/main/src/core/config.js"
click node_onboarding "https://github.com/shamanthhiremath/opencluely/blob/main/src/core/first-run.js"
click node_installer "https://github.com/shamanthhiremath/opencluely/blob/main/src/core/whisper-installer.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_main,node_user,node_screen_sharing toneBlue
class node_capture,node_speech,node_worker,node_worker_script toneAmber
class node_session,node_llm,node_prompts toneMint
class node_windows,node_main_ui,node_chat_ui,node_answer_ui,node_settings_ui toneRose
class node_config,node_onboarding,node_installer,node_microphone,node_gemini toneIndigo
```

## Components

### App orchestration

- [Application controller](https://github.com/shamanthhiremath/opencluely/blob/main/main.js): `main.js`

### Question input

- [Screen capture](https://github.com/shamanthhiremath/opencluely/blob/main/src/services/capture.service.js): `src/services/capture.service.js`
- [Speech recognition](https://github.com/shamanthhiremath/opencluely/blob/main/src/services/speech.service.js): `src/services/speech.service.js`
- [Whisper worker](https://github.com/shamanthhiremath/opencluely/blob/main/src/services/whisper-worker.service.js): `src/services/whisper-worker.service.js`
- [Whisper process](https://github.com/shamanthhiremath/opencluely/blob/main/scripts/whisper_worker.py): `scripts/whisper_worker.py`

### Context and AI

- [Session memory](https://github.com/shamanthhiremath/opencluely/blob/main/src/managers/session.manager.js): `src/managers/session.manager.js`
- [Gemini service](https://github.com/shamanthhiremath/opencluely/blob/main/src/services/llm.service.js): `src/services/llm.service.js`
- [Skill prompts](https://github.com/shamanthhiremath/opencluely/tree/main/prompts): `prompts`

### Windows and controls

- [Window manager](https://github.com/shamanthhiremath/opencluely/blob/main/src/managers/window.manager.js): `src/managers/window.manager.js`
- [Overlay controls](https://github.com/shamanthhiremath/opencluely/blob/main/src/ui/main-window.js): `src/ui/main-window.js`
- [Chat panel](https://github.com/shamanthhiremath/opencluely/blob/main/src/ui/chat-window.js): `src/ui/chat-window.js`
- [Answer window](https://github.com/shamanthhiremath/opencluely/blob/main/llm-response.html): `llm-response.html`
- [Settings window](https://github.com/shamanthhiremath/opencluely/blob/main/src/ui/settings-window.js): `src/ui/settings-window.js`

### Configuration

- [App configuration](https://github.com/shamanthhiremath/opencluely/blob/main/src/core/config.js): `src/core/config.js`
- [First-run onboarding](https://github.com/shamanthhiremath/opencluely/blob/main/src/core/first-run.js): `src/core/first-run.js`
- [Whisper setup](https://github.com/shamanthhiremath/opencluely/blob/main/src/core/whisper-installer.js): `src/core/whisper-installer.js`

### Other components

- **User**
- **Microphone**
- **Google Gemini**
- **Screen-sharing apps**

## Connections

- User → Overlay controls: asks or controls
- User → Microphone: speaks
- Microphone → Speech recognition: audio
- Overlay controls → Application controller: sends input
- Application controller → Screen capture: requests screenshot
- Screen capture → Application controller: returns image
- Application controller → Speech recognition: controls capture
- Speech recognition → Whisper worker: transcribes locally
- Whisper worker → Whisper process: dispatches requests
- Speech recognition → Application controller: emits transcript
- Application controller → Session memory: records input
- Application controller → Gemini service: requests answer
- Session memory → Application controller: provides history
- Application controller → Gemini service: supplies context
- Gemini service → Skill prompts: loads skill prompts
- Gemini service → Google Gemini: sends AI request
- Google Gemini → Gemini service: streams response
- Application controller → Window manager: manages windows
- Window manager → Answer window: dispatches answer
- Window manager → Chat panel: manages panel
- Application controller → App configuration: reads settings
- Settings window → Application controller: saves settings
- Application controller → First-run onboarding: checks first run
- First-run onboarding → Whisper setup: sets up Whisper
- Screen-sharing apps → Window manager: triggers hiding