How the whole fleet fits together

One name, eight landscapes, one control plane

Every deployed workload has one four-part name: Landscape · Platform · Service · Module (LPSM).

A landscape fixes how a deployment behaves: its secrets, its data, its lifetime and its network edge. There are eight.

Primordial, the control plane, decides what should run. The serving clusters run it. If Primordial stops, traffic and login keep working; only deploys pause.

Source of truth for every statement here: the diene design corpus (concepts/ARCHITECTURE.md, concepts/environments.md, concepts/secrets-chain.md, and the node goals in goals/), corpus main e0568f0 (2026-11-06). Each section ends with its source files. Orange note pins mark open decisions or details that are not settled.

01Big picture
02LPSM names
038 landscapes
04How each starts
05Planes
06Charts
07Deploy, animated
08Garden in motion
09Forks
10Multi-region
11Runtimes & runners
12How diene is built
13Failure drill
14Glossary

01 · Big picture

Five layers, one direction of control

Git holds every input. Humans edit only fleet/registry/, the <platform>.carbon repo and service repos.
Primordial reads Git and writes desired state into clusters and vendors.
Serving clusters run the real product traffic.
Development instances run copies for developers, tests and previews. They never touch serving data, except castform, which runs on a fork (a copy) of it.
Outside services (DNS, the ledger bucket, data vendors) live outside Primordial so they survive its loss.

landscapes (environment kinds)

serving host landscapes: pichu, pikachu, raichu, ampharos

DNS-only virtual landscapes: mew, celebi

Helm charts per service (the 2-chart law)

diene custom resource types (CRDs)

5 s

health poll that drives all public DNS

Tap any box: what it is, where it runs, which repo owns it

Gitsource of truth · humans edit here

▼ pulled by ArgoCD (SCM discovery of *.carbon) ▼

Control plane · Primordialone permanent cluster · not a serving landscape

▼ renders + syncs app charts, CRs, DNS ▼

Serving plane · registered host landscapesreal data · real users

Development plane · Garden instancesno real data, except castform (fork of real data)

Outside · must survive Primordial lossexternal services

Pick a box above

Each box opens a plain description: what it does, where it runs, and which repo or node owns it.

Sources: ARCHITECTURE.md §1–§3, §8–§9; environments.md §1.

02 · LPSM, the one name

Four slots name every workload

L · Landscape

The environment kind: raichu, lapras, castform…

P · Platform

A product family. Registered by creating its .carbon repo. Example: mercury.

S · Service

One repo, one deployable: .<svc>. Example: argon.zinc.

M · Module

One named piece inside a service: an API, a database (maindb), a cache.

Remember this

Hostnames are the coordinate reversed: module first, landscape last.
Instance is not a fifth slot. It is added only where a physical name must be unique (one developer, one CI run, one preview).
Cleanup never selects by instance. Cleanup uses allocation ID + generation.

Try it: build the names from a coordinate

Module

Service

Platform

Landscape

Instance (Garden only)

Dependency module

Dependency class

m modules servicep platformi instancel landscape

noteOpen on your agenda

Error records (the Problem custom resource) are named {service}.{module}.{landscape}.{version} today, which leaves out platform. A proposal to name them in full LPSM order is waiting on your answer in the error-records agenda item.

Sources: ARCHITECTURE.md §2, §7 (secret address), §9 (external names); goals/instance-segment-naming.md; goals/helm-wrapper.md (fullname rule).

03 · The eight landscapes

A landscape is a rule set, not a place

A landscape fixes four rules: secret class, data posture, lifetime, network edge.
Location is a property of a cluster. Consistency (one dataset) is a property of a landscape.
Six landscapes are Garden workload profiles (development copies). Primordial and serving are not.
A new landscape is a new row of settings, never new machinery.

Pick a landscape

ENTEI is not a ninth landscape

ENTEI is one registered cluster with role anonymous-vcluster-host and traffic: false.
It hosts the eevee and castform virtual clusters (vclusters). It runs no application, no shared Logto and no shared database.
It shares only the public gateway (kgateway), cert-manager, DNS/TLS for hosted names, and the exposure materializer.
If ENTEI dies, eevee and castform go down together. Serving is not affected.

