Deployment model · one service, end to end

Draft: not yet agreed. Nothing here is settled until you answer the open points.

Example: service tin on platform nitroso · Bun API + worker · Postgres + queue

The service repo, file by file

You write the code, config, problem and signal files, and chart values. Tools make the rest: cyanprint (template files), problemgen, obs gen, releaser, nix and bun.

  • From template = cyanprint renders it; a template update changes it. Do not edit by hand.
  • Generated = a tool writes it. Some are committed and checked for drift in CI; some are build output and never committed.
  • Vendored = copied in from a package (agent skills).

Tree = the design for nitroso.tin, using the real folder names from the bun-consumer branch where they exist. Where the branch and the papers differ, the tag says so.

Not in a generated repo: probes/ and .github/named-checks/ (factory only). No paper says which step strips them. OPEN · T3

The service repo nitroso.tin. Tap a line for “made by” and “used by”.
  • HAND-WRITTEN 26
  • GENERATED 17
  • FROM TEMPLATE 36
  • VENDORED 1
  • GENERATED.cyan_state.yaml

    Made by: cyanprint, when the repo is created; again on each template update

    Used by: cyanprint update (records your template answers)

    DECIDED · R4 never hand-edit PAPERS SILENT · who runs updates

  • FROM TEMPLATE.github/

    Made by: cyanprint (workspace + bun-base + bun-consumer layers)

    Used by: GitHub Actions

    • FROM TEMPLATEworkflows/ci.yaml

      Made by: cyanprint

      Used by: every push and PR: pre-commit, unit, int, build, docker, helm, sit

      BUILT · workspace, bun-consumer

    • FROM TEMPLATEworkflows/release.yaml

      Made by: cyanprint

      Used by: after green CI on main: releaser picks the version and tags v1.4.3

      DECIDED · R10; releaser.md BUILT

    • FROM TEMPLATEworkflows/cd.yaml

      Made by: cyanprint

      Used by: on the tag: release note, image, app chart (primordial chart missing)

      BUILT · bun-consumer cd.yaml CONTRADICTION · P1

    • FROM TEMPLATEworkflows/⚡reusable-*.yaml

      Made by: cyanprint

      Used by: called by ci, cd, release (precommit, test, build, docker, helm, sit, release, release-note)

      BUILT CONTRADICTION · release-note missing on bun-consumer

    • FROM TEMPLATEdependabot.yml · actionlint.yaml · action-majors.yaml

      Made by: cyanprint

      Used by: weekly bumps; workflow lint; trusted action majors

      BUILT · workspace

  • FROM TEMPLATE.claude/

    Made by: cyanprint + skills-sync

    Used by: coding agents

    • FROM TEMPLATEskills/<topic>/SKILL.md

      Made by: cyanprint (each layer adds its own)

      Used by: agents

      DECIDED · R15 BUILT

    • VENDOREDskills/vendor/<package>/

      Made by: skills-sync, copied from node_modules/@atomicloud/diene.*/skills

      Used by: agents; checked at setup, pre-commit and CI

      DECIDED · skills-sync ruling; A125 BUILT

  • HAND-WRITTENCLAUDE.md · README.md

    Made by: cyanprint first, then you

    Used by: people and agents

    BUILT

  • FROM TEMPLATEflake.nix

    Made by: cyanprint (nix root + workspace)

    Used by: nix develop shells for dev, ci, cd, releaser

    DECIDED · workspace BUILT

  • GENERATEDflake.lock

    Made by: nix (nix flake update)

    Used by: every CI job's tool versions

    BUILT

  • FROM TEMPLATEnix/

    Made by: cyanprint; each layer appends, never rewrites

    Used by: dev shell, pre-commit hooks, CI shells

    • FROM TEMPLATEpackages.nix · shells.nix · env.nix · fmt.nix · pre-commit.nix

      Made by: cyanprint

      Used by: the dev shell and the git hooks

      BUILT · workspace:nix/*

  • GENERATED.pre-commit-config.yaml

    Made by: nix shell hook (not committed)

    Used by: git hooks: lint, types, helm check, secret scan, commit lint

    BUILT · gitignored

  • FROM TEMPLATE.envrc

    Made by: cyanprint

    Used by: direnv loads the nix shell

    BUILT

  • FROM TEMPLATETaskfile.yaml · tasks/

    Made by: cyanprint

    Used by: people: task setup / lint / build / test / dev / up

    DECIDED · R7 BUILT

  • FROM TEMPLATEscripts/

    Made by: cyanprint

    Used by: one script per CI job; local helpers for Taskfile

    • FROM TEMPLATEci/*.sh

      Made by: cyanprint

      Used by: CI jobs (pre-commit, docker, helm, release, test, build, sit)

      DECIDED · R5, R6 BUILT CONTRADICTION · compile.sh calls a missing setup.sh

    • FROM TEMPLATElocal/*.sh · local/docker-compose.yaml

      Made by: cyanprint

      Used by: task up: local Postgres, Redis, MinIO and telemetry

      BUILT · bun-consumer

  • FROM TEMPLATErelease.yaml

    Made by: cyanprint

    Used by: releaser: version from commit messages, changelog, tag

    DECIDED · R10 BUILT

  • GENERATEDChangelog.md

    Made by: releaser, on every release

    Used by: people

    DECIDED · never hand-edit BUILT

  • FROM TEMPLATEdocs/

    Made by: cyanprint

    Used by: people and agents

    • FROM TEMPLATEstandards/<topic>/index.md

      Made by: cyanprint (workspace, shared, observability, bun-base)

      Used by: the binding rules for the repo

      DECIDED · shared.md BUILT

    • GENERATEDdeveloper/CommitConventions.md

      Made by: releaser, from release.yaml

      Used by: people writing commits

      DECIDED · DP9 BUILT

  • FROM TEMPLATEchart-checks.yaml

    Made by: cyanprint

    Used by: pins the policy repo (stand-in) by commit for chart-checks

    DECIDED · OD D52, D75 BUILT · workspace CONTRADICTION · not yet on bun-consumer

  • GENERATED.chart-checks/

    Made by: chart-checks install downloads the pinned policies (not committed)

    Used by: chart-checks check in pre-commit and CI

    DECIDED · chart-checks.md

  • FROM TEMPLATEskills-sync.yaml · dlint.yaml · biome.json · tsconfig.json · knip*.json · bunfig.*.toml

    Made by: cyanprint (workspace + bun-base)

    Used by: lint, types, dead code, test tiers

    BUILT · bun-base

  • HAND-WRITTENpackage.json

    Made by: cyanprint first, then you (dependencies)

    Used by: bun; the version field is stamped by releaser

    BUILT

  • GENERATEDbun.lock

    Made by: bun install

    Used by: frozen installs in Docker and CI

    BUILT

  • HAND-WRITTENsrc/

    Made by: cyanprint sample, then you

    Used by: the image

    • HAND-WRITTENindex.ts

      Made by: cyanprint sample, then you

      Used by: the image entry: api, worker, db-init, health commands

      BUILT · bun-consumer: worker, db-init, health OPEN · T1 no api command in any template

    • HAND-WRITTENapi/ (HTTP routes)

      Made by: you

      Used by: the api command

      OPEN · T1 no Bun API template PoC TESTED · PoC src/index.ts

    • HAND-WRITTENworker/consumer.ts

      Made by: cyanprint sample, then you

      Used by: the worker command: reads the queue (Redis streams)

      DECIDED · bun-consumer.md BUILT

    • HAND-WRITTENdomain/ · adapters/ · init/

      Made by: cyanprint sample (fenced), then you

      Used by: business logic, database and queue access, db-init

      BUILT

    • HAND-WRITTENconfig/schema.ts

      Made by: cyanprint sample, then you

      Used by: the config loader; source for the config JSON schema

      BUILT

    • GENERATED<api package>/problems (typed code)

      Made by: problemgen generate, committed, drift checked in CI

      Used by: your API code returns these Problems

      DECIDED · problemgen.md; OD D62, D63 OPEN · tool PR 104 open; not on any branch

    • GENERATEDgenerated/ (signal types)

      Made by: obs gen, committed, drift checked in CI

      Used by: one typed call per metric, log and span

      DECIDED · observability §3.4 OPEN · X8 obs not built

  • HAND-WRITTENproblems/

    Made by: you

    Used by: problemgen

    • HAND-WRITTENapi.v1.problems.yaml

      Made by: you: every error the API can return, as a Problem

      Used by: problemgen → typed code + Problem record

      DECIDED · OD D62, D66, D102 CONTRADICTION · X5 built keeps a list in src/domain/problems.ts

  • HAND-WRITTENproblemgen.yaml

    Made by: cyanprint fills platform and service; you set output paths

    Used by: problemgen

    DECIDED · problemgen.md

  • HAND-WRITTEN<signal contract file>

    Made by: you: metrics, log events, spans with bounded labels

    Used by: obs gen, obs check, obs alerts in CI

    DECIDED · observability §3 PAPERS SILENT · name and path

  • HAND-WRITTENconfig/

    Made by: you

    Used by: copied into the app chart at build → ConfigMap

    • HAND-WRITTENsettings.yaml

      Made by: cyanprint sample, then you: full defaults

      Used by: the app loader, base layer

      BUILT · bun-consumer

    • HAND-WRITTENpichu.settings.yaml (one per landscape)

      Made by: you: only what differs; must set errorPortal.url

      Used by: the app loader, landscape layer

      DECIDED · OD D102 CONTRADICTION · S2 papers also say config/pichu.yaml

    • HAND-WRITTENdev.yaml

      Made by: you

      Used by: local scripts

      BUILT

  • GENERATEDschemas/tin.schema.json

    Made by: schema-gen from src/config/schema.ts, committed

    Used by: editors; a pre-commit hook fails on drift

    BUILT · bun-consumer

  • HAND-WRITTENmigrations/pg/001_init.sql · seed/

    Made by: you

    Used by: baked into the image → db-init Job

    DECIDED · R20 BUILT

  • HAND-WRITTENobservability/

    Made by: you (from template stubs)

    Used by: copied into the primordial chart → Grafana objects on Primordial

    • HAND-WRITTENSIGNALS.md

      Made by: you

      Used by: the signal decision record

      DECIDED · observability-block.md

    • HAND-WRITTENdashboards/ · alerts/<slug>/<severity>.yaml · runbook.md

      Made by: you

      Used by: GrafanaDashboard, GrafanaAlertRuleGroup

      DECIDED · observability-block.md BUILT · stubs only

  • HAND-WRITTENe2e/profile-scenarios/

    Made by: you

    Used by: the profile benchmark in CI

    DECIDED · observability §11.5 OPEN · not built

  • GENERATEDe2e/profile-baseline/<svc>.<scenario>.json

    Made by: obs profile baseline --update, committed by PR

    Used by: obs profile compare in CI

    DECIDED · observability §11.5 OPEN · not built

  • HAND-WRITTENtests/

    Made by: cyanprint samples, then you

    Used by: unit, integration and SIT tiers

    BUILT

  • FROM TEMPLATEinfra/

    Made by: cyanprint

    Used by: CI/CD packaging

    • FROM TEMPLATEDockerfile

      Made by: cyanprint (workspace stub → bun-base → bun-consumer)

      Used by: the image build

      BUILT · oven/bun:1.3.13-alpine CONTRADICTION · observability standard wants glibc ≥1.4 + --compile

    • FROM TEMPLATEroot_chart/ (the app chart)

      Made by: cyanprint

      Used by: published as the app chart → every cluster

      DECIDED · R20 BUILT · bun-consumer; workspace

      • FROM TEMPLATEChart.yaml

        Made by: cyanprint; version set by CD

        Used by: helm package

        BUILT

      • FROM TEMPLATEtemplates/deployment.yaml

        Made by: cyanprint

        Used by: Deployments tin-api, tin-worker, with LPSM labels and the reload label

        DECIDED · OD D59 BUILT · workspace reload helper; bun-consumer worker

      • FROM TEMPLATEtemplates/service.yaml · httproute.yaml

        Made by: cyanprint (API template — none exists yet)

        Used by: Service + HTTPRoute for tin-api

        DECIDED · R20 OPEN · T1, K5

      • FROM TEMPLATEtemplates/configmap.yaml

        Made by: cyanprint

        Used by: ConfigMap tin-config from files/config/

        BUILT

      • FROM TEMPLATEtemplates/externalsecret.yaml

        Made by: cyanprint

        Used by: ExternalSecret → Secret tin

        BUILT CONTRADICTION · S3, S4

      • FROM TEMPLATEtemplates/dbinit-job.yaml

        Made by: cyanprint

        Used by: the db-init hook Job

        BUILT

      • FROM TEMPLATEtemplates/_helpers.tpl

        Made by: cyanprint

        Used by: names, labels, reload annotations

        BUILT · workspace root.reload.*

      • HAND-WRITTENvalues.yaml

        Made by: cyanprint sample, then you

        Used by: chart defaults (replicas, ports, reload: restart)

        BUILT

      • HAND-WRITTENvalues.<landscape>.yaml

        Made by: you

        Used by: per-landscape chart values

        DECIDED · HW CONTRADICTION · P6 PoC uses landscapes/<l>.yaml

      • GENERATEDfiles/config/

        Made by: build step copies config/ in (not committed)

        Used by: the ConfigMap

        DECIDED · HW; R20 CONTRADICTION · S1 CI has no copy step

      • GENERATEDvalues.schema.json

        Made by: helm-schema hook

        Used by: helm validation

        DECIDED · HW CONTRADICTION · no generator hook on bun-consumer

      • GENERATEDREADME.md

        Made by: helm-docs from README.md.gotmpl

        Used by: people

        BUILT

    • FROM TEMPLATEprimordial_chart/ (records)

      Made by: cyanprint

      Used by: published as the primordial chart → Primordial

      DECIDED · R20 BUILT · bun-consumer

      • FROM TEMPLATEChart.yaml

        Made by: cyanprint; version set by CD

        Used by: helm package

        BUILT

      • FROM TEMPLATEtemplates/database.yaml · keyvalue.yaml

        Made by: cyanprint

        Used by: Database tin, KeyValue tin records

        DECIDED · OD D4 CONTRADICTION · X1 built: one platformdependency.yaml

      • GENERATEDtemplates/problems/*.yaml

        Made by: problemgen generate, committed

        Used by: Problem tin.api.<landscape>.v1 records

        DECIDED · problemgen.md CONTRADICTION · X5 built: files/problems.json

      • FROM TEMPLATEtemplates/grafana-{folder,dashboards,alerts}.yaml

        Made by: cyanprint

        Used by: Grafana objects on Primordial

        BUILT

      • FROM TEMPLATEtemplates/logto.yaml

        Made by: cyanprint (off unless the API checks tokens)

        Used by: LogtoResource / LogtoApp

        DECIDED · logto-operator.md BUILT · logtoapp.yaml

      • HAND-WRITTENvalues.yaml

        Made by: you: database and queue modules

        Used by: the records' spec

        DECIDED · OD D4 PoC TESTED · PoC infra/primordial/values.yaml

      • HAND-WRITTENvalues.<landscape>.yaml

        Made by: you: provider per landscape (Neon in pichu, PlanetScale in raichu…)

        Used by: per-landscape records

        PoC TESTED · PoC landscapes/raichu.yaml OPEN · G-P7 where per-landscape settings live

      • GENERATEDfiles/observability/

        Made by: build step copies observability/ in (not committed)

        Used by: Grafana templates

        BUILT · gitignored CONTRADICTION · copy step not in CI

  • GENERATEDdist/ · node_modules/ · coverage/

    Made by: bun build, bun install, tests (not committed)

    Used by: image build, local runs

    BUILT · gitignored

All pages

  1. 1The picturerepos → published → cluster
  2. 2The file treewhat you write vs what is made
  3. 3In the clusterobjects, namespaces, landscapes
  4. 4A change travelscode, config, secret, chart…
  5. 5Open pointswhat you settle next