# senkuuuuu/amadeus architecture

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

- Interactive diagram: https://gitdiagram.com/senkuuuuu/amadeus
- Repository: https://github.com/senkuuuuu/amadeus

## Overview

Amadeus is a desktop character-chat application. Its main flow is login against a local SQLite database, a startup animation, then an asynchronous chat window: the user records speech, it is transcribed, sent to Character AI, analyzed for emotion, and answered with speech and matching character animation. The main window coordinates these stages and also manages conversation state. The README documents Character AI and UnrealSpeech integrations; source excerpts show the orchestration and local data/rendering links. Some audio and integration internals were not sampled, so those links are documented rather than inferred beyond the evidence.

Main entry points: [`modules/windows/amadeus_window.py`](https://github.com/senkuuuuu/amadeus/blob/main/modules/windows/amadeus_window.py) (Chat Window), [`modules/windows/log_in_window.py`](https://github.com/senkuuuuu/amadeus/blob/main/modules/windows/log_in_window.py) (Login Window), [`main.py`](https://github.com/senkuuuuu/amadeus/blob/main/main.py) (App Entry), [`modules/data_handlers/handle_data.py`](https://github.com/senkuuuuu/amadeus/blob/main/modules/data_handlers/handle_data.py) (Account and Chat Data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Desktop Flow"]
  node_main["App Entry<br/>[main.py]"]
  node_login["Login Window<br/>[log_in_window.py]"]
  node_startup["Startup Window<br/>[start_up_window.py]"]
  node_amadeus["Chat Window<br/>[amadeus_window.py]"]
end

subgraph group_chat["Chat and Voice"]
  node_recorder["Audio Recorder<br/>[record_audio.py]"]
  node_transcriber["Speech Recognition<br/>[voice_to_text.py]"]
  node_character_ai["Character AI Client"]
  node_emotion["Emotion Analysis"]
  node_tts["Text-to-Speech<br/>[text_to_voice.py]"]
  node_playback["Speech Playback<br/>[start_speaking.py]"]
end

subgraph group_visual["Visual Interface"]
  node_sprite_fetch["Sprite Fetcher<br/>[fetch_sprites.py]"]
  node_ui_generator["GUI Element Generator"]
  node_dialogs["Popup Dialogs"]
  node_renderer["Animation Renderer<br/>[renderer.py]"]
end

subgraph group_data["Local Data"]
  node_db[("SQLite Database")]
  node_data_access["Account and Chat Data<br/>[handle_data.py]"]
  node_resource_path["Resource Path Resolver"]
  node_cleanup["Task and Temp Cleanup<br/>[cleaner.py]"]
end

node_user(("Desktop User"))
node_mic(("Microphone"))
node_character_service{{"Character AI Service"}}
node_voice_service{{"UnrealSpeech Service"}}

node_user -->|"launches"| node_main
node_main -->|"opens"| node_login
node_login -->|"checks credentials"| node_data_access
node_data_access -->|"queries"| node_db
node_main -->|"opens"| node_startup
node_main -->|"starts chat"| node_amadeus
node_startup -->|"renders animation"| node_renderer
node_login -->|"creates controls"| node_ui_generator
node_login -->|"shows prompts"| node_dialogs
node_login -->|"loads artwork"| node_sprite_fetch
node_amadeus -->|"loads chat state"| node_data_access
node_amadeus -->|"records input"| node_recorder
node_mic -.->|"provides audio"| node_recorder
node_amadeus -->|"transcribes recording"| node_transcriber
node_amadeus -->|"sends user text"| node_character_ai
node_character_ai -.->|"requests response"| node_character_service
node_amadeus -->|"analyzes response"| node_emotion
node_emotion -->|"selects emotion sprites"| node_sprite_fetch
node_amadeus -->|"speaks response"| node_tts
node_tts -.->|"requests speech"| node_voice_service
node_amadeus -->|"plays generated audio"| node_playback
node_amadeus -->|"renders chat animation"| node_renderer
node_renderer -->|"loads sprites"| node_sprite_fetch
node_amadeus -->|"builds interface"| node_ui_generator
node_amadeus -->|"shows confirmations"| node_dialogs
node_amadeus -->|"cleans up on exit"| node_cleanup
node_data_access -->|"resolves database path"| node_resource_path
node_sprite_fetch -->|"resolves sprite path"| node_resource_path

click node_main "https://github.com/senkuuuuu/amadeus/blob/main/main.py"
click node_login "https://github.com/senkuuuuu/amadeus/blob/main/modules/windows/log_in_window.py"
click node_startup "https://github.com/senkuuuuu/amadeus/blob/main/modules/windows/start_up_window.py"
click node_amadeus "https://github.com/senkuuuuu/amadeus/blob/main/modules/windows/amadeus_window.py"
click node_db "https://github.com/senkuuuuu/amadeus/blob/main/amadeus_database.db"
click node_data_access "https://github.com/senkuuuuu/amadeus/blob/main/modules/data_handlers/handle_data.py"
click node_resource_path "https://github.com/senkuuuuu/amadeus/blob/main/modules/data_handlers/executable_file_redirector.py"
click node_sprite_fetch "https://github.com/senkuuuuu/amadeus/blob/main/modules/data_handlers/fetch_sprites.py"
click node_cleanup "https://github.com/senkuuuuu/amadeus/blob/main/modules/data_handlers/cleaner.py"
click node_ui_generator "https://github.com/senkuuuuu/amadeus/blob/main/modules/essentials/pygame_obj_generator.py"
click node_dialogs "https://github.com/senkuuuuu/amadeus/blob/main/modules/essentials/dialog_box_tkinter.py"
click node_renderer "https://github.com/senkuuuuu/amadeus/blob/main/modules/essentials/renderer.py"
click node_recorder "https://github.com/senkuuuuu/amadeus/blob/main/modules/functionality/record_audio.py"
click node_transcriber "https://github.com/senkuuuuu/amadeus/blob/main/modules/functionality/voice_to_text.py"
click node_character_ai "https://github.com/senkuuuuu/amadeus/blob/main/modules/essentials/character_ai_async.py"
click node_emotion "https://github.com/senkuuuuu/amadeus/blob/main/modules/essentials/emotion_analysis_hugging_face.py"
click node_tts "https://github.com/senkuuuuu/amadeus/blob/main/modules/functionality/text_to_voice.py"
click node_playback "https://github.com/senkuuuuu/amadeus/blob/main/modules/functionality/start_speaking.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_main,node_login,node_startup,node_amadeus,node_user toneBlue
class node_recorder,node_transcriber,node_character_ai,node_emotion,node_tts,node_playback toneAmber
class node_sprite_fetch,node_ui_generator,node_dialogs,node_renderer toneMint
class node_db,node_data_access,node_resource_path,node_cleanup toneRose
class node_mic,node_character_service,node_voice_service toneIndigo
```

## Components

### Desktop Flow

- [App Entry](https://github.com/senkuuuuu/amadeus/blob/main/main.py): `main.py`
- [Login Window](https://github.com/senkuuuuu/amadeus/blob/main/modules/windows/log_in_window.py): `modules/windows/log_in_window.py`
- [Startup Window](https://github.com/senkuuuuu/amadeus/blob/main/modules/windows/start_up_window.py): `modules/windows/start_up_window.py`
- [Chat Window](https://github.com/senkuuuuu/amadeus/blob/main/modules/windows/amadeus_window.py): `modules/windows/amadeus_window.py`

### Chat and Voice

- [Audio Recorder](https://github.com/senkuuuuu/amadeus/blob/main/modules/functionality/record_audio.py): `modules/functionality/record_audio.py`
- [Speech Recognition](https://github.com/senkuuuuu/amadeus/blob/main/modules/functionality/voice_to_text.py): `modules/functionality/voice_to_text.py`
- [Character AI Client](https://github.com/senkuuuuu/amadeus/blob/main/modules/essentials/character_ai_async.py): `modules/essentials/character_ai_async.py`
- [Emotion Analysis](https://github.com/senkuuuuu/amadeus/blob/main/modules/essentials/emotion_analysis_hugging_face.py): `modules/essentials/emotion_analysis_hugging_face.py`
- [Text-to-Speech](https://github.com/senkuuuuu/amadeus/blob/main/modules/functionality/text_to_voice.py): `modules/functionality/text_to_voice.py`
- [Speech Playback](https://github.com/senkuuuuu/amadeus/blob/main/modules/functionality/start_speaking.py): `modules/functionality/start_speaking.py`

### Visual Interface

- [Sprite Fetcher](https://github.com/senkuuuuu/amadeus/blob/main/modules/data_handlers/fetch_sprites.py): `modules/data_handlers/fetch_sprites.py`
- [GUI Element Generator](https://github.com/senkuuuuu/amadeus/blob/main/modules/essentials/pygame_obj_generator.py): `modules/essentials/pygame_obj_generator.py`
- [Popup Dialogs](https://github.com/senkuuuuu/amadeus/blob/main/modules/essentials/dialog_box_tkinter.py): `modules/essentials/dialog_box_tkinter.py`
- [Animation Renderer](https://github.com/senkuuuuu/amadeus/blob/main/modules/essentials/renderer.py): `modules/essentials/renderer.py`

### Local Data

- [SQLite Database](https://github.com/senkuuuuu/amadeus/blob/main/amadeus_database.db): `amadeus_database.db`
- [Account and Chat Data](https://github.com/senkuuuuu/amadeus/blob/main/modules/data_handlers/handle_data.py): `modules/data_handlers/handle_data.py`
- [Resource Path Resolver](https://github.com/senkuuuuu/amadeus/blob/main/modules/data_handlers/executable_file_redirector.py): `modules/data_handlers/executable_file_redirector.py`
- [Task and Temp Cleanup](https://github.com/senkuuuuu/amadeus/blob/main/modules/data_handlers/cleaner.py): `modules/data_handlers/cleaner.py`

### Other components

- **Desktop User**
- **Microphone**
- **Character AI Service**
- **UnrealSpeech Service**

## Connections

- Desktop User → App Entry: launches (evidence: `README.md`)
- App Entry → Login Window: opens (evidence: `main.py`)
- Login Window → Account and Chat Data: checks credentials (evidence: `modules/windows/log_in_window.py`)
- Account and Chat Data → SQLite Database: queries (evidence: `modules/data_handlers/handle_data.py`)
- App Entry → Startup Window: opens (evidence: `main.py`)
- App Entry → Chat Window: starts chat (evidence: `main.py`)
- Startup Window → Animation Renderer: renders animation (evidence: `modules/windows/start_up_window.py`)
- Login Window → GUI Element Generator: creates controls (evidence: `modules/windows/log_in_window.py`)
- Login Window → Popup Dialogs: shows prompts (evidence: `modules/windows/log_in_window.py`)
- Login Window → Sprite Fetcher: loads artwork (evidence: `modules/windows/log_in_window.py`)
- Chat Window → Account and Chat Data: loads chat state (evidence: `modules/windows/amadeus_window.py`)
- Chat Window → Audio Recorder: records input (evidence: `modules/windows/amadeus_window.py`)
- Microphone → Audio Recorder: provides audio
- Chat Window → Speech Recognition: transcribes recording (evidence: `modules/windows/amadeus_window.py`)
- Chat Window → Character AI Client: sends user text (evidence: `modules/windows/amadeus_window.py`)
- Character AI Client → Character AI Service: requests response (evidence: `README.md`)
- Chat Window → Emotion Analysis: analyzes response (evidence: `modules/windows/amadeus_window.py`)
- Emotion Analysis → Sprite Fetcher: selects emotion sprites
- Chat Window → Text-to-Speech: speaks response (evidence: `modules/windows/amadeus_window.py`)
- Text-to-Speech → UnrealSpeech Service: requests speech (evidence: `README.md`)
- Chat Window → Speech Playback: plays generated audio (evidence: `modules/windows/amadeus_window.py`)
- Chat Window → Animation Renderer: renders chat animation (evidence: `modules/windows/amadeus_window.py`)
- Animation Renderer → Sprite Fetcher: loads sprites (evidence: `modules/essentials/renderer.py`)
- Chat Window → GUI Element Generator: builds interface (evidence: `modules/windows/amadeus_window.py`)
- Chat Window → Popup Dialogs: shows confirmations (evidence: `modules/windows/amadeus_window.py`)
- Chat Window → Task and Temp Cleanup: cleans up on exit (evidence: `modules/windows/amadeus_window.py`)
- Account and Chat Data → Resource Path Resolver: resolves database path (evidence: `modules/data_handlers/handle_data.py`)
- Sprite Fetcher → Resource Path Resolver: resolves sprite path (evidence: `modules/data_handlers/fetch_sprites.py`)
