DevOps and Architecture Documentation

CI/CD Pipelines

A good pipeline provides fast feedback and repeatable deployments.

┌──────┐   ┌──────┐   ┌──────┐   ┌────────┐   ┌────────┐
│ Lint │──►│ Test │──►│Build │──►│Deploy  │──►│Release │
│      │   │      │   │      │   │Staging │   │  Prod  │
└──────┘   └──────┘   └──────┘   └────────┘   └────────┘
   │          │          │            │
   ▼          ▼          ▼            ▼
 SAST     Unit +      Compile,    Smoke
 scan    Integr.    Container.   Tests

Figure 9.1 — CI/CD pipeline stages. Fail fast by running cheap checks before expensive ones.

Pipeline Principles

Principle	Why
Fail fast	Run cheapest, fastest checks first (lint → test → build)
Immutable artefacts	Build once, promote the same artefact through environments
Idempotent deployments	Running the same pipeline twice produces the same result

Environment Strategy

Environment	Purpose	Data	Deploy Trigger
Dev	Local development	Synthetic / anonymised	Local build
Test/CI	Automated testing	Synthetic	Branch push
Staging	Pre-production validation	Anonymised subset	Merge to main
Production	Live	Real	Manual or scheduled release

Table 9.1 — Typical environment hierarchy. Keep environments as similar as possible.

Observability

Monitoring tells you something is wrong. Observability lets you ask why.

Three Pillars

Pillar	What	Example Tooling
Logs	Discrete events with metadata	ELK, Loki, CloudWatch
Metrics	Aggregated measurements over time	Prometheus, Grafana
Traces	Request flow across services	OpenTelemetry, Jaeger

Figure 9.2 — The three pillars of observability. Each answers different questions about system behaviour.

Key Metrics (USE Method)

Metric	What It Tells You	Target
Latency (p50, p95, p99)	How fast is the system responding?	Define per endpoint
Traffic (req/s)	How much load is the system handling?	Trend over time
Errors (rate, 5xx)	Is the system functioning correctly?	< 1 %
Saturation (CPU, memory, connections)	Is the system nearing capacity?	< 80 %

Architecture Documentation

Documentation rots when it’s disconnected from reality. Keep it alive:

Technique	How	Why It Works
ADRs	Capture decisions with context	Documents why, not just what
Diagrams as code	PlantUML, Mermaid, Structurizr	Version-controlled, reviewable
README as living doc	Update when the system changes	Single source of truth for new joiners
Lightweight RFCs	Propose changes before building	Feedback early, shared ownership

Table 9.2 — Documentation techniques that stay relevant over time.

Minimum viable documentation

For any non-trivial system, maintain these four artefacts: a system context diagram, an architecture overview (C4 level 2-3), an ADR decision log, and an operational runbook.

Next: Chapter 10 — Architecture Evaluation and Emerging Trends