The repository is not the system

A repository can be beautifully organised while the production system remains a complete mystery.

The source tree tells you what someone intended to commit. It does not automatically tell you which branch is deployed, which secrets exist, which dashboard owns the schedule, which manual setting changed behaviour or whether the service is still used at all.

The missing layers

To understand a running system, you usually need to connect at least five kinds of evidence:

• intent: plans, decisions, architecture and ownership;
• implementation: repositories, packages, configuration and migrations;
• delivery: workflows, branches, build outputs and deployment records;
• provider state: domains, routes, bindings, policies and account-level settings;
• operations: logs, alerts, runbooks, support history and recovery evidence.

The repository is essential, but it is not sovereign over facts it cannot observe.

Why this gets worse with managed platforms

Modern cloud services make sensible defaults easy and account-level settings invisible. That is usually a good trade. It becomes a bad one when critical behaviour exists only in a provider console and nobody has captured it anywhere durable.

A domain route, Zero Trust policy or scheduled job can materially change the system without appearing in the application source. The next person reading the repository receives a plausible but incomplete story.

Build a connected explanation

The goal is not to duplicate every provider field into YAML. That creates a second system to keep wrong.

Instead, preserve the important relationships:

1. which provider resources belong to the service;
2. which settings are security or availability boundaries;
3. how current state can be inspected;
4. what is managed as code and what is intentionally managed elsewhere;
5. where deployment and runtime evidence can be found.

A good repository should explain how to inspect the rest of the system. It should not pretend the rest of the system does not exist.