# rcbyron/hey-athena-client architecture

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

- Interactive diagram: https://gitdiagram.com/rcbyron/hey-athena-client
- Repository: https://github.com/rcbyron/hey-athena-client

## Overview

1. **What this repository is**
   - `hey-athena-client` is a Python 3 voice-assistant framework, not a single-purpose app.
   - Its architecture is built around a small core runtime plus pluggable “modules” that respond to spoken/text commands.

2. **Primary runtime flow**
   - The usual loop is: capture audio input → speech-to-text (`athena/stt.py`) → intent/command handling in the brain (`athena/brain.py`) → module/task dispatch → text-to-speech output (`athena/tts.py`) and/or side effects.
   - The assistant’s wake-word / trigger phrase is driven by `athena/keyphrases.txt` and the input pipeline.

3. **Core orchestration boundary**
   - `athena/brain.py` appears to be the central coordinator for interpreting input and selecting actions.
   - `athena/mods.py` is the module loader/registry layer, responsible for discovering available modules and making them available at runtime.
   - `athena/apis.py` is the runtime registry for API helper objects used by modules.

4. **Module architecture**
   - Modules live under `athena/modules/active/` and are the main extension mechanism.
   - Each active module groups one or more tasks; tasks match user text and execute actions.
   - The abstraction is defined in `athena/classes/module.py` and `athena/classes/task.py`, with response/input helper types in `athena/classes/response.py` and `athena/classes/input_field.py`.

5. **How commands are represented**
   - The repository models commands as pattern-matching tasks rather than a global intent graph.
   - This makes each module self-contained: a module owns its own triggers, priority, and action logic.
   - Module priority and task priority determine which action wins when multiple patterns match.

6. **Built-in capabilities**
   - The bundled active modules show the assistant’s intended feature set: conversation, music, shop, Twitter, Uber, SMS texting, Google search, voice browsing, geolocation, Wolfram queries, and basic control modules.
   - These modules are examples/reference implementations for adding new capabilities.

7. **API/service integration layer**
   - `athena/api_library/` contains reusable service adapters, such as `geo_info_api.py`, `ifttt_api.py`, `sms_text_api.py`, `user_api.py`, and `voice_browse_api.py`.
   - These are not modules themselves; they are utility/service clients that modules call.
   - The README also implies external integrations like IFTTT, Google, Twitter, Uber, and Wolfram Alpha.

8. **State, configuration, and user-specific data**
   - `athena/settings.py` and `athena/user_config.py` hold configuration boundaries between framework defaults and user-specific settings.
   - This is important architecturally because modules can rely on runtime configuration, credentials, and user preferences without hardcoding them into module logic.

9. **I/O and media assets**
   - `athena/data/media/` contains audio prompts and response sounds, such as beeps and error/test audio.
   - These assets support the conversational UX and are part of the assistant’s feedback loop after speech recognition or action execution.

10. **Browser automation support**
   - `athena/chrome/` packages platform-specific Chromedriver binaries.
   - This indicates that some modules use Selenium-driven browser automation, especially for voice browsing or web interaction, and that this capability is treated as a deployment/runtime dependency.

11. **Passive modules are a planned boundary**
   - `athena/modules/passive/` exists as a separate namespace, but the README describes passive modules as “soon-to-be implemented.”
   - The intended architectural split is between active, user-triggered tasks and passive, event/schedule-triggered tasks.

12. **Support services inside the package**
   - `athena/log.py` centralizes logging behavior.
   - `athena/__main__.py` suggests the package is executable as a module, while `setup.py` and `MANIFEST.in` package it for distribution.

13. **Quality and verification**
   - Tests under `athena/tests/` cover audio, microphone, dependency, and input behavior.
   - The test layout reflects the main runtime risks: audio stack, hardware access, and environment dependencies.

14. **Documentation and generated artifacts**
   - `docs/` is a Sphinx documentation site with API docs and user guides.
   - `docs/html/` is generated output and not part of the runtime architecture, but it mirrors the package structure and confirms the public surfaces of core, API library, and active modules.

15. **Diagram-friendly summary**
   - A clean architecture diagram would show:
     - user audio/text input at the edge,
     - STT/TTS as the speech boundary,
     - a central brain and module registry in the core,
     - active modules as pluggable command handlers,
     - API library adapters feeding external services,
     - config/logging/media as supporting infrastructure.

