# davidmonterocrespo24/velxio architecture

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

- Interactive diagram: https://gitdiagram.com/davidmonterocrespo24/velxio
- Repository: https://github.com/davidmonterocrespo24/velxio

## Overview

Velxio is a browser-based embedded-board and circuit emulator. The main workflow is to create or load a project, place and wire components, compile firmware, and run it in a board simulator while observing serial and electrical behavior. The frontend owns project/editor state and dispatches among CPU-family runtimes; backend APIs provide compilation and selected emulation services. The README documents additional capabilities such as examples, libraries, custom chips, SPICE, and MCP tools. Some links below rely on README-level workflow documentation because their implementation was not sampled.

Main entry points: [`frontend/src/store/useSimulatorStore.ts`](https://github.com/davidmonterocrespo24/velxio/blob/master/frontend/src/store/useSimulatorStore.ts) (Simulator State), [`frontend/src/pages/EditorPage.tsx`](https://github.com/davidmonterocrespo24/velxio/blob/master/frontend/src/pages/EditorPage.tsx) (Project Editor), [`backend/app/main.py`](https://github.com/davidmonterocrespo24/velxio/blob/master/backend/app/main.py) (Backend API), [`backend/app/api/routes/compile.py`](https://github.com/davidmonterocrespo24/velxio/blob/master/backend/app/api/routes/compile.py) (Compile Routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Project Workspace"]
  node_editor["Project Editor<br/>[EditorPage.tsx]"]
  node_editor_state["Project State<br/>[useProjectStore.ts]"]
  node_sim_state["Simulator State"]
  node_compiler_client["Compile Client<br/>[compilation.ts]"]
end

subgraph group_simulation["Circuit Simulation"]
  node_avr["AVR Runtime<br/>[AVRSimulator.ts]"]
  node_rp2040["RP2040 Runtime<br/>[RP2040Simulator.ts]"]
  node_esp32["ESP32 Runtime<br/>[Esp32Bridge.ts]"]
  node_esp32c3["ESP32-C3 Runtime"]
  node_pi_runtime["Pi Runtime<br/>[PiBridgeShim.ts]"]
  node_pin_manager["Pin Manager<br/>[PinManager.ts]"]
  node_spice["SPICE Circuit Solver"]
  node_custom_chips["Custom Chip Runtime<br/>[ChipRuntime.ts]"]
end

subgraph group_backend["Backend Services"]
  node_backend_api["Backend API<br/>[main.py]"]
  node_compile_api["Compile Routes<br/>[compile.py]"]
  node_arduino_compile["Arduino Compiler<br/>[arduino_cli.py]"]
  node_espidf_compile["ESP-IDF Compiler<br/>[espidf_compiler.py]"]
  node_sim_api["Simulation Routes<br/>[simulation.py]"]
  node_esp_manager["ESP Emulation Manager"]
end

subgraph group_catalog["Learning and Components"]
  node_examples["Project Examples<br/>[examples.ts]"]
  node_component_catalog["Component Catalog"]
  node_library_ui["Library Manager"]
end

subgraph group_integrations["Extensions"]
  node_mcp["MCP Tools<br/>[server.py]"]
  node_gateway["IoT Gateway<br/>[iot_gateway.py]"]
end

node_user(("Engineer"))

node_user -->|"edits projects"| node_editor
node_editor -.->|"updates project"| node_editor_state
node_examples -.->|"loads projects"| node_editor
node_user -->|"selects parts"| node_component_catalog
node_editor -.->|"runs project"| node_sim_state
node_sim_state -->|"dispatches runtime"| node_avr
node_sim_state -->|"dispatches runtime"| node_rp2040
node_sim_state -->|"dispatches runtime"| node_esp32c3
node_sim_state -.->|"dispatches runtime"| node_esp32
node_sim_state -->|"dispatches runtime"| node_pi_runtime
node_sim_state -->|"uses pin state"| node_pin_manager
node_editor -->|"requests compile"| node_compiler_client
node_compiler_client -->|"sends compile request"| node_backend_api
node_backend_api -->|"routes requests"| node_compile_api
node_compile_api -->|"compiles sketches"| node_arduino_compile
node_compile_api -->|"compiles ESP-IDF"| node_espidf_compile
node_backend_api -->|"routes simulation"| node_sim_api
node_sim_api -->|"manages emulation"| node_esp_manager
node_sim_state -.->|"simulates analog circuits"| node_spice
node_user -->|"manages libraries"| node_library_ui
node_library_ui -.->|"requests libraries"| node_backend_api
node_user -->|"creates chips"| node_custom_chips
node_user -->|"uses agent tools"| node_mcp
node_user -.->|"uses device gateway"| node_gateway

click node_editor "https://github.com/davidmonterocrespo24/velxio/blob/master/frontend/src/pages/EditorPage.tsx"
click node_editor_state "https://github.com/davidmonterocrespo24/velxio/blob/master/frontend/src/store/useProjectStore.ts"
click node_sim_state "https://github.com/davidmonterocrespo24/velxio/blob/master/frontend/src/store/useSimulatorStore.ts"
click node_compiler_client "https://github.com/davidmonterocrespo24/velxio/blob/master/frontend/src/services/compilation.ts"
click node_examples "https://github.com/davidmonterocrespo24/velxio/blob/master/frontend/src/data/examples.ts"
click node_component_catalog "https://github.com/davidmonterocrespo24/velxio/blob/master/frontend/src/services/ComponentRegistry.ts"
click node_avr "https://github.com/davidmonterocrespo24/velxio/blob/master/frontend/src/simulation/AVRSimulator.ts"
click node_rp2040 "https://github.com/davidmonterocrespo24/velxio/blob/master/frontend/src/simulation/RP2040Simulator.ts"
click node_esp32 "https://github.com/davidmonterocrespo24/velxio/blob/master/frontend/src/simulation/Esp32Bridge.ts"
click node_esp32c3 "https://github.com/davidmonterocrespo24/velxio/blob/master/frontend/src/simulation/Esp32C3Simulator.ts"
click node_pi_runtime "https://github.com/davidmonterocrespo24/velxio/blob/master/frontend/src/simulation/PiBridgeShim.ts"
click node_pin_manager "https://github.com/davidmonterocrespo24/velxio/blob/master/frontend/src/simulation/PinManager.ts"
click node_spice "https://github.com/davidmonterocrespo24/velxio/blob/master/frontend/src/simulation/spice/CircuitSimulationService.ts"
click node_backend_api "https://github.com/davidmonterocrespo24/velxio/blob/master/backend/app/main.py"
click node_compile_api "https://github.com/davidmonterocrespo24/velxio/blob/master/backend/app/api/routes/compile.py"
click node_arduino_compile "https://github.com/davidmonterocrespo24/velxio/blob/master/backend/app/services/arduino_cli.py"
click node_espidf_compile "https://github.com/davidmonterocrespo24/velxio/blob/master/backend/app/services/espidf_compiler.py"
click node_sim_api "https://github.com/davidmonterocrespo24/velxio/blob/master/backend/app/api/routes/simulation.py"
click node_esp_manager "https://github.com/davidmonterocrespo24/velxio/blob/master/backend/app/services/esp_qemu_manager.py"
click node_library_ui "https://github.com/davidmonterocrespo24/velxio/blob/master/frontend/src/components/simulator/LibraryManagerModal.tsx"
click node_custom_chips "https://github.com/davidmonterocrespo24/velxio/blob/master/frontend/src/simulation/customChips/ChipRuntime.ts"
click node_mcp "https://github.com/davidmonterocrespo24/velxio/blob/master/backend/app/mcp/server.py"
click node_gateway "https://github.com/davidmonterocrespo24/velxio/blob/master/backend/app/api/routes/iot_gateway.py"

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_editor,node_editor_state,node_sim_state,node_compiler_client toneBlue
class node_avr,node_rp2040,node_esp32,node_esp32c3,node_pi_runtime,node_pin_manager,node_spice,node_custom_chips toneAmber
class node_backend_api,node_compile_api,node_arduino_compile,node_espidf_compile,node_sim_api,node_esp_manager toneMint
class node_examples,node_component_catalog,node_library_ui toneRose
class node_mcp,node_gateway,node_user toneIndigo
```

## Components

### Project Workspace

- [Project Editor](https://github.com/davidmonterocrespo24/velxio/blob/master/frontend/src/pages/EditorPage.tsx): `frontend/src/pages/EditorPage.tsx`
- [Project State](https://github.com/davidmonterocrespo24/velxio/blob/master/frontend/src/store/useProjectStore.ts): `frontend/src/store/useProjectStore.ts`
- [Simulator State](https://github.com/davidmonterocrespo24/velxio/blob/master/frontend/src/store/useSimulatorStore.ts): `frontend/src/store/useSimulatorStore.ts`
- [Compile Client](https://github.com/davidmonterocrespo24/velxio/blob/master/frontend/src/services/compilation.ts): `frontend/src/services/compilation.ts`

### Circuit Simulation

- [AVR Runtime](https://github.com/davidmonterocrespo24/velxio/blob/master/frontend/src/simulation/AVRSimulator.ts): `frontend/src/simulation/AVRSimulator.ts`
- [RP2040 Runtime](https://github.com/davidmonterocrespo24/velxio/blob/master/frontend/src/simulation/RP2040Simulator.ts): `frontend/src/simulation/RP2040Simulator.ts`
- [ESP32 Runtime](https://github.com/davidmonterocrespo24/velxio/blob/master/frontend/src/simulation/Esp32Bridge.ts): `frontend/src/simulation/Esp32Bridge.ts`
- [ESP32-C3 Runtime](https://github.com/davidmonterocrespo24/velxio/blob/master/frontend/src/simulation/Esp32C3Simulator.ts): `frontend/src/simulation/Esp32C3Simulator.ts`
- [Pi Runtime](https://github.com/davidmonterocrespo24/velxio/blob/master/frontend/src/simulation/PiBridgeShim.ts): `frontend/src/simulation/PiBridgeShim.ts`
- [Pin Manager](https://github.com/davidmonterocrespo24/velxio/blob/master/frontend/src/simulation/PinManager.ts): `frontend/src/simulation/PinManager.ts`
- [SPICE Circuit Solver](https://github.com/davidmonterocrespo24/velxio/blob/master/frontend/src/simulation/spice/CircuitSimulationService.ts): `frontend/src/simulation/spice/CircuitSimulationService.ts`
- [Custom Chip Runtime](https://github.com/davidmonterocrespo24/velxio/blob/master/frontend/src/simulation/customChips/ChipRuntime.ts): `frontend/src/simulation/customChips/ChipRuntime.ts`

### Backend Services

- [Backend API](https://github.com/davidmonterocrespo24/velxio/blob/master/backend/app/main.py): `backend/app/main.py`
- [Compile Routes](https://github.com/davidmonterocrespo24/velxio/blob/master/backend/app/api/routes/compile.py): `backend/app/api/routes/compile.py`
- [Arduino Compiler](https://github.com/davidmonterocrespo24/velxio/blob/master/backend/app/services/arduino_cli.py): `backend/app/services/arduino_cli.py`
- [ESP-IDF Compiler](https://github.com/davidmonterocrespo24/velxio/blob/master/backend/app/services/espidf_compiler.py): `backend/app/services/espidf_compiler.py`
- [Simulation Routes](https://github.com/davidmonterocrespo24/velxio/blob/master/backend/app/api/routes/simulation.py): `backend/app/api/routes/simulation.py`
- [ESP Emulation Manager](https://github.com/davidmonterocrespo24/velxio/blob/master/backend/app/services/esp_qemu_manager.py): `backend/app/services/esp_qemu_manager.py`

### Learning and Components

- [Project Examples](https://github.com/davidmonterocrespo24/velxio/blob/master/frontend/src/data/examples.ts): `frontend/src/data/examples.ts`
- [Component Catalog](https://github.com/davidmonterocrespo24/velxio/blob/master/frontend/src/services/ComponentRegistry.ts): `frontend/src/services/ComponentRegistry.ts`
- [Library Manager](https://github.com/davidmonterocrespo24/velxio/blob/master/frontend/src/components/simulator/LibraryManagerModal.tsx): `frontend/src/components/simulator/LibraryManagerModal.tsx`

### Extensions

- [MCP Tools](https://github.com/davidmonterocrespo24/velxio/blob/master/backend/app/mcp/server.py): `backend/app/mcp/server.py`
- [IoT Gateway](https://github.com/davidmonterocrespo24/velxio/blob/master/backend/app/api/routes/iot_gateway.py): `backend/app/api/routes/iot_gateway.py`

### Other components

- **Engineer**

## Connections

- Engineer → Project Editor: edits projects (evidence: `README.md`)
- Project Editor → Project State: updates project
- Project Examples → Project Editor: loads projects
- Engineer → Component Catalog: selects parts (evidence: `README.md`)
- Project Editor → Simulator State: runs project
- Simulator State → AVR Runtime: dispatches runtime (evidence: `frontend/src/store/useSimulatorStore.ts`)
- Simulator State → RP2040 Runtime: dispatches runtime (evidence: `frontend/src/store/useSimulatorStore.ts`)
- Simulator State → ESP32-C3 Runtime: dispatches runtime (evidence: `frontend/src/store/useSimulatorStore.ts`)
- Simulator State → ESP32 Runtime: dispatches runtime (evidence: `frontend/src/store/useSimulatorStore.ts`)
- Simulator State → Pi Runtime: dispatches runtime (evidence: `frontend/src/store/useSimulatorStore.ts`)
- Simulator State → Pin Manager: uses pin state (evidence: `frontend/src/store/useSimulatorStore.ts`)
- Project Editor → Compile Client: requests compile (evidence: `README.md`)
- Compile Client → Backend API: sends compile request (evidence: `README.md`)
- Backend API → Compile Routes: routes requests (evidence: `backend/app/main.py`)
- Compile Routes → Arduino Compiler: compiles sketches (evidence: `backend/app/api/routes/compile.py`)
- Compile Routes → ESP-IDF Compiler: compiles ESP-IDF (evidence: `backend/app/api/routes/compile.py`)
- Backend API → Simulation Routes: routes simulation (evidence: `backend/app/main.py`)
- Simulation Routes → ESP Emulation Manager: manages emulation (evidence: `backend/app/api/routes/simulation.py`)
- Simulator State → SPICE Circuit Solver: simulates analog circuits
- Engineer → Library Manager: manages libraries (evidence: `README.md`)
- Library Manager → Backend API: requests libraries
- Engineer → Custom Chip Runtime: creates chips (evidence: `README.md`)
- Engineer → MCP Tools: uses agent tools (evidence: `README.md`)
- Engineer → IoT Gateway: uses device gateway