# slimevr/slimevr-firmware-webbuilder architecture

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

- Interactive diagram: https://gitdiagram.com/slimevr/slimevr-firmware-webbuilder
- Repository: https://github.com/slimevr/slimevr-firmware-webbuilder

## Overview

1. **What this repo is**
   - This is a **NestJS backend API** for building **SlimeVR tracker firmware** from configurable inputs such as boards, IMUs, pins, and other firmware options.
   - There is no frontend in this repo; the service is the orchestration layer between HTTP requests, the firmware build toolchain, database state, and artifact storage.

2. **Top-level application boundary**
   - `src/main.ts` is the runtime entrypoint.
   - `src/app.module.ts` wires the application together.
   - `src/instrument.ts` is a separate bootstrap concern, likely for app instrumentation/telemetry, kept outside the business modules so it doesn’t pollute request handling.

3. **HTTP/API layer**
   - `src/app.controller.ts` provides the root controller.
   - `src/firmware/firmware.controller.ts` is the main API surface for firmware-related operations.
   - The controller boundary is where external clients submit build requests, query build state, or retrieve build-related metadata.

4. **Firmware orchestration subsystem**
   - `src/firmware/firmware.module.ts`, `firmware.service.ts`, and `firmware.types.ts` contain the core domain logic.
   - This subsystem is responsible for turning a requested firmware configuration into a concrete build plan, coordinating the build, and returning or persisting the result.
   - The `types.ts` file suggests explicit domain contracts for request/response payloads and build configuration data.

5. **Build engine integration**
   - `src/firmware/platformio.service.ts` isolates integration with **PlatformIO**, which is the actual firmware build toolchain.
   - This is a key architectural boundary: the API layer does not directly build firmware; it delegates to a dedicated service that wraps the external build system.
   - That separation makes it easier to swap build mechanics without changing the public API.

6. **Persistence layer**
   - `src/db.schema.ts` defines the database schema used by the application.
   - `drizzle.config.ts` plus the `drizzle/` directory indicate **Drizzle ORM** with versioned SQL migrations.
   - The database is used for durable state around firmware builds and related metadata rather than for heavy binary storage.

7. **Artifact storage**
   - The repo includes **MinIO** configuration under `docker/minio/`, which means build outputs are stored in object storage rather than directly in the database or local disk.
   - This is the natural place for compiled firmware binaries, archives, or other generated artifacts.
   - MinIO is a major infrastructure boundary in the system: database stores metadata, MinIO stores the actual files.

8. **Configuration and source management**
   - `.env.template` and `src/env.ts` show that runtime configuration is environment-driven.
   - `sources.json` is an important operational input: the README says the container checks it every 5 minutes to add different firmware versions.
   - That means firmware source/version availability is controlled by a file-based config layer, not only by code or DB records.

9. **Deployment/runtime model**
   - `Dockerfile`, `docker-compose.yml`, and `docker-compose.dev.yml` define the containerized runtime.
   - The README explicitly recommends the **dev compose** setup and shows that the service expects **PostgreSQL** plus **MinIO** alongside the API container.
   - This repo is therefore designed as a multi-container backend system, not a standalone binary.

10. **Operational setup**
   - The README’s MinIO access/secret key files under `docker/minio/` are part of the operational contract for bringing the stack up.
   - Migrations are applied separately with `drizzle-kit migrate`, so schema evolution is explicit and controlled.
   - This implies the app startup path is lightweight, while initialization of persistent infrastructure is handled out-of-band.

11. **Tooling and language stack**
   - The codebase is **TypeScript** on **NestJS**.
   - It uses **Drizzle** for schema/migrations, **Docker** for runtime packaging, and **Nix** files (`flake.nix`, `shell.nix`, `flake.lock`) for reproducible developer environments.
   - `nestia.config.ts` suggests additional API typing/codegen support around the NestJS boundary.

12. **Data flow summary**
   - Client sends a firmware build request to the API.
   - The firmware module validates/normalizes the requested configuration and resolves the appropriate source/version.
   - The PlatformIO integration performs the build.
   - Build metadata is persisted in Postgres via Drizzle.
   - Generated firmware artifacts are stored in MinIO and referenced from the database.

13. **How to draw the architecture**
   - Model this as a **single backend service** with three external dependencies: **Postgres**, **MinIO**, and **PlatformIO/build tooling**.
   - Keep the API/controller layer, firmware orchestration layer, build execution layer, and storage layer as distinct boxes.
   - Show `sources.json` and environment config as supporting inputs to the service rather than runtime services themselves.

