Architecture as Code - Book Structure

This document describes the logical structure for the book "Architecture as Code" which is organised into seven narrative parts plus extended appendices. Thirty-eight chapters, appendices, and structured templates build upon each other to provide a complete understanding of Architecture as Code and Infrastructure as Code for organisations operating in diverse global contexts.

Table of Contents

Part 1: Foundations (Chapters 1-4)

Foundational concepts, principles, and documentation practices

Part 2: Architecture Platform (Chapters 5-8)

Core technical building blocks for Architecture as Code implementations

Part 3: Security & Governance (Chapters 9-12, including 9B and 9C)

Security, policy automation, governance, and compliance as code

Part 4: Delivery & Operations (Chapters 13-16, including 15A and 15B)

Testing, delivery practices, cost optimisation, and migration strategies

Part 5: Organisation & Leadership (Chapters 17-21)

Organisational change, team design, management models, and collaborative delivery

Part 6: Experience & Best Practices (Chapters 22-24)

Cross-disciplinary collaboration and codified best practices

Part 7: Future & Wrap-up (Chapters 25-27, including 26A and 26B)

Future outlook, risk avoidance, and closing guidance

Appendices and Reference Material (Chapters 28-34 plus maturity resources)

Reference material, author information, technical enablers, and the Architecture as Code maturity model

Chapter Structure

Part 1: Foundations (Chapters 1-4)

Focus: Foundational concepts, principles, and documentation practices for Architecture as Code

Chapter File Title Description
1 01_introduction.md Introduction to Architecture as Code Introduction to the concept Architecture as Code and its relation to Infrastructure as Code
2 02_fundamental_principles.md Fundamental Principles of Architecture as Code Fundamental principles including declarative architecture definition and holistic perspective
3 03_version_control.md Version Control and Code Structure Best practices for version control of architecture code
4 04_adr.md Architecture Decision Records (ADR) Structured documentation of architecture decisions

Part 2: Architecture Platform (Chapters 5-8)

Focus: Core technical building blocks and automation patterns for Architecture as Code

Chapter File Title Description
5 05_automation_devops_cicd.md Automation, DevOps and CI/CD for Infrastructure as Code Holistic approach to CI/CD, DevOps practices and automation for IaC
6 06_structurizr.md Structurizr: Architecture Modeling as Code Using Structurizr DSL and C4 model for architecture visualisation and documentation
7 07_containerisation.md Containerisation and Orchestration as Code Container-based Architecture as Code
8 08_microservices.md Microservices Architecture as Code Applying Architecture as Code disciplines across microservices estates

Part 3: Security & Governance (Chapters 9-12, including 9B and 9C)

Focus: Security automation, policy enforcement, governance, and compliance requirements

Chapter File Title Description
9 09_security_fundamentals.md Security Fundamentals for Architecture as Code Foundational security principles, policies, and core practices
9B 09b_security_patterns.md Advanced Security Patterns and Implementation Advanced patterns, practical implementations, and future trends
9C 09c_risk_and_threat_as_code.md Risk as Code and Threat Handling as Code Codifying risk catalogues, automation, and incident playbooks
10 10_policy_and_security.md Policy and Security as Code in Detail Detailed review of policy-as-code
11 11_governance_as_code.md Governance as Code Codifying governance processes, approval flows, and tooling support
12 12_compliance.md Compliance and Regulatory Adherence Regulatory compliance considerations for international organisations

Part 4: Delivery & Operations (Chapters 13-16, including 15A and 15B)

Focus: Testing strategies, delivery patterns, evidence automation, financial optimisation, and migration approaches

Chapter File Title Description
13 13_testing_strategies.md Testing Strategies for Infrastructure as Code Testing of IaC and architecture code
14 14_practical_implementation.md Architecture as Code in Practice Practical implementation examples
15A 15_evidence_as_code.md Evidence as Code and Continuous Assurance Automated evidence pipelines that connect policy automation to operational reporting
15B 15_cost_optimization.md Cost Optimisation and Resource Management Economic optimisation of resources
16 16_migration.md Migration from Traditional Infrastructure Migration strategies and best practices

Part 5: Organisation & Leadership (Chapters 17-21)

Focus: Organisational transformation, leadership models, and digitally enabled collaboration

Chapter File Title Description
17 17_organisational_change.md Organisational Change and Team Structures Organisational development for IaC
18 18_team_structure.md Team Structure and Competency Development for IaC Team organisation and competency development
19 19_management_as_code.md Management as Code Leadership practices encoded in collaborative tooling
20 20_ai_agent_team.md AI Agent Team for Architecture as Code Initiatives Structure, roles, and processes for virtual agent teams
21 21_digitalisation.md Digitalisation through Code-based Infrastructure Digital transformation through IaC

Part 6: Experience & Best Practices (Chapters 22-24)

Focus: Cross-disciplinary collaboration and lessons learned

