# henryklunaris/hey-jev architecture

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

- Interactive diagram: https://gitdiagram.com/henryklunaris/hey-jev
- Repository: https://github.com/henryklunaris/hey-jev

## Overview

Hey Jev is a macOS voice assistant: the user speaks in push-to-talk or wake-word mode, speech is transcribed locally, Jev classifies the request, and the assistant performs a Mac action or answers a question, then speaks a reply. The README also documents timers/reminders and a native status window with live countdowns and key settings. The excerpts show selected implementation details; timer and action orchestration links not directly visible are kept conservative.

Main entry points: [`siri.py`](https://github.com/henryklunaris/hey-jev/blob/main/siri.py) (Turn handling), [`assistant_ui.py`](https://github.com/henryklunaris/hey-jev/blob/main/assistant_ui.py) (Status window), [`secrets_store.py`](https://github.com/henryklunaris/hey-jev/blob/main/secrets_store.py) (Key storage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_capture["Voice input"]
  node_audio["Audio capture<br/>[siri.py]"]
  node_wake["Wake detection<br/>[siri.py]"]
  node_whisper["Local transcription<br/>[siri.py]"]
end

subgraph group_assistant["Assistant runtime"]
  node_turn["Turn handling<br/>[siri.py]"]
  node_jev["Intent decisions<br/>[siri.py]"]
  node_llm["Question answers<br/>[siri.py]"]
  node_timers["Timers and reminders<br/>[siri.py]"]
  node_reply["Reply selection<br/>[siri.py]"]
  node_tts["Speech synthesis<br/>[siri.py]"]
end

subgraph group_actions["Mac actions"]
  node_actions["Mac commands<br/>[siri.py]"]
end

subgraph group_experience["App experience"]
  node_ui["Status window<br/>[assistant_ui.py]"]
  node_secrets[("Key storage<br/>[secrets_store.py]")]
end

node_user(("User"))
node_macos["macOS"]
node_typesafe["TypeSafe Jev"]
node_openrouter["OpenRouter"]
node_fish["Fish Audio"]

node_user -->|"speaks to"| node_audio
node_ui -->|"starts runtime"| node_turn
node_ui -->|"sends controls"| node_turn
node_audio -->|"queues phrases"| node_wake
node_wake -->|"transcribes locally"| node_whisper
node_whisper -->|"provides text"| node_turn
node_user -->|"submits text"| node_turn
node_turn -->|"classifies request"| node_jev
node_jev -->|"requests decisions"| node_typesafe
node_turn -->|"dispatches action"| node_actions
node_actions -->|"runs commands"| node_macos
node_turn -->|"asks questions"| node_llm
node_llm -->|"requests answer"| node_openrouter
node_turn -->|"handles timer requests"| node_timers
node_timers -->|"provides countdowns"| node_ui
node_turn -->|"selects response"| node_reply
node_reply -->|"renders speech"| node_tts
node_tts -->|"requests audio"| node_fish
node_tts -->|"plays audio"| node_macos
node_ui -->|"reads and saves keys"| node_secrets

click node_ui "https://github.com/henryklunaris/hey-jev/blob/main/assistant_ui.py"
click node_audio "https://github.com/henryklunaris/hey-jev/blob/main/siri.py"
click node_wake "https://github.com/henryklunaris/hey-jev/blob/main/siri.py"
click node_whisper "https://github.com/henryklunaris/hey-jev/blob/main/siri.py"
click node_turn "https://github.com/henryklunaris/hey-jev/blob/main/siri.py"
click node_jev "https://github.com/henryklunaris/hey-jev/blob/main/siri.py"
click node_llm "https://github.com/henryklunaris/hey-jev/blob/main/siri.py"
click node_timers "https://github.com/henryklunaris/hey-jev/blob/main/siri.py"
click node_actions "https://github.com/henryklunaris/hey-jev/blob/main/siri.py"
click node_reply "https://github.com/henryklunaris/hey-jev/blob/main/siri.py"
click node_tts "https://github.com/henryklunaris/hey-jev/blob/main/siri.py"
click node_secrets "https://github.com/henryklunaris/hey-jev/blob/main/secrets_store.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_audio,node_wake,node_whisper,node_user toneBlue
class node_turn,node_jev,node_llm,node_timers,node_reply,node_tts toneAmber
class node_actions,node_openrouter toneMint
class node_ui,node_secrets toneRose
class node_macos,node_typesafe,node_fish toneIndigo
```

## Components

### Voice input

- [Audio capture](https://github.com/henryklunaris/hey-jev/blob/main/siri.py): `siri.py`
- [Wake detection](https://github.com/henryklunaris/hey-jev/blob/main/siri.py): `siri.py`
- [Local transcription](https://github.com/henryklunaris/hey-jev/blob/main/siri.py): `siri.py`

### Assistant runtime

- [Turn handling](https://github.com/henryklunaris/hey-jev/blob/main/siri.py): `siri.py`
- [Intent decisions](https://github.com/henryklunaris/hey-jev/blob/main/siri.py): `siri.py`
- [Question answers](https://github.com/henryklunaris/hey-jev/blob/main/siri.py): `siri.py`
- [Timers and reminders](https://github.com/henryklunaris/hey-jev/blob/main/siri.py): `siri.py`
- [Reply selection](https://github.com/henryklunaris/hey-jev/blob/main/siri.py): `siri.py`
- [Speech synthesis](https://github.com/henryklunaris/hey-jev/blob/main/siri.py): `siri.py`

### Mac actions

- [Mac commands](https://github.com/henryklunaris/hey-jev/blob/main/siri.py): `siri.py`

### App experience

- [Status window](https://github.com/henryklunaris/hey-jev/blob/main/assistant_ui.py): `assistant_ui.py`
- [Key storage](https://github.com/henryklunaris/hey-jev/blob/main/secrets_store.py): `secrets_store.py`

### Other components

- **User**
- **macOS**
- **TypeSafe Jev**
- **OpenRouter**
- **Fish Audio**

## Connections

- User → Audio capture: speaks to
- Status window → Turn handling: starts runtime
- Status window → Turn handling: sends controls
- Audio capture → Wake detection: queues phrases
- Wake detection → Local transcription: transcribes locally
- Local transcription → Turn handling: provides text
- User → Turn handling: submits text
- Turn handling → Intent decisions: classifies request
- Intent decisions → TypeSafe Jev: requests decisions
- Turn handling → Mac commands: dispatches action
- Mac commands → macOS: runs commands
- Turn handling → Question answers: asks questions
- Question answers → OpenRouter: requests answer
- Turn handling → Timers and reminders: handles timer requests
- Timers and reminders → Status window: provides countdowns
- Turn handling → Reply selection: selects response
- Reply selection → Speech synthesis: renders speech
- Speech synthesis → Fish Audio: requests audio
- Speech synthesis → macOS: plays audio
- Status window → Key storage: reads and saves keys