# esp-mosaico/esp-mosaico-vibe architecture

> Architecture diagram of the GitHub repository esp-mosaico/esp-mosaico-vibe, 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/esp-mosaico/esp-mosaico-vibe
- Repository: https://github.com/esp-mosaico/esp-mosaico-vibe

## Overview

ESP-Mosaico Vibe is a workspace launcher and agent-guided workflow for creating and operating ESP-Mosaico applications; the implementation of most product commands lives in the utils submodule. The README documents project creation, simulator preview, firmware builds, device recovery and updates, Gateway observation, and a separate game-development path. Submodule internals were not sampled, so links below reflect documented ownership and behavior only.

Main entry points: [`submodule/esp-mosaico-utils`](https://github.com/esp-mosaico/esp-mosaico-vibe/tree/main/submodule/esp-mosaico-utils) (Product CLI), [`mosaico.py`](https://github.com/esp-mosaico/esp-mosaico-vibe/blob/main/mosaico.py) (Workspace launcher), [`projects`](https://github.com/esp-mosaico/esp-mosaico-vibe/tree/main/projects) (Generated application), [`submodule/esp-mosaico-bsp`](https://github.com/esp-mosaico/esp-mosaico-vibe/tree/main/submodule/esp-mosaico-bsp) (Board examples)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspace CLI"]
  node_launcher["Workspace launcher<br/>[mosaico.py]"]
  node_cli["Product CLI"]
end

subgraph group_apps["App Development"]
  node_project_init["Project creation"]
  node_hello_template["Hello World template"]
  node_generated_app["Generated application"]
  node_build["Firmware build"]
  node_preview["GSP preview"]
  node_bsp["Board examples"]
end

subgraph group_device["Device Operations"]
  node_recovery["Device recovery"]
  node_system_update["System update"]
  node_app_update["App update"]
  node_gateway["Gateway workbench"]
end

subgraph group_integrations["External Components"]
  node_game_engine["Game runtime"]
  node_idf["ESP-IDF"]
end

node_developer(("Developer"))

node_developer -->|"runs"| node_launcher
node_launcher -->|"calls"| node_cli
node_cli -->|"dispatches"| node_project_init
node_project_init -->|"reads"| node_hello_template
node_project_init -->|"creates"| node_generated_app
node_cli -->|"dispatches"| node_build
node_build -->|"builds with"| node_idf
node_cli -->|"dispatches"| node_preview
node_preview -->|"previews"| node_generated_app
node_developer -->|"chooses examples"| node_bsp
node_developer -->|"develops games with"| node_game_engine
node_cli -->|"dispatches"| node_recovery
node_cli -->|"dispatches"| node_system_update
node_cli -->|"dispatches"| node_app_update
node_cli -->|"dispatches"| node_gateway

click node_launcher "https://github.com/esp-mosaico/esp-mosaico-vibe/blob/main/mosaico.py"
click node_cli "https://github.com/esp-mosaico/esp-mosaico-vibe/tree/main/submodule/esp-mosaico-utils"
click node_project_init "https://github.com/esp-mosaico/esp-mosaico-vibe/tree/main/submodule/esp-mosaico-utils"
click node_hello_template "https://github.com/esp-mosaico/esp-mosaico-vibe/tree/main/submodule/esp-mosaico-utils"
click node_generated_app "https://github.com/esp-mosaico/esp-mosaico-vibe/tree/main/projects"
click node_build "https://github.com/esp-mosaico/esp-mosaico-vibe/tree/main/submodule/esp-mosaico-utils"
click node_preview "https://github.com/esp-mosaico/esp-mosaico-vibe/tree/main/submodule/esp-mosaico-utils"
click node_bsp "https://github.com/esp-mosaico/esp-mosaico-vibe/tree/main/submodule/esp-mosaico-bsp"
click node_game_engine "https://github.com/esp-mosaico/esp-mosaico-vibe/tree/main/submodule/raylib-lite-engine"
click node_recovery "https://github.com/esp-mosaico/esp-mosaico-vibe/tree/main/submodule/esp-mosaico-utils"
click node_system_update "https://github.com/esp-mosaico/esp-mosaico-vibe/tree/main/submodule/esp-mosaico-utils"
click node_app_update "https://github.com/esp-mosaico/esp-mosaico-vibe/tree/main/submodule/esp-mosaico-utils"
click node_gateway "https://github.com/esp-mosaico/esp-mosaico-vibe/tree/main/submodule/esp-mosaico-utils"

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_launcher,node_cli toneBlue
class node_project_init,node_hello_template,node_generated_app,node_build,node_preview,node_bsp toneAmber
class node_recovery,node_system_update,node_app_update,node_gateway toneMint
class node_game_engine,node_idf toneRose
class node_developer toneIndigo
```

## Components

### Workspace CLI

- [Workspace launcher](https://github.com/esp-mosaico/esp-mosaico-vibe/blob/main/mosaico.py): `mosaico.py`
- [Product CLI](https://github.com/esp-mosaico/esp-mosaico-vibe/tree/main/submodule/esp-mosaico-utils): `submodule/esp-mosaico-utils`

### App Development

- [Project creation](https://github.com/esp-mosaico/esp-mosaico-vibe/tree/main/submodule/esp-mosaico-utils): `submodule/esp-mosaico-utils`
- [Hello World template](https://github.com/esp-mosaico/esp-mosaico-vibe/tree/main/submodule/esp-mosaico-utils): `submodule/esp-mosaico-utils`
- [Generated application](https://github.com/esp-mosaico/esp-mosaico-vibe/tree/main/projects): `projects`
- [Firmware build](https://github.com/esp-mosaico/esp-mosaico-vibe/tree/main/submodule/esp-mosaico-utils): `submodule/esp-mosaico-utils`
- [GSP preview](https://github.com/esp-mosaico/esp-mosaico-vibe/tree/main/submodule/esp-mosaico-utils): `submodule/esp-mosaico-utils`
- [Board examples](https://github.com/esp-mosaico/esp-mosaico-vibe/tree/main/submodule/esp-mosaico-bsp): `submodule/esp-mosaico-bsp`

### Device Operations

- [Device recovery](https://github.com/esp-mosaico/esp-mosaico-vibe/tree/main/submodule/esp-mosaico-utils): `submodule/esp-mosaico-utils`
- [System update](https://github.com/esp-mosaico/esp-mosaico-vibe/tree/main/submodule/esp-mosaico-utils): `submodule/esp-mosaico-utils`
- [App update](https://github.com/esp-mosaico/esp-mosaico-vibe/tree/main/submodule/esp-mosaico-utils): `submodule/esp-mosaico-utils`
- [Gateway workbench](https://github.com/esp-mosaico/esp-mosaico-vibe/tree/main/submodule/esp-mosaico-utils): `submodule/esp-mosaico-utils`

### External Components

- [Game runtime](https://github.com/esp-mosaico/esp-mosaico-vibe/tree/main/submodule/raylib-lite-engine): `submodule/raylib-lite-engine`
- **ESP-IDF**

### Other components

- **Developer**

## Connections

- Developer → Workspace launcher: runs
- Workspace launcher → Product CLI: calls
- Product CLI → Project creation: dispatches
- Project creation → Hello World template: reads
- Project creation → Generated application: creates
- Product CLI → Firmware build: dispatches
- Firmware build → ESP-IDF: builds with
- Product CLI → GSP preview: dispatches
- GSP preview → Generated application: previews
- Developer → Board examples: chooses examples
- Developer → Game runtime: develops games with
- Product CLI → Device recovery: dispatches
- Product CLI → System update: dispatches
- Product CLI → App update: dispatches
- Product CLI → Gateway workbench: dispatches