Platform Engineering & IDP Design

Designing Internal Developer Platforms — golden paths, thinnest viable platform, Backstage, cognitive load reduction, and the CNCF Platform Engineering maturity model.

Overview

Platform as a product

Platform Engineering is the discipline of building and operating Internal Developer Platforms (IDPs) that reduce cognitive load on development teams and provide self-service infrastructure. It applies product thinking to internal tooling.

Core principles

Platform as a Product — Development teams are customers: a product roadmap, feedback, measured adoption and iteration on developer needs, not on what the platform team finds technically interesting
Thinnest Viable Platform (TVP) — Start with the smallest set of capabilities that delivers real value; do not build a comprehensive platform before validating demand; expand on measured developer pain
Golden Paths — Opinionated, paved paths for the most common use cases: deploy a containerized service, create a PostgreSQL database, add monitoring
Cognitive Load — The mental effort to understand, build and operate a service; too many tools, undocumented APIs and manual steps raise it and slow delivery

> [!IMPORTANT] Golden paths are the easy default, not the only way: teams can go off-path with justification.

The developer portal

The Internal Developer Portal is the UI and API surface of a platform. Backstage (a CNCF incubating project) is the most common framework.

Software Catalog — Inventory of services, owners and dependencies
Templates — Self-service scaffolding
TechDocs — Docs-as-code
Plugins — An ecosystem of integrations

CNCF Platform Engineering Maturity Model

Starting point — No platform team; each team manages its own infrastructure
1. Provisional — A platform team exists and provides some shared services ad hoc
2. Operational — A defined platform with documented golden paths and SLAs
3. Scalable — Platform-as-product, self-service capabilities, measured developer adoption
4. Optimizing — The platform drives competitive advantage and an industry-leading developer experience

Team Topologies context

> [!TIP] In Team Topologies the platform team is one of four team types; it exists to reduce cognitive load on stream-aligned teams through X-as-a-service interfaces.

Key concepts

Internal Developer Platform (IDP): The full set of tools, workflows, and self-service capabilities provided by a platform team to development teams. Includes infrastructure provisioning, deployment pipelines, observability, and golden path templates.
Golden Path: An opinionated, documented, well-maintained set of tools and workflows for common use cases. A golden path for deploying a new microservice includes Helm chart templates, CI/CD setup, monitoring dashboards, and alerting in a single scaffolding command.
Thinnest Viable Platform: The smallest set of platform capabilities that provides measurable value. Platform teams should start thin and expand based on validated developer needs, not engineer judgment.
Backstage: CNCF graduated open-source IDP framework from Spotify. Core features: Software Catalog (service registry with ownership and dependency tracking), Software Templates (self-service scaffolding), TechDocs (Markdown docs rendered in the portal), and a plugin ecosystem.
Cognitive Load: Mental effort required to understand and operate a system. Platform engineering reduces cognitive load on stream-aligned teams by handling infrastructure complexity. Team Topologies identifies three types: intrinsic (inherent problem complexity), extraneous (accidental complexity from poor tools), germane (learning that builds expertise).
Platform SLOs: Service Level Objectives defined by the platform team for platform services: API availability, provisioning latency, support response time. Platforms are internal services — they need SLOs to be accountable to developer customers.

When to use it

Designing or evaluating an Internal Developer Platform for an engineering organization
Interview questions about platform engineering, developer experience, and team topologies
Explaining Backstage, golden paths, and platform-as-product to engineering leadership
Building a roadmap for a new platform team
Measuring platform engineering success with developer experience metrics