golden-path

The golden-path repository holds the recommended way to build a product on Airframe: one template that generates a new product’s repository, and the Terraform modules that product uses to create its services, database and secrets. A product generated from it starts with a working application, its infrastructure, a pipeline made of the platform’s components and a runbook, deploying to Cloud Run behind single sign-on. It is a default, not a requirement: after the first commit, the code is the team’s.

What it is for

Every product needs the same plumbing: projects wired to the platform, a service with structured logs and telemetry, a database with backups, secrets by name, a pipeline. Writing it again for each product is slow and drifts. The golden path writes it once, keeps it tested, and hands each new product a copy that already passes every check.

What is in it

The template: one Copier template (Copier generates a project from a template and a set of answers) with a stack answer for three stacks: Node (NestJS and React), Python (the FastAPI full-stack template) and Java (Spring PetClinic). Everything outside the application folder is shared by all three: the Terraform roots, the pipeline file, the product’s description for the architecture catalog, the runbook and the instructions for a coding agent.
The modules: service-project and airframe-context, which read what the project factory made; cloud-run-service, cloud-sql, secrets, preview-substrate, database-seed and grafana-dashboard. Each has its own tests against mocked providers.
The examples: one product rendered for each stack, from the live catalog, kept identical to what the template produces today.
A failing fixture: a root the policy pack must refuse, which proves on every change that the pack still bites.

How it connects

The catalog and landing-zone feed it. When a product is created, control-plane’s GitLab root runs the template with the product’s catalog entry and its Ready output from the project factory as answers, and commits the result as the repository’s first commit.
Products use its modules. A product’s roots call the modules, pinned to a commit, instead of declaring cloud resources one by one.
It includes control-plane’s components. The generated pipeline file includes only the platform’s components, which is what the policy pack requires of every product.
It is part of every release. A release names the commit of the template and of the modules, together with the other parts.

Who changes it, and how

Changes are merge requests approved by the platform team, with the gate’s approval required. The pipeline is the template’s release gate:

whenever the template, the examples or the pipeline change, it renders the three examples again from the live catalog and fails if they differ from the committed ones;
it builds and tests a stack’s example whenever that stack’s template files, its example or the pipeline change;
it runs the modules’ tests, validates each example as a product root, and runs the policy pack against the examples and the failing fixture.

The platform’s build and test jobs know only these three stacks. A product on another stack, with its own Dockerfile on a platform base image, runs none of them, and its merge requests fail the test-coverage gate until its catalog entry lowers the required coverage, which a team lead or a domain lead must approve. This is a known gap.

The repository has no roots of its own and costs nothing while idle.

Where it lives

In the golden-path repository: