/

Ambitwin · source-available, not open source · © 2026 Nicolò Ghignatti

Toolchain Overview

Keywords on this page
WordMeaningExample
ToolchainEvery program used to build, check, ship and run Ambitwinmise, moon, cargo, docker
PinOne exact version written in a file, so every machine uses the samerust = "1.99.1"
RecipeA named command in a just filejust test affected
TaskA named job of one project, run by moontelemetry:test
ProjectOne package moon knows aboutbackend/telemetry
AffectedA project or task whose input files changedEditing src/main.rs affects telemetry:test
Cache hitA task whose inputs did not change, so its old result is replayed8 ms instead of 6 s
ImageA packed, runnable copy of one serviceghcr.io/nickghignatti/ambitwin-telemetry:latest
RegistryWhere images are stored and pulled fromGitHub Container Registry, ghcr.io
ClusterMachines that run the images, managed by KubernetesLocal k3d cluster ambitwin

The path a change takes, from the editor to a running cluster, and the tool that owns each step. Each tool has one job; this page shows how they connect. The three build tools share one page: Build System.


The map

LayerToolJobConfigPage
Buildmise, moon, justPins the versions, runs the per-project tasks with caching, and gives the commands a person types.mise.toml, .moon/, JustfileBuild System
Dependenciesnpm, uv, cargo, goInstall and lock each language’s librarieslockfilesDependencies
Checksclippy, gofmt, go vet, eslint, ruff, pyrightStyle and mistakesper projectLinting
Testscargo test, go test, vitest, pytest, PlaywrightProve the code worksper projectTesting
ImagesdockerPacks each serviceeach Dockerfile, docker/rust-base/Docker
Local stackdocker composeRuns every service together on one machinedocker-compose.yml filesCompose
GateGitHub ActionsRuns the checks on every pull request.github/workflows/, .github/services.jsonCI
Versions of the productrelease-pleaseTurns commit messages into releases and changelogsrelease-please-config.jsonRelease Please
Clusterk3d, kubectl, istioctlRuns the images with Istio in frontk8s/Kubernetes
DocsQuarkdownBuilds this sitedocumentation/just docs build
flowchart LR
    P["person"] --> J["just"]
    J --> M["mise exec"]
    M --> Mo["moon"]
    Mo --> L["cargo, go, npm, uv"]
    J --> D["docker compose"]
    J --> K["kubectl, k3d"]
    J --> Q["quarkdown"]
    G["GitHub Actions"] --> L
    G --> R["ghcr.io"]
    R --> K

just is the only door for a person. GitHub Actions calls the language tools directly, without moon, but reads the same pins.


A change from editor to cluster

Example. A developer fixes a bug in backend/telemetry/src/kernel/ingest.rs and wants it running in the local cluster.

sequenceDiagram
    autonumber
    participant Dev as Developer
    participant J as just
    participant Mi as mise
    participant Mo as moon
    participant C as cargo
    participant GH as GitHub Actions
    participant RP as release-please
    participant Reg as ghcr.io
    participant K as k3d cluster
    Dev->>J: just lint affected
    J->>Mi: mise exec -- moon run :lint --affected
    Mi->>Mo: moon with pinned tools on PATH
    Mo->>Mo: changed files: ingest.rs, so telemetry is affected
    Mo->>C: cargo clippy -- -D warnings, in backend/telemetry
    Dev->>J: just test affected
    J->>Mi: mise exec -- moon run :test --affected
    Mo->>C: cargo test --lib --test architecture
    Dev->>GH: push branch, open pull request to master
    GH->>GH: ci-gate: which services changed?
    GH->>C: fmt, clippy, audit, tests, release build for telemetry
    GH->>GH: build the telemetry image, scan it
    Dev->>GH: merge into master
    GH->>RP: cd-release: read commit messages
    RP-->>GH: open or update the release pull request
    GH->>Reg: cd-registry: build and push ambitwin-telemetry, tags latest and commit hash
    Dev->>J: just k8s restart telemetry
    J->>K: kubectl rollout restart deployment/telemetry
    K->>Reg: pull ambitwin-telemetry:latest
    K-->>Dev: new pods running

What happens at each step

