slimevr/slimevr-firmware-webbuilder

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.