All six Garden profiles side by side build modes · data · secrets · edge

Landscape	Runs on	Build modes	Data	Secrets	Edge
lapras	laptop k3d, kept	sync · build-local · target-pull	local CNPG, Dragonfly, MinIO, Mailpit, local Logto	read-only lapras seed; no writes	Boron direct to approved services
ditto	fresh cluster per test run	build-local · target-pull	deterministic fixtures	read-only ditto seed + demo credentials	loopback-only local kgateway
rotom	laptop k3d, offline, kept	sync only	signed offline bundle only	fake local store; zero keys	loopback-only local kgateway
absol	fresh cluster per run, offline	build-local from bundle	same bundle as rotom	fake local store; zero keys	loopback-only local kgateway
eevee	vcluster on ENTEI, one per person	sync · build-local · target-pull	local dependencies on host volumes	read-only eevee seed	ENTEI shared edge, real HTTPS
castform	vcluster on ENTEI, one per preview	target-pull only	forks of Neon, Upstash, Tigris	read-only castform seed + short-lived doors	ENTEI shared edge

Build modes: sync = hot reload from source; build-local = build the image on this machine; target-pull = pull the exact image CI built (by digest).

Sources: environments.md §1, §1.1, §1.2, §1.3.

04 · How each landscape starts

Three ways in: bootstrap, Git, or `pls`

Bootstrap · primordial

The seed-cluster bootstrap creates Primordial, ArgoCD, Infisical and the fleet root app.
Root of trust: the SOPS root key.
After that, Primordial's own ArgoCD keeps it in line with Git.

Git · serving

New landscape or cluster: one pull request to fleet/registry/.
New platform: create the .carbon repo.
New service: create the .<svc> repo.
Release: Kargo edits one row file per stage.
On/off for traffic: set traffic: true|false on the cluster.

pls · the six Garden profiles

pls env up --profile  starts one.
pls env down --profile  stops it.
pls env doctor checks it without changing anything.
pls is the command-line tool shipped by the garden-k3d-profiles node; it runs Garden.

Pick a landscape: the exact start sequence

Sources: environments.md §1.3, §3; goals/garden-k3d-profiles.md (pls commands); goals/garden-vcluster-profiles.md (eevee, castform); goals/ci-k3d-lanes.md (nsc lanes); ARCHITECTURE.md §10–§11.

05 · Planes

Primordial decides, clusters serve

The rule behind everything

Nothing on a live request path depends on Primordial. Primordial composes desired state. If it is down for hours, deploys pause; traffic, failover and login keep working.

Control plane

Primordial. ArgoCD, Kargo, the operators, Infisical. Outside the landscape registry. Never load-bearing for traffic.

Serving plane