StepWhoWhat happens
1justFinds recipe affected in just/lint.just. It first runs recipe workflows, which checks .github/workflows/ against .github/services.json
2miseReads .mise.toml, puts Rust 1.99.1, Go 1.27.3, Node 24, Python 3.14.8, uv 0.13.5 and moon 2.6.4 first on PATH
3moonStarts with the pinned tools for itself and every child it starts
4moonAsks git for changed files, matches them against each task’s inputs
5cargoLints only telemetry. A warning fails the run
6–8moon, cargoSame for tests. telemetry:test runs unit tests plus tests/architecture.rs, never the database tests
9DeveloperOpens a pull request to master
10ci-gate.ymlWorks out the changed services from paths, using .github/services.json
11tpl-rust-ci.ymlReads the Rust pin from .mise.toml, then runs the checks for that service only
12ci-gate.ymlBuilds the service image to prove the Dockerfile still works
13DeveloperMerges
14–15cd-release.ymlrelease-please reads fix(telemetry): … and prepares the next version
16cd-registry.ymlBuilds every changed service’s image and pushes it to ghcr.io
17–19just, kubectlA restart makes the pods pull :latest again
20ClusterThe fix runs

Why each tool

ToolReplacesWhy
misenvm, rustup defaults, pyenv, a global uvOne file pins every language. A tool found on the machine’s own PATH can be a different version
moonHand-written loops over foldersKnows every project, runs only what changed, replays unchanged results
justLong commands kept in people’s heads, a MakefileNamed recipes, just --list shows them all, works the same for every language
GitHub ActionsRunning checks by hand before a mergeEvery pull request is checked the same way, on a clean machine
release-pleaseWriting version numbers and changelogs by handVersions follow the commit messages
docker composeStarting a dozen services by handOne command starts the whole stack
k3d + IstioA cloud cluster for testingA real Kubernetes with the production mesh, on one laptop

Rules for every change

A change that breaks one is rejected, even with CI green. The rules for the structure itself are in Architecture Overview.

