# Architecture Design Principles > Distilled architecture & design principles for building self-service developer platforms, control-plane / data-plane separation, and edge-centralized cross-cutting concerns — drawn from a senior platform engineer's 8-year retrospective on building Atlassian's Envoy-based load-balancing platform (Open Service Broker + Sovereign xDS control plane + AWS infra + sidecar model). Covers the three IaC layers (image / infra / runtime), the template+context pattern for dynamic proxy configuration, forced-migration as an adoption tool, long-term maintenance discipline (churn as a smell, build vs maintain as distinct skills), and the non-technical engineering skills (diplomacy, mentoring vs teaching). Use when: (1) designing a self-service internal developer platform, (2) deciding between native proxy features vs sidecars, (3) introducing or migrating to Envoy / xDS / service mesh, (4) implementing the Open Service Broker spec or any resource-provisioning API, (5) abstracting cloud complexity (AWS CloudFormation, Packer - Skill: `broomva/architecture-design-principles` (Agent Skill, multi-file: 19 files) - Install (CLI): `npx skillmds@latest add broomva/architecture-design-principles` - Raw SKILL.md: https://api.skillmd.com/api/skills/broomva/architecture-design-principles/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: DevOps & Infra - Author: broomva (https://skillmd.com/u/broomva) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/broomva/architecture-design-principles --- # Architecture & Design Principles — Platform Engineering at Scale A field-tested distillation of how to build a developer platform that serves ~1000 services across ~13 regions on ~2000 long-lived proxies, derived from an 8-year platform-engineering retrospective (Atlassian, 2017-2025). The talk is structured as a chronological build-up; this skill re-organises it as a **principle map** plus deep-dive references. ## Why this skill exists Platform-engineering content online tends toward two failure modes: 1. **Vendor demos** that show the happy path of a tool without the failure modes that emerged at year three. 2. **Conference talks** that describe a finished system without the sequence of decisions that produced it. This talk is unusual because it walks chronologically through *how* a small team built a self-service load-balancing platform, *which choices compounded*, and *which non-technical skills mattered most over eight years*. The principles below are the durable shape of that experience. ## Principle Map (with canonical grounding) Each principle is anchored to its canonical name in the established literature. Use the canonical name in PRs and code review; reviewers can verify against the cited source. Detailed grounding lives in [`references/06-canon-and-citations.md`](references/06-canon-and-citations.md); the canonical/novel/controversial breakdown lives in [`references/07-contrasts.md`](references/07-contrasts.md). | # | Principle | Canonical name | Source | |---|-----------|----------------|--------| | 1 | **Abstract the complexity, not the power** | Thinnest Viable Platform (TVP) | Skelton & Pais 2019 *Team Topologies* | | 2 | **Three IaC layers: image, infra, runtime** | Build / Release / Run (Factor V) | Wiggins 2011 *12-Factor App* §V | | 3 | **Control plane / data plane split** | Control plane / data plane (Istio) | Envoy xDS protocol; Istio architecture | | 4 | **Template + Context separation** | Helm/Kustomize templating (primary); Open Host Service (DDD analogy) | Helm/Kustomize docs; Evans 2003 DDD p. 374 | | 5 | **Async task orchestration** | Parallel Saga (async-eventual-orchestrated) | Ford et al 2021 *Hard Parts* Ch. 12; Richardson saga pattern | | 6 | **Validate at the boundary** | Anti-Corruption Layer (semantic-translation form) | Evans 2003 DDD p. 364 | | 7 | **Centralize cross-cutting concerns at the edge** | Gateway pattern + edge-centric architecture | Fowler PoEAA p. 466; microservices.io | | 8 | **Sidecar for what the proxy can't do natively** ⚠ | Sidecar pattern *(now a choice, not default — see ambient mesh)* | Istio 1.24 (Nov 2024) Ambient GA; Buoyant Linkerd benchmarks | | 9 | **Forced migration via removed alternatives** | Strangler Fig + specific forcing function | Fowler 2004 Strangler Fig; Microsoft Learn | | 10 | **Build for the operator, not just the user** | SRE runbook/playbook discipline | Google SRE Workbook Ch. 8 | | 11 | **Churn is a smell** | Atomic, triggered, dynamic fitness function | Ford et al 2023 *Building Evolutionary Architectures* 2e | | 12 | **Building ≠ Maintaining ≠ Operating** | Toil discipline (50/25/25 cap) + DORA throughput-vs-stability | Rau, Google SRE Book Ch. 5; Forsgren et al 2018 *Accelerate* | | 13 | **Diplomacy is an engineering skill** | Care Personally (Scott); leverage equation (Grove) | Scott 2017 *Radical Candor*; Grove 1983 *High Output Management* | | 14 | **Mentoring ≠ Teaching** | Career vs psychosocial functions (Kram); Alpha Geek anti-pattern | Kram 1985 + Allen et al 2004 meta-analysis; Fournier 2017 *Manager's Path* Ch. 2 | ⚠ **2026 freshness flag — sidecars**: the talk's sidecar pattern is now a deliberate architecture *choice*, not the default. Istio Ambient (GA November 7, 2024, v1.24) replaces per-pod sidecars with per-node ztunnel + per-namespace waypoint proxies; published savings ~90%+ proxy resources. Linkerd doubles down on sidecars with its Rust micro- proxy and disputes the resource claims. Pick a side deliberately; cite your reasoning. See [`references/07-contrasts.md`](references/07-contrasts.md#sidecars-in-2026). For each principle, the columns "When to apply" and "Anti-pattern it prevents" live in the numbered reference files (`01-self-service-platforms.md` … `07-contrasts.md`) and in [`references/07-contrasts.md`](references/07-contrasts.md), which is the canonical place to look for the operational guidance. ## The Reference Architecture (from the talk) The talk's central diagram, reconstructed: ``` ┌─────────────────────────────────────────────────────────────────────┐ │ DEVELOPER │ │ │ │ │ │ "pls provision a load balancer" (JSON in version control) │ │ ▼ │ │ ┌────────┐ ┌─────┐ ┌────────┐ ┌──────────┐ │ │ │FastAPI │───▶│ SQS │───▶│ Worker │───▶│ DynamoDB │ │ │ │ (OSB) │◀───┴─────┘ │ │───▶│Route53, │ │ │ └────────┘ └────────┘ │CloudFront│ │ │ │API calls │ │ │ ── Open Service Broker (Tier 1) ───────────────── │ │ │ │ ┌─────────────────────┐ │ │ │ Sovereign (xDS) │ reads DB + S3 → renders templates │ │ │ ┌─────────────────┐ │ │ │ │ │ Templates │ │ xDS API ──▶┌──────────┐ │ │ │ │ + Context │─┼──────────────▶│ 2000 │ │ │ │ │ → Clusters │ │ │ Envoy │ 13 regions │ │ │ │ → Routes │ │ │ proxies │ │ │ │ │ → Listeners │ │ │ (EC2) │ │ │ │ └─────────────────┘ │ └──────────┘ │ │ └─────────────────────┘ ▲ │ │ │ │ │ ┌──────────────────────┐ │ │ │ │ AWS CloudFormation │ provisions ─────┘ │ │ │ Parameters, VPC, │ │ │ │ Subnet, IGW, SG, │ │ │ │ ASG, NLB, IAM, ACM, │ │ │ │ Route53, KeyPair │ │ │ │ │ │ │ │ │ ▼ │ │ │ │ AMI ◀──── Packer + SaltStack (image build) │ │ └──────────────────────┘ │ └─────────────────────────────────────────────────────────────────────┘ ``` Three IaC layers map onto three different products in this stack: - **Image** — Packer + SaltStack. Cadence: weeks. Risk: high (every proxy rebakes). - **Infrastructure** — CloudFormation. Cadence: months. Risk: medium (regional). - **Runtime config** — Sovereign / xDS. Cadence: seconds. Risk: per-tenant. This separation is what lets a small platform team ship features daily without restarting customer traffic. Most platform-team failures come from collapsing these layers (e.g., redeploying proxies to ship a routing change). ## Edge-Centralized Cross-Cutting Concerns The second half of the talk reconstructs the "what is the proxy *for*" question: ``` Customer (the outside world) │ ▲ ▼ │ ┌─────────────┐ │ CloudFront │ ←── DDoS protection └─────────────┘ │ ▲ ▼ │ ┌─────────────┐ │ NLB │ └─────────────┘ │ ▲ ▼ │ ┌───────────────────┐ ┌─────────────────┐ │ Envoy │ ←──▶│ Sidecars │ │ (Access logs, │ │ • Authentication│ (Rust) │ routing, │ │ • Authorization │ │ HTTP filters) │ │ • Rate Limiting │ └───────────────────┘ └─────────────────┘ │ ▲ ▼ │ ┌───────┐ ┌───────┐ ┌───────┐ ... (a "bazillion" backends) │backend│ │backend│ │backend│ └───────┘ └───────┘ └───────┘ ``` **The rule**: the further left a concern is solved, the cheaper it gets per backend. Solving DDoS at CloudFront protects all 1000 services. Solving auth at the Envoy + sidecar pair means 1000 backend teams don't each implement OAuth. **The cost**: cross-cutting concerns at the edge belong to the platform team. Backend teams lose some autonomy in exchange for not having to think about those concerns. ## When to Use This Skill Invoke this skill explicitly when: - Designing an **internal developer platform** (IDP) from scratch or evaluating one - Choosing between **native proxy features and sidecars** - Implementing an **Open Service Broker** or any resource-provisioning API - Planning a **fleet-wide migration** to new infrastructure - Auditing a long-lived codebase for **churn / coupling / maintenance burden** - Onboarding engineers to an existing platform - Mentoring vs training a junior engineer - Justifying time spent on **diplomacy / conflict resolution** as engineering work ## Reference Map For depth on each principle group: - [Self-Service Platforms](references/01-self-service-platforms.md) — OSB, xDS, 3-layer IaC, template+context, async task, boundary validation - [Edge Compute & Sidecars](references/02-edge-compute-sidecars.md) — cross-cutting concerns, sidecar tradeoffs, multi-team contribution - [Platform Migration](references/03-platform-migration.md) — forced migration, removing the old path, migration cost calculus - [Long-Term Maintenance](references/04-long-term-maintenance.md) — churn as smell, build vs maintain, operator-centric design, AI-coupling risk - [Non-Technical Engineering Skills](references/05-non-technical.md) — diplomacy, mentoring vs teaching, conflict anticipation, curse of knowledge - [Canon and Citations](references/06-canon-and-citations.md) — master citation index across Platform Engineering, SRE/DORA, Architecture Patterns, Modern Tooling (2026), and Staff+ Engineering canon, with full bibliographies - [Contrasts (canonical / novel / controversial)](references/07-contrasts.md) — for each principle, whether it matches canon, extends canon, or diverges from the 2026 canon; how to cite each in code review - [Source: talk transcript & diagrams](references/source/talk.md) — full attribution, timestamps, key visual frames ## Grounded Best Practices — TL;DR Every principle in this skill has a canonical name and a named source. The full grounding is in [`references/06-canon-and-citations.md`](references/06-canon-and-citations.md). The five canon clusters and what they ground: - **Platform Engineering canon** (Skelton & Pais *Team Topologies* 2019; Conway 1968; *Accelerate* 2018; Humanitec State of Platform Engineering Reports 2022-2024; Hohpe *Architect Elevator* 2020; Backstage v1.50 / Crossplane 2.0) → grounds principles 1, 7, 9 and the "platform team" framing throughout. - **SRE & DORA canon** (Google SRE Book 2016; SRE Workbook 2018; *Accelerate* 2018; DORA 2024 J-curve finding; DORA 2025 AI-as-amplifier finding) → grounds principles 10, 11, 12 and the AI-coupling-risk framing in `04-long-term-maintenance.md`. - **Architecture Patterns canon** (Evans *DDD* 2003 — ACL, Open Host Service; Fowler *PoEAA* 2002 — Gateway; Fowler 2004 — Strangler Fig; Ford/Parsons/Kua 2017 + 2nd ed 2023 — fitness functions; Ford/Richards/Sadalage/Dehghani 2021 — saga patterns; Wiggins 2011 — 12-Factor V; AWS Well-Architected; Nygard 2011 — ADRs; Brown — C4) → grounds principles 2, 3, 4, 5, 6, 7, 9, 11. - **Modern Tooling 2026 reality check** (Envoy v1.38 + go-control-plane; OSB v2.17 not deprecated but Crossplane 2.0 is the 2026 substrate; Istio Ambient GA Nov 2024 / Linkerd micro-proxy debate; SMI archived Sept 2023; Backstage v1.50 + Spotify Portal GA; SaltStack in decline; Terraform Stacks GA HashiConf 2025) → grounds the freshness flags on principles 3, 8, and the tooling notes throughout. - **Staff+ Engineering canon** (Reilly *Staff Engineer's Path* 2022 — three pillars + "You're a Role Model Now"; Fournier *Manager's Path* 2017 — Alpha Geek anti-pattern; Larson *Staff Engineer* 2021 — Tech Lead archetype; Camerer/Loewenstein/Weber 1989 + Heath brothers 2007 — curse of knowledge; Scott *Radical Candor* 2017 — Ruinous Empathy; Grove *High Output Management* 1983 — leverage equation; Kram 1985 + Allen et al 2004 — mentoring research; Edmondson 1999/2018 — psychological safety; Hogan *Resilient Management* 2019) → grounds principles 13, 14 and `05-non-technical.md` throughout. The contrast matrix at [`references/07-contrasts.md`](references/07-contrasts.md) catalogs **where** each principle is canonical, novel, or controversial against the 2026 canon — useful when defending a design in code review. ## Anti-Heuristics (when NOT to apply) - **Greenfield project, no compounding cost yet.** The three-IaC-layer split, the control-plane separation, and the template+context pattern are *amortizations* of cost over many tenants. A single-team service doesn't need them. - **Cross-cutting concerns of a single team.** Edge centralization is correct when N teams need the same thing. For one team's auth, just put it in the app. - **Forced migration without an actually-better target.** The talk's forced migration worked because the new platform was strictly better. Forcing migration to a not-yet-better platform burns trust. - **Churn-as-smell on actively-developed code.** Churn is a smell on *finished* features that won't stop changing — not on features that are still being built. ## Talk Attribution > "I was laid off by Atlassian" — Vasilios Syrakis, 2026-05-10 > https://www.youtube.com/watch?v=55pTFVoclvE (40m05s) > > Despite the click-bait title, this is one of the densest first-person > retrospectives on platform engineering at scale published in recent memory. > Vasilios built and open-sourced Sovereign (the Envoy xDS control plane) > while at Atlassian; the talk reconstructs the system from memory on Excalidraw. Open-source artifact mentioned in the talk: **Sovereign** (Envoy xDS management server in Python/FastAPI) — see talk for Bitbucket link; the design is what matters here, not the specific repo.