# tinkrwave/desktop_companion architecture

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

- Interactive diagram: https://gitdiagram.com/tinkrwave/desktop_companion
- Repository: https://github.com/tinkrwave/desktop_companion

## Overview

DeskBuddy is an ESP32-C3 desk companion. Touches and motion trigger screen changes or gesture reactions; the firmware drives the OLED and buzzer, while connected services provide live information and Bluetooth relays phone notifications and navigation. The tree contains only `desktop_bot.ino`, and no source excerpt was provided, so this map uses README-documented behavior and does not infer internal module boundaries or call order.

Main entry points: [`desktop_bot.ino`](https://github.com/tinkrwave/desktop_companion/blob/main/desktop_bot.ino) (DeskBuddy firmware)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Interaction hardware"]
  node_touch["Touch sensor<br/>[desktop_bot.ino]"]
  node_motion["MPU6050<br/>[desktop_bot.ino]"]
  node_display["OLED display<br/>[desktop_bot.ino]"]
  node_buzzer["Piezo buzzer<br/>[desktop_bot.ino]"]
end

subgraph group_firmware["Companion behavior"]
  node_runtime["DeskBuddy firmware<br/>[desktop_bot.ino]"]
  node_screens["Screens and reactions<br/>[desktop_bot.ino]"]
end

subgraph group_connected["Connected features"]
  node_weather["Weather service"]
  node_youtube["YouTube API"]
  node_chronos["Chronos app"]
  node_maps["Google Maps"]
end

node_person(("Desk user"))
node_phone(("Phone"))

node_person -->|"touches"| node_touch
node_person -->|"moves device"| node_motion
node_touch -->|"provides input"| node_runtime
node_motion -->|"provides motion"| node_runtime
node_runtime -->|"reacts to input"| node_screens
node_screens -->|"shows screens"| node_display
node_runtime -->|"plays tunes"| node_buzzer
node_runtime -->|"gets live weather"| node_weather
node_runtime -->|"gets subscriber count"| node_youtube
node_phone -->|"pairs through"| node_chronos
node_chronos -->|"forwards notifications"| node_runtime
node_maps -->|"provides directions"| node_chronos
node_chronos -->|"forwards navigation"| node_runtime

click node_touch "https://github.com/tinkrwave/desktop_companion/blob/main/desktop_bot.ino"
click node_motion "https://github.com/tinkrwave/desktop_companion/blob/main/desktop_bot.ino"
click node_runtime "https://github.com/tinkrwave/desktop_companion/blob/main/desktop_bot.ino"
click node_screens "https://github.com/tinkrwave/desktop_companion/blob/main/desktop_bot.ino"
click node_display "https://github.com/tinkrwave/desktop_companion/blob/main/desktop_bot.ino"
click node_buzzer "https://github.com/tinkrwave/desktop_companion/blob/main/desktop_bot.ino"

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_touch,node_motion,node_display,node_buzzer,node_person toneBlue
class node_runtime,node_screens toneAmber
class node_weather,node_youtube,node_chronos,node_maps toneMint
class node_phone toneIndigo
```

## Components

### Interaction hardware

- [Touch sensor](https://github.com/tinkrwave/desktop_companion/blob/main/desktop_bot.ino): `desktop_bot.ino`
- [MPU6050](https://github.com/tinkrwave/desktop_companion/blob/main/desktop_bot.ino): `desktop_bot.ino`
- [OLED display](https://github.com/tinkrwave/desktop_companion/blob/main/desktop_bot.ino): `desktop_bot.ino`
- [Piezo buzzer](https://github.com/tinkrwave/desktop_companion/blob/main/desktop_bot.ino): `desktop_bot.ino`

### Companion behavior

- [DeskBuddy firmware](https://github.com/tinkrwave/desktop_companion/blob/main/desktop_bot.ino): `desktop_bot.ino`
- [Screens and reactions](https://github.com/tinkrwave/desktop_companion/blob/main/desktop_bot.ino): `desktop_bot.ino`

### Connected features

- **Weather service**
- **YouTube API**
- **Chronos app**
- **Google Maps**

### Other components

- **Desk user**
- **Phone**

## Connections

- Desk user → Touch sensor: touches (evidence: `README.md`)
- Desk user → MPU6050: moves device (evidence: `README.md`)
- Touch sensor → DeskBuddy firmware: provides input (evidence: `README.md`)
- MPU6050 → DeskBuddy firmware: provides motion (evidence: `README.md`)
- DeskBuddy firmware → Screens and reactions: reacts to input (evidence: `README.md`)
- Screens and reactions → OLED display: shows screens (evidence: `README.md`)
- DeskBuddy firmware → Piezo buzzer: plays tunes (evidence: `README.md`)
- DeskBuddy firmware → Weather service: gets live weather (evidence: `README.md`)
- DeskBuddy firmware → YouTube API: gets subscriber count (evidence: `README.md`)
- Phone → Chronos app: pairs through (evidence: `README.md`)
- Chronos app → DeskBuddy firmware: forwards notifications (evidence: `README.md`)
- Google Maps → Chronos app: provides directions (evidence: `README.md`)
- Chronos app → DeskBuddy firmware: forwards navigation (evidence: `README.md`)