RuleWhat it meansWhy
Tools only through mise and justjust <recipe> or mise exec -- <tool>, never a tool found on the machine’s PATHAnother version gives other lint and test results
Test what changesRust: #[cfg(test)] and tests/. Go: *_test.go. Python: tests/. Frontend: src/utils/** with *.spec.ts beside the fileBehaviour with no test can break unseen
Frontend unit tests cover pure logic onlyScreens are covered by frontend/e2e/ (Playwright) and backend/acceptance/A component test checks markup, not behaviour
Docs change in the same commit as the codeThe matching documentation/**.qd page moves with the codeDocs fixed later are never fixed
Conventional Commitsfeat(twin): …, scopes in Namingrelease-please reads the type; a bad message is silently “no release”
New package registered once.moon/workspace.yml and .github/services.jsonmoon and CI see only what is listed

From branch to merge

flowchart LR
    A["branch from master"] --> B["just setup install"]
    B --> C["code, with just stack dev"]
    C --> D["just lint fix"]
    D --> E["just test affected"]
    E --> F["just setup deps-check, just setup audit"]
    F --> G["conventional commit"]
    G --> H["pull request"]
    H --> I["ci-gate / ci-passed"]
    I --> J["merge"]
StepCommandWhat it catchesCI counterpart
1just lint affectedStyle and mistakes in changed projectslint step of each language leg. Rust in CI also runs cargo fmt --check and --all-targets
2just test affectedBroken behaviour in changed projectstest step of each language leg
3just setup deps-checkLockfile out of step with its manifestinstall step of each leg (npm ci, uv sync --locked)
4just setup auditKnown security holes, npm, uv and cargo onlyaudit steps and dependency-review
5just test allEverything, before opening the pull requestevery leg

The only required check on a pull request is ci-gate / ci-passed. Details: GitHub Actions CI.


I want to …

I want toCommandTool behind it
Install every tool and libraryjust setup installmise install, then moon run :deps
Start from clean lockfilesjust setup clean-installmoon run :relock, then :deps
Check lockfiles match their manifestsjust setup deps-checkmoon run :deps :deps-check
Check for known security holesjust setup auditmoon run :audit
Create the local .envjust stack envscripts/env/*.sh
Run everything locallyjust stack devscripts/compose/compose-run.py, docker compose up --watch
Run without the assistantjust stack dev --no-agentsame
Stop everythingjust stack downdocker compose down --remove-orphans
Follow one service’s logsjust stack logs telemetrydocker compose logs -f
Lint what changedjust lint affectedmoon run :lint --affected
Fix lint findingsjust lint fixmoon run :lint-fix
Test what changedjust test affectedmoon run :test --affected
Test one servicejust test telemetrymoon run telemetry:test
Test one service against real databasesjust test telemetry-integrationmoon run telemetry:test-integration
Run the cross-service suitejust test integrationbackend/acceptance/run-integration-tests.sh
Empty the local databasesjust db cleardocker compose exec … mongosh, psql
Build the docsjust docs buildQuarkdown
Create the local clusterjust k8s setupk3d, kubectl, istioctl
Ship a new image to the clusterjust k8s restart telemetrykubectl rollout restart
See every recipejustjust --list

Where each fact lives

Each fact has one home. A second copy would drift.

FactHomeRead by
Tool versions.mise.tomlmise; CI’s setup-rust and setup-go; docs.just; cd-registry.yml for the Rust base image
Which projects exist.moon/workspace.ymlmoon
How a language is built, tested, linted.moon/tasks/<language>.ymlmoon
Which services exist, their image, their databases.github/services.jsonevery CI workflow, scripts/check-workflow-registry.py
Commands a person typesJustfile, just/*.justjust

Two pins live outside the mise file

CI’s setup-node asks for Node 24.x, and setup-python reads .python-version (3.14). Both agree with .mise.toml today, but nothing checks it. just itself is not pinned: CI installs 1.42.4.


Naming

A name says what a thing is, so a reader can guess its role without opening it. Linters check the code style of each language; review checks everything else on this page.

Services

A service has one short name, the same on every surface, with no -service suffix.

SurfaceExample
Directorybackend/telemetry, backend/digital-twin
Cargo crate, Go module, binarytelemetry, digital-twin
moon projecttelemetry, digital-twin
Compose service, hostnametelemetry:3000, digital-twin:3000
Environment variableTELEMETRY_URL, DIGITAL_TWIN_URL
Docker imageambitwin-telemetry
Kubernetes manifestk8s/deployments/telemetry.yml
Doc pagedocumentation/docs/services/telemetry.qd

Known exceptions

NameWhereShort form used
digital-twin.github/services.json key, Docker image, commit scopetwin, ambitwin-twin
sensor-simulatorDocker imageambitwin-simulator
claims-gatewaycommit scopegateway

Top-level folders

The folder says what kind of thing it holds.

PathHolds
backend/<name>/A deployable service
backend/libs/Go modules built into services, never deployed
backend/acceptance/The cross-service acceptance suite. Each service keeps its own tests/
schemas/Every shape that crosses a service boundary: json/ schemas, fixtures/, Rust crates *-schema
simulators/Fake sensors and routers for local runs
tooling/Shared tool config, like eslint-config

Rust

The six Rust services and the four *-schema crates follow standard Rust style, checked by clippy.

ThingStyleExample
Module, filesnake_caseredis_fanout.rs, alert_listener.rs
Functionsnake_casefiltered_channel, resolve_channel
Type, traitPascalCaseTelemetryEnvelope, AlertEvent
ConstantSCREAMING_SNAKE_CASERAW_CHANNEL, ALERTS_TOPIC
Schema crate<area>-schema, used as <area>_schematelemetry-schema, telemetry_schema::AlertEvent

Folder names inside a service follow its layering:

ServiceFolders
telemetrytypes/, kernel/, plugins/, adapters/
digital-twin, notification, chatdomain/, service/, adapters/driving/, adapters/driven/
socketcore/, shell/
dashboardflat: api/, infra/, tunnel.rs

Go

claims-gateway, tenancy, registry, provisioner and the three backend/libs/ modules follow standard Go style, checked by gofmt and go vet.

ThingStyleExample
Package, folderone lowercase word, no underscorestenancyclient, storefake, oidcverifier
Exported namePascalCaseRequireSignature, Config
Unexported namecamelCaseroleIn, handler
ConstantPascalCase or camelCase, by visibilitynever SCREAMING_SNAKE_CASE

Layout:

PathHolds
cmd/<svc>/main.goWiring only
internal/apiHTTP handlers
internal/serviceThe rules
internal/store, internal/storefakePostgres, and its in-memory stand-in for tests
internal/<other>clientA client for another service, like tenancyclient
internal/configEnvironment variables

Python

agent, aq-simulator, ap-simulator and backend/acceptance follow PEP 8, checked by ruff.

ThingStyleExample
Module, function, variablesnake_casecedar_authz.py, can_ingest_documents
ClassPascalCaseAuthUser
ConstantSCREAMING_SNAKE_CASEROLE_WEIGHTS
Agent tool namesnake_case, verb firstsearch_docs, get_latest_sensor_data

TypeScript

Frontend, Vue 3

ThingStyleExampleAvoid
ComponentPascalCase, two words or moreChatBubble.vue, NotificationMenu.vuecard.vue
Component folderfeature, then rolecomponents/commons/forms/TextInput.vue
View, a page with a routePascalCase + ViewDashboardView.vue, DomainsView.vueDashboard.vue
Folder under views/, components/, composables/, utils/, stores/, types/kebab-case, one per featuredigital-twin/, administration/grouping by widget kind, like modals/
Shared piecescommons/ inside each of those folderscomposables/commons/useApi.ts
ComposablecamelCase, starts with useuseAuth.ts, useSessionKeepAlive.tsgetAuth.ts
Pinia storefile camelCase, export use<Name>Storestores/digital-twin/buildings.ts, useBuildingsStore
HelpercamelCaseutils/commons/telemetry.tsTelemetry.ts
Unit testbeside the file, .spec.tstelemetry.spec.ts

sensor-simulator, Node

PathHolds
src/index.tsStart-up
src/router.tsRoutes
src/controller/HTTP handlers, like simController.ts
src/services/The simulation, like simulatorService.ts
src/models/Shapes, like signal.ts

Messages

ThingStyleExampleRule
Kafka topickebab-case, what happenedbuilding-registration-requested, alertsDeclared once, in a schemas/*-schema crate
Dead-letter topictopic + .dlqalerts.dlq
Kafka consumer groupwhat it reads, not who readsalerts, building-registrations, wifi-observationsSee “Renaming carries data”
Redis channelarea:kind[:id]telemetry:raw, telemetry:filtered:b1Built only by *-schema functions
Socket.IO roombuilding:<id>, domain:<name>building:b1Built only in socket/src/core/rooms.rs
Cedar actionPascalCase verbRead, Edit, IngestDocumentsDeclared in backend/libs/auth-policy
System identitysystem:<name>system:notification-serviceNever renamed: pinned by a test

Branches

<type>/<short-kebab-description>, using the commit types.

TypeExample
featfeat/private-domains
fixfix/jwt-expiry-off-by-one
chorechore/bump-dependencies
docsdocs/reshaping
refactorrefactor/extract-token-service

Commit scopes

The scope is the service or area, so history can be filtered by part:

gateway, tenancy, registry, provisioner, twin, telemetry, dashboard, notification, socket, chat, frontend, agent, ci, docs, k8s.

feat(twin): add per-room colour overrides
fix(gateway): reject expired refresh tokens

Nothing in CI checks the format. A malformed message is silently treated as “no release”: Release Please.

Other names

ThingStyleExample
Environment variableUPPER_SNAKE_CASEGATEWAY_ISSUER, INTERNAL_SIGNING_SECRET
Variable naming another service<SERVICE>_URLTELEMETRY_URL
Metric source for dashboardanything ending in _METRICS_URLSENSOR_METRICS_URL, TWIN_METRICS_URL
Workflow file<kind>-<name>.yml, kind is ci, cd, maint or tplci-gate.yml, cd-release.yml, tpl-rust-ci.yml
Doc pagekebab-case.qdbuild-system.qd
Fixture, JSON schemakebab-case.json, kebab-case.schema.jsontelemetry-envelope.json

Renaming carries data

Some names own stored state. Changing one starts from empty, with no error.

NameWhat a rename does
Compose volumeCompose builds the real name from the project and the declared name. A new name mounts a new, empty volume and leaves the old one with all the data. Move the data in the same change
Kafka consumer groupA group with no saved position starts from the oldest message: the whole topic is read again. Harmless for registrations. For alerts it sends old breaches again, only held back by the 5-minute cooldown
Database nameA rename is a migration, so names stay: chatdb, twindb, notificationdb
System identitysystem:notification-service keeps its old name: a test pins it byte for byte, and logs keep one stable source

dashboard ignores the database in its URI

Its compose MONGO_URI ends in /contractsdb, but infra/db.rs always opens database ambitwin, collection preferences. The path in the URI changes nothing.

Check for orphans after a rename

docker volume ls lists every volume. One no compose file names is orphaned: move its data or delete it on purpose.