# maglore9900/max_headroom architecture

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

- Interactive diagram: https://gitdiagram.com/maglore9900/max_headroom
- Repository: https://github.com/maglore9900/max_headroom

## Overview

##### Main Components

a) Core System Components:
- Speech Input Handler (Speech-to-Text)
- Google Speech Recognition
- Faster-Whisper Option
- Natural Language Processing (LLM)
- OpenAI Integration
- Ollama Integration
- Speech Output System
- AllTalk TTS Integration
- Fallback pyttsx3 System
- Agent Orchestrator

b) Tool Integrations:
- Spotify Controller
- Windows Application Manager
- Window Focus Controller
- Timer System
- Journal System (planned)

**Top Layer: User Interaction**

**Middle Layer: Core Processing**

**Bottom Layer: Tool Integration**

##### Key Relationships

- Input Flow: Microphone → Speech Recognition → NLP Processing
- Output Flow: LLM Response → Text-to-Speech → Audio Output
- Tool Integration: Agent → Individual Tools
- Configuration System: Environment Variables → Component Configuration

##### Specific Implementation Details

**[User Input] → [Wake Word Detection ("Hey Max")]**
- ↓
**[Speech Recognition] → [Agent (modules/agent.py)]**
- ↓
**[LLM Processing] ←→ [Character Prompt System]**
- ↓
**[Tool Router] → [Various Tools]**
- ↓
**[Speech Output] → [Audio Generation]**

##### Important Architectural Notes

- Modular nature of the system (all tools in separate modules)
- Fallback systems (speech recognition and TTS)
- Configuration points (.env file influence)
- Character customization system

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph User["User Interaction Layer"]
        UI[User Input]
        WW["Wake Word Detection<br/>(Hey Max)"]
        AO[Audio Output]
    end

    subgraph Core["Core Processing Layer"]
        SR["Speech Recognition"]
        Agent["Agent Orchestrator"]:::agent
        LLM["LLM Processing"]:::llm
        PS["Character Prompt<br/>System"]:::prompt
        TR["Tool Router"]
        SO["Speech Output<br/>System"]:::speech
    end

    subgraph Tools["Tool Integration Layer"]
        SP["Spotify<br/>Controller"]:::tool
        WA["Windows App<br/>Manager"]:::tool
        WF["Window Focus<br/>Controller"]:::tool
        TS["Timer<br/>System"]:::tool
        JS["Journal System<br/>(Planned)"]:::tool
    end

    subgraph Config["Configuration Layer"]
        ENV["Environment<br/>Variables"]:::config
        PD["Platform Dependencies"]:::config
        AI["Application Index"]:::config
    end

    UI --> WW
    WW --> SR
    SR --> Agent
    Agent <--> LLM
    LLM <--> PS
    Agent --> TR
    TR --> SP & WA & WF & TS & JS
    Agent --> SO
    SO --> AO
    ENV --> Agent
    ENV --> LLM
    ENV --> SO
    PD --> Agent
    AI --> WA

    %% Click Events
    click Agent "https://github.com/maglore9900/max_headroom/blob/main/modules/agent.py"
    click LLM "https://github.com/maglore9900/max_headroom/blob/main/modules/adapter.py"
    click SO "https://github.com/maglore9900/max_headroom/blob/main/modules/speak.py"
    click PS "https://github.com/maglore9900/max_headroom/blob/main/modules/prompts.py"
    click SP "https://github.com/maglore9900/max_headroom/blob/main/modules/spotify.py"
    click WA "https://github.com/maglore9900/max_headroom/blob/main/modules/app_launcher.py"
    click WF "https://github.com/maglore9900/max_headroom/blob/main/modules/windows_focus.py"
    click TS "https://github.com/maglore9900/max_headroom/blob/main/modules/timer.py"
    click JS "https://github.com/maglore9900/max_headroom/blob/main/modules/journal.py"
    click ENV "https://github.com/maglore9900/max_headroom/blob/main/example_env.txt"
    click PD "https://github.com/maglore9900/max_headroom/blob/main/requirements_windows.txt"
    click AI "https://github.com/maglore9900/max_headroom/blob/main/tmp/app_index.json"

    %% Styling
    classDef agent fill:#6495ED
    classDef llm fill:#4169E1
    classDef prompt fill:#1E90FF
    classDef speech fill:#87CEEB
    classDef tool fill:#98FB98
    classDef config fill:#DDA0DD
    
    %% Legend
    subgraph Legend
        L1["Core Components"]:::agent
        L2["Tool Integrations"]:::tool
        L3["Configuration"]:::config
    end
```