Main entry points: [`athena/api_library`](https://github.com/rcbyron/hey-athena-client/tree/demo-branch/athena/api_library) (API library), [`athena/classes/task.py`](https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/classes/task.py) (Task base), [`athena/brain.py`](https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/brain.py) (Brain), [`athena/classes/module.py`](https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/classes/module.py) (Module base)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core runtime"]
  node_stt["Speech to text<br/>runtime input<br/>[stt.py]"]
  node_brain{{"Brain<br/>orchestrator<br/>[brain.py]"}}
  node_mods["Module loader<br/>registry<br/>[mods.py]"]
  node_apis["API registry<br/>runtime registry<br/>[apis.py]"]
  node_tts["Text to speech<br/>runtime output<br/>[tts.py]"]
  node_classes_module["Module base<br/>abstraction<br/>[module.py]"]
  node_classes_task["Task base<br/>abstraction<br/>[task.py]"]
  node_classes_response["Response type<br/>abstraction<br/>[response.py]"]
  node_classes_input["Input field<br/>abstraction<br/>[input_field.py]"]
end

subgraph group_extensions["Extensions"]
  node_active_modules["Active modules<br/>pluggable features"]
  node_conversation["Conversation<br/>active module<br/>[conversation.py]"]
  node_music["Music<br/>active module<br/>[music.py]"]
  node_google["Google<br/>active module<br/>[google.py]"]
  node_voice_browse["Voice browse<br/>active module<br/>[voice_browse.py]"]
  node_sms_text["SMS text<br/>active module<br/>[sms_text.py]"]
  node_geo_info["Geo info<br/>active module<br/>[geo_info.py]"]
  node_twitter["Twitter<br/>active module<br/>[twitter.py]"]
  node_uber["Uber<br/>active module<br/>[uber.py]"]
  node_wolfram["Wolfram<br/>active module<br/>[wolfram.py]"]
  node_athena_control["Control<br/>active module<br/>[athena_control.py]"]
  node_hello_world["Hello world<br/>active module<br/>[hello_world.py]"]
end

subgraph group_services["Service adapters"]
  node_api_library["API library<br/>service adapters"]
  node_geo_info_api["Geo API<br/>adapter<br/>[geo_info_api.py]"]
  node_ifttt_api["IFTTT API<br/>adapter<br/>[ifttt_api.py]"]
  node_sms_text_api["SMS API<br/>adapter<br/>[sms_text_api.py]"]
  node_user_api["User API<br/>adapter<br/>[user_api.py]"]
  node_voice_browse_api["Browse API<br/>adapter"]
end

subgraph group_infra["Support assets"]
  node_settings["Settings<br/>config<br/>[settings.py]"]
  node_user_config["User config<br/>[user_config.py]"]
  node_keyphrases["Keyphrases<br/>trigger data<br/>[keyphrases.txt]"]
  node_media[("Media assets<br/>audio assets")]
  node_chrome["Chromedriver<br/>runtime binary"]
  node_log["Logging<br/>support<br/>[log.py]"]
end

subgraph group_docs["Docs & tests"]
  node_tests["Tests<br/>verification"]
end

node_stt -->|"transcribed input"| node_brain
node_keyphrases -->|"wake phrase"| node_stt
node_brain -->|"resolve modules"| node_mods
node_brain -->|"use APIs"| node_apis
node_brain -->|"speak output"| node_tts
node_mods -->|"load"| node_active_modules
node_active_modules -->|"implements"| node_classes_module
node_active_modules -->|"contains tasks"| node_classes_task
node_classes_task -->|"returns"| node_classes_response
node_classes_module -->|"reads"| node_settings
node_classes_module -->|"reads"| node_user_config
node_conversation -->|"defines"| node_classes_task
node_music -->|"defines"| node_classes_task
node_google -->|"defines"| node_classes_task
node_voice_browse -->|"defines"| node_classes_task
node_voice_browse -->|"drives"| node_chrome
node_sms_text -->|"calls"| node_sms_text_api
node_geo_info -->|"calls"| node_geo_info_api
node_twitter -->|"calls"| node_ifttt_api
node_uber -->|"calls"| node_voice_browse_api
node_wolfram -->|"uses"| node_api_library
node_api_library -->|"includes"| node_user_api
node_api_library -->|"includes"| node_voice_browse_api
node_api_library -->|"includes"| node_ifttt_api
node_api_library -->|"includes"| node_geo_info_api
node_api_library -->|"includes"| node_sms_text_api
node_tts -->|"plays"| node_media
node_log -->|"logs"| node_brain
node_tests -->|"covers"| node_stt
node_tests -->|"covers"| node_mods

click node_stt "https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/stt.py"
click node_brain "https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/brain.py"
click node_mods "https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/mods.py"
click node_apis "https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/apis.py"
click node_tts "https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/tts.py"
click node_classes_module "https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/classes/module.py"
click node_classes_task "https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/classes/task.py"
click node_classes_response "https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/classes/response.py"
click node_classes_input "https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/classes/input_field.py"
click node_active_modules "https://github.com/rcbyron/hey-athena-client/tree/demo-branch/athena/modules/active"
click node_conversation "https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/modules/active/conversation.py"
click node_music "https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/modules/active/music.py"
click node_google "https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/modules/active/google.py"
click node_voice_browse "https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/modules/active/voice_browse.py"
click node_sms_text "https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/modules/active/sms_text.py"
click node_geo_info "https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/modules/active/geo_info.py"
click node_twitter "https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/modules/active/twitter.py"
click node_uber "https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/modules/active/uber.py"
click node_wolfram "https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/modules/active/wolfram.py"
click node_athena_control "https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/modules/active/athena_control.py"
click node_hello_world "https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/modules/active/hello_world.py"
click node_api_library "https://github.com/rcbyron/hey-athena-client/tree/demo-branch/athena/api_library"
click node_geo_info_api "https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/api_library/geo_info_api.py"
click node_ifttt_api "https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/api_library/ifttt_api.py"
click node_sms_text_api "https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/api_library/sms_text_api.py"
click node_user_api "https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/api_library/user_api.py"
click node_voice_browse_api "https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/api_library/voice_browse_api.py"
click node_settings "https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/settings.py"
click node_user_config "https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/user_config.py"
click node_keyphrases "https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/keyphrases.txt"
click node_media "https://github.com/rcbyron/hey-athena-client/tree/demo-branch/athena/data/media"
click node_chrome "https://github.com/rcbyron/hey-athena-client/tree/demo-branch/athena/chrome"
click node_log "https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/log.py"
click node_tests "https://github.com/rcbyron/hey-athena-client/tree/demo-branch/athena/tests"

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_stt,node_brain,node_mods,node_apis,node_tts,node_classes_module,node_classes_task,node_classes_response,node_classes_input toneBlue
class node_active_modules,node_conversation,node_music,node_google,node_voice_browse,node_sms_text,node_geo_info,node_twitter,node_uber,node_wolfram,node_athena_control,node_hello_world toneAmber
class node_api_library,node_geo_info_api,node_ifttt_api,node_sms_text_api,node_user_api,node_voice_browse_api toneMint
class node_settings,node_user_config,node_keyphrases,node_media,node_chrome,node_log toneRose
class node_tests toneIndigo
```

## Components

### Core runtime

Assistant loop, orchestration, and shared abstractions

- [Speech to text](https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/stt.py): runtime input · Audio capture and transcription boundary · `athena/stt.py`
- [Brain](https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/brain.py): orchestrator · Central command interpretation and action selection · `athena/brain.py`
- [Module loader](https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/mods.py): registry · Discovers and registers available modules · `athena/mods.py`
- [API registry](https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/apis.py): runtime registry · Shared API helper objects exposed to modules · `athena/apis.py`
- [Text to speech](https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/tts.py): runtime output · Voice output and spoken feedback · `athena/tts.py`
- [Module base](https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/classes/module.py): abstraction · Module lifecycle and metadata contract · `athena/classes/module.py`
- [Task base](https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/classes/task.py): abstraction · Pattern-matching command unit · `athena/classes/task.py`
- [Response type](https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/classes/response.py): abstraction · Response payload and output shaping · `athena/classes/response.py`
- [Input field](https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/classes/input_field.py): abstraction · Structured user input helper · `athena/classes/input_field.py`

### Extensions

Pluggable active modules and passive namespace

- [Active modules](https://github.com/rcbyron/hey-athena-client/tree/demo-branch/athena/modules/active): pluggable features · User-triggered command handlers · `athena/modules/active`
- [Conversation](https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/modules/active/conversation.py): active module · Dialogue and conversational behavior · `athena/modules/active/conversation.py`
- [Music](https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/modules/active/music.py): active module · Music and media actions · `athena/modules/active/music.py`
- [Google](https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/modules/active/google.py): active module · Search and web lookup actions · `athena/modules/active/google.py`
- [Voice browse](https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/modules/active/voice_browse.py): active module · Browser-driven voice interaction · `athena/modules/active/voice_browse.py`
- [SMS text](https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/modules/active/sms_text.py): active module · Text messaging actions · `athena/modules/active/sms_text.py`
- [Geo info](https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/modules/active/geo_info.py): active module · Location and geolocation actions · `athena/modules/active/geo_info.py`
- [Twitter](https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/modules/active/twitter.py): active module · Social posting and retrieval · `athena/modules/active/twitter.py`
- [Uber](https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/modules/active/uber.py): active module · Ride booking actions · `athena/modules/active/uber.py`
- [Wolfram](https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/modules/active/wolfram.py): active module · Computational query actions · `athena/modules/active/wolfram.py`
- [Control](https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/modules/active/athena_control.py): active module · Assistant control and runtime commands · `athena/modules/active/athena_control.py`
- [Hello world](https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/modules/active/hello_world.py): active module · Reference example module · `athena/modules/active/hello_world.py`

### Service adapters

Reusable API clients used by modules

- [API library](https://github.com/rcbyron/hey-athena-client/tree/demo-branch/athena/api_library): service adapters · Reusable integration clients for modules · `athena/api_library`
- [Geo API](https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/api_library/geo_info_api.py): adapter · Geolocation service client · `athena/api_library/geo_info_api.py`
- [IFTTT API](https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/api_library/ifttt_api.py): adapter · Webhook and automation client · `athena/api_library/ifttt_api.py`
- [SMS API](https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/api_library/sms_text_api.py): adapter · SMS gateway client · `athena/api_library/sms_text_api.py`
- [User API](https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/api_library/user_api.py): adapter · User profile and preference client · `athena/api_library/user_api.py`
- [Browse API](https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/api_library/voice_browse_api.py): adapter · Browser automation client · `athena/api_library/voice_browse_api.py`

### Support assets

Configuration, media, browser binaries, and logs

- [Settings](https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/settings.py): config · Framework defaults and runtime settings · `athena/settings.py`
- [User config](https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/user_config.py): config · User-specific configuration and credentials · `athena/user_config.py`
- [Keyphrases](https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/keyphrases.txt): trigger data · Wake-word and trigger phrase list · `athena/keyphrases.txt`
- [Media assets](https://github.com/rcbyron/hey-athena-client/tree/demo-branch/athena/data/media): audio assets · Prompts and response sounds · `athena/data/media`
- [Chromedriver](https://github.com/rcbyron/hey-athena-client/tree/demo-branch/athena/chrome): runtime binary · Bundled browser automation drivers · `athena/chrome`
- [Logging](https://github.com/rcbyron/hey-athena-client/blob/demo-branch/athena/log.py): support · Central logging behavior · `athena/log.py`

### Docs & tests

Verification and documentation surfaces

- [Tests](https://github.com/rcbyron/hey-athena-client/tree/demo-branch/athena/tests): verification · Audio, input, mic, and dependency checks · `athena/tests`

## Connections

- Speech to text → Brain: transcribed input · Speech input is handed to the command brain
- Keyphrases → Speech to text: wake phrase · Trigger phrases gate the input pipeline
- Brain → Module loader: resolve modules · Brain asks the registry for available handlers
- Brain → API registry: use APIs · Brain exposes runtime helpers to command handlers
- Brain → Text to speech: speak output · Brain routes responses to speech output
- Module loader → Active modules: load · Loader discovers active modules at runtime
- Active modules → Module base: implements · Modules follow the shared module contract
- Active modules → Task base: contains tasks · Modules are composed of pattern-matching tasks
- Task base → Response type: returns · Tasks produce structured responses
- Module base → Settings: reads · Modules depend on framework configuration
- Module base → User config: reads · Modules depend on user-specific settings
- Conversation → Task base: defines · Representative task-driven module behavior
- Music → Task base: defines · Music commands are implemented as tasks
- Google → Task base: defines · Search actions are implemented as tasks
- Voice browse → Task base: defines · Browser automation commands are implemented as tasks
- Voice browse → Chromedriver: drives · Voice browsing relies on bundled browser binaries
- SMS text → SMS API: calls · SMS module uses the SMS adapter
- Geo info → Geo API: calls · Geolocation module uses the geo adapter
- Twitter → IFTTT API: calls · Social actions can route through automation services
- Uber → Browse API: calls · Ride workflows may use browser automation helpers
- Wolfram → API library: uses · Computational queries rely on service adapters
- API library → User API: includes · Shared adapter package contains user client
- API library → Browse API: includes · Shared adapter package contains browse client
- API library → IFTTT API: includes · Shared adapter package contains IFTTT client
- API library → Geo API: includes · Shared adapter package contains geo client
- API library → SMS API: includes · Shared adapter package contains SMS client
- Text to speech → Media assets: plays · Speech output uses bundled prompts and sounds
- Logging → Brain: logs · Runtime logging supports orchestration and diagnostics
- Tests → Speech to text: covers · Tests exercise audio and transcription boundaries
- Tests → Module loader: covers · Tests exercise environment and dependency behavior
