# dulnith-liyanage/desk-companion architecture

> Architecture diagram of the GitHub repository dulnith-liyanage/desk-companion, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dulnith-liyanage/desk-companion
- Repository: https://github.com/dulnith-liyanage/desk-companion

## Overview

Desk Companion is ESP32-C3 firmware for a touch-operated Yeti desk companion. A touch gesture selects its face reactions, clock and alarm views, Pomodoro timer, or Yeti Run game; the OLED presents the resulting interface, while sound and vibration provide alerts and feedback. A browser dashboard configures settings stored in flash, and a background task retrieves weather from OpenWeatherMap. The README describes these capabilities, but no source excerpts were provided, so relationships below are limited to documented behavior; implementation nodes point to the single sketch.

Main entry points: [`desk_companion.ino`](https://github.com/dulnith-liyanage/desk-companion/blob/main/desk_companion.ino) (Touch Controls)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Touch and Display"]
  node_touch["Touch Controls<br/>[desk_companion.ino]"]
  node_oled["OLED Display<br/>[desk_companion.ino]"]
end

subgraph group_modes["Companion Modes"]
  node_face["Animated Face<br/>[desk_companion.ino]"]
  node_clock["Clock Views<br/>[desk_companion.ino]"]
  node_alarms["Alarm Manager<br/>[desk_companion.ino]"]
  node_pomodoro["Pomodoro Timer<br/>[desk_companion.ino]"]
  node_game["Yeti Run<br/>[desk_companion.ino]"]
  node_sleep["Sleep Mode<br/>[desk_companion.ino]"]
end

subgraph group_services["Network and Settings"]
  node_dashboard["Web Dashboard<br/>[desk_companion.ino]"]
  node_weather["Weather Retrieval<br/>[desk_companion.ino]"]
  node_nvs[("NVS Settings<br/>[desk_companion.ino]")]
end

subgraph group_feedback["Hardware Feedback"]
  node_buzzer["Buzzer<br/>[desk_companion.ino]"]
  node_vibration["Vibration Motor<br/>[desk_companion.ino]"]
end

node_user(("User"))
node_browser(("Browser"))
node_owm(("OpenWeatherMap"))

node_user -->|"gestures"| node_touch
node_touch -->|"triggers reactions"| node_face
node_touch -->|"double tap"| node_clock
node_touch -->|"long press"| node_alarms
node_touch -->|"triple tap"| node_pomodoro
node_touch -->|"quad tap"| node_game
node_touch -->|"wakes"| node_sleep
node_face -->|"renders"| node_oled
node_clock -->|"renders"| node_oled
node_alarms -->|"renders"| node_oled
node_pomodoro -->|"renders"| node_oled
node_game -->|"renders"| node_oled
node_browser -->|"configures"| node_dashboard
node_dashboard -->|"saves settings"| node_nvs
node_weather -->|"fetches weather"| node_owm
node_weather -->|"shows conditions"| node_oled
node_pomodoro -->|"alerts"| node_buzzer
node_pomodoro -->|"alerts"| node_vibration
node_game -->|"rumbles on collision"| node_vibration
node_alarms -->|"sounds alarm"| node_buzzer

click node_touch "https://github.com/dulnith-liyanage/desk-companion/blob/main/desk_companion.ino"
click node_oled "https://github.com/dulnith-liyanage/desk-companion/blob/main/desk_companion.ino"
click node_face "https://github.com/dulnith-liyanage/desk-companion/blob/main/desk_companion.ino"
click node_clock "https://github.com/dulnith-liyanage/desk-companion/blob/main/desk_companion.ino"
click node_alarms "https://github.com/dulnith-liyanage/desk-companion/blob/main/desk_companion.ino"
click node_pomodoro "https://github.com/dulnith-liyanage/desk-companion/blob/main/desk_companion.ino"
click node_game "https://github.com/dulnith-liyanage/desk-companion/blob/main/desk_companion.ino"
click node_sleep "https://github.com/dulnith-liyanage/desk-companion/blob/main/desk_companion.ino"
click node_dashboard "https://github.com/dulnith-liyanage/desk-companion/blob/main/desk_companion.ino"
click node_weather "https://github.com/dulnith-liyanage/desk-companion/blob/main/desk_companion.ino"
click node_nvs "https://github.com/dulnith-liyanage/desk-companion/blob/main/desk_companion.ino"
click node_buzzer "https://github.com/dulnith-liyanage/desk-companion/blob/main/desk_companion.ino"
click node_vibration "https://github.com/dulnith-liyanage/desk-companion/blob/main/desk_companion.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_oled,node_user,node_browser toneBlue
class node_face,node_clock,node_alarms,node_pomodoro,node_game,node_sleep toneAmber
class node_dashboard,node_weather,node_nvs toneMint
class node_buzzer,node_vibration toneRose
class node_owm toneIndigo
```

## Components

### Touch and Display

- [Touch Controls](https://github.com/dulnith-liyanage/desk-companion/blob/main/desk_companion.ino): `desk_companion.ino`
- [OLED Display](https://github.com/dulnith-liyanage/desk-companion/blob/main/desk_companion.ino): `desk_companion.ino`

### Companion Modes

- [Animated Face](https://github.com/dulnith-liyanage/desk-companion/blob/main/desk_companion.ino): `desk_companion.ino`
- [Clock Views](https://github.com/dulnith-liyanage/desk-companion/blob/main/desk_companion.ino): `desk_companion.ino`
- [Alarm Manager](https://github.com/dulnith-liyanage/desk-companion/blob/main/desk_companion.ino): `desk_companion.ino`
- [Pomodoro Timer](https://github.com/dulnith-liyanage/desk-companion/blob/main/desk_companion.ino): `desk_companion.ino`
- [Yeti Run](https://github.com/dulnith-liyanage/desk-companion/blob/main/desk_companion.ino): `desk_companion.ino`
- [Sleep Mode](https://github.com/dulnith-liyanage/desk-companion/blob/main/desk_companion.ino): `desk_companion.ino`

### Network and Settings

- [Web Dashboard](https://github.com/dulnith-liyanage/desk-companion/blob/main/desk_companion.ino): `desk_companion.ino`
- [Weather Retrieval](https://github.com/dulnith-liyanage/desk-companion/blob/main/desk_companion.ino): `desk_companion.ino`
- [NVS Settings](https://github.com/dulnith-liyanage/desk-companion/blob/main/desk_companion.ino): `desk_companion.ino`

### Hardware Feedback

- [Buzzer](https://github.com/dulnith-liyanage/desk-companion/blob/main/desk_companion.ino): `desk_companion.ino`
- [Vibration Motor](https://github.com/dulnith-liyanage/desk-companion/blob/main/desk_companion.ino): `desk_companion.ino`

### Other components

- **User**
- **Browser**
- **OpenWeatherMap**

## Connections

- User → Touch Controls: gestures (evidence: `README.md`)
- Touch Controls → Animated Face: triggers reactions (evidence: `README.md`)
- Touch Controls → Clock Views: double tap (evidence: `README.md`)
- Touch Controls → Alarm Manager: long press (evidence: `README.md`)
- Touch Controls → Pomodoro Timer: triple tap (evidence: `README.md`)
- Touch Controls → Yeti Run: quad tap (evidence: `README.md`)
- Touch Controls → Sleep Mode: wakes (evidence: `README.md`)
- Animated Face → OLED Display: renders (evidence: `README.md`)
- Clock Views → OLED Display: renders (evidence: `README.md`)
- Alarm Manager → OLED Display: renders (evidence: `README.md`)
- Pomodoro Timer → OLED Display: renders (evidence: `README.md`)
- Yeti Run → OLED Display: renders (evidence: `README.md`)
- Browser → Web Dashboard: configures (evidence: `README.md`)
- Web Dashboard → NVS Settings: saves settings (evidence: `README.md`)
- Weather Retrieval → OpenWeatherMap: fetches weather (evidence: `README.md`)
- Weather Retrieval → OLED Display: shows conditions (evidence: `README.md`)
- Pomodoro Timer → Buzzer: alerts (evidence: `README.md`)
- Pomodoro Timer → Vibration Motor: alerts (evidence: `README.md`)
- Yeti Run → Vibration Motor: rumbles on collision (evidence: `README.md`)
- Alarm Manager → Buzzer: sounds alarm (evidence: `README.md`)