# ianoliveru/project-akiha architecture

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

- Interactive diagram: https://gitdiagram.com/ianoliveru/project-akiha
- Repository: https://github.com/ianoliveru/project-akiha

## Overview

Project Akiha is a Windows-first desktop companion combining chat, a persistent animated pet, memory, optional voice, permission-gated desktop actions, and opt-in integrations. The principal workflow is user input through the UI and application controllers to an AI provider, with conversation and memory context assembled from local persistence before a response is presented. Separate branches cover pet care and progression, voice capture and playback, and integrations/notifications. The README documents the layer boundaries and major capabilities; unsampled subsystem links are therefore shown only where those documented relationships support them.

Main entry points: [`project_akiha/ui`](https://github.com/ianoliveru/project-akiha/tree/main/project_akiha/ui) (Desktop UI), [`project_akiha/app/voice_controller.py`](https://github.com/ianoliveru/project-akiha/blob/main/project_akiha/app/voice_controller.py) (Voice controller), [`project_akiha/app/chat_controller.py`](https://github.com/ianoliveru/project-akiha/blob/main/project_akiha/app/chat_controller.py) (Chat controller), [`project_akiha/core/actions`](https://github.com/ianoliveru/project-akiha/tree/main/project_akiha/core/actions) (Action policy and execution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Desktop experience"]
  node_ui["Desktop UI"]
  node_app["App controllers"]
  node_theme["UI theme<br/>[theme.py]"]
  node_settings["Configuration<br/>[settings.py]"]
end

subgraph group_conversation["Conversation and memory"]
  node_chat["Chat controller<br/>[chat_controller.py]"]
  node_ai["AI providers"]
  node_memory["Memory pipeline<br/>[pipeline.py]"]
  node_memoryrepo["Memory repository<br/>[repository.py]"]
  node_conversations[("Conversation storage")]
  node_database[("SQLite persistence")]
  node_migrator["Database migrations<br/>[migrator.py]"]
end

subgraph group_companion["Pet and behavior"]
  node_pet["Pet care and progression"]
  node_behavior["Activity and mood"]
end

subgraph group_voice["Voice runtime"]
  node_voiceui["Voice interface"]
  node_voice["Voice controller"]
  node_voice_session["Voice sessions"]
  node_voice_state["Voice state<br/>[voice.py]"]
  node_microphone["Audio capture<br/>[qt_microphone.py]"]
  node_speech["Speech providers"]
  node_live["Gemini Live"]
end

subgraph group_actions["Actions and integrations"]
  node_actions["Action policy and execution"]
  node_clarification["Action clarification"]
  node_envelope["Command envelope"]
  node_spotify["Spotify integration<br/>[client.py]"]
  node_gmail["Gmail integration"]
  node_discord["Discord integration"]
  node_notifications["Notification controls"]
end

node_user(("User"))
node_external["External services"]

node_user -->|"interacts"| node_ui
node_ui -->|"routes input"| node_app
node_app -->|"coordinates chat"| node_chat
node_chat -->|"requests response"| node_ai
node_chat -->|"assembles context"| node_memory
node_memory -->|"stores memories"| node_memoryrepo
node_chat -->|"persists messages"| node_conversations
node_conversations -->|"uses SQLite"| node_database
node_memoryrepo -->|"uses SQLite"| node_database
node_migrator -.->|"migrates schema"| node_database
node_ui -->|"supports care"| node_pet
node_ui -->|"shows behavior"| node_behavior
node_voiceui -->|"sends voice requests"| node_voice
node_voice -->|"updates state"| node_voice_state
node_voice -.->|"coordinates turns"| node_voice_session
node_voice -.->|"captures speech"| node_microphone
node_voice -->|"uses providers"| node_speech
node_voiceui -.->|"starts live mode"| node_live
node_app -->|"authorizes actions"| node_actions
node_actions -.->|"requires clarification"| node_clarification
node_actions -.->|"validates commands"| node_envelope
node_actions -.->|"dispatches playback"| node_spotify
node_external -.->|"serves API"| node_spotify
node_external -.->|"serves metadata"| node_gmail
node_external -.->|"sends events"| node_discord
node_gmail -.->|"feeds notifications"| node_notifications
node_discord -.->|"feeds notifications"| node_notifications
node_spotify -.->|"may notify"| node_notifications
node_ui -.->|"uses styling"| node_theme
node_settings -->|"configures runtime"| node_app

click node_ui "https://github.com/ianoliveru/project-akiha/tree/main/project_akiha/ui"
click node_app "https://github.com/ianoliveru/project-akiha/tree/main/project_akiha/app"
click node_theme "https://github.com/ianoliveru/project-akiha/blob/main/project_akiha/ui/theme.py"
click node_settings "https://github.com/ianoliveru/project-akiha/blob/main/project_akiha/config/settings.py"
click node_chat "https://github.com/ianoliveru/project-akiha/blob/main/project_akiha/app/chat_controller.py"
click node_ai "https://github.com/ianoliveru/project-akiha/tree/main/project_akiha/providers/ai"
click node_memory "https://github.com/ianoliveru/project-akiha/blob/main/project_akiha/core/memory/pipeline.py"
click node_memoryrepo "https://github.com/ianoliveru/project-akiha/blob/main/project_akiha/core/memory/repository.py"
click node_conversations "https://github.com/ianoliveru/project-akiha/blob/main/project_akiha/database/sqlite_conversation_repository.py"
click node_database "https://github.com/ianoliveru/project-akiha/tree/main/project_akiha/database"
click node_pet "https://github.com/ianoliveru/project-akiha/tree/main/project_akiha/core/pet"
click node_behavior "https://github.com/ianoliveru/project-akiha/tree/main/project_akiha/core/behavior"
click node_voiceui "https://github.com/ianoliveru/project-akiha/tree/main/project_akiha/ui"
click node_voice "https://github.com/ianoliveru/project-akiha/blob/main/project_akiha/app/voice_controller.py"
click node_voice_session "https://github.com/ianoliveru/project-akiha/blob/main/project_akiha/app/voice_session_coordinator.py"
click node_voice_state "https://github.com/ianoliveru/project-akiha/blob/main/project_akiha/core/state/voice.py"
click node_microphone "https://github.com/ianoliveru/project-akiha/blob/main/project_akiha/providers/voice/qt_microphone.py"
click node_speech "https://github.com/ianoliveru/project-akiha/tree/main/project_akiha/providers/voice"
click node_live "https://github.com/ianoliveru/project-akiha/tree/main/project_akiha/providers/live"
click node_actions "https://github.com/ianoliveru/project-akiha/tree/main/project_akiha/core/actions"
click node_clarification "https://github.com/ianoliveru/project-akiha/blob/main/project_akiha/services/action_clarification.py"
click node_envelope "https://github.com/ianoliveru/project-akiha/blob/main/project_akiha/services/command_envelope.py"
click node_spotify "https://github.com/ianoliveru/project-akiha/blob/main/project_akiha/integrations/spotify/client.py"
click node_gmail "https://github.com/ianoliveru/project-akiha/tree/main/project_akiha/integrations/gmail"
click node_discord "https://github.com/ianoliveru/project-akiha/tree/main/project_akiha/integrations/discord"
click node_notifications "https://github.com/ianoliveru/project-akiha/tree/main/project_akiha/core/notifications"
click node_migrator "https://github.com/ianoliveru/project-akiha/blob/main/project_akiha/database/migrator.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_ui,node_app,node_theme,node_settings,node_user toneBlue
class node_chat,node_ai,node_memory,node_memoryrepo,node_conversations,node_database,node_migrator toneAmber
class node_pet,node_behavior toneMint
class node_voiceui,node_voice,node_voice_session,node_voice_state,node_microphone,node_speech,node_live toneRose
class node_actions,node_clarification,node_envelope,node_spotify,node_gmail,node_discord,node_notifications,node_external toneIndigo
```

## Components

### Desktop experience

- [Desktop UI](https://github.com/ianoliveru/project-akiha/tree/main/project_akiha/ui): `project_akiha/ui`
- [App controllers](https://github.com/ianoliveru/project-akiha/tree/main/project_akiha/app): `project_akiha/app`
- [UI theme](https://github.com/ianoliveru/project-akiha/blob/main/project_akiha/ui/theme.py): `project_akiha/ui/theme.py`
- [Configuration](https://github.com/ianoliveru/project-akiha/blob/main/project_akiha/config/settings.py): `project_akiha/config/settings.py`

### Conversation and memory

- [Chat controller](https://github.com/ianoliveru/project-akiha/blob/main/project_akiha/app/chat_controller.py): `project_akiha/app/chat_controller.py`
- [AI providers](https://github.com/ianoliveru/project-akiha/tree/main/project_akiha/providers/ai): `project_akiha/providers/ai`
- [Memory pipeline](https://github.com/ianoliveru/project-akiha/blob/main/project_akiha/core/memory/pipeline.py): `project_akiha/core/memory/pipeline.py`
- [Memory repository](https://github.com/ianoliveru/project-akiha/blob/main/project_akiha/core/memory/repository.py): `project_akiha/core/memory/repository.py`
- [Conversation storage](https://github.com/ianoliveru/project-akiha/blob/main/project_akiha/database/sqlite_conversation_repository.py): `project_akiha/database/sqlite_conversation_repository.py`
- [SQLite persistence](https://github.com/ianoliveru/project-akiha/tree/main/project_akiha/database): `project_akiha/database`
- [Database migrations](https://github.com/ianoliveru/project-akiha/blob/main/project_akiha/database/migrator.py): `project_akiha/database/migrator.py`

### Pet and behavior

- [Pet care and progression](https://github.com/ianoliveru/project-akiha/tree/main/project_akiha/core/pet): `project_akiha/core/pet`
- [Activity and mood](https://github.com/ianoliveru/project-akiha/tree/main/project_akiha/core/behavior): `project_akiha/core/behavior`

### Voice runtime

- [Voice interface](https://github.com/ianoliveru/project-akiha/tree/main/project_akiha/ui): `project_akiha/ui`
- [Voice controller](https://github.com/ianoliveru/project-akiha/blob/main/project_akiha/app/voice_controller.py): `project_akiha/app/voice_controller.py`
- [Voice sessions](https://github.com/ianoliveru/project-akiha/blob/main/project_akiha/app/voice_session_coordinator.py): `project_akiha/app/voice_session_coordinator.py`
- [Voice state](https://github.com/ianoliveru/project-akiha/blob/main/project_akiha/core/state/voice.py): `project_akiha/core/state/voice.py`
- [Audio capture](https://github.com/ianoliveru/project-akiha/blob/main/project_akiha/providers/voice/qt_microphone.py): `project_akiha/providers/voice/qt_microphone.py`
- [Speech providers](https://github.com/ianoliveru/project-akiha/tree/main/project_akiha/providers/voice): `project_akiha/providers/voice`
- [Gemini Live](https://github.com/ianoliveru/project-akiha/tree/main/project_akiha/providers/live): `project_akiha/providers/live`

### Actions and integrations

- [Action policy and execution](https://github.com/ianoliveru/project-akiha/tree/main/project_akiha/core/actions): `project_akiha/core/actions`
- [Action clarification](https://github.com/ianoliveru/project-akiha/blob/main/project_akiha/services/action_clarification.py): `project_akiha/services/action_clarification.py`
- [Command envelope](https://github.com/ianoliveru/project-akiha/blob/main/project_akiha/services/command_envelope.py): `project_akiha/services/command_envelope.py`
- [Spotify integration](https://github.com/ianoliveru/project-akiha/blob/main/project_akiha/integrations/spotify/client.py): `project_akiha/integrations/spotify/client.py`
- [Gmail integration](https://github.com/ianoliveru/project-akiha/tree/main/project_akiha/integrations/gmail): `project_akiha/integrations/gmail`
- [Discord integration](https://github.com/ianoliveru/project-akiha/tree/main/project_akiha/integrations/discord): `project_akiha/integrations/discord`
- [Notification controls](https://github.com/ianoliveru/project-akiha/tree/main/project_akiha/core/notifications): `project_akiha/core/notifications`

### Other components

- **User**
- **External services**

## Connections

- User → Desktop UI: interacts
- Desktop UI → App controllers: routes input (evidence: `project_akiha/ui/hosted_live_session_worker.py`)
- App controllers → Chat controller: coordinates chat
- Chat controller → AI providers: requests response (evidence: `project_akiha/app/chat_controller.py`)
- Chat controller → Memory pipeline: assembles context
- Memory pipeline → Memory repository: stores memories (evidence: `project_akiha/core/memory/pipeline.py`)
- Chat controller → Conversation storage: persists messages (evidence: `project_akiha/app/chat_controller.py`)
- Conversation storage → SQLite persistence: uses SQLite
- Memory repository → SQLite persistence: uses SQLite
- Database migrations → SQLite persistence: migrates schema (evidence: `project_akiha/database/sqlite_pet_repository.py`)
- Desktop UI → Pet care and progression: supports care
- Desktop UI → Activity and mood: shows behavior
- Voice interface → Voice controller: sends voice requests
- Voice controller → Voice state: updates state (evidence: `project_akiha/app/voice_controller.py`)
- Voice controller → Voice sessions: coordinates turns
- Voice controller → Audio capture: captures speech
- Voice controller → Speech providers: uses providers
- Voice interface → Gemini Live: starts live mode
- App controllers → Action policy and execution: authorizes actions (evidence: `project_akiha/app/action_clarification_controller.py`)
- Action policy and execution → Action clarification: requires clarification
- Action policy and execution → Command envelope: validates commands
- Action policy and execution → Spotify integration: dispatches playback
- External services → Spotify integration: serves API
- External services → Gmail integration: serves metadata
- External services → Discord integration: sends events
- Gmail integration → Notification controls: feeds notifications
- Discord integration → Notification controls: feeds notifications
- Spotify integration → Notification controls: may notify
- Desktop UI → UI theme: uses styling (evidence: `project_akiha/ui/manager_presentation.py`)
- Configuration → App controllers: configures runtime
