Learn the Platform
A teaching layer for the platform. The ADRs record why we decided things; the runbooks tell you how to do a task; the architecture docs are reference. These docs are the fourth kind — their job is to build the mental model in someone who doesn’t have it yet, from the ground up.
Each subsystem is a short course: an Orientation (a guided journey you read start to finish) and a Reference (look-up once you have the model) — plus, for the deeper subsystems, optional deep dives (open one hard mechanism) and tutorials (hands-on, learn-by-doing).
Start here
Section titled “Start here”| You are… | Start with |
|---|---|
| You want the point before the parts | Why the Platform Exists — the problem it solves and the one-sentence thesis, before any machinery. |
| New to the platform | The domain model — the shared vocabulary (Team / Product / Service / Environment) everything else is built on. Read it first. |
| Curious how it all fits together | The Life of a Deployment — one git push traced across every control plane. The big-picture map the modules hang off. |
| Ready for how things are built | The Environment API — the clearest example of how the platform turns a declaration into running infrastructure. |
| A developer shipping a service | The domain model (it’s the model your code lives in), then the “developer’s 2-minute view” at the end of each orientation. |
| Extending or operating a subsystem | That subsystem’s Reference, then its house skill / runbook (linked at the bottom of each module). |
Modules
Section titled “Modules”| Module | Status |
|---|---|
| Domain model — Team / Product / Service / Environment: the shared vocabulary (start here) | ✅ available |
| Teams — the ownership envelope: onboard a team and set the bounds its products and environments inherit | ✅ available |
| Onboarding a Product — put a new app on the platform: one registry entry → its whole per-product footprint derives | ✅ available |
| Environment API — how environments get provisioned (Crossplane) | ✅ available |
| Self-service cloud resources — an S3 bucket / queue / topic / table from your claim, with derived least-privilege IAM (developer-facing) | ✅ available |
| Delivery — git → running across stages, safely (ArgoCD, the promotion ladder, Rollouts) | ✅ available |
| Observability — the platform observes your workload for you (LGTM+P, eBPF zero-code, correlation, SLOs, agent-obs) | ✅ available |
| Policy & admission — the guardrail engine at the cluster door (Kyverno: validate · mutate · generate) | ✅ available |
| Identity & access — decide once, derive everywhere, borrow dangerous power (Keycloak, Pod Identity, temporary power) | ✅ available |
| Supply chain — trust provenance, not names (keyless signing, SLSA, verify-at-admission) | ✅ available |
| Runtime security — defend the running workload (assume-breach): Falco detection · WireGuard encryption · mTLS/SPIRE | ✅ available |
| Foundations — the substrate everything runs on: AWS accounts & SCPs, IaC, networking, the private cluster & Cilium, compute, access (a sub-curriculum) | ✅ available |
| The agentic platform — running governed AI agents (the XAgent runtime, bounding an agent, the autonomy ladder, the triage copilot) | ✅ available |
| Cost & FinOps — cost as an engineering signal on a loop (Inform → Optimize → Operate: two meters, the levers, budget guardrails) | ✅ available |
| Secrets & config — the best secret is one that doesn’t exist (federation · SOPS config-in-git · ESO + Secrets Manager · rotation) | ✅ available |
| Operations — run the platform: platctl walks the dependency graph to build · park · rebuild · recover (the DAG orchestrator, cluster parking, day-2 durable fixes) | ✅ available |
| Developer experience — Vercel-like DX over the machinery: a single pane of glass (Backstage) + golden paths (the scaffolder), every change a PR | ✅ available |
Compliance & regulated workloads — compliance-aware by design, not certified: a lens over the security modules + a declared tier dial (honest built-vs-inert-vs-aspirational) |
✅ available |
Spine: The Life of a Deployment — one git push across every plane (control plane) |
✅ available |
| Spine: The Life of a Request — one user request, edge to pod (data plane) | ✅ available |
| Spine: How the Platform Fits — the control-plane map (the same structure at rest) | ✅ available |
| Spine: The Security Model — the same layers as concentric defenses (defense in depth) | ✅ available |
| Spine: Why the Platform Exists — the North Star behind all the machinery | ✅ available |
The portal is being built one subsystem at a time, proving the format before scaling. The modules marked ✅ available exist today; those marked ⏳ planned are listed so the shape of the whole is visible, not because they exist yet.
Reference aids
Section titled “Reference aids”- Glossary — the shared vocabulary that recurs across modules (namespace, Composition, admission, Team / Product / …), each with a link to its canonical doc. Look a term up here; the modules teach it in context.
For authors
Section titled “For authors”The inventory is the master plan — every course the portal intends to cover, by domain, with a build sequence. New modules are written against the mold, the shared template and rules that keep the portal in one consistent voice. Read both before adding a module. Finishing a module includes the crosslink pass and clearing any rows you satisfy in the crosslink backlog.