# agharsallah/esp-labs-web architecture

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

- Interactive diagram: https://gitdiagram.com/agharsallah/esp-labs-web
- Repository: https://github.com/agharsallah/esp-labs-web

## Overview

ESP32 Labs is a browser-based, interactive bench guide for learning the ESP32-S3. A learner opens a lesson, follows its wiring and command steps, and uses an in-browser simulator; progress and lesson variants are retained locally. From there, the guide supports reading the lab firmware line by line and exploring chip and datasheet material. The graph also preserves the board, parts, bench log, and localization capabilities documented in the README. Several subsystem links rely on README descriptions because their implementation files were not sampled.

Main entry points: [`src/app/router.tsx`](https://github.com/agharsallah/esp-labs-web/blob/main/src/app/router.tsx) (Hash router), [`src/features/code/reader/CodeReader.tsx`](https://github.com/agharsallah/esp-labs-web/blob/main/src/features/code/reader/CodeReader.tsx) (Code reader), [`src/features/chip/pages/ChipHome.tsx`](https://github.com/agharsallah/esp-labs-web/blob/main/src/features/chip/pages/ChipHome.tsx) (Chip guide), [`src/features/lesson/LessonPage.tsx`](https://github.com/agharsallah/esp-labs-web/blob/main/src/features/lesson/LessonPage.tsx) (Lesson page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_entry["App entry<br/>[main.tsx]"]
  node_router["Hash router<br/>[router.tsx]"]
end

subgraph group_learning["Lessons and labs"]
  node_home["Labs home<br/>[LabsHome.tsx]"]
  node_lesson["Lesson page<br/>[LessonPage.tsx]"]
  node_lessonmodel["Lesson model<br/>[lesson.ts]"]
  node_lessoncontent["Lesson content<br/>[sound.ts]"]
  node_widgetregistry["Widget registry<br/>[registry.ts]"]
  node_simulator["Lab simulators<br/>[simulation.ts]"]
  node_terminal["Serial monitor<br/>[Terminal.tsx]"]
  node_progress["Progress state<br/>[progress-store.ts]"]
  node_board["3D board<br/>[BoardExplorer.tsx]"]
  node_parts["Parts library<br/>[PartsPage.tsx]"]
  node_benchlog["Bench log<br/>[log-route.tsx]"]
end

subgraph group_code["Firmware reader"]
  node_codereader["Code reader<br/>[CodeReader.tsx]"]
  node_codecontent["Tours and glossary<br/>[content-query.ts]"]
  node_codetour["Tour and story<br/>[tour.ts]"]
end

subgraph group_reference["Chip reference"]
  node_chipguide["Chip guide<br/>[ChipHome.tsx]"]
  node_pins["Pinout<br/>[PinsPage.tsx]"]
  node_atlas["Peripheral atlas<br/>[AtlasPage.tsx]"]
  node_book["Reference book<br/>[BookReader.tsx]"]
  node_refcontent["Reference queries<br/>[queries.ts]"]
end

subgraph group_shared["Guide services"]
  node_i18n["Localization<br/>[i18n.ts]"]
  node_settings["Settings<br/>[SettingsPage.tsx]"]
end

node_learner(("Learner"))
node_firmware["esp-labs firmware"]

node_learner -->|"opens guide"| node_router
node_entry -->|"renders routes"| node_router
node_entry -->|"initializes"| node_i18n
node_router -->|"routes home"| node_home
node_router -->|"routes lesson"| node_lesson
node_learner -->|"follows steps"| node_lesson
node_lessoncontent -->|"defines lessons"| node_lessonmodel
node_lessonmodel -->|"references widgets"| node_widgetregistry
node_lesson -->|"renders preview"| node_simulator
node_simulator -->|"shows commands"| node_terminal
node_learner -->|"enters commands"| node_terminal
node_learner -->|"ticks steps"| node_progress
node_home -->|"shows board"| node_board
node_router -->|"routes parts"| node_parts
node_router -->|"routes log"| node_benchlog
node_router -->|"routes code"| node_codereader
node_codereader -->|"reads firmware"| node_firmware
node_codereader -->|"loads explanations"| node_codecontent
node_codereader -->|"supports tours"| node_codetour
node_router -->|"routes datasheet"| node_chipguide
node_chipguide -->|"offers pinout"| node_pins
node_chipguide -->|"offers atlas"| node_atlas
node_chipguide -->|"opens book"| node_book
node_book -->|"loads sections"| node_refcontent
node_router -->|"routes settings"| node_settings

click node_entry "https://github.com/agharsallah/esp-labs-web/blob/main/src/main.tsx"
click node_router "https://github.com/agharsallah/esp-labs-web/blob/main/src/app/router.tsx"
click node_home "https://github.com/agharsallah/esp-labs-web/blob/main/src/features/home/LabsHome.tsx"
click node_lesson "https://github.com/agharsallah/esp-labs-web/blob/main/src/features/lesson/LessonPage.tsx"
click node_lessonmodel "https://github.com/agharsallah/esp-labs-web/blob/main/src/domain/lesson.ts"
click node_lessoncontent "https://github.com/agharsallah/esp-labs-web/blob/main/src/content/lessons/sound.ts"
click node_widgetregistry "https://github.com/agharsallah/esp-labs-web/blob/main/src/widgets/registry.ts"
click node_simulator "https://github.com/agharsallah/esp-labs-web/blob/main/src/labs/shared/simulation.ts"
click node_terminal "https://github.com/agharsallah/esp-labs-web/blob/main/src/ui/terminal/Terminal.tsx"
click node_progress "https://github.com/agharsallah/esp-labs-web/blob/main/src/features/progress/progress-store.ts"
click node_board "https://github.com/agharsallah/esp-labs-web/blob/main/src/features/home/board3d/BoardExplorer.tsx"
click node_parts "https://github.com/agharsallah/esp-labs-web/blob/main/src/features/parts/PartsPage.tsx"
click node_benchlog "https://github.com/agharsallah/esp-labs-web/blob/main/src/app/routes/log-route.tsx"
click node_codereader "https://github.com/agharsallah/esp-labs-web/blob/main/src/features/code/reader/CodeReader.tsx"
click node_codecontent "https://github.com/agharsallah/esp-labs-web/blob/main/src/features/code/content-query.ts"
click node_codetour "https://github.com/agharsallah/esp-labs-web/blob/main/src/domain/code/tour.ts"
click node_chipguide "https://github.com/agharsallah/esp-labs-web/blob/main/src/features/chip/pages/ChipHome.tsx"
click node_pins "https://github.com/agharsallah/esp-labs-web/blob/main/src/features/chip/pages/PinsPage.tsx"
click node_atlas "https://github.com/agharsallah/esp-labs-web/blob/main/src/features/chip/pages/AtlasPage.tsx"
click node_book "https://github.com/agharsallah/esp-labs-web/blob/main/src/features/reference/book/BookReader.tsx"
click node_refcontent "https://github.com/agharsallah/esp-labs-web/blob/main/src/features/reference/queries.ts"
click node_i18n "https://github.com/agharsallah/esp-labs-web/blob/main/src/i18n/i18n.ts"
click node_settings "https://github.com/agharsallah/esp-labs-web/blob/main/src/features/settings/SettingsPage.tsx"

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_entry,node_router toneBlue
class node_home,node_lesson,node_lessonmodel,node_lessoncontent,node_widgetregistry,node_simulator,node_terminal,node_progress,node_board,node_parts,node_benchlog toneAmber
class node_codereader,node_codecontent,node_codetour toneMint
class node_chipguide,node_pins,node_atlas,node_book,node_refcontent toneRose
class node_i18n,node_settings,node_learner,node_firmware toneIndigo
```

## Components

### Application

- [App entry](https://github.com/agharsallah/esp-labs-web/blob/main/src/main.tsx): `src/main.tsx`
- [Hash router](https://github.com/agharsallah/esp-labs-web/blob/main/src/app/router.tsx): `src/app/router.tsx`

### Lessons and labs

- [Labs home](https://github.com/agharsallah/esp-labs-web/blob/main/src/features/home/LabsHome.tsx): `src/features/home/LabsHome.tsx`
- [Lesson page](https://github.com/agharsallah/esp-labs-web/blob/main/src/features/lesson/LessonPage.tsx): `src/features/lesson/LessonPage.tsx`
- [Lesson model](https://github.com/agharsallah/esp-labs-web/blob/main/src/domain/lesson.ts): `src/domain/lesson.ts`
- [Lesson content](https://github.com/agharsallah/esp-labs-web/blob/main/src/content/lessons/sound.ts): `src/content/lessons/sound.ts`
- [Widget registry](https://github.com/agharsallah/esp-labs-web/blob/main/src/widgets/registry.ts): `src/widgets/registry.ts`
- [Lab simulators](https://github.com/agharsallah/esp-labs-web/blob/main/src/labs/shared/simulation.ts): `src/labs/shared/simulation.ts`
- [Serial monitor](https://github.com/agharsallah/esp-labs-web/blob/main/src/ui/terminal/Terminal.tsx): `src/ui/terminal/Terminal.tsx`
- [Progress state](https://github.com/agharsallah/esp-labs-web/blob/main/src/features/progress/progress-store.ts): `src/features/progress/progress-store.ts`
- [3D board](https://github.com/agharsallah/esp-labs-web/blob/main/src/features/home/board3d/BoardExplorer.tsx): `src/features/home/board3d/BoardExplorer.tsx`
- [Parts library](https://github.com/agharsallah/esp-labs-web/blob/main/src/features/parts/PartsPage.tsx): `src/features/parts/PartsPage.tsx`
- [Bench log](https://github.com/agharsallah/esp-labs-web/blob/main/src/app/routes/log-route.tsx): `src/app/routes/log-route.tsx`

### Firmware reader

- [Code reader](https://github.com/agharsallah/esp-labs-web/blob/main/src/features/code/reader/CodeReader.tsx): `src/features/code/reader/CodeReader.tsx`
- [Tours and glossary](https://github.com/agharsallah/esp-labs-web/blob/main/src/features/code/content-query.ts): `src/features/code/content-query.ts`
- [Tour and story](https://github.com/agharsallah/esp-labs-web/blob/main/src/domain/code/tour.ts): `src/domain/code/tour.ts`

### Chip reference

- [Chip guide](https://github.com/agharsallah/esp-labs-web/blob/main/src/features/chip/pages/ChipHome.tsx): `src/features/chip/pages/ChipHome.tsx`
- [Pinout](https://github.com/agharsallah/esp-labs-web/blob/main/src/features/chip/pages/PinsPage.tsx): `src/features/chip/pages/PinsPage.tsx`
- [Peripheral atlas](https://github.com/agharsallah/esp-labs-web/blob/main/src/features/chip/pages/AtlasPage.tsx): `src/features/chip/pages/AtlasPage.tsx`
- [Reference book](https://github.com/agharsallah/esp-labs-web/blob/main/src/features/reference/book/BookReader.tsx): `src/features/reference/book/BookReader.tsx`
- [Reference queries](https://github.com/agharsallah/esp-labs-web/blob/main/src/features/reference/queries.ts): `src/features/reference/queries.ts`

### Guide services

- [Localization](https://github.com/agharsallah/esp-labs-web/blob/main/src/i18n/i18n.ts): `src/i18n/i18n.ts`
- [Settings](https://github.com/agharsallah/esp-labs-web/blob/main/src/features/settings/SettingsPage.tsx): `src/features/settings/SettingsPage.tsx`

### Other components

- **Learner**
- **esp-labs firmware**

## Connections

- Learner → Hash router: opens guide (evidence: `README.md`)
- App entry → Hash router: renders routes
- App entry → Localization: initializes (evidence: `src/main.tsx`)
- Hash router → Labs home: routes home (evidence: `src/app/router.tsx`)
- Hash router → Lesson page: routes lesson (evidence: `src/app/router.tsx`)
- Learner → Lesson page: follows steps (evidence: `README.md`)
- Lesson content → Lesson model: defines lessons (evidence: `src/content/lessons/sound.ts`)
- Lesson model → Widget registry: references widgets (evidence: `src/domain/lesson.ts`)
- Lesson page → Lab simulators: renders preview (evidence: `README.md`)
- Lab simulators → Serial monitor: shows commands (evidence: `README.md`)
- Learner → Serial monitor: enters commands (evidence: `README.md`)
- Learner → Progress state: ticks steps (evidence: `README.md`)
- Labs home → 3D board: shows board (evidence: `README.md`)
- Hash router → Parts library: routes parts (evidence: `src/app/router.tsx`)
- Hash router → Bench log: routes log (evidence: `src/app/router.tsx`)
- Hash router → Code reader: routes code (evidence: `src/app/router.tsx`)
- Code reader → esp-labs firmware: reads firmware (evidence: `README.md`)
- Code reader → Tours and glossary: loads explanations (evidence: `src/features/code/content-query.ts`)
- Code reader → Tour and story: supports tours (evidence: `README.md`)
- Hash router → Chip guide: routes datasheet (evidence: `src/app/router.tsx`)
- Chip guide → Pinout: offers pinout (evidence: `README.md`)
- Chip guide → Peripheral atlas: offers atlas (evidence: `README.md`)
- Chip guide → Reference book: opens book (evidence: `README.md`)
- Reference book → Reference queries: loads sections (evidence: `README.md`)
- Hash router → Settings: routes settings (evidence: `src/app/router.tsx`)