architecture-design-principles

name	architecture-design-principles
category	governance
description	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, SaltStack/Ansible/Puppet) behind a developer-friendly API, (6) centralizing cross-cutting concerns (auth, authz, rate limiting, DDoS, access logs) at the edge, (7) planning a fleet-wide migration to new infrastructure, (8) auditing a long-lived codebase for churn / coupling / maintenance burden, (9) onboarding engineers to an existing platform, (10) deciding when to mentor vs train, (11) user says "platform engineering", "control plane", "data plane", "xDS", "Envoy", "service broker", "edge compute", "sidecar", "cross-cutting concerns", "self-service", "internal developer platform", "IDP", "platform migration", "code churn", "long-term maintenance", "mentoring vs teaching".
metadata	{"source":{"talk":"I was laid off by Atlassian","speaker":"Vasilios Syrakis","date":"2026-05-10T00:00:00.000Z","duration":2405,"url":"https://www.youtube.com/watch?v=55pTFVoclvE"},"type":"distillation","domain":"platform-engineering"}

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