# bitshank-2338/clicky-windows architecture

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

- Interactive diagram: https://gitdiagram.com/bitshank-2338/clicky-windows
- Repository: https://github.com/bitshank-2338/clicky-windows

## Overview

Clicky is a Windows desktop AI tutor that takes voice or panel questions, optionally adds screen and web context, generates a provider-backed answer, then speaks it and can point at screen elements. Its principal runtime coordinator is companion_manager.py; main.py wires it to the panel, tray, overlay and hotkeys. Additional branches cover tutoring, journal/documents, recordings, routines, drawing/Drive and browser/MCP features documented in the README. Some of those modules were not sampled, so their links are documented rather than inferred from unseen calls.

Main entry points: [`companion_manager.py`](https://github.com/bitshank-2338/clicky-windows/blob/main/companion_manager.py) (Conversation manager), [`main.py`](https://github.com/bitshank-2338/clicky-windows/blob/main/main.py) (App bootstrap), [`ui/panel.py`](https://github.com/bitshank-2338/clicky-windows/blob/main/ui/panel.py) (Chat panel), [`audio/ambient_listener.py`](https://github.com/bitshank-2338/clicky-windows/blob/main/audio/ambient_listener.py) (Wake and capture)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Desktop interaction"]
  node_main["App bootstrap<br/>[main.py]"]
  node_panel["Chat panel<br/>[panel.py]"]
  node_overlay["Cursor overlay<br/>[overlay.py]"]
  node_tray["System tray<br/>[tray.py]"]
end

subgraph group_coordination["Conversation runtime"]
  node_manager["Conversation manager"]
  node_tutor["Tutor behavior<br/>[tutor.py]"]
end

subgraph group_perception["Voice and screen"]
  node_ambient["Wake and capture"]
  node_stt["Speech recognition"]
  node_screen["Screen capture<br/>[capture.py]"]
  node_privacy["Privacy masking<br/>[privacy.py]"]
  node_tts["Speech output"]
  node_playback["Audio playback<br/>[playback.py]"]
end

subgraph group_intelligence["AI services"]
  node_providers["LLM providers"]
  node_models["Model registry<br/>[model_registry.py]"]
  node_locator["Visual locator"]
  node_pointer["Pointer animation<br/>[hybrid_pointer.py]"]
  node_search["Web search<br/>[web_search.py]"]
end

subgraph group_learning["Learning and tools"]
  node_storage[("Local settings<br/>[storage.py]")]
  node_journal["Journal and review<br/>[journal.py]"]
  node_documents["Document context<br/>[pdf_context.py]"]
  node_ocr["OCR fallback<br/>[ocr.py]"]
  node_recorder["Lesson recording<br/>[lesson_recorder.py]"]
  node_jobs["Jobs and routines<br/>[jobs.py]"]
  node_drive["Clicky Drive<br/>[drive.py]"]
  node_drawing["Sketch and drawing<br/>[drawing.py]"]
  node_browser["Browser Link<br/>[browser_bridge.py]"]
  node_connectors["MCP connectors<br/>[connectors.py]"]
end

node_user(("User"))

node_user -->|"asks in"| node_panel
node_user -->|"speaks to"| node_ambient
node_main -->|"launches"| node_panel
node_main -->|"launches"| node_tray
node_main -->|"launches"| node_overlay
node_main -->|"creates"| node_manager
node_main -.->|"starts"| node_ambient
node_panel -->|"submits questions"| node_manager
node_manager -->|"classifies requests"| node_tutor
node_ambient -->|"transcribes speech"| node_stt
node_manager -.->|"requests transcription"| node_stt
node_manager -.->|"captures context"| node_screen
node_screen -->|"redacts capture"| node_privacy
node_manager -.->|"adds web context"| node_search
node_manager -->|"generates response"| node_providers
node_manager -.->|"selects model"| node_models
node_manager -.->|"locates targets"| node_locator
node_pointer -->|"uses locator"| node_locator
node_manager -->|"directs pointing"| node_pointer
node_manager -.->|"speaks response"| node_tts
node_tts -->|"plays audio"| node_playback
node_overlay -->|"shows guidance"| node_user
node_manager -.->|"logs Q&amp;A"| node_journal
node_journal -->|"persists records"| node_storage
node_manager -.->|"uses attached context"| node_documents
node_documents -->|"uses OCR support"| node_ocr
node_manager -.->|"records lessons"| node_recorder
node_manager -.->|"runs routines"| node_jobs
node_manager -.->|"supports Drive"| node_drive
node_manager -.->|"supports Sketch"| node_drawing
node_browser -.->|"links browser"| node_manager
node_manager -.->|"reviews MCP tools"| node_connectors

click node_main "https://github.com/bitshank-2338/clicky-windows/blob/main/main.py"
click node_panel "https://github.com/bitshank-2338/clicky-windows/blob/main/ui/panel.py"
click node_overlay "https://github.com/bitshank-2338/clicky-windows/blob/main/ui/overlay.py"
click node_tray "https://github.com/bitshank-2338/clicky-windows/blob/main/ui/tray.py"
click node_manager "https://github.com/bitshank-2338/clicky-windows/blob/main/companion_manager.py"
click node_tutor "https://github.com/bitshank-2338/clicky-windows/blob/main/tutor.py"
click node_ambient "https://github.com/bitshank-2338/clicky-windows/blob/main/audio/ambient_listener.py"
click node_stt "https://github.com/bitshank-2338/clicky-windows/tree/main/audio/stt"
click node_screen "https://github.com/bitshank-2338/clicky-windows/blob/main/screen/capture.py"
click node_privacy "https://github.com/bitshank-2338/clicky-windows/blob/main/screen/privacy.py"
click node_providers "https://github.com/bitshank-2338/clicky-windows/tree/main/ai"
click node_models "https://github.com/bitshank-2338/clicky-windows/blob/main/ai/model_registry.py"
click node_locator "https://github.com/bitshank-2338/clicky-windows/blob/main/ai/universal_locator.py"
click node_pointer "https://github.com/bitshank-2338/clicky-windows/blob/main/ai/hybrid_pointer.py"
click node_search "https://github.com/bitshank-2338/clicky-windows/blob/main/ai/web_search.py"
click node_tts "https://github.com/bitshank-2338/clicky-windows/tree/main/audio/tts"
click node_playback "https://github.com/bitshank-2338/clicky-windows/blob/main/audio/playback.py"
click node_storage "https://github.com/bitshank-2338/clicky-windows/blob/main/storage.py"
click node_journal "https://github.com/bitshank-2338/clicky-windows/blob/main/tutor_features/journal.py"
click node_documents "https://github.com/bitshank-2338/clicky-windows/blob/main/tutor_features/pdf_context.py"
click node_ocr "https://github.com/bitshank-2338/clicky-windows/blob/main/tutor_features/ocr.py"
click node_recorder "https://github.com/bitshank-2338/clicky-windows/blob/main/tutor_features/lesson_recorder.py"
click node_jobs "https://github.com/bitshank-2338/clicky-windows/blob/main/jobs.py"
click node_drive "https://github.com/bitshank-2338/clicky-windows/blob/main/drive.py"
click node_drawing "https://github.com/bitshank-2338/clicky-windows/blob/main/drawing.py"
click node_browser "https://github.com/bitshank-2338/clicky-windows/blob/main/browser_bridge.py"
click node_connectors "https://github.com/bitshank-2338/clicky-windows/blob/main/connectors.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_main,node_panel,node_overlay,node_tray,node_user toneBlue
class node_manager,node_tutor toneAmber
class node_ambient,node_stt,node_screen,node_privacy,node_tts,node_playback toneMint
class node_providers,node_models,node_locator,node_pointer,node_search toneRose
class node_storage,node_journal,node_documents,node_ocr,node_recorder,node_jobs,node_drive,node_drawing,node_browser,node_connectors toneIndigo
```

## Components

### Desktop interaction

- [App bootstrap](https://github.com/bitshank-2338/clicky-windows/blob/main/main.py): `main.py`
- [Chat panel](https://github.com/bitshank-2338/clicky-windows/blob/main/ui/panel.py): `ui/panel.py`
- [Cursor overlay](https://github.com/bitshank-2338/clicky-windows/blob/main/ui/overlay.py): `ui/overlay.py`
- [System tray](https://github.com/bitshank-2338/clicky-windows/blob/main/ui/tray.py): `ui/tray.py`

### Conversation runtime

- [Conversation manager](https://github.com/bitshank-2338/clicky-windows/blob/main/companion_manager.py): `companion_manager.py`
- [Tutor behavior](https://github.com/bitshank-2338/clicky-windows/blob/main/tutor.py): `tutor.py`

### Voice and screen

- [Wake and capture](https://github.com/bitshank-2338/clicky-windows/blob/main/audio/ambient_listener.py): `audio/ambient_listener.py`
- [Speech recognition](https://github.com/bitshank-2338/clicky-windows/tree/main/audio/stt): `audio/stt`
- [Screen capture](https://github.com/bitshank-2338/clicky-windows/blob/main/screen/capture.py): `screen/capture.py`
- [Privacy masking](https://github.com/bitshank-2338/clicky-windows/blob/main/screen/privacy.py): `screen/privacy.py`
- [Speech output](https://github.com/bitshank-2338/clicky-windows/tree/main/audio/tts): `audio/tts`
- [Audio playback](https://github.com/bitshank-2338/clicky-windows/blob/main/audio/playback.py): `audio/playback.py`

### AI services

- [LLM providers](https://github.com/bitshank-2338/clicky-windows/tree/main/ai): `ai`
- [Model registry](https://github.com/bitshank-2338/clicky-windows/blob/main/ai/model_registry.py): `ai/model_registry.py`
- [Visual locator](https://github.com/bitshank-2338/clicky-windows/blob/main/ai/universal_locator.py): `ai/universal_locator.py`
- [Pointer animation](https://github.com/bitshank-2338/clicky-windows/blob/main/ai/hybrid_pointer.py): `ai/hybrid_pointer.py`
- [Web search](https://github.com/bitshank-2338/clicky-windows/blob/main/ai/web_search.py): `ai/web_search.py`

### Learning and tools

- [Local settings](https://github.com/bitshank-2338/clicky-windows/blob/main/storage.py): `storage.py`
- [Journal and review](https://github.com/bitshank-2338/clicky-windows/blob/main/tutor_features/journal.py): `tutor_features/journal.py`
- [Document context](https://github.com/bitshank-2338/clicky-windows/blob/main/tutor_features/pdf_context.py): `tutor_features/pdf_context.py`
- [OCR fallback](https://github.com/bitshank-2338/clicky-windows/blob/main/tutor_features/ocr.py): `tutor_features/ocr.py`
- [Lesson recording](https://github.com/bitshank-2338/clicky-windows/blob/main/tutor_features/lesson_recorder.py): `tutor_features/lesson_recorder.py`
- [Jobs and routines](https://github.com/bitshank-2338/clicky-windows/blob/main/jobs.py): `jobs.py`
- [Clicky Drive](https://github.com/bitshank-2338/clicky-windows/blob/main/drive.py): `drive.py`
- [Sketch and drawing](https://github.com/bitshank-2338/clicky-windows/blob/main/drawing.py): `drawing.py`
- [Browser Link](https://github.com/bitshank-2338/clicky-windows/blob/main/browser_bridge.py): `browser_bridge.py`
- [MCP connectors](https://github.com/bitshank-2338/clicky-windows/blob/main/connectors.py): `connectors.py`

### Other components

- **User**

## Connections

- User → Chat panel: asks in
- User → Wake and capture: speaks to
- App bootstrap → Chat panel: launches (evidence: `main.py`)
- App bootstrap → System tray: launches (evidence: `main.py`)
- App bootstrap → Cursor overlay: launches (evidence: `main.py`)
- App bootstrap → Conversation manager: creates (evidence: `main.py`)
- App bootstrap → Wake and capture: starts (evidence: `main.py`)
- Chat panel → Conversation manager: submits questions (evidence: `companion_manager.py`)
- Conversation manager → Tutor behavior: classifies requests (evidence: `companion_manager.py`)
- Wake and capture → Speech recognition: transcribes speech (evidence: `audio/ambient_listener.py`)
- Conversation manager → Speech recognition: requests transcription (evidence: `companion_manager.py`)
- Conversation manager → Screen capture: captures context (evidence: `companion_manager.py`)
- Screen capture → Privacy masking: redacts capture (evidence: `screen/capture.py`)
- Conversation manager → Web search: adds web context (evidence: `companion_manager.py`)
- Conversation manager → LLM providers: generates response (evidence: `companion_manager.py`)
- Conversation manager → Model registry: selects model (evidence: `companion_manager.py`)
- Conversation manager → Visual locator: locates targets (evidence: `companion_manager.py`)
- Pointer animation → Visual locator: uses locator (evidence: `ai/hybrid_pointer.py`)
- Conversation manager → Pointer animation: directs pointing (evidence: `ai/hybrid_pointer.py`)
- Conversation manager → Speech output: speaks response (evidence: `companion_manager.py`)
- Speech output → Audio playback: plays audio (evidence: `audio/tts/edge_tts_provider.py`)
- Cursor overlay → User: shows guidance
- Conversation manager → Journal and review: logs Q&A (evidence: `companion_manager.py`)
- Journal and review → Local settings: persists records (evidence: `tutor_features/journal.py`)
- Conversation manager → Document context: uses attached context (evidence: `companion_manager.py`)
- Document context → OCR fallback: uses OCR support (evidence: `tutor_features/pdf_context.py`)
- Conversation manager → Lesson recording: records lessons (evidence: `companion_manager.py`)
- Conversation manager → Jobs and routines: runs routines (evidence: `companion_manager.py`)
- Conversation manager → Clicky Drive: supports Drive (evidence: `companion_manager.py`)
- Conversation manager → Sketch and drawing: supports Sketch
- Browser Link → Conversation manager: links browser (evidence: `companion_manager.py`)
- Conversation manager → MCP connectors: reviews MCP tools