architecture-principles

name	architecture-principles
description	Define and enforce 8-12 architecture principles with rationale and implications. Use when establishing guardrails for technology choices, ADR reviews, or platform paved roads.

Architecture Principles

Principles are durable, opinionated statements that constrain design space and accelerate decisions. Done well (TOGAF / Spewak style: statement, rationale, implications) they reduce ADR debate, anchor reviews, and become inputs to fitness functions and policy-as-code.

Stack Baseline (2026)

Concern	Recommended
Format	TOGAF 10.x principle template (Name, Statement, Rationale, Implications)
Storage	Repo-as-source-of-truth (/docs/principles/*.md), rendered via Backstage TechDocs
Linkage	ADRs (MADR 4.0), fitness functions, paved-road catalog
Decisioning	Lightweight RFC + architecture council (async-first)
Enforcement	OPA/Conftest, ArchUnit, Backstage scorecards
Reference	TOGAF 10.x; Spewak EAP; Team Topologies

When to Use

• Establishing a new platform, BU, or modernization program.
• Recurring ADR debates without a shared compass.
• Paved-road definition for a developer platform.
• M&A integration requiring rapid alignment.

Prerequisites

• Business strategy and target operating model understood.
• Stakeholders identified (engineering, security, SRE, product, finance).
• ADR process in place; otherwise establish first.

Instructions

flowchart LR
  V[Vision + constraints] --> D[Draft 8-12 principles]
  D --> R[Review w/ stakeholders]
  R --> P[Publish in repo + Backstage]
  P --> E[Enforce: ADRs, fitness, OPA]
  E --> M[Measure adherence]
  M --> U[Revise yearly]

1. Anchor in business outcomes and constraints (compliance, cost, talent). Avoid restating motherhood ("we value quality").
2. Limit to 8-12 principles. More than 12 means none are remembered.
3. Write each principle with: Name, Statement (imperative), Rationale (why), Implications (what changes, what's harder).
4. Tension-check. Each principle should reject some option; if it forbids nothing, delete it. Capture explicit trade-offs.
5. Operationalize. Map every principle to at least one mechanism: ADR template prompt, fitness function, OPA policy, or scorecard check.
6. Govern. Annual review; principles can be deprecated. Track which ADRs cite which principle.

## P-04: Buy or adopt before build
- Statement: Prefer managed or open-source solutions over bespoke for non-differentiating capabilities.
- Rationale: Engineering capacity is finite; differentiation lives in the domain.
- Implications:
  - ADRs must justify build with explicit differentiation hypothesis.
  - Vendor and OSS evaluation template required (license, SLSA level, exit cost).
  - Platform team curates an approved catalog; off-catalog choices need exception.

# OPA enforcement of P-07: All services emit OpenTelemetry
package paved_road
deny[msg] {
  input.kind == "Service"
  not input.spec.observability.otel.enabled
  msg := "Principle P-07 violation: OpenTelemetry must be enabled"
}

Common Pitfalls

Pitfall	Mitigation
Vague slogans	Test: does it forbid a real option? If no, rewrite
30+ principles	Cap at 12; archive the rest as guidelines
No enforcement	Tie each to ADR prompt, fitness function, or policy
Principles ignored in reviews	Add "Principles considered" section to ADR template
Static forever	Schedule annual review; allow deprecation

Output Format

• /docs/principles/index.md plus one file per principle.
• ADR template referencing principles.
• Mapping table: Principle -> enforcement mechanism (test, policy, scorecard).

Authoritative References

• The Open Group, TOGAF Standard, 10th Edition (2022, updates 2025).
• Steven Spewak, Enterprise Architecture Planning.
• Gregor Hohpe, The Software Architect Elevator, O'Reilly.
• Skelton & Pais, Team Topologies.
• ISO/IEC/IEEE 42010:2022 - architecture description.