# system-nebula/maya-unified architecture

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

- Interactive diagram: https://gitdiagram.com/system-nebula/maya-unified
- Repository: https://github.com/system-nebula/maya-unified

## Overview

Maya Unified combines a local, dashboard-operated voice assistant with optional platform APIs and music tools. The primary path is operator audio through speech recognition, the LLM agent, and speech synthesis, with the gateway and voice hub handling dashboard requests. Separate branches represent documented memory, music playback, and platform capabilities. Some branches are documented only at product level; dashed, uncited links mark relationships not verified in the sampled source.

Main entry points: [`packages/voice-runtime/agent.py`](https://github.com/system-nebula/maya-unified/blob/main/packages/voice-runtime/agent.py) (Voice agent), [`services/voice/hub.py`](https://github.com/system-nebula/maya-unified/blob/main/services/voice/hub.py) (Voice hub), [`apps/dashboard`](https://github.com/system-nebula/maya-unified/tree/main/apps/dashboard) (Web dashboard), [`apps/maya-gateway/src/maya_gateway/main.py`](https://github.com/system-nebula/maya-unified/blob/main/apps/maya-gateway/src/maya_gateway/main.py) (Platform API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_voice["Voice runtime"]
  node_voice_hub["Voice hub<br/>[hub.py]"]
  node_session["Session control"]
  node_voice_agent["Voice agent<br/>[agent.py]"]
  node_stt["Speech recognition<br/>[stt.py]"]
  node_llm["Language model<br/>[llm.py]"]
  node_tts["Speech synthesis<br/>[tts.py]"]
end

subgraph group_gateway["Dashboard access"]
  node_dashboard["Web dashboard"]
  node_voice_routes["Voice routes<br/>[voice_routes.py]"]
end

subgraph group_state["Memory and state"]
  node_memory_manager["Memory manager<br/>[manager.py]"]
  node_operator_settings["Operator settings<br/>[public.py]"]
  node_database[("Postgres store<br/>[connection.py]")]
end

subgraph group_music["Music tools"]
  node_cmd_queue["Queue command<br/>[queue.py]"]
  node_player["Dashboard player<br/>[player.py]"]
  node_music_ontology["Music ontology<br/>[ontology.py]"]
end

subgraph group_platform["Platform services"]
  node_platform_gateway["Platform API<br/>[main.py]"]
  node_platform_routes["Platform routes"]
  node_feed_ingest["Feed ingestion"]
  node_research["Research service"]
  node_image_api["Image generation<br/>[api.py]"]
end

node_operator(("Operator"))

node_operator -->|"uses"| node_dashboard
node_dashboard -.->|"requests voice"| node_voice_routes
node_voice_routes -->|"calls"| node_voice_hub
node_voice_hub -->|"delegates"| node_voice_agent
node_voice_hub -->|"coordinates"| node_session
node_operator -.->|"provides audio"| node_stt
node_stt -->|"transcribes for"| node_voice_agent
node_voice_agent -->|"requests response"| node_llm
node_llm -->|"returns text"| node_voice_agent
node_voice_agent -->|"synthesizes reply"| node_tts
node_voice_agent -.->|"uses memory"| node_memory_manager
node_voice_hub -->|"loads settings"| node_operator_settings
node_operator_settings -.->|"persists state"| node_database
node_dashboard -.->|"submits queue command"| node_cmd_queue
node_cmd_queue -->|"schedules resolution"| node_player
node_player -->|"looks up music"| node_music_ontology
node_operator -.->|"uses platform APIs"| node_platform_gateway
node_platform_gateway -->|"registers routes"| node_platform_routes
node_platform_routes -.->|"runs research"| node_research
node_platform_gateway -->|"exposes image API"| node_image_api
node_operator -.->|"publishes feed sources"| node_feed_ingest

click node_dashboard "https://github.com/system-nebula/maya-unified/tree/main/apps/dashboard"
click node_voice_routes "https://github.com/system-nebula/maya-unified/blob/main/apps/gateway/voice_routes.py"
click node_voice_hub "https://github.com/system-nebula/maya-unified/blob/main/services/voice/hub.py"
click node_session "https://github.com/system-nebula/maya-unified/blob/main/services/voice/session_controller.py"
click node_voice_agent "https://github.com/system-nebula/maya-unified/blob/main/packages/voice-runtime/agent.py"
click node_stt "https://github.com/system-nebula/maya-unified/blob/main/packages/voice-runtime/stt.py"
click node_llm "https://github.com/system-nebula/maya-unified/blob/main/packages/voice-runtime/llm.py"
click node_tts "https://github.com/system-nebula/maya-unified/blob/main/packages/voice-runtime/tts.py"
click node_memory_manager "https://github.com/system-nebula/maya-unified/blob/main/packages/voice-runtime/memory/manager.py"
click node_operator_settings "https://github.com/system-nebula/maya-unified/blob/main/services/settings/public.py"
click node_database "https://github.com/system-nebula/maya-unified/blob/main/packages/maya-db/src/maya_db/connection.py"
click node_cmd_queue "https://github.com/system-nebula/maya-unified/blob/main/services/cmd/executors/queue.py"
click node_player "https://github.com/system-nebula/maya-unified/blob/main/services/dashboard/player.py"
click node_music_ontology "https://github.com/system-nebula/maya-unified/blob/main/services/music/ontology.py"
click node_platform_gateway "https://github.com/system-nebula/maya-unified/blob/main/apps/maya-gateway/src/maya_gateway/main.py"
click node_platform_routes "https://github.com/system-nebula/maya-unified/tree/main/apps/maya-gateway/src/maya_gateway/routes"
click node_feed_ingest "https://github.com/system-nebula/maya-unified/tree/main/apps/maya-ingest/src/maya_ingest/flows"
click node_research "https://github.com/system-nebula/maya-unified/blob/main/apps/maya-gateway/src/maya_gateway/services/research_service.py"
click node_image_api "https://github.com/system-nebula/maya-unified/blob/main/packages/maya-image/src/maya_image/api.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_voice_hub,node_session,node_voice_agent,node_stt,node_llm,node_tts toneBlue
class node_dashboard,node_voice_routes toneAmber
class node_memory_manager,node_operator_settings,node_database toneMint
class node_cmd_queue,node_player,node_music_ontology toneRose
class node_platform_gateway,node_platform_routes,node_feed_ingest,node_research,node_image_api,node_operator toneIndigo
```

## Components

### Voice runtime

- [Voice hub](https://github.com/system-nebula/maya-unified/blob/main/services/voice/hub.py): `services/voice/hub.py`
- [Session control](https://github.com/system-nebula/maya-unified/blob/main/services/voice/session_controller.py): `services/voice/session_controller.py`
- [Voice agent](https://github.com/system-nebula/maya-unified/blob/main/packages/voice-runtime/agent.py): `packages/voice-runtime/agent.py`
- [Speech recognition](https://github.com/system-nebula/maya-unified/blob/main/packages/voice-runtime/stt.py): `packages/voice-runtime/stt.py`
- [Language model](https://github.com/system-nebula/maya-unified/blob/main/packages/voice-runtime/llm.py): `packages/voice-runtime/llm.py`
- [Speech synthesis](https://github.com/system-nebula/maya-unified/blob/main/packages/voice-runtime/tts.py): `packages/voice-runtime/tts.py`

### Dashboard access

- [Web dashboard](https://github.com/system-nebula/maya-unified/tree/main/apps/dashboard): `apps/dashboard`
- [Voice routes](https://github.com/system-nebula/maya-unified/blob/main/apps/gateway/voice_routes.py): `apps/gateway/voice_routes.py`

### Memory and state

- [Memory manager](https://github.com/system-nebula/maya-unified/blob/main/packages/voice-runtime/memory/manager.py): `packages/voice-runtime/memory/manager.py`
- [Operator settings](https://github.com/system-nebula/maya-unified/blob/main/services/settings/public.py): `services/settings/public.py`
- [Postgres store](https://github.com/system-nebula/maya-unified/blob/main/packages/maya-db/src/maya_db/connection.py): `packages/maya-db/src/maya_db/connection.py`

### Music tools

- [Queue command](https://github.com/system-nebula/maya-unified/blob/main/services/cmd/executors/queue.py): `services/cmd/executors/queue.py`
- [Dashboard player](https://github.com/system-nebula/maya-unified/blob/main/services/dashboard/player.py): `services/dashboard/player.py`
- [Music ontology](https://github.com/system-nebula/maya-unified/blob/main/services/music/ontology.py): `services/music/ontology.py`

### Platform services

- [Platform API](https://github.com/system-nebula/maya-unified/blob/main/apps/maya-gateway/src/maya_gateway/main.py): `apps/maya-gateway/src/maya_gateway/main.py`
- [Platform routes](https://github.com/system-nebula/maya-unified/tree/main/apps/maya-gateway/src/maya_gateway/routes): `apps/maya-gateway/src/maya_gateway/routes`
- [Feed ingestion](https://github.com/system-nebula/maya-unified/tree/main/apps/maya-ingest/src/maya_ingest/flows): `apps/maya-ingest/src/maya_ingest/flows`
- [Research service](https://github.com/system-nebula/maya-unified/blob/main/apps/maya-gateway/src/maya_gateway/services/research_service.py): `apps/maya-gateway/src/maya_gateway/services/research_service.py`
- [Image generation](https://github.com/system-nebula/maya-unified/blob/main/packages/maya-image/src/maya_image/api.py): `packages/maya-image/src/maya_image/api.py`

### Other components

- **Operator**

## Connections

- Operator → Web dashboard: uses (evidence: `README.md`)
- Web dashboard → Voice routes: requests voice
- Voice routes → Voice hub: calls (evidence: `apps/gateway/voice_routes.py`)
- Voice hub → Voice agent: delegates (evidence: `services/voice/hub.py`)
- Voice hub → Session control: coordinates (evidence: `services/voice/hub.py`)
- Operator → Speech recognition: provides audio (evidence: `README.md`)
- Speech recognition → Voice agent: transcribes for (evidence: `README.md`)
- Voice agent → Language model: requests response (evidence: `README.md`)
- Language model → Voice agent: returns text (evidence: `README.md`)
- Voice agent → Speech synthesis: synthesizes reply (evidence: `README.md`)
- Voice agent → Memory manager: uses memory
- Voice hub → Operator settings: loads settings (evidence: `services/voice/hub.py`)
- Operator settings → Postgres store: persists state
- Web dashboard → Queue command: submits queue command
- Queue command → Dashboard player: schedules resolution (evidence: `services/cmd/executors/queue.py`)
- Dashboard player → Music ontology: looks up music (evidence: `services/dashboard/player.py`)
- Operator → Platform API: uses platform APIs (evidence: `README.md`)
- Platform API → Platform routes: registers routes (evidence: `apps/maya-gateway/src/maya_gateway/main.py`)
- Platform routes → Research service: runs research
- Platform API → Image generation: exposes image API (evidence: `apps/maya-gateway/src/maya_gateway/main.py`)
- Operator → Feed ingestion: publishes feed sources