# kodediy/kode-sim architecture

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

- Interactive diagram: https://gitdiagram.com/kodediy/kode-sim
- Repository: https://github.com/kodediy/kode-sim

## Overview

kode-sim builds kodeOS or a kode-sdk app, runs the unchanged firmware in esp-emu, and presents a simulated Kode Dot through a browser window. Its runtime combines Rust-modeled board chips with kemu firmware stand-ins for capabilities esp-emu lacks, including the display, microSD, network, USB, and console. Separate commands support building, installing apps into running kodeOS, and headless scenario reviews. The documented workflow and sampled imports support the main command and bridge links; some unsampled subsystem wiring is shown only where the README states it.

Main entry points: [`crates/kode-sim/src/bridge.rs`](https://github.com/kodediy/kode-sim/blob/main/crates/kode-sim/src/bridge.rs) (Device bridge), [`crates/kode-sim/src/run.rs`](https://github.com/kodediy/kode-sim/blob/main/crates/kode-sim/src/run.rs) (Simulator run), [`crates/kode-sim/src/main.rs`](https://github.com/kodediy/kode-sim/blob/main/crates/kode-sim/src/main.rs) (Command router), [`firmware/kemu/include/kemu_link.h`](https://github.com/kodediy/kode-sim/blob/main/firmware/kemu/include/kemu_link.h) (Firmware link)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_commands["Commands and workflows"]
  node_cli["Command router<br/>[main.rs]"]
  node_build["Project build<br/>[build.rs]"]
  node_install["App installation<br/>[install.rs]"]
  node_review["Scenario review<br/>[review.rs]"]
  node_run["Simulator run<br/>[run.rs]"]
end

subgraph group_runtime["Emulation runtime"]
  node_emu["ESP emulator<br/>[emu.rs]"]
  node_bridge["Device bridge<br/>[bridge.rs]"]
  node_cosim["Co-simulation client<br/>[client.rs]"]
  node_protocol["Kemu protocol<br/>[proto.rs]"]
  node_serial["Console serial<br/>[serial.rs]"]
end

subgraph group_device["Device models"]
  node_chips["Board chip models<br/>[chips.rs]"]
  node_chipmodels["I2C chip behavior<br/>[board.rs]"]
  node_audio["Audio I/O<br/>[audio.rs]"]
  node_usbhost["USB host computer<br/>[usbhost.rs]"]
  node_sdcard[("Card image<br/>[sdcard.rs]")]
end

subgraph group_firmware["Firmware stand-ins"]
  node_kemu["Firmware link<br/>[kemu_link.h]"]
  node_panel["Display stand-in<br/>[kemu_panel.c]"]
  node_sd["MicroSD stand-in<br/>[kemu_sd.c]"]
  node_usb["USB device model<br/>[usbdcd.c]"]
end

subgraph group_interface["User interface"]
  node_web["Web server<br/>[web.rs]"]
  node_window["Simulator window<br/>[window.rs]"]
  node_webui["Device controls<br/>[sim.js]"]
end

node_user(("Developer"))

node_user -->|"runs commands"| node_cli
node_cli -->|"dispatches build"| node_build
node_cli -->|"dispatches install"| node_install
node_cli -->|"dispatches review"| node_review
node_cli -->|"dispatches run"| node_run
node_run -->|"builds project"| node_build
node_run -->|"boots firmware"| node_emu
node_run -->|"starts device bridge"| node_bridge
node_run -->|"serves device page"| node_web
node_run -->|"opens window"| node_window
node_install -->|"builds app"| node_build
node_install -->|"installs in running OS"| node_bridge
node_review -->|"can build project"| node_build
node_review -->|"runs headless scenario"| node_bridge
node_emu -->|"connects chip bus"| node_cosim
node_emu -->|"answers virtual parts"| node_chips
node_chips -->|"models board chips"| node_chipmodels
node_bridge -->|"starts and controls"| node_emu
node_bridge -->|"decodes device frames"| node_protocol
node_bridge -->|"reads console"| node_serial
node_bridge -->|"starts USB host"| node_usbhost
node_bridge -->|"reads card sectors"| node_sdcard
node_bridge -.->|"handles sound"| node_audio
node_kemu -->|"shares frame format"| node_protocol
node_kemu -.->|"carries display frames"| node_panel
node_kemu -.->|"carries card requests"| node_sd
node_kemu -.->|"carries USB traffic"| node_usb
node_web -->|"routes page messages"| node_bridge
node_window -->|"opens served page"| node_web
node_webui -.->|"sends controls"| node_web
node_usbhost -->|"talks to device"| node_usb
node_sd -.->|"uses card image"| node_sdcard

click node_cli "https://github.com/kodediy/kode-sim/blob/main/crates/kode-sim/src/main.rs"
click node_build "https://github.com/kodediy/kode-sim/blob/main/crates/kode-sim/src/build.rs"
click node_install "https://github.com/kodediy/kode-sim/blob/main/crates/kode-sim/src/install.rs"
click node_review "https://github.com/kodediy/kode-sim/blob/main/crates/kode-sim/src/review.rs"
click node_run "https://github.com/kodediy/kode-sim/blob/main/crates/kode-sim/src/run.rs"
click node_emu "https://github.com/kodediy/kode-sim/blob/main/crates/kode-sim/src/emu.rs"
click node_bridge "https://github.com/kodediy/kode-sim/blob/main/crates/kode-sim/src/bridge.rs"
click node_cosim "https://github.com/kodediy/kode-sim/blob/main/crates/cosim/src/client.rs"
click node_protocol "https://github.com/kodediy/kode-sim/blob/main/crates/kode-sim/src/proto.rs"
click node_chips "https://github.com/kodediy/kode-sim/blob/main/crates/kode-sim/src/chips.rs"
click node_chipmodels "https://github.com/kodediy/kode-sim/blob/main/crates/kodedot-chips/src/board.rs"
click node_audio "https://github.com/kodediy/kode-sim/blob/main/crates/kode-sim/src/audio.rs"
click node_kemu "https://github.com/kodediy/kode-sim/blob/main/firmware/kemu/include/kemu_link.h"
click node_panel "https://github.com/kodediy/kode-sim/blob/main/firmware/kemu/src/kemu_panel.c"
click node_sd "https://github.com/kodediy/kode-sim/blob/main/firmware/kemu/src/kemu_sd.c"
click node_usb "https://github.com/kodediy/kode-sim/blob/main/firmware/kemu/models/usbdcd.c"
click node_usbhost "https://github.com/kodediy/kode-sim/blob/main/crates/kode-sim/src/usbhost.rs"
click node_sdcard "https://github.com/kodediy/kode-sim/blob/main/crates/kode-sim/src/sdcard.rs"
click node_web "https://github.com/kodediy/kode-sim/blob/main/crates/kode-sim/src/web.rs"
click node_window "https://github.com/kodediy/kode-sim/blob/main/crates/kode-sim/src/window.rs"
click node_webui "https://github.com/kodediy/kode-sim/blob/main/web/sim.js"
click node_serial "https://github.com/kodediy/kode-sim/blob/main/crates/kode-sim/src/serial.rs"

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_cli,node_build,node_install,node_review,node_run toneBlue
class node_emu,node_bridge,node_cosim,node_protocol,node_serial toneAmber
class node_chips,node_chipmodels,node_audio,node_usbhost,node_sdcard toneMint
class node_kemu,node_panel,node_sd,node_usb toneRose
class node_web,node_window,node_webui,node_user toneIndigo
```

## Components

### Commands and workflows

- [Command router](https://github.com/kodediy/kode-sim/blob/main/crates/kode-sim/src/main.rs): `crates/kode-sim/src/main.rs`
- [Project build](https://github.com/kodediy/kode-sim/blob/main/crates/kode-sim/src/build.rs): `crates/kode-sim/src/build.rs`
- [App installation](https://github.com/kodediy/kode-sim/blob/main/crates/kode-sim/src/install.rs): `crates/kode-sim/src/install.rs`
- [Scenario review](https://github.com/kodediy/kode-sim/blob/main/crates/kode-sim/src/review.rs): `crates/kode-sim/src/review.rs`
- [Simulator run](https://github.com/kodediy/kode-sim/blob/main/crates/kode-sim/src/run.rs): `crates/kode-sim/src/run.rs`

### Emulation runtime

- [ESP emulator](https://github.com/kodediy/kode-sim/blob/main/crates/kode-sim/src/emu.rs): `crates/kode-sim/src/emu.rs`
- [Device bridge](https://github.com/kodediy/kode-sim/blob/main/crates/kode-sim/src/bridge.rs): `crates/kode-sim/src/bridge.rs`
- [Co-simulation client](https://github.com/kodediy/kode-sim/blob/main/crates/cosim/src/client.rs): `crates/cosim/src/client.rs`
- [Kemu protocol](https://github.com/kodediy/kode-sim/blob/main/crates/kode-sim/src/proto.rs): `crates/kode-sim/src/proto.rs`
- [Console serial](https://github.com/kodediy/kode-sim/blob/main/crates/kode-sim/src/serial.rs): `crates/kode-sim/src/serial.rs`

### Device models

- [Board chip models](https://github.com/kodediy/kode-sim/blob/main/crates/kode-sim/src/chips.rs): `crates/kode-sim/src/chips.rs`
- [I2C chip behavior](https://github.com/kodediy/kode-sim/blob/main/crates/kodedot-chips/src/board.rs): `crates/kodedot-chips/src/board.rs`
- [Audio I/O](https://github.com/kodediy/kode-sim/blob/main/crates/kode-sim/src/audio.rs): `crates/kode-sim/src/audio.rs`
- [USB host computer](https://github.com/kodediy/kode-sim/blob/main/crates/kode-sim/src/usbhost.rs): `crates/kode-sim/src/usbhost.rs`
- [Card image](https://github.com/kodediy/kode-sim/blob/main/crates/kode-sim/src/sdcard.rs): `crates/kode-sim/src/sdcard.rs`

### Firmware stand-ins

- [Firmware link](https://github.com/kodediy/kode-sim/blob/main/firmware/kemu/include/kemu_link.h): `firmware/kemu/include/kemu_link.h`
- [Display stand-in](https://github.com/kodediy/kode-sim/blob/main/firmware/kemu/src/kemu_panel.c): `firmware/kemu/src/kemu_panel.c`
- [MicroSD stand-in](https://github.com/kodediy/kode-sim/blob/main/firmware/kemu/src/kemu_sd.c): `firmware/kemu/src/kemu_sd.c`
- [USB device model](https://github.com/kodediy/kode-sim/blob/main/firmware/kemu/models/usbdcd.c): `firmware/kemu/models/usbdcd.c`

### User interface

- [Web server](https://github.com/kodediy/kode-sim/blob/main/crates/kode-sim/src/web.rs): `crates/kode-sim/src/web.rs`
- [Simulator window](https://github.com/kodediy/kode-sim/blob/main/crates/kode-sim/src/window.rs): `crates/kode-sim/src/window.rs`
- [Device controls](https://github.com/kodediy/kode-sim/blob/main/web/sim.js): `web/sim.js`

### Other components

- **Developer**

## Connections

- Developer → Command router: runs commands (evidence: `crates/kode-sim/src/main.rs`)
- Command router → Project build: dispatches build (evidence: `crates/kode-sim/src/main.rs`)
- Command router → App installation: dispatches install (evidence: `crates/kode-sim/src/main.rs`)
- Command router → Scenario review: dispatches review (evidence: `crates/kode-sim/src/main.rs`)
- Command router → Simulator run: dispatches run (evidence: `crates/kode-sim/src/main.rs`)
- Simulator run → Project build: builds project (evidence: `crates/kode-sim/src/run.rs`)
- Simulator run → ESP emulator: boots firmware (evidence: `crates/kode-sim/src/run.rs`)
- Simulator run → Device bridge: starts device bridge (evidence: `crates/kode-sim/src/run.rs`)
- Simulator run → Web server: serves device page (evidence: `crates/kode-sim/src/run.rs`)
- Simulator run → Simulator window: opens window (evidence: `crates/kode-sim/src/run.rs`)
- App installation → Project build: builds app (evidence: `README.md`)
- App installation → Device bridge: installs in running OS (evidence: `crates/kode-sim/src/install.rs`)
- Scenario review → Project build: can build project (evidence: `README.md`)
- Scenario review → Device bridge: runs headless scenario (evidence: `crates/kode-sim/src/review.rs`)
- ESP emulator → Co-simulation client: connects chip bus (evidence: `README.md`)
- ESP emulator → Board chip models: answers virtual parts (evidence: `crates/kode-sim/src/emu.rs`)
- Board chip models → I2C chip behavior: models board chips (evidence: `README.md`)
- Device bridge → ESP emulator: starts and controls (evidence: `crates/kode-sim/src/bridge.rs`)
- Device bridge → Kemu protocol: decodes device frames (evidence: `crates/kode-sim/src/bridge.rs`)
- Device bridge → Console serial: reads console (evidence: `crates/kode-sim/src/bridge.rs`)
- Device bridge → USB host computer: starts USB host (evidence: `crates/kode-sim/src/bridge.rs`)
- Device bridge → Card image: reads card sectors (evidence: `crates/kode-sim/src/bridge.rs`)
- Device bridge → Audio I/O: handles sound
- Firmware link → Kemu protocol: shares frame format (evidence: `firmware/kemu/include/kemu_link.h`)
- Firmware link → Display stand-in: carries display frames (evidence: `firmware/kemu/src/kemu_panel.c`)
- Firmware link → MicroSD stand-in: carries card requests (evidence: `firmware/kemu/src/kemu_sd.c`)
- Firmware link → USB device model: carries USB traffic
- Web server → Device bridge: routes page messages (evidence: `crates/kode-sim/src/web.rs`)
- Simulator window → Web server: opens served page (evidence: `README.md`)
- Device controls → Web server: sends controls
- USB host computer → USB device model: talks to device (evidence: `crates/kode-sim/src/usbhost.rs`)
- MicroSD stand-in → Card image: uses card image
