# mbamotria/aideskassistant architecture

> Architecture diagram of the GitHub repository mbamotria/aideskassistant, 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/mbamotria/aideskassistant
- Repository: https://github.com/mbamotria/aideskassistant

## Overview

This is an ESP32 voice-assistant firmware: a button-triggered recording is saved locally, transcribed by Deepgram, answered by OpenAI, shown on the OLED, and spoken using Google TTS. The single implementation file also handles time and weather display, SD storage, and FreeRTOS task dispatch. The README documents these capabilities; the source excerpts are partial, so uncertain internal wiring is omitted.

Main entry points: [`src/main.cpp`](https://github.com/mbamotria/aideskassistant/blob/main/src/main.cpp) (Transcription Task)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Voice Interaction"]
  node_loop["Main Loop<br/>[main.cpp]"]
  node_record["Recording Task<br/>[main.cpp]"]
  node_transcription["Transcription Task<br/>[main.cpp]"]
  node_tts["TTS Task<br/>[main.cpp]"]
end

subgraph group_services["AI Services"]
  node_deepgram["Deepgram STT"]
  node_openai["OpenAI Chat"]
  node_googletts["Google TTS"]
end

subgraph group_media["Audio and Storage"]
  node_sd[("SD Card")]
  node_microphone["I2S Microphone"]
  node_speaker["I2S Speaker"]
end

subgraph group_status["Display and Status"]
  node_oled["OLED Display"]
  node_weather["Weather API"]
  node_ntp["NTP Server"]
  node_displaylogic["Display and Status<br/>[main.cpp]"]
end

node_user(("User"))
node_button(("Trigger Button"))

node_user -->|"presses"| node_button
node_button -->|"signals"| node_loop
node_loop -->|"dispatches"| node_record
node_record -->|"captures audio"| node_microphone
node_record -->|"writes WAV"| node_sd
node_record -->|"dispatches"| node_transcription
node_transcription -->|"reads WAV"| node_sd
node_transcription -->|"uploads audio"| node_deepgram
node_transcription -->|"sends transcript"| node_openai
node_transcription -->|"updates response"| node_displaylogic
node_transcription -->|"dispatches"| node_tts
node_tts -->|"requests speech"| node_googletts
node_tts -->|"writes audio"| node_sd
node_tts -->|"reads audio"| node_sd
node_tts -->|"plays audio"| node_speaker
node_loop -->|"updates status"| node_displaylogic
node_loop -->|"fetches weather"| node_weather
node_loop -->|"syncs time"| node_ntp
node_displaylogic -->|"renders"| node_oled

click node_loop "https://github.com/mbamotria/aideskassistant/blob/main/src/main.cpp"
click node_record "https://github.com/mbamotria/aideskassistant/blob/main/src/main.cpp"
click node_transcription "https://github.com/mbamotria/aideskassistant/blob/main/src/main.cpp"
click node_tts "https://github.com/mbamotria/aideskassistant/blob/main/src/main.cpp"
click node_displaylogic "https://github.com/mbamotria/aideskassistant/blob/main/src/main.cpp"

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_loop,node_record,node_transcription,node_tts,node_user toneBlue
class node_deepgram,node_openai,node_googletts toneAmber
class node_sd,node_microphone,node_speaker toneMint
class node_oled,node_weather,node_ntp,node_displaylogic toneRose
class node_button toneIndigo
```

## Components

### Voice Interaction

- [Main Loop](https://github.com/mbamotria/aideskassistant/blob/main/src/main.cpp): `src/main.cpp`
- [Recording Task](https://github.com/mbamotria/aideskassistant/blob/main/src/main.cpp): `src/main.cpp`
- [Transcription Task](https://github.com/mbamotria/aideskassistant/blob/main/src/main.cpp): `src/main.cpp`
- [TTS Task](https://github.com/mbamotria/aideskassistant/blob/main/src/main.cpp): `src/main.cpp`

### AI Services

- **Deepgram STT**
- **OpenAI Chat**
- **Google TTS**

### Audio and Storage

- **SD Card**
- **I2S Microphone**
- **I2S Speaker**

### Display and Status

- **OLED Display**
- **Weather API**
- **NTP Server**
- [Display and Status](https://github.com/mbamotria/aideskassistant/blob/main/src/main.cpp): `src/main.cpp`

### Other components

- **User**
- **Trigger Button**

## Connections

- User → Trigger Button: presses
- Trigger Button → Main Loop: signals
- Main Loop → Recording Task: dispatches
- Recording Task → I2S Microphone: captures audio
- Recording Task → SD Card: writes WAV
- Recording Task → Transcription Task: dispatches
- Transcription Task → SD Card: reads WAV
- Transcription Task → Deepgram STT: uploads audio
- Transcription Task → OpenAI Chat: sends transcript
- Transcription Task → Display and Status: updates response
- Transcription Task → TTS Task: dispatches
- TTS Task → Google TTS: requests speech
- TTS Task → SD Card: writes audio
- TTS Task → SD Card: reads audio
- TTS Task → I2S Speaker: plays audio
- Main Loop → Display and Status: updates status
- Main Loop → Weather API: fetches weather
- Main Loop → NTP Server: syncs time
- Display and Status → OLED Display: renders