# austinio7116/thumbyone architecture

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

- Interactive diagram: https://gitdiagram.com/austinio7116/thumbyone
- Repository: https://github.com/austinio7116/thumbyone

## Overview

ThumbyOne is unified multi-boot firmware for the Thumby Color. The principal workflow is: the user chooses a system in the lobby; the handoff code reboots into its flash slot; the selected system runs, using shared FAT storage where applicable, and can return to the lobby. The lobby also exposes that shared drive over USB and offers defragmentation. Groups reflect the lobby, shared platform services, and documented runtime systems. Several systems are documented in the README but have no implementation files in this tree; their nodes therefore have null paths, and their internals are not inferred.

Main entry points: [`lobby/lobby_main.c`](https://github.com/austinio7116/thumbyone/blob/main/lobby/lobby_main.c) (System lobby), [`common/thumbyone_handoff.c`](https://github.com/austinio7116/thumbyone/blob/main/common/thumbyone_handoff.c) (Slot handoff), [`common/fs/thumbyone_fs.c`](https://github.com/austinio7116/thumbyone/blob/main/common/fs/thumbyone_fs.c) (Shared FAT access), [`lobby/lobby_usb.c`](https://github.com/austinio7116/thumbyone/blob/main/lobby/lobby_usb.c) (USB drive access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_lobby["Lobby"]
  node_lobby_ui["System lobby<br/>[lobby_main.c]"]
  node_picker["Game picker<br/>[picker.c]"]
  node_usb["USB drive access<br/>[lobby_usb.c]"]
  node_defrag["FAT defragmenter<br/>[lobby_defrag.c]"]
end

subgraph group_platform["Shared platform"]
  node_handoff["Slot handoff"]
  node_layout["Flash slot layout<br/>[slot_layout.h]"]
  node_fatfs["Shared FAT access<br/>[thumbyone_fs.c]"]
  node_disk["Flash disk<br/>[thumbyone_disk.c]"]
  node_settings["Shared settings"]
end

subgraph group_systems["Runtime systems"]
  node_emulation["Emulation systems"]
  node_micropython["MicroPython games"]
  node_mote["Mote platform"]
  node_craft["ThumbyCraft"]
  node_rogue["ThumbyRogue"]
end

subgraph group_hardware["Device hardware"]
  node_backlight["Backlight control"]
  node_battery["Battery readings"]
  node_led["Status LED<br/>[thumbyone_led.c]"]
  node_display["LCD display<br/>[lcd_gc9107.c]"]
end

node_user(("Device user"))
node_host(("USB host"))

node_user -->|"chooses system"| node_lobby_ui
node_lobby_ui -->|"requests slot"| node_handoff
node_handoff -->|"resolves partition"| node_layout
node_handoff -.->|"boots slot"| node_emulation
node_handoff -.->|"boots slot"| node_micropython
node_handoff -.->|"boots slot"| node_mote
node_handoff -.->|"boots slot"| node_craft
node_handoff -.->|"boots optional slot"| node_rogue
node_lobby_ui -->|"pumps USB"| node_usb
node_host -->|"mounts drive"| node_usb
node_usb -->|"reads and writes"| node_disk
node_lobby_ui -->|"offers compaction"| node_defrag
node_defrag -->|"compacts volume"| node_fatfs
node_fatfs -->|"uses sectors"| node_disk
node_lobby_ui -.->|"mounts shared drive"| node_fatfs
node_picker -->|"scans games"| node_fatfs
node_picker -.->|"returns to lobby"| node_handoff
node_lobby_ui -.->|"loads and saves"| node_settings
node_settings -->|"reads and writes"| node_fatfs
node_lobby_ui -.->|"controls brightness"| node_backlight
node_lobby_ui -.->|"reads level"| node_battery
node_lobby_ui -.->|"updates indicator"| node_led
node_lobby_ui -.->|"renders interface"| node_display

click node_lobby_ui "https://github.com/austinio7116/thumbyone/blob/main/lobby/lobby_main.c"
click node_picker "https://github.com/austinio7116/thumbyone/blob/main/common/picker/picker.c"
click node_handoff "https://github.com/austinio7116/thumbyone/blob/main/common/thumbyone_handoff.c"
click node_layout "https://github.com/austinio7116/thumbyone/blob/main/common/slot_layout.h"
click node_usb "https://github.com/austinio7116/thumbyone/blob/main/lobby/lobby_usb.c"
click node_defrag "https://github.com/austinio7116/thumbyone/blob/main/lobby/lobby_defrag.c"
click node_fatfs "https://github.com/austinio7116/thumbyone/blob/main/common/fs/thumbyone_fs.c"
click node_disk "https://github.com/austinio7116/thumbyone/blob/main/common/fs/thumbyone_disk.c"
click node_settings "https://github.com/austinio7116/thumbyone/blob/main/common/lib/thumbyone_settings.c"
click node_backlight "https://github.com/austinio7116/thumbyone/blob/main/common/lib/thumbyone_backlight.c"
click node_battery "https://github.com/austinio7116/thumbyone/blob/main/common/lib/thumbyone_battery.c"
click node_led "https://github.com/austinio7116/thumbyone/blob/main/common/lib/thumbyone_led.c"
click node_display "https://github.com/austinio7116/thumbyone/blob/main/common/picker/lcd_gc9107.c"

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_lobby_ui,node_picker,node_usb,node_defrag,node_user toneBlue
class node_handoff,node_layout,node_fatfs,node_disk,node_settings toneAmber
class node_emulation,node_micropython,node_mote,node_craft,node_rogue toneMint
class node_backlight,node_battery,node_led,node_display toneRose
class node_host toneIndigo
```

## Components

### Lobby

- [System lobby](https://github.com/austinio7116/thumbyone/blob/main/lobby/lobby_main.c): `lobby/lobby_main.c`
- [Game picker](https://github.com/austinio7116/thumbyone/blob/main/common/picker/picker.c): `common/picker/picker.c`
- [USB drive access](https://github.com/austinio7116/thumbyone/blob/main/lobby/lobby_usb.c): `lobby/lobby_usb.c`
- [FAT defragmenter](https://github.com/austinio7116/thumbyone/blob/main/lobby/lobby_defrag.c): `lobby/lobby_defrag.c`

### Shared platform

- [Slot handoff](https://github.com/austinio7116/thumbyone/blob/main/common/thumbyone_handoff.c): `common/thumbyone_handoff.c`
- [Flash slot layout](https://github.com/austinio7116/thumbyone/blob/main/common/slot_layout.h): `common/slot_layout.h`
- [Shared FAT access](https://github.com/austinio7116/thumbyone/blob/main/common/fs/thumbyone_fs.c): `common/fs/thumbyone_fs.c`
- [Flash disk](https://github.com/austinio7116/thumbyone/blob/main/common/fs/thumbyone_disk.c): `common/fs/thumbyone_disk.c`
- [Shared settings](https://github.com/austinio7116/thumbyone/blob/main/common/lib/thumbyone_settings.c): `common/lib/thumbyone_settings.c`

### Runtime systems

- **Emulation systems**
- **MicroPython games**
- **Mote platform**
- **ThumbyCraft**
- **ThumbyRogue**

### Device hardware

- [Backlight control](https://github.com/austinio7116/thumbyone/blob/main/common/lib/thumbyone_backlight.c): `common/lib/thumbyone_backlight.c`
- [Battery readings](https://github.com/austinio7116/thumbyone/blob/main/common/lib/thumbyone_battery.c): `common/lib/thumbyone_battery.c`
- [Status LED](https://github.com/austinio7116/thumbyone/blob/main/common/lib/thumbyone_led.c): `common/lib/thumbyone_led.c`
- [LCD display](https://github.com/austinio7116/thumbyone/blob/main/common/picker/lcd_gc9107.c): `common/picker/lcd_gc9107.c`

### Other components

- **Device user**
- **USB host**

## Connections

- Device user → System lobby: chooses system
- System lobby → Slot handoff: requests slot
- Slot handoff → Flash slot layout: resolves partition (evidence: `common/slot_layout.h`)
- Slot handoff → Emulation systems: boots slot
- Slot handoff → MicroPython games: boots slot
- Slot handoff → Mote platform: boots slot
- Slot handoff → ThumbyCraft: boots slot
- Slot handoff → ThumbyRogue: boots optional slot
- System lobby → USB drive access: pumps USB
- USB host → USB drive access: mounts drive
- USB drive access → Flash disk: reads and writes
- System lobby → FAT defragmenter: offers compaction (evidence: `lobby/lobby_main.c`)
- FAT defragmenter → Shared FAT access: compacts volume
- Shared FAT access → Flash disk: uses sectors
- System lobby → Shared FAT access: mounts shared drive
- Game picker → Shared FAT access: scans games (evidence: `common/picker/picker.c`)
- Game picker → Slot handoff: returns to lobby (evidence: `common/picker/picker.c`)
- System lobby → Shared settings: loads and saves (evidence: `lobby/lobby_main.c`)
- Shared settings → Shared FAT access: reads and writes
- System lobby → Backlight control: controls brightness (evidence: `lobby/lobby_main.c`)
- System lobby → Battery readings: reads level (evidence: `lobby/lobby_main.c`)
- System lobby → Status LED: updates indicator (evidence: `lobby/lobby_main.c`)
- System lobby → LCD display: renders interface (evidence: `lobby/lobby_main.c`)