# fuling0519/esp32-electronic-pet architecture

> Architecture diagram of the GitHub repository fuling0519/esp32-electronic-pet, 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/fuling0519/esp32-electronic-pet
- Repository: https://github.com/fuling0519/esp32-electronic-pet

## Overview

This repository is firmware for an offline ESP32 electronic bird pet. The principal loop samples joystick events, advances pet time and needs, renders the resulting state, and dispatches care, sleep, adoption, or memorial actions; saves preserve the current pet and graveyard across restarts. Distinct stages include egg cracking and hatching, growth, care and illness, death, memorial browsing, and adoption. The README documents additional behavior beyond the sampled excerpts; uncertain internal wiring for those details is not inferred here.

Main entry points: [`src/main.cpp`](https://github.com/fuling0519/esp32-electronic-pet/blob/main/src/main.cpp) (Application loop), [`src/ui/UiController.cpp`](https://github.com/fuling0519/esp32-electronic-pet/blob/main/src/ui/UiController.cpp) (Screens and actions), [`src/storage/Save.cpp`](https://github.com/fuling0519/esp32-electronic-pet/blob/main/src/storage/Save.cpp) (Current pet saves), [`src/pet/PetData.cpp`](https://github.com/fuling0519/esp32-electronic-pet/blob/main/src/pet/PetData.cpp) (Pet state and needs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_main["Application loop<br/>[main.cpp]"]
  node_input["Input events<br/>[Input.cpp]"]
end

subgraph group_pet["Pet lifecycle"]
  node_clock["Pet clock<br/>[PetClock.cpp]"]
  node_petdata["Pet state and needs<br/>[PetData.cpp]"]
  node_name["Pet naming<br/>[PetName.cpp]"]
  node_snapshot["Pet snapshot<br/>[PetSnapshot.cpp]"]
end

subgraph group_interface["User interface"]
  node_ui["Screens and actions<br/>[UiController.cpp]"]
  node_icons["Pet artwork<br/>[PetIcons.cpp]"]
  node_display["OLED display<br/>[Display.cpp]"]
  node_sound["Buzzer audio<br/>[Sound.cpp]"]
end

subgraph group_persistence["Persistence"]
  node_save[("Current pet saves<br/>[Save.cpp]")]
  node_format["Save format<br/>[SaveFormat.h]"]
  node_memorials[("Graveyard records<br/>[Memorials.cpp]")]
end

node_owner(("Pet owner"))
node_joystick(("Joystick"))
node_esp(("ESP32 hardware"))
node_nvs[("Preferences NVS")]

node_owner -->|"operates"| node_joystick
node_joystick -->|"GPIO input"| node_input
node_esp -->|"runs firmware"| node_main
node_main -->|"polls events"| node_input
node_main -->|"advances time"| node_clock
node_clock -->|"elapsed seconds"| node_petdata
node_main -->|"applies actions"| node_petdata
node_main -->|"creates names"| node_name
node_main -->|"updates and dispatches"| node_ui
node_input -->|"input events"| node_ui
node_ui -->|"reads state"| node_petdata
node_ui -->|"draws screens"| node_display
node_ui -->|"plays cues"| node_sound
node_ui -->|"uses artwork"| node_icons
node_main -->|"loads and saves"| node_save
node_main -->|"manages records"| node_memorials
node_save -->|"restores state"| node_petdata
node_save -->|"serializes snapshot"| node_snapshot
node_save -->|"uses layout"| node_format
node_save -->|"reads and writes"| node_nvs
node_memorials -->|"reads and writes"| node_nvs

click node_main "https://github.com/fuling0519/esp32-electronic-pet/blob/main/src/main.cpp"
click node_input "https://github.com/fuling0519/esp32-electronic-pet/blob/main/src/hardware/Input.cpp"
click node_clock "https://github.com/fuling0519/esp32-electronic-pet/blob/main/src/pet/PetClock.cpp"
click node_petdata "https://github.com/fuling0519/esp32-electronic-pet/blob/main/src/pet/PetData.cpp"
click node_name "https://github.com/fuling0519/esp32-electronic-pet/blob/main/src/pet/PetName.cpp"
click node_snapshot "https://github.com/fuling0519/esp32-electronic-pet/blob/main/src/pet/PetSnapshot.cpp"
click node_ui "https://github.com/fuling0519/esp32-electronic-pet/blob/main/src/ui/UiController.cpp"
click node_icons "https://github.com/fuling0519/esp32-electronic-pet/blob/main/src/ui/PetIcons.cpp"
click node_display "https://github.com/fuling0519/esp32-electronic-pet/blob/main/src/hardware/Display.cpp"
click node_sound "https://github.com/fuling0519/esp32-electronic-pet/blob/main/src/hardware/Sound.cpp"
click node_save "https://github.com/fuling0519/esp32-electronic-pet/blob/main/src/storage/Save.cpp"
click node_format "https://github.com/fuling0519/esp32-electronic-pet/blob/main/src/storage/SaveFormat.h"
click node_memorials "https://github.com/fuling0519/esp32-electronic-pet/blob/main/src/storage/Memorials.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_main,node_input toneBlue
class node_clock,node_petdata,node_name,node_snapshot,node_nvs toneAmber
class node_ui,node_icons,node_display,node_sound toneMint
class node_save,node_format,node_memorials toneRose
class node_owner,node_joystick,node_esp toneIndigo
```

## Components

### Application

- [Application loop](https://github.com/fuling0519/esp32-electronic-pet/blob/main/src/main.cpp): `src/main.cpp`
- [Input events](https://github.com/fuling0519/esp32-electronic-pet/blob/main/src/hardware/Input.cpp): `src/hardware/Input.cpp`

### Pet lifecycle

- [Pet clock](https://github.com/fuling0519/esp32-electronic-pet/blob/main/src/pet/PetClock.cpp): `src/pet/PetClock.cpp`
- [Pet state and needs](https://github.com/fuling0519/esp32-electronic-pet/blob/main/src/pet/PetData.cpp): `src/pet/PetData.cpp`
- [Pet naming](https://github.com/fuling0519/esp32-electronic-pet/blob/main/src/pet/PetName.cpp): `src/pet/PetName.cpp`
- [Pet snapshot](https://github.com/fuling0519/esp32-electronic-pet/blob/main/src/pet/PetSnapshot.cpp): `src/pet/PetSnapshot.cpp`

### User interface

- [Screens and actions](https://github.com/fuling0519/esp32-electronic-pet/blob/main/src/ui/UiController.cpp): `src/ui/UiController.cpp`
- [Pet artwork](https://github.com/fuling0519/esp32-electronic-pet/blob/main/src/ui/PetIcons.cpp): `src/ui/PetIcons.cpp`
- [OLED display](https://github.com/fuling0519/esp32-electronic-pet/blob/main/src/hardware/Display.cpp): `src/hardware/Display.cpp`
- [Buzzer audio](https://github.com/fuling0519/esp32-electronic-pet/blob/main/src/hardware/Sound.cpp): `src/hardware/Sound.cpp`

### Persistence

- [Current pet saves](https://github.com/fuling0519/esp32-electronic-pet/blob/main/src/storage/Save.cpp): `src/storage/Save.cpp`
- [Save format](https://github.com/fuling0519/esp32-electronic-pet/blob/main/src/storage/SaveFormat.h): `src/storage/SaveFormat.h`
- [Graveyard records](https://github.com/fuling0519/esp32-electronic-pet/blob/main/src/storage/Memorials.cpp): `src/storage/Memorials.cpp`

### Other components

- **Pet owner**
- **Joystick**
- **ESP32 hardware**
- **Preferences NVS**

## Connections

- Pet owner → Joystick: operates
- Joystick → Input events: GPIO input
- ESP32 hardware → Application loop: runs firmware
- Application loop → Input events: polls events
- Application loop → Pet clock: advances time
- Pet clock → Pet state and needs: elapsed seconds
- Application loop → Pet state and needs: applies actions
- Application loop → Pet naming: creates names
- Application loop → Screens and actions: updates and dispatches
- Input events → Screens and actions: input events
- Screens and actions → Pet state and needs: reads state
- Screens and actions → OLED display: draws screens
- Screens and actions → Buzzer audio: plays cues
- Screens and actions → Pet artwork: uses artwork
- Application loop → Current pet saves: loads and saves
- Application loop → Graveyard records: manages records
- Current pet saves → Pet state and needs: restores state
- Current pet saves → Pet snapshot: serializes snapshot
- Current pet saves → Save format: uses layout
- Current pet saves → Preferences NVS: reads and writes
- Graveyard records → Preferences NVS: reads and writes