Chapter File Title Description
22 22_documentation_vs_architecture.md Documentation as Code vs Architecture as Code Distinction between documentation and architecture disciplines, modelling vs diagram tools
23 23_soft_as_code_interplay.md The Interplay Between Soft As Code Disciplines Cross-disciplinary synergies between soft "as code" practices
24 24_best_practices.md Best Practices and Lessons Learned Summary of best practices

Part 7: Future & Wrap-up (Chapters 25-27, including 26A and 26B)

Focus: Strategic outlook, risk avoidance, and concluding guidance

Chapter File Title Description
25 25_future_trends.md Future Trends and Development in Architecture as Code Development trends, technological future, and long-term perspectives
26A 26a_prerequisites_for_aac.md Prerequisites for Architecture as Code Adoption Organisational, technical, and economic readiness signals
26B 26b_aac_anti_patterns.md Anti-Patterns in Architecture as Code Programmes Common pitfalls, early warning indicators, and recovery playbooks
27 27_conclusion.md Conclusion Concluding reflections

Appendices

Chapter / Appendix File Title Description
Glossary glossary.md Glossary Glossary and definitions
About the Author about_the_author.md About the Author Profile of Gunnar Nordqvist and context for the book's expertise
Appendix A 30_appendix_code_examples.md Appendix A: Code Examples and Technical Implementations Technical architecture code implementations
Appendix B appendix_b_technical_architecture.md Appendix B: Technical Architecture for Book Production Technical book production infrastructure
32 32_finos_project_blueprint.md Appendix C: FINOS Project Blueprint Operational blueprint demonstrating governance as code alignment
33 33_references.md References and Sources Citations supporting the manuscript
34 appendix_templates_and_tools.md Appendix D: Templates and Tools Directory of reusable maturity and compliance artefacts
Appendix – Maturity Model architecture_as_code_maturity_model.md Architecture as Code Maturity Model Progressive maturity staircase linking “as code” disciplines
Appendix – Maturity Radar maturity_model_radar.html Architecture as Code Maturity Radar Tool Interactive radar visualisation accompanying the maturity model
Appendix – Control Mapping Matrix appendix_d_control_mapping_matrix_template.md Control Mapping Matrix Template Compliance acceleration template that complements the maturity model

Archived Drafts

The archive/ folder stores markdown chapters that have been retired from the active manuscript. These files are excluded from the automated build sequence in build_book.sh but remain available for reference and future revisions.

File Original Chapter Notes
archive/cloud_architecture.md Chapter 6 (Swedish draft) Superseded by the current English material covering cloud-native execution.
archive/microservices_architecture_en.md Chapter 8 translation Retained as a translation reference after the live chapter was rewritten.
archive/lovable_mockups_sv.md Chapter 20 workshop Vendor-specific Swedish workshop material preserved for future localisation work.
archive/future_trends_sv.md Chapter 25 draft Swedish-language narrative replaced by the live Chapter 25.
archive/future_development_sv.md Chapter 26 companion Swedish continuation of future-planning material folded into later revisions.

Archive filenames intentionally avoid numeric prefixes so that tooling can distinguish archived content from active chapters.

Book Organisation Principles

The book's seven-part structure follows a logical progression:

  1. Part 1: Foundations – Establishes core concepts and principles that underpin Architecture as Code work
  2. Part 2: Architecture Platform – Builds the technical capabilities required for codified architecture
  3. Part 3: Security & Governance – Ensures safety, control, and regulatory alignment
  4. Part 4: Delivery & Operations – Provides the practices needed to deliver and operate architecture as code
  5. Part 5: Organisation & Leadership – Aligns teams, leadership, and collaboration models with the new operating model
  6. Part 6: Experience & Best Practices – Shares cross-disciplinary experiences and lessons learned
  7. Part 7: Future & Wrap-up – Explores the future direction and concludes the narrative, supported by appendices

This structure ensures: - Logical progression: Each part builds upon knowledge from previous parts - Thematic grouping: Related topics are covered together for better comprehension - Balance: Theory and practice are balanced throughout all parts - Adaptability: Guidance is written for international applicability with notes for adapting to local regulatory requirements

Diagrams and Images

The images/ directory contains: - Mermaid files (.mmd): Source code for diagrams that are automatically converted to PNG - PNG files (.png): Generated diagram images used in the book

Each chapter has associated diagrams that illustrate key concepts and processes.

Build Process

The book is built automatically through:

  1. Diagram generation: Mermaid diagrams are converted to PNG images
  2. PDF generation: All chapters are combined into a complete PDF using Pandoc
  3. Version control: The entire process is version controlled via Git

Local Building

# Build the complete book
cd docs
./build_book.sh

CI/CD

The book is built automatically when changes are made to the docs/ directory through GitHub Actions.

Target Audience

This book is intended for: - IT architects and system designers - DevOps engineers and infrastructure specialists - Developers working with cloud technologies - Technology leaders and decision makers - Project managers for digitalisation initiatives

Authors and Contributors

See about_the_author.md for detailed information about the book's author and the expertise behind this comprehensive guide.

Last updated: 2024-12-03