Host-landscape clusters. Each sits behind a cloud load balancer with fixed IPs. TLS ends at the cluster gateway (cert-manager, Let's Encrypt).

Development plane

Garden instances. k3d on laptops, nsc in CI, vclusters on ENTEI. Argo and Kargo never run inside these.

Edge plane

DNS + edge docs. Route 53 is primary, Cloudflare is secondary. The fleet, landscape and catalog docs are published twice: R2 and S3/CloudFront.

Every dependency has three layers

Layer	What it is	Where it lives
Contract	Endpoint, credentials, behaviour. Same for every realization.	the app's config + secret names
Provisioning plane	Creates and resizes the dependency. Never on the traffic path.	Primordial (vendor APIs)
Data plane	The only layer that requests actually traverse.	vendor or in-cluster engine

Delivery: where a dependency is realized

delivery	Meaning	Used for
external	A vendor's data plane, reconciled from Primordial	Neon (Postgres), Upstash (KV), Tigris / R2 / S3 (storage)
replicated	Fanned out to every eligible cluster of the landscape	Dragonfly cache only (one instance per claim)
local	Applied directly inside one Garden instance	CNPG, MinIO, Dragonfly KV + cache, Mailpit

Also called a plane: the execution plane

The execution plane is the machinery that builds diene itself (the ratchet: nodes, rounds, reviews). Its identifiers never appear in shipped docs. See section 12.

Sources: ARCHITECTURE.md §1 (axiom 7), §3, §4, §7 (T4-LAYERS, delivery); environments.md §1.2; rules/AUTHORING-RULES.md (execution plane).

06 · Charts

The 2-chart law, used twice = 4 charts per platform

The 4 chart concept (confirmed 2026-11-07)

The design docs call this the 2-chart law (rule R20). A platform applies it twice: once for its carbon home repo and once per service. That gives the 4 chart kinds below.

1 · Service app chart

Runtime only. Deployment, Service, the database-init hook Job.

Goes to every host cluster of each landscape. One Argo Application per service × landscape × cluster.

2 · Service primordial chart

Custom resources only. PlatformDependency, WebhookRoute, Problem, LogtoApp…

Goes to Primordial. One Application per service × landscape.

3 · Carbon app chart

The platform's namespace + SecretStore.

Goes to each host cluster. Services read secrets through this store.

4 · Carbon primordial chart

Platform-shared CRs: ProviderAccount, shared PlatformDependency, WebhookEngine.

Goes to Primordial. The only render home for platform-shared dependencies.

Plus one fleet chart

diene-platform, the compiler chart, lives in fleet/registry/charts/. Per platform it renders the Platform CR, the Kargo pipelines and the platform ApplicationSet. It is Git-sourced on the moving tag machinery-stable; every other chart is published as OCI.

Try it: how many Argo Applications does one platform make?

Services: 3

Landscapes in platform.yaml: 4

Clusters per landscape: 1

Counts follow ARCHITECTURE.md §8: g1 = one primordial Application per service × landscape; g2 = one app Application per service × landscape × cluster. Carbon is an ordinary chart-only service, so it counts as one more service here.

Try it: promote one release of zinc through the stages

Where config values come from, in order last one wins

values.yaml: the chart's base.
values.<landscape>.yaml: the landscape overlay.
values.<cluster>.yaml: the cluster overlay, usually one identity value.
The row file's optional values: block: a short-lived ops override, folded back into the chart at the next release. A probe flags overrides older than 7 days.

Landscape and cluster are two independent stacked dimensions, never one combined file.

Sources: ARCHITECTURE.md §1 (axiom 5), §8; rules/SAMPLE-CREATING-RULES.md R20; goals/charts/carbon.md; goals/helm-wrapper.md (overlays).

07 · Deploy, animated

Tap a repo, watch its charts land

One release, charts onceA repo publishes its charts once. ArgoCD on Primordial fans them out.

P · primordial chartLands on Primordial, once per landscape.

A · app chartLands on every cluster of every landscape in platform.yaml.

3D view · drag to turn, pinch or scroll to zoom

Loading the 3D view…

Top layer: GitHub repos. Middle: Primordial. Bottom: host clusters (example names) and, to the side, the data vendors. Colours match the 2D pictures: indigo = app chart, pink = primordial chart, orange = Git and Kargo edits, green = controllers.

Tap a repo (in the picture or here)

Landscapes listed in argon.carbon's platform.yaml

0charts shipped

0Primordial Applications

0app Applications (clusters)

Tap argon.carbon to start.

Cluster names (opal, ruby, emerald) are examples. raichu has 2 clusters here to show the per-cluster fan-out.

How and where a deployment happens

1 / 8

Sources: ARCHITECTURE.md §8 (repos, discovery, three sources, g1/g2, Kargo per-service promotion, release trace), §9 (controllers), secrets-chain.md (Platform CR write path).

08 · Garden in motion

`pls env up`, piece by piece

One graphGarden runs one deployment graph for all six development profiles. pls drives it.

Only settings changeWhere the cluster runs, the network, secrets and data differ per profile.

No Argo, no KargoThey never run inside these clusters.

Pick a profile, watch it come up

Sources: environments.md §1.1–§1.4; goals/garden-k3d-profiles.md, goals/garden-vcluster-profiles.md, goals/ci-k3d-lanes.md; ARCHITECTURE.md §3, §4 (ENTEI traffic path).

09 · How a preview fork works

castform copies real data, then throws it away

Fixed at creationNewer commits mean a new preview, never an update.

3 data classes forkedPostgres (Neon), KV (Upstash), storage (Tigris). Cache starts empty.

Cleanup lives outsidefork-reaper owns it, so it works even if the preview's cluster is already gone.

Fork source

1 / 10

What cannot be forked

Dragonfly (cache or KV), MinIO, R2 and S3: the fork is refused with a ForkUnsupported condition. Nothing is faked.
Local CNPG has no fork mechanic. A local module that needs real data uses a remote Neon branch instead.

Sources: environments.md §3 (preview model, R-P1…R-P9), §1.2 (castform row); goals/dependency-operator.md (fork mechanics table, broker-only creation); goals/fork-reaper.md (release steps); ARCHITECTURE.md §5 (forked identity safety).

10 · Multi-region

Login is global, data is local

Home-sharding: each user has one home landscape per platform, stored as a claim in their identity.
Production has two home landscapes today: raichu (Singapore) and ampharos (US).
Each landscape has its own Logto issuer and its own dataset. There is no cross-region database.
Caches stay regional with a time limit (TTL).

Try it: one user signs in

DNS across regions

Names that span several landscapes use Route 53 geoproximity: one record set per landscape, nearest healthy one answers. Example: hooks.webhook.mercury.mew.cluster.atomi.cloud.

Virtual landscapes

mew (production) and celebi (staging) are names only. They exist because OIDC browsers and webhook senders need one stable address that survives region changes.

A whole region dies

That is a restore event, not a routing event: restore from cross-vendor backup and move the declaration. Expect hours (data loss window: minutes).

Why not a global database

AWS's strongly consistent multi-region options exclude Singapore (mid-2026), break EF Core, and cost 3–5× Neon.
A globally consistent Redis does not exist.

Sources: ARCHITECTURE.md §2 (multi-region), §4 (geoproximity, edge docs), §5 (client flow, token lifetimes).

11 · Runtimes and runners

Five languages, one runner per job

Runtimes (what services are written in)

Runtime	Templates	Libraries (`lib/<lang>-*`)
Bun (TypeScript)	bun-base, bun-lib, bun-cli, bun-consumer, nextjs-frontend	result, interfaces, core-utils, config, otel, problems, auth-engine, api-engine, frontend-utils, standard-config, e2e
.NET	dotnet-base, dotnet-lib, dotnet-api	result, interfaces, core-utils, config, otel, problems, auth-engine, api-engine, server-engine, standard-config, e2e
Go	go-base, go-lib, go-consumer, operator-template	errors-problems, interfaces, core-utils, config, otel, auth-engine, api-engine, standard-config, e2e
Dart / Flutter	dart-lib, flutter-base, flutter-e4	result, problems, interfaces, core-utils, config, auth-engine, api-engine, e2e
Next.js (web)	nextjs-frontend, frontend-standalone-chart	uses the Bun libraries

Every language starts its libraries in the same order: result → interfaces → core-utils.

Runners (what executes each job)

Garden, via pls

Runs the one deployment graph for all six development profiles. Owns up, down, reset.

ArgoCD + Kargo

Run Primordial and serving only. Argo syncs Git to clusters; Kargo promotes one service's release stage by stage.

GitHub Actions on Namespace

CI. Runner label nscloud-ubuntu-26.04-amd64-16x32. Fallback: nscloud-ubuntu-24.04-amd64-16x32.

nsc instance (CI test lanes)

ditto and absol tests each get one throwaway nsc machine with built-in k3s, then nsc destroy --force.

task (Taskfile)

The per-repo command surface: build, test, chart tasks. Files are .yaml.

Cloudflare Workers

Only two kinds: web frontends (Next.js) and erbium's error portal. Released as tagged versions through CloudflareDeploy.

Kubernetes substrates (where clusters come from)

Substrate	Used by	Lifetime
k3d	lapras, rotom (laptop)	kept across down/up
nsc k3s	ditto, absol (CI)	one run, then destroyed
vcluster on ENTEI	eevee, castform	lease: days–weeks (eevee), 7-day renewable (castform)
Provider clusters	serving (DigitalOcean, AWS, OCI; EKS Auto Mode is the AWS direction)	permanent; removed only by Decommission

noteNot settled

EKS Auto Mode is "assumed green" (decision S11), not live-verified. Production use waits on your live test of aws-load-balancer-eip-allocations.

Sources: ARCHITECTURE.md §3, §3.1, §8, §10; environments.md §1.2; goals/ci-k3d-lanes.md; ratchet graph (nodes and edges, 2026-11-07).

12 · How diene itself is built

Templates branch on three switches

Every template starts as a working sample repo that builds and passes CI.
Templates form a tree from workspace → shared. Each child removes or adds one capability.
The switches (dimensions): language, Helm on/off, Docker on/off, observability on/off.

Try it: flip the switches, see which template node exists Language

Capabilities

Four kinds of link between nodes

Link	Meaning	Example
template-depend	A template built on a parent template	shared → bun-base
template-materialize	Real code created from a template	bun-lib → lib/bun-result
library-depend	Code that uses a published library	lib/bun-result → lib/bun-config
execution-depend	Needs another node to run its proof	observability-block → bun-base-w-observability

Build planes: from sample to a real repo

Template plane

Working sample repos, e.g. helm-wrapper. Released as CyanPrint templates.

Code plane

Real code materialized from a template, e.g. charts/carbon (copied from helm-wrapper).

Template-publish plane

Code turned back into a template, e.g. the new carbon-template node.

Instance plane

One real repo per platform or service, stamped with cyanprint create, e.g. mercury.carbon.

Sources: ratchet graph (node types template/code, edge kinds), carbon goal discussion; goals/workspace.md, goals/shared.md.

13 · Failure drill

Break one piece, see what still works

Pick what fails

Sources: ARCHITECTURE.md §1 (axiom 7), §3, §4 (failure rungs, Cloudflare outage posture), §7 (vendor posture); environments.md §1.1 (ENTEI).

14 · Glossary

Every word on this page

LPSM: Landscape / Platform / Service / Module: the four-slot name of every deployed workload.
Landscape: A rule set for secrets, data, lifetime and network edge. One landscape = one consistent dataset per platform.
Host landscape: A landscape that owns clusters: pichu, pikachu, raichu, ampharos.
Virtual landscape: A DNS-only name over host landscapes: mew, celebi. Owns no clusters or data.
Cluster mark: A gem name (opal, ruby, emerald…) that shows the provider. A cluster = landscape × mark.
Gem siblings: Two clusters of one landscape, same dataset, used for blue/green cutover.
Primordial: The one permanent control-plane cluster: ArgoCD, Kargo, operators, Infisical.
ENTEI: The one host cluster for eevee and castform vclusters. Not a landscape.
Instance: One developer, run or preview inside a landscape. A naming add-on, not an LPSM slot.
Allocation ID + generation: The only key used to clean up or fence an instance.
Garden: The tool that runs the deployment graph for development profiles.
pls: The command-line tool that drives Garden: pls env up, down, doctor.
vcluster: A virtual Kubernetes cluster that runs inside a host cluster.
Carbon: A platform's home repo (.carbon). Creating it registers the platform.
Row: One file per service per landscape in fleet/platforms//landscapes/<l>/<svc>.yaml. Kargo edits it to promote.
T3 / fleet-operator: The operator on Primordial with the cluster, platform, dependency, traffic, webhook and cf-deploy controllers. Graph node: dependency-operator.
SoS: Secrets-of-secrets: the Infisical project that holds each platform's machine credentials.
ESO: External Secrets Operator: copies secrets from Infisical into Kubernetes Secrets.
forkSource: castform's setting: staging or production. Production needs a separate grant and allows one preview at a time.
Decommission: The explicit custom resource that deletes something for real. Deleting a repo or a CR alone never destroys data.