# kareemsasa3/aether architecture

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

- Interactive diagram: https://gitdiagram.com/kareemsasa3/aether
- Repository: https://github.com/kareemsasa3/aether

## Overview

Aether publishes real-time audio analysis from a PipeWire-backed daemon through a seqlock shared-memory contract. Consumers include the query client, terminal visualizer, RGB controller, and desktop integrations. The graph preserves these branches and the visualizer’s state, rendering, overlays, and style system; some integration links are documented rather than source-inspected.

Main entry points: [`aether_client.py`](https://github.com/kareemsasa3/aether/blob/main/aether_client.py) (Query Client), [`aether.py`](https://github.com/kareemsasa3/aether/blob/main/aether.py) (TUI Runtime), [`aether_shm.py`](https://github.com/kareemsasa3/aether/blob/main/aether_shm.py) (Seqlock Memory), [`aether_daemon.py`](https://github.com/kareemsasa3/aether/blob/main/aether_daemon.py) (Audio Daemon)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_publisher["Audio Publisher"]
  node_daemon["Audio Daemon<br/>[aether_daemon.py]"]
  node_config["Audio Config<br/>[aether_config.py]"]
end

subgraph group_contract["Shared Data Contract"]
  node_shm[("Seqlock Memory<br/>[aether_shm.py]")]
  node_client["Query Client<br/>[aether_client.py]"]
end

subgraph group_consumers["Reference Consumers"]
  node_rgb["RGB Controller<br/>[aether_rgb.py]"]
end

subgraph group_visualizer["Terminal Visualizer"]
  node_visualizer["TUI Runtime<br/>[aether.py]"]
  node_state["Signal State<br/>[engine.py]"]
  node_render["Terminal Rendering<br/>[render.py]"]
  node_overlays["Menus<br/>[overlays.py]"]
  node_catalog["Style Catalog<br/>[style_catalog.py]"]
  node_styles["Style Plugins"]
end

subgraph group_integrations["Desktop Integrations"]
  node_hue["Hue Sync<br/>[aether-hue-sync.py]"]
  node_discord["Discord Presence"]
  node_obs["OBS Ducking"]
  node_dunst["Notification Pauser"]
  node_status["Status Bar Scripts"]
end

node_pipewire(("PipeWire"))
node_user(("CLI User"))
node_openrgb["OpenRGB"]
node_huebridge["Hue Bridge"]
node_discordservice["Discord"]
node_obsservice["OBS Studio"]
node_dunstservice["Dunst"]

node_pipewire -->|"provides audio"| node_daemon
node_daemon -->|"reads settings"| node_config
node_daemon -->|"publishes snapshots"| node_shm
node_client -->|"reads snapshots"| node_shm
node_user -->|"queries bands"| node_client
node_user -->|"launches"| node_visualizer
node_visualizer -->|"reads events"| node_shm
node_visualizer -->|"updates state"| node_state
node_visualizer -->|"draws frames"| node_render
node_visualizer -->|"opens menus"| node_overlays
node_visualizer -->|"loads styles"| node_catalog
node_overlays -->|"lists styles"| node_catalog
node_catalog -->|"loads plugins"| node_styles
node_user -->|"launches"| node_rgb
node_rgb -->|"reads snapshots"| node_shm
node_rgb -.->|"controls LEDs"| node_openrgb
node_hue -->|"reads bands"| node_client
node_hue -->|"updates lights"| node_huebridge
node_discord -->|"reads bands"| node_client
node_discord -->|"updates presence"| node_discordservice
node_obs -->|"reads energy"| node_client
node_obs -->|"adjusts volume"| node_obsservice
node_dunst -->|"reads bass"| node_client
node_dunst -->|"pauses alerts"| node_dunstservice
node_status -.->|"reads status"| node_client

click node_daemon "https://github.com/kareemsasa3/aether/blob/main/aether_daemon.py"
click node_config "https://github.com/kareemsasa3/aether/blob/main/aether_config.py"
click node_shm "https://github.com/kareemsasa3/aether/blob/main/aether_shm.py"
click node_client "https://github.com/kareemsasa3/aether/blob/main/aether_client.py"
click node_visualizer "https://github.com/kareemsasa3/aether/blob/main/aether.py"
click node_state "https://github.com/kareemsasa3/aether/blob/main/engine.py"
click node_render "https://github.com/kareemsasa3/aether/blob/main/render.py"
click node_overlays "https://github.com/kareemsasa3/aether/blob/main/ui/overlays.py"
click node_catalog "https://github.com/kareemsasa3/aether/blob/main/style_catalog.py"
click node_styles "https://github.com/kareemsasa3/aether/tree/main/styles"
click node_rgb "https://github.com/kareemsasa3/aether/blob/main/aether_rgb.py"
click node_hue "https://github.com/kareemsasa3/aether/blob/main/integrations/hue/aether-hue-sync.py"
click node_discord "https://github.com/kareemsasa3/aether/blob/main/integrations/discord/aether-discord-rpc.py"
click node_obs "https://github.com/kareemsasa3/aether/blob/main/integrations/obs/aether-obs-ducking.py"
click node_dunst "https://github.com/kareemsasa3/aether/blob/main/integrations/dunst/aether-pause-daemon.py"
click node_status "https://github.com/kareemsasa3/aether/tree/main/integrations"

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_daemon,node_config,node_user toneBlue
class node_shm,node_client toneAmber
class node_rgb toneMint
class node_visualizer,node_state,node_render,node_overlays,node_catalog,node_styles toneRose
class node_hue,node_discord,node_obs,node_dunst,node_status,node_pipewire,node_openrgb,node_huebridge,node_discordservice,node_obsservice,node_dunstservice toneIndigo
```

## Components

### Audio Publisher

- [Audio Daemon](https://github.com/kareemsasa3/aether/blob/main/aether_daemon.py): `aether_daemon.py`
- [Audio Config](https://github.com/kareemsasa3/aether/blob/main/aether_config.py): `aether_config.py`

### Shared Data Contract

- [Seqlock Memory](https://github.com/kareemsasa3/aether/blob/main/aether_shm.py): `aether_shm.py`
- [Query Client](https://github.com/kareemsasa3/aether/blob/main/aether_client.py): `aether_client.py`

### Reference Consumers

- [RGB Controller](https://github.com/kareemsasa3/aether/blob/main/aether_rgb.py): `aether_rgb.py`

### Terminal Visualizer

- [TUI Runtime](https://github.com/kareemsasa3/aether/blob/main/aether.py): `aether.py`
- [Signal State](https://github.com/kareemsasa3/aether/blob/main/engine.py): `engine.py`
- [Terminal Rendering](https://github.com/kareemsasa3/aether/blob/main/render.py): `render.py`
- [Menus](https://github.com/kareemsasa3/aether/blob/main/ui/overlays.py): `ui/overlays.py`
- [Style Catalog](https://github.com/kareemsasa3/aether/blob/main/style_catalog.py): `style_catalog.py`
- [Style Plugins](https://github.com/kareemsasa3/aether/tree/main/styles): `styles`

### Desktop Integrations

- [Hue Sync](https://github.com/kareemsasa3/aether/blob/main/integrations/hue/aether-hue-sync.py): `integrations/hue/aether-hue-sync.py`
- [Discord Presence](https://github.com/kareemsasa3/aether/blob/main/integrations/discord/aether-discord-rpc.py): `integrations/discord/aether-discord-rpc.py`
- [OBS Ducking](https://github.com/kareemsasa3/aether/blob/main/integrations/obs/aether-obs-ducking.py): `integrations/obs/aether-obs-ducking.py`
- [Notification Pauser](https://github.com/kareemsasa3/aether/blob/main/integrations/dunst/aether-pause-daemon.py): `integrations/dunst/aether-pause-daemon.py`
- [Status Bar Scripts](https://github.com/kareemsasa3/aether/tree/main/integrations): `integrations`

### Other components

- **PipeWire**
- **CLI User**
- **OpenRGB**
- **Hue Bridge**
- **Discord**
- **OBS Studio**
- **Dunst**

## Connections

- PipeWire → Audio Daemon: provides audio (evidence: `README.md`)
- Audio Daemon → Audio Config: reads settings (evidence: `aether_daemon.py`)
- Audio Daemon → Seqlock Memory: publishes snapshots (evidence: `README.md`)
- Query Client → Seqlock Memory: reads snapshots (evidence: `aether_client.py`)
- CLI User → Query Client: queries bands (evidence: `aether_client.py`)
- CLI User → TUI Runtime: launches (evidence: `README.md`)
- TUI Runtime → Seqlock Memory: reads events (evidence: `aether.py`)
- TUI Runtime → Signal State: updates state (evidence: `aether.py`)
- TUI Runtime → Terminal Rendering: draws frames (evidence: `aether.py`)
- TUI Runtime → Menus: opens menus (evidence: `aether.py`)
- TUI Runtime → Style Catalog: loads styles (evidence: `aether.py`)
- Menus → Style Catalog: lists styles (evidence: `ui/overlays.py`)
- Style Catalog → Style Plugins: loads plugins (evidence: `style_catalog.py`)
- CLI User → RGB Controller: launches (evidence: `README.md`)
- RGB Controller → Seqlock Memory: reads snapshots (evidence: `aether_rgb.py`)
- RGB Controller → OpenRGB: controls LEDs (evidence: `README.md`)
- Hue Sync → Query Client: reads bands (evidence: `integrations/hue/aether-hue-sync.py`)
- Hue Sync → Hue Bridge: updates lights (evidence: `integrations/hue/aether-hue-sync.py`)
- Discord Presence → Query Client: reads bands (evidence: `integrations/discord/aether-discord-rpc.py`)
- Discord Presence → Discord: updates presence (evidence: `integrations/discord/aether-discord-rpc.py`)
- OBS Ducking → Query Client: reads energy (evidence: `integrations/obs/aether-obs-ducking.py`)
- OBS Ducking → OBS Studio: adjusts volume (evidence: `integrations/obs/aether-obs-ducking.py`)
- Notification Pauser → Query Client: reads bass (evidence: `integrations/dunst/aether-pause-daemon.py`)
- Notification Pauser → Dunst: pauses alerts (evidence: `integrations/dunst/aether-pause-daemon.py`)
- Status Bar Scripts → Query Client: reads status (evidence: `README.md`)
