# cifertech/tamafi architecture

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

- Interactive diagram: https://gitdiagram.com/cifertech/tamafi
- Repository: https://github.com/cifertech/tamafi

## Overview

TamaFi is ESP32-S3 virtual-pet firmware: device inputs and nearby WiFi inform pet behavior, which updates the pet’s life state and is presented through the TFT interface, sound, and LEDs. The README documents autonomous hunting, exploration, rest, mood, evolution, menus, and persistent settings. The main firmware and several behavior modules are unsampled, so documented relationships are cited to the README; UI asset use is supported by the ui.cpp reference index and excerpt.

Main entry points: [`TamaFi/ui.cpp`](https://github.com/cifertech/tamafi/blob/main/TamaFi/ui.cpp) (Screens and menus), [`TamaFi/TamaFi.ino`](https://github.com/cifertech/tamafi/blob/main/TamaFi/TamaFi.ino) (Firmware loop), [`TamaFi/egg_hatch.h`](https://github.com/cifertech/tamafi/blob/main/TamaFi/egg_hatch.h) (Hatch and rest), [`TamaFi/ui_anim.h`](https://github.com/cifertech/tamafi/blob/main/TamaFi/ui_anim.h) (Animation timing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_pet["Pet Behavior"]
  node_firmware["Firmware loop<br/>[TamaFi.ino]"]
  node_autonomy["Decision engine<br/>[TamaFi.ino]"]
  node_life["Stats and evolution<br/>[TamaFi.ino]"]
  node_hatch["Hatch and rest<br/>[egg_hatch.h]"]
end

subgraph group_interface["Display Interface"]
  node_ui["Screens and menus<br/>[ui.cpp]"]
  node_animations["Animation timing<br/>[ui_anim.h]"]
end

subgraph group_device["Device Services"]
  node_display["TFT display<br/>[User_Setup.h]"]
  node_preferences[("Flash preferences<br/>[TamaFi.ino]")]
  node_pixels["NeoPixel feedback<br/>[TamaFi.ino]"]
  node_sound["Retro sound<br/>[TamaFi.ino]"]
end

subgraph group_assets["Visual Assets"]
  node_petart["Pet sprites<br/>[StoneGolem.h]"]
  node_background["Background art<br/>[background.h]"]
  node_effects["Effect art<br/>[effect.h]"]
end

node_user(("Pet owner"))
node_buttons["Tactile buttons"]
node_wifi["Nearby WiFi"]

node_user -->|"presses"| node_buttons
node_buttons -->|"controls"| node_firmware
node_firmware -->|"updates"| node_autonomy
node_wifi -->|"informs"| node_autonomy
node_autonomy -->|"adjusts stats"| node_life
node_autonomy -->|"triggers rest"| node_hatch
node_firmware -->|"draws screens"| node_ui
node_ui -->|"renders"| node_display
node_ui -->|"uses timings"| node_animations
node_ui -->|"renders sprites"| node_petart
node_ui -->|"draws background"| node_background
node_ui -->|"draws overlays"| node_effects
node_firmware -->|"saves settings"| node_preferences
node_autonomy -->|"sets mood patterns"| node_pixels
node_firmware -->|"plays sequences"| node_sound

click node_firmware "https://github.com/cifertech/tamafi/blob/main/TamaFi/TamaFi.ino"
click node_autonomy "https://github.com/cifertech/tamafi/blob/main/TamaFi/TamaFi.ino"
click node_life "https://github.com/cifertech/tamafi/blob/main/TamaFi/TamaFi.ino"
click node_hatch "https://github.com/cifertech/tamafi/blob/main/TamaFi/egg_hatch.h"
click node_display "https://github.com/cifertech/tamafi/blob/main/User_Setup.h"
click node_ui "https://github.com/cifertech/tamafi/blob/main/TamaFi/ui.cpp"
click node_animations "https://github.com/cifertech/tamafi/blob/main/TamaFi/ui_anim.h"
click node_petart "https://github.com/cifertech/tamafi/blob/main/TamaFi/StoneGolem.h"
click node_background "https://github.com/cifertech/tamafi/blob/main/TamaFi/background.h"
click node_effects "https://github.com/cifertech/tamafi/blob/main/TamaFi/effect.h"
click node_preferences "https://github.com/cifertech/tamafi/blob/main/TamaFi/TamaFi.ino"
click node_pixels "https://github.com/cifertech/tamafi/blob/main/TamaFi/TamaFi.ino"
click node_sound "https://github.com/cifertech/tamafi/blob/main/TamaFi/TamaFi.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_firmware,node_autonomy,node_life,node_hatch toneBlue
class node_ui,node_animations toneAmber
class node_display,node_preferences,node_pixels,node_sound toneMint
class node_petart,node_background,node_effects toneRose
class node_user,node_buttons,node_wifi toneIndigo
```

## Components

### Pet Behavior

- [Firmware loop](https://github.com/cifertech/tamafi/blob/main/TamaFi/TamaFi.ino): `TamaFi/TamaFi.ino`
- [Decision engine](https://github.com/cifertech/tamafi/blob/main/TamaFi/TamaFi.ino): `TamaFi/TamaFi.ino`
- [Stats and evolution](https://github.com/cifertech/tamafi/blob/main/TamaFi/TamaFi.ino): `TamaFi/TamaFi.ino`
- [Hatch and rest](https://github.com/cifertech/tamafi/blob/main/TamaFi/egg_hatch.h): `TamaFi/egg_hatch.h`

### Display Interface

- [Screens and menus](https://github.com/cifertech/tamafi/blob/main/TamaFi/ui.cpp): `TamaFi/ui.cpp`
- [Animation timing](https://github.com/cifertech/tamafi/blob/main/TamaFi/ui_anim.h): `TamaFi/ui_anim.h`

### Device Services

- [TFT display](https://github.com/cifertech/tamafi/blob/main/User_Setup.h): `User_Setup.h`
- [Flash preferences](https://github.com/cifertech/tamafi/blob/main/TamaFi/TamaFi.ino): `TamaFi/TamaFi.ino`
- [NeoPixel feedback](https://github.com/cifertech/tamafi/blob/main/TamaFi/TamaFi.ino): `TamaFi/TamaFi.ino`
- [Retro sound](https://github.com/cifertech/tamafi/blob/main/TamaFi/TamaFi.ino): `TamaFi/TamaFi.ino`

### Visual Assets

- [Pet sprites](https://github.com/cifertech/tamafi/blob/main/TamaFi/StoneGolem.h): `TamaFi/StoneGolem.h`
- [Background art](https://github.com/cifertech/tamafi/blob/main/TamaFi/background.h): `TamaFi/background.h`
- [Effect art](https://github.com/cifertech/tamafi/blob/main/TamaFi/effect.h): `TamaFi/effect.h`

### Other components

- **Pet owner**
- **Tactile buttons**
- **Nearby WiFi**

## Connections

- Pet owner → Tactile buttons: presses (evidence: `README.md`)
- Tactile buttons → Firmware loop: controls (evidence: `README.md`)
- Firmware loop → Decision engine: updates (evidence: `README.md`)
- Nearby WiFi → Decision engine: informs (evidence: `README.md`)
- Decision engine → Stats and evolution: adjusts stats (evidence: `README.md`)
- Decision engine → Hatch and rest: triggers rest (evidence: `README.md`)
- Firmware loop → Screens and menus: draws screens (evidence: `README.md`)
- Screens and menus → TFT display: renders (evidence: `README.md`)
- Screens and menus → Animation timing: uses timings (evidence: `TamaFi/ui.cpp`)
- Screens and menus → Pet sprites: renders sprites (evidence: `TamaFi/ui.cpp`)
- Screens and menus → Background art: draws background (evidence: `TamaFi/ui.cpp`)
- Screens and menus → Effect art: draws overlays (evidence: `TamaFi/ui.cpp`)
- Firmware loop → Flash preferences: saves settings (evidence: `README.md`)
- Decision engine → NeoPixel feedback: sets mood patterns (evidence: `README.md`)
- Firmware loop → Retro sound: plays sequences (evidence: `README.md`)
