Version Control and Code Structure

All courses / Architecture as Code / Module 1 / Chapter 3

Learning objectives

After the lesson the participant can:

• Distinguish the responsibilities of Architecture as Code and Infrastructure as Code across the chapter's five dimensions.
• Compare mono-repo, multi-repo and hybrid topologies and justify a choice for a given organisation.
• Compare GitFlow and trunk-based development for architecture assets.
• Specify the branch protections and automated checks an architectural repository needs.

Key concepts

Layered abstraction of AaC and IaC

Architecture as Code sits one abstraction layer above Infrastructure as Code. It defines the opinionated guardrails that keep architectural intent enforceable, while Infrastructure as Code implements the concrete runtime changes. Version control is the contract between the layers.

Hybrid topology

A single canonical repository holds the architectural source of truth (models, policies, ADRs and golden-path templates) while service teams run their own repositories that reference the shared modules and policies. Governance stays centralised without forcing a mono-repo.

Trunk-based development

Nearly all work stays on a single main branch, with short-lived feature branches merged within a day or two. It suits architecture assets because definitions should reflect reality continuously, but it depends on reliable automated validation.

GitFlow with release gates

Long-lived develop, release and main branches give clear checkpoints for governance sign-off. Teams should codify release gate criteria, such as all ADRs having the status accepted and all diagrams rendering without errors, as automated checks.

Branch protection for architectural repositories

Mandatory rules that require status checks (documentation build, diagram generation, infrastructure linting), pull-request reviews, signed commits and linear history, so that architectural artefacts cannot bypass the agreed quality gates.

Interactive exercises

Do them here and get feedback at once. Choose a card and then where it belongs, or drag it.

Teaching plan

Discussion

1. The chapter says trunk-based development works best when the team trusts its automated validation. What would have to be true of your pipelines before you trusted the main branch at all times?
2. What does it change for an auditor when compliance is verified through repository history instead of bespoke documentation?
3. Where should the line between the architectural source of truth and the execution artefacts run in your own repositories?

Written exercise

Self-test

Choose an answer to see whether it is right, or open the answer below each question.

1. In the chapter's comparison, what is the primary artefact of Architecture as Code as opposed to Infrastructure as Code?

   1. Codified guardrails, architectural policies and structural models
   2. Environment templates, resource modules and orchestration logic for deployment
   3. Plan, apply and monitoring reports on the runtime state
   4. Container images, build pipelines and deployment manifests
   Show the answer

   A. Codified guardrails, architectural policies and structural models
   The table gives codified guardrails, architectural policies and structural models as the primary artefact of Architecture as Code; environment templates, resource modules and orchestration logic belong to Infrastructure as Code.

2. Why does the chapter say Architecture as Code workflows generally benefit from trunk-based development?

   1. Because it removes the need for pull-request reviews
   2. Because organisations with formal change-control requirements always demand a single branch
   3. Because definitions are long-lived and should reflect reality continuously
   4. Because long-lived release branches cannot be protected
   Show the answer

   C. Because definitions are long-lived and should reflect reality continuously
   The chapter argues that architectural definitions are long-lived assets that should reflect reality continuously, not periodically, so the canonical model should never diverge far from the development state.

3. What is the principal drawback of a mono-repo that the chapter names?

   1. Cross-cutting changes cannot be made in one pull request
   2. Scale: clone times, CI durations and merge conflicts increase
   3. Shared tooling has to be configured separately per team
   4. Access control can only be granted to one owning team
   Show the answer

   B. Scale: clone times, CI durations and merge conflicts increase
   The mono-repo makes cross-cutting changes atomic and configures shared tooling once; its principal drawback is scale, as clone times, CI run durations and merge-conflict frequency grow with the repository.