Main entry points: [`src/firmware/firmware.service.ts`](https://github.com/slimevr/slimevr-firmware-webbuilder/blob/main/src/firmware/firmware.service.ts) (Firmware service), [`docker-compose.dev.yml`](https://github.com/slimevr/slimevr-firmware-webbuilder/blob/main/docker-compose.dev.yml) (Compose stack), [`src/app.module.ts`](https://github.com/slimevr/slimevr-firmware-webbuilder/blob/main/src/app.module.ts) (App module), [`src/firmware/firmware.module.ts`](https://github.com/slimevr/slimevr-firmware-webbuilder/blob/main/src/firmware/firmware.module.ts) (Firmware module)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_service["Backend service"]
  node_main(("Bootstrap<br/>Nest entrypoint<br/>[main.ts]"))
  node_appmodule["App module<br/>Nest composition<br/>[app.module.ts]"]
  node_appcontroller["Root controller<br/>HTTP controller<br/>[app.controller.ts]"]
  node_instrument(("Instrument<br/>telemetry bootstrap<br/>[instrument.ts]"))
  node_firmwarecontroller["Firmware API<br/>HTTP controller"]
  node_firmwaremodule["Firmware module<br/>Nest module<br/>[firmware.module.ts]"]
  node_firmwareservice["Firmware service<br/>orchestrator"]
  node_firmwaretypes["Firmware types<br/>domain contracts<br/>[firmware.types.ts]"]
  node_platformio["PlatformIO<br/>build adapter"]
end

subgraph group_storage["Storage"]
  node_dbschema["DB schema<br/>Drizzle schema<br/>[db.schema.ts]"]
  node_migrations["Migrations<br/>[0000_thick_leo.sql]"]
  node_postgres[("Postgres<br/>metadata store")]
  node_minio[("MinIO<br/>artifact store")]
end

subgraph group_runtime["Runtime"]
  node_env["Env config<br/>runtime config<br/>[env.ts]"]
  node_sources["Sources manifest<br/>source registry<br/>[sources.json]"]
  node_compose["Compose stack<br/>deployment"]
  node_dockerfile["Dockerfile<br/>container build"]
end

node_main -->|"starts"| node_appmodule
node_main -->|"loads"| node_instrument
node_appmodule -->|"registers"| node_appcontroller
node_appmodule -->|"imports"| node_firmwaremodule
node_firmwaremodule -->|"registers"| node_firmwarecontroller
node_firmwaremodule -->|"provides"| node_firmwareservice
node_firmwareservice -->|"uses"| node_firmwaretypes
node_firmwareservice -->|"delegates"| node_platformio
node_firmwareservice -->|"resolves"| node_sources
node_firmwareservice -->|"reads"| node_env
node_firmwareservice -->|"persists via"| node_dbschema
node_dbschema -->|"maps to"| node_postgres
node_migrations -->|"applies to"| node_postgres
node_platformio -->|"writes artifacts"| node_minio
node_firmwarecontroller -->|"calls"| node_firmwareservice
node_compose -->|"includes"| node_postgres
node_compose -->|"includes"| node_minio
node_compose -->|"builds"| node_dockerfile

click node_main "https://github.com/slimevr/slimevr-firmware-webbuilder/blob/main/src/main.ts"
click node_appmodule "https://github.com/slimevr/slimevr-firmware-webbuilder/blob/main/src/app.module.ts"
click node_appcontroller "https://github.com/slimevr/slimevr-firmware-webbuilder/blob/main/src/app.controller.ts"
click node_instrument "https://github.com/slimevr/slimevr-firmware-webbuilder/blob/main/src/instrument.ts"
click node_firmwarecontroller "https://github.com/slimevr/slimevr-firmware-webbuilder/blob/main/src/firmware/firmware.controller.ts"
click node_firmwaremodule "https://github.com/slimevr/slimevr-firmware-webbuilder/blob/main/src/firmware/firmware.module.ts"
click node_firmwareservice "https://github.com/slimevr/slimevr-firmware-webbuilder/blob/main/src/firmware/firmware.service.ts"
click node_firmwaretypes "https://github.com/slimevr/slimevr-firmware-webbuilder/blob/main/src/firmware/firmware.types.ts"
click node_platformio "https://github.com/slimevr/slimevr-firmware-webbuilder/blob/main/src/firmware/platformio.service.ts"
click node_env "https://github.com/slimevr/slimevr-firmware-webbuilder/blob/main/src/env.ts"
click node_sources "https://github.com/slimevr/slimevr-firmware-webbuilder/blob/main/sources.json"
click node_dbschema "https://github.com/slimevr/slimevr-firmware-webbuilder/blob/main/src/db.schema.ts"
click node_migrations "https://github.com/slimevr/slimevr-firmware-webbuilder/blob/main/drizzle/0000_thick_leo.sql"
click node_minio "https://github.com/slimevr/slimevr-firmware-webbuilder/tree/main/docker/minio"
click node_compose "https://github.com/slimevr/slimevr-firmware-webbuilder/blob/main/docker-compose.dev.yml"
click node_dockerfile "https://github.com/slimevr/slimevr-firmware-webbuilder/tree/main/Dockerfile"

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_main,node_appmodule,node_appcontroller,node_instrument,node_firmwarecontroller,node_firmwaremodule,node_firmwareservice,node_firmwaretypes,node_platformio toneBlue
class node_dbschema,node_migrations,node_postgres,node_minio toneAmber
class node_env,node_sources,node_compose,node_dockerfile toneMint
```

## Components

### Backend service

NestJS API and firmware orchestration

- [Bootstrap](https://github.com/slimevr/slimevr-firmware-webbuilder/blob/main/src/main.ts): Nest entrypoint · Starts the API process · `src/main.ts`
- [App module](https://github.com/slimevr/slimevr-firmware-webbuilder/blob/main/src/app.module.ts): Nest composition · Wires controllers and providers · `src/app.module.ts`
- [Root controller](https://github.com/slimevr/slimevr-firmware-webbuilder/blob/main/src/app.controller.ts): HTTP controller · Base API surface · `src/app.controller.ts`
- [Instrument](https://github.com/slimevr/slimevr-firmware-webbuilder/blob/main/src/instrument.ts): telemetry bootstrap · Separate startup instrumentation · `src/instrument.ts`
- [Firmware API](https://github.com/slimevr/slimevr-firmware-webbuilder/blob/main/src/firmware/firmware.controller.ts): HTTP controller · Build and firmware endpoints · `src/firmware/firmware.controller.ts`
- [Firmware module](https://github.com/slimevr/slimevr-firmware-webbuilder/blob/main/src/firmware/firmware.module.ts): Nest module · Domain boundary for firmware flows · `src/firmware/firmware.module.ts`
- [Firmware service](https://github.com/slimevr/slimevr-firmware-webbuilder/blob/main/src/firmware/firmware.service.ts): orchestrator · Resolves configs and coordinates builds · `src/firmware/firmware.service.ts`
- [Firmware types](https://github.com/slimevr/slimevr-firmware-webbuilder/blob/main/src/firmware/firmware.types.ts): domain contracts · Request and build data shapes · `src/firmware/firmware.types.ts`
- [PlatformIO](https://github.com/slimevr/slimevr-firmware-webbuilder/blob/main/src/firmware/platformio.service.ts): build adapter · Wraps external firmware toolchain · `src/firmware/platformio.service.ts`

### Storage

Persistent metadata and artifact storage

- [DB schema](https://github.com/slimevr/slimevr-firmware-webbuilder/blob/main/src/db.schema.ts): Drizzle schema · Tables for build metadata · `src/db.schema.ts`
- [Migrations](https://github.com/slimevr/slimevr-firmware-webbuilder/blob/main/drizzle/0000_thick_leo.sql): Drizzle migrations · Versioned schema changes · `drizzle/0000_thick_leo.sql`
- **Postgres**: metadata store · Durable build state and metadata
- [MinIO](https://github.com/slimevr/slimevr-firmware-webbuilder/tree/main/docker/minio): artifact store · Stores built firmware outputs · `docker/minio`

### Runtime

Container and deployment inputs

- [Env config](https://github.com/slimevr/slimevr-firmware-webbuilder/blob/main/src/env.ts): runtime config · Environment-driven settings · `src/env.ts`
- [Sources manifest](https://github.com/slimevr/slimevr-firmware-webbuilder/blob/main/sources.json): source registry · Firmware versions and source inputs · `sources.json`
- [Compose stack](https://github.com/slimevr/slimevr-firmware-webbuilder/blob/main/docker-compose.dev.yml): deployment · API, Postgres, and MinIO runtime setup · `docker-compose.dev.yml`
- [Dockerfile](https://github.com/slimevr/slimevr-firmware-webbuilder/tree/main/Dockerfile): container build · Container image for the service · `Dockerfile`

## Connections

- Bootstrap → App module: starts · Bootstraps the Nest application
- Bootstrap → Instrument: loads · Initializes instrumentation at startup
- App module → Root controller: registers · Exposes the root controller
- App module → Firmware module: imports · Includes firmware subsystem
- Firmware module → Firmware API: registers · Publishes firmware HTTP endpoints
- Firmware module → Firmware service: provides · Makes orchestration service available
- Firmware service → Firmware types: uses · Shares domain contracts
- Firmware service → PlatformIO: delegates · Hands off actual build execution
- Firmware service → Sources manifest: resolves · Selects firmware source/version inputs
- Firmware service → Env config: reads · Consumes runtime configuration
- Firmware service → DB schema: persists via · Stores build metadata model
- DB schema → Postgres: maps to · Schema is stored in Postgres
- Migrations → Postgres: applies to · Migrates database state
- PlatformIO → MinIO: writes artifacts · Build outputs are stored in object storage
- Firmware API → Firmware service: calls · HTTP requests trigger orchestration
- Compose stack → Postgres: includes · Local stack dependency
- Compose stack → MinIO: includes · Local stack dependency
- Compose stack → Dockerfile: builds · Containerized service runtime