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; the canonical/novel/controversial breakdown lives in 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.

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, 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 — OSB, xDS, 3-layer IaC, template+context, async task, boundary validation
• Edge Compute & Sidecars — cross-cutting concerns, sidecar tradeoffs, multi-team contribution
• Platform Migration — forced migration, removing the old path, migration cost calculus
• Long-Term Maintenance — churn as smell, build vs maintain, operator-centric design, AI-coupling risk
• Non-Technical Engineering Skills — diplomacy, mentoring vs teaching, conflict anticipation, curse of knowledge
• Canon and Citations — master citation index across Platform Engineering, SRE/DORA, Architecture Patterns, Modern Tooling (2026), and Staff+ Engineering canon, with full bibliographies
• Contrasts (canonical / novel / controversial) — 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 — 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. 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 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.