# ayhansh/mac-ai-buddy architecture

> Architecture diagram of the GitHub repository ayhansh/mac-ai-buddy, 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/ayhansh/mac-ai-buddy
- Repository: https://github.com/ayhansh/mac-ai-buddy

## Overview

Mac AI Buddy is a laptop-run conversational controller for an ESP32 desk robot. The main flow captures speech, sends it to an AI provider for a response and possible tool requests, executes approved local capabilities, then synthesizes and plays speech. Distinct branches cover local semantic memory and guarded X posting. The README and sampled source support the main wiring; some subsystem details are known only from documented capabilities and the source index.

Main entry points: [`minibot/agent/robot_agent.py`](https://github.com/ayhansh/mac-ai-buddy/blob/main/minibot/agent/robot_agent.py) (Conversation agent), [`minibot/audio/capture.py`](https://github.com/ayhansh/mac-ai-buddy/blob/main/minibot/audio/capture.py) (Turn capture), [`minibot/memory/manager.py`](https://github.com/ayhansh/mac-ai-buddy/blob/main/minibot/memory/manager.py) (Memory retrieval), [`minibot/robot/hardware.py`](https://github.com/ayhansh/mac-ai-buddy/blob/main/minibot/robot/hardware.py) (Robot capabilities)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime orchestration"]
  node_cli["Composition root<br/>[cli.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_agent["Conversation agent<br/>[robot_agent.py]"]
  node_events["Event bus<br/>[bus.py]"]
end

subgraph group_conversation["Conversation and audio"]
  node_audio_source["Microphone input<br/>[mac_mic.py]"]
  node_audio_capture["Turn capture<br/>[capture.py]"]
  node_vad["Voice activity<br/>[vad.py]"]
  node_dsp["Audio DSP<br/>[dsp.py]"]
  node_ai_interface["AI interface<br/>[provider.py]"]
  node_gemini["Gemini provider<br/>[gemini_provider.py]"]
  node_openai["OpenAI provider<br/>[openai_provider.py]"]
  node_speech["Speech synthesis"]
end

subgraph group_robot["Robot hardware"]
  node_hardware["Robot capabilities<br/>[hardware.py]"]
  node_esp32["ESP32 transport<br/>[esp32_client.py]"]
  node_firmware["Robot firmware<br/>[ai_mini_bot.ino]"]
end

subgraph group_memory["Local memory"]
  node_memory_manager["Memory retrieval<br/>[manager.py]"]
  node_embeddings["Local embeddings<br/>[embeddings.py]"]
  node_memory_store[("SQLite memory<br/>[store.py]")]
end

subgraph group_social["X account"]
  node_account["Posting policy<br/>[account.py]"]
  node_xclient["X transport<br/>[x_client.py]"]
end

node_user(("User"))
node_x_service["X service"]

node_user -->|"speaks to"| node_audio_source
node_audio_source -->|"provides audio"| node_audio_capture
node_audio_capture -->|"uses voice gating"| node_vad
node_audio_capture -->|"uses processing"| node_dsp
node_agent -->|"captures turns"| node_audio_capture
node_agent -->|"sends audio"| node_ai_interface
node_gemini -->|"implements"| node_ai_interface
node_openai -->|"implements"| node_ai_interface
node_agent -->|"synthesizes replies"| node_speech
node_agent -->|"dispatches tools"| node_hardware
node_hardware -->|"delegates commands"| node_esp32
node_esp32 -->|"calls HTTP API"| node_firmware
node_speech -->|"plays audio"| node_hardware
node_agent -->|"reads and writes"| node_memory_manager
node_memory_manager -->|"embeds queries"| node_embeddings
node_memory_manager -->|"retrieves and stores"| node_memory_store
node_agent -->|"requests social actions"| node_account
node_account -->|"publishes through"| node_xclient
node_xclient -->|"sends API requests"| node_x_service
node_agent -->|"publishes events"| node_events
node_cli -->|"constructs and starts"| node_agent
node_cli -->|"loads settings"| node_config

click node_cli "https://github.com/ayhansh/mac-ai-buddy/blob/main/minibot/cli.py"
click node_config "https://github.com/ayhansh/mac-ai-buddy/blob/main/minibot/config.py"
click node_agent "https://github.com/ayhansh/mac-ai-buddy/blob/main/minibot/agent/robot_agent.py"
click node_events "https://github.com/ayhansh/mac-ai-buddy/blob/main/minibot/events/bus.py"
click node_audio_source "https://github.com/ayhansh/mac-ai-buddy/blob/main/minibot/audio/mac_mic.py"
click node_audio_capture "https://github.com/ayhansh/mac-ai-buddy/blob/main/minibot/audio/capture.py"
click node_vad "https://github.com/ayhansh/mac-ai-buddy/blob/main/minibot/audio/vad.py"
click node_dsp "https://github.com/ayhansh/mac-ai-buddy/blob/main/minibot/audio/dsp.py"
click node_ai_interface "https://github.com/ayhansh/mac-ai-buddy/blob/main/minibot/ai/provider.py"
click node_gemini "https://github.com/ayhansh/mac-ai-buddy/blob/main/minibot/ai/gemini_provider.py"
click node_openai "https://github.com/ayhansh/mac-ai-buddy/blob/main/minibot/ai/openai_provider.py"
click node_speech "https://github.com/ayhansh/mac-ai-buddy/blob/main/minibot/speech/elevenlabs_provider.py"
click node_hardware "https://github.com/ayhansh/mac-ai-buddy/blob/main/minibot/robot/hardware.py"
click node_esp32 "https://github.com/ayhansh/mac-ai-buddy/blob/main/minibot/robot/esp32_client.py"
click node_firmware "https://github.com/ayhansh/mac-ai-buddy/blob/main/ai_mini_bot.ino"
click node_memory_manager "https://github.com/ayhansh/mac-ai-buddy/blob/main/minibot/memory/manager.py"
click node_embeddings "https://github.com/ayhansh/mac-ai-buddy/blob/main/minibot/memory/embeddings.py"
click node_memory_store "https://github.com/ayhansh/mac-ai-buddy/blob/main/minibot/memory/store.py"
click node_account "https://github.com/ayhansh/mac-ai-buddy/blob/main/minibot/social/account.py"
click node_xclient "https://github.com/ayhansh/mac-ai-buddy/blob/main/minibot/social/x_client.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_cli,node_config,node_agent,node_events,node_user toneBlue
class node_audio_source,node_audio_capture,node_vad,node_dsp,node_ai_interface,node_gemini,node_openai,node_speech toneAmber
class node_hardware,node_esp32,node_firmware toneMint
class node_memory_manager,node_embeddings,node_memory_store toneRose
class node_account,node_xclient,node_x_service toneIndigo
```

## Components

### Runtime orchestration

- [Composition root](https://github.com/ayhansh/mac-ai-buddy/blob/main/minibot/cli.py): `minibot/cli.py`
- [Configuration](https://github.com/ayhansh/mac-ai-buddy/blob/main/minibot/config.py): `minibot/config.py`
- [Conversation agent](https://github.com/ayhansh/mac-ai-buddy/blob/main/minibot/agent/robot_agent.py): `minibot/agent/robot_agent.py`
- [Event bus](https://github.com/ayhansh/mac-ai-buddy/blob/main/minibot/events/bus.py): `minibot/events/bus.py`

### Conversation and audio

- [Microphone input](https://github.com/ayhansh/mac-ai-buddy/blob/main/minibot/audio/mac_mic.py): `minibot/audio/mac_mic.py`
- [Turn capture](https://github.com/ayhansh/mac-ai-buddy/blob/main/minibot/audio/capture.py): `minibot/audio/capture.py`
- [Voice activity](https://github.com/ayhansh/mac-ai-buddy/blob/main/minibot/audio/vad.py): `minibot/audio/vad.py`
- [Audio DSP](https://github.com/ayhansh/mac-ai-buddy/blob/main/minibot/audio/dsp.py): `minibot/audio/dsp.py`
- [AI interface](https://github.com/ayhansh/mac-ai-buddy/blob/main/minibot/ai/provider.py): `minibot/ai/provider.py`
- [Gemini provider](https://github.com/ayhansh/mac-ai-buddy/blob/main/minibot/ai/gemini_provider.py): `minibot/ai/gemini_provider.py`
- [OpenAI provider](https://github.com/ayhansh/mac-ai-buddy/blob/main/minibot/ai/openai_provider.py): `minibot/ai/openai_provider.py`
- [Speech synthesis](https://github.com/ayhansh/mac-ai-buddy/blob/main/minibot/speech/elevenlabs_provider.py): `minibot/speech/elevenlabs_provider.py`

### Robot hardware

- [Robot capabilities](https://github.com/ayhansh/mac-ai-buddy/blob/main/minibot/robot/hardware.py): `minibot/robot/hardware.py`
- [ESP32 transport](https://github.com/ayhansh/mac-ai-buddy/blob/main/minibot/robot/esp32_client.py): `minibot/robot/esp32_client.py`
- [Robot firmware](https://github.com/ayhansh/mac-ai-buddy/blob/main/ai_mini_bot.ino): `ai_mini_bot.ino`

### Local memory

- [Memory retrieval](https://github.com/ayhansh/mac-ai-buddy/blob/main/minibot/memory/manager.py): `minibot/memory/manager.py`
- [Local embeddings](https://github.com/ayhansh/mac-ai-buddy/blob/main/minibot/memory/embeddings.py): `minibot/memory/embeddings.py`
- [SQLite memory](https://github.com/ayhansh/mac-ai-buddy/blob/main/minibot/memory/store.py): `minibot/memory/store.py`

### X account

- [Posting policy](https://github.com/ayhansh/mac-ai-buddy/blob/main/minibot/social/account.py): `minibot/social/account.py`
- [X transport](https://github.com/ayhansh/mac-ai-buddy/blob/main/minibot/social/x_client.py): `minibot/social/x_client.py`

### Other components

- **User**
- **X service**

## Connections

- User → Microphone input: speaks to (evidence: `README.md`)
- Microphone input → Turn capture: provides audio (evidence: `minibot/agent/robot_agent.py`)
- Turn capture → Voice activity: uses voice gating (evidence: `minibot/audio/capture.py`)
- Turn capture → Audio DSP: uses processing (evidence: `minibot/audio/capture.py`)
- Conversation agent → Turn capture: captures turns (evidence: `minibot/agent/robot_agent.py`)
- Conversation agent → AI interface: sends audio (evidence: `README.md`)
- Gemini provider → AI interface: implements (evidence: `minibot/ai/gemini_provider.py`)
- OpenAI provider → AI interface: implements (evidence: `minibot/ai/openai_provider.py`)
- Conversation agent → Speech synthesis: synthesizes replies (evidence: `minibot/agent/robot_agent.py`)
- Conversation agent → Robot capabilities: dispatches tools (evidence: `minibot/agent/robot_agent.py`)
- Robot capabilities → ESP32 transport: delegates commands (evidence: `minibot/robot/hardware.py`)
- ESP32 transport → Robot firmware: calls HTTP API (evidence: `README.md`)
- Speech synthesis → Robot capabilities: plays audio (evidence: `minibot/speech/elevenlabs_provider.py`)
- Conversation agent → Memory retrieval: reads and writes (evidence: `minibot/agent/robot_agent.py`)
- Memory retrieval → Local embeddings: embeds queries (evidence: `minibot/memory/manager.py`)
- Memory retrieval → SQLite memory: retrieves and stores (evidence: `minibot/memory/manager.py`)
- Conversation agent → Posting policy: requests social actions (evidence: `minibot/agent/robot_agent.py`)
- Posting policy → X transport: publishes through (evidence: `minibot/social/account.py`)
- X transport → X service: sends API requests (evidence: `minibot/social/x_client.py`)
- Conversation agent → Event bus: publishes events (evidence: `minibot/agent/robot_agent.py`)
- Composition root → Conversation agent: constructs and starts (evidence: `minibot/cli.py`)
- Composition root → Configuration: loads settings (evidence: `minibot/cli.py`)
