# Internal Developer Platforms
All Internal Developer Platforms notes →1 — The Rise of Internal Developer Platforms
Traces why IDPs emerged from the developer productivity crisis and clarifies how the term relates to, and differs from, platform engineering more broadly.
2 — What Is an Internal Developer Platform?
Defines an IDP by its consumers, providers, and boundaries rather than by any specific tool stack.
3 — Platform Goals
Lays out the goals, self-service, consistency, reliability, security, developer experience, and operational excellence, every later Part in this book is designed against.
4 — Build vs Buy
A decision framework for choosing between a custom-built platform, a commercial IDP product, and composing one from the open-source ecosystem.
1 — IDP Reference Architecture
A reference architecture for an IDP spanning logical layers, physical deployment topology, and the interfaces between them.
2 — Platform Building Blocks
Enumerates the building blocks, portal, catalog, templates, APIs, automation engine, identity, and observability, that recur across every IDP implementation, each expanded in its own later Part.
3 — Control Plane vs Data Plane
Separates what the platform's control plane decides from what actually executes on the runtime plane, and why conflating the two is a common architecture mistake.
4 — Platform Domains
Maps the platform's scope across infrastructure, application, security, networking, data, and observability domains.
1 — Self-Service Philosophy
The philosophy behind self-service: removing the platform team as an approval bottleneck so engineering autonomy scales independently of platform headcount.
2 — Self-Service Workflows
Catalogs the concrete workflows, environment provisioning, service creation, infrastructure and access requests, deployments, a self-service platform must expose end to end.
3 — Service Provisioning
Covers provisioning mechanics from infrastructure and runtime through resource lifecycle management, and where approval workflows still belong.
4 — Platform APIs
API design principles for the resource, infrastructure, and event APIs that make self-service programmable rather than portal-only.
1 — What Are Golden Paths?
Defines golden paths as opinionated, standardized workflows, and is honest about their benefits and their limitations.
2 — Designing Golden Paths
A design process for golden paths that encodes technology, architecture, operational, and security standards into a single opinionated path.
3 — Golden Path Examples
Worked golden-path examples across six common workload shapes: new microservice, API service, scheduled job, event-driven service, frontend application, and data pipeline.
4 — Maintaining Golden Paths
How a golden path stays alive after launch: versioning, deprecation, and incorporating user feedback without breaking every service that already adopted it.
1 — Why Software Catalogs Matter
Makes the case for a software catalog as the discoverability, ownership, documentation, and governance backbone of a platform.
2 — Service Catalog Design
Catalog design choices, entity types, metadata schema, ownership fields, and relationship modeling, that determine whether the catalog stays trustworthy at scale.
3 — Catalog Data Model
A concrete data model spanning services, APIs, libraries, systems, components, and resources as first-class catalog entities.
4 — Ownership Models
Ownership models, team, domain, business-unit, and product-based, and the trade-offs each makes for accountability at scale.
1 — Introduction to Backstage
Introduces Backstage's architecture, core concepts, and plugin ecosystem as the most widely adopted open-source IDP foundation.
2 — Backstage Software Catalog
How Backstage implements the software catalog concepts from Part V: entity descriptors, catalog-info.yaml, and the catalog processing pipeline.
3 — Backstage Scaffolder
Backstage's Scaffolder plugin as the software-template execution engine: how a template becomes a running service.
4 — Backstage TechDocs
TechDocs as Backstage's docs-as-code layer: how documentation stays attached to its owning entity in the catalog.
5 — Backstage Plugins
Surveys the Backstage plugin ecosystem, Kubernetes, GitHub, Argo CD, Grafana, PagerDuty, Jenkins, and where a custom plugin becomes necessary.
6 — Extending Backstage
Extending Backstage beyond off-the-shelf plugins: custom plugin development, component overrides, authentication providers, and branding.
1 — Why Templates Matter
Why software templates, not documentation, are the mechanism that actually makes a golden path get followed.
2 — Service Templates
Service-level templates that scaffold a new microservice with the organization's standards already applied.
3 — Infrastructure Templates
Infrastructure-level templates for provisioning the cloud resources a service depends on alongside its code scaffold.
4 — Organization Standards
How organization-wide standards, language versions, CI pipelines, security baselines, get encoded into templates rather than enforced after the fact.
5 — Template Versioning
Versioning strategy for templates so that already-scaffolded services can adopt improvements without a breaking migration.
6 — Template Governance
Governance over who can publish a template, how it gets reviewed, and how deprecation of an old template is communicated.
1 — API-Driven Platforms
Why every platform capability should be reachable by API first, with the portal UI as a client of that API rather than the source of truth.
2 — Event-Driven Automation
Event-driven automation, reacting to catalog and provisioning events rather than polling, as the backbone of platform responsiveness.
3 — Workflow Engines
Workflow engines for orchestrating multi-step platform operations (provision, configure, register, notify) with retries and visibility.
4 — Platform Orchestration
Orchestration patterns that coordinate multiple platform capabilities, catalog, templates, provisioning, access, into a single self-service action.
5 — Infrastructure Automation
Infrastructure automation, Terraform/Crossplane-style provisioning, as the execution layer behind self-service infrastructure requests.
6 — Policy Automation
Policy-as-code automation (OPA/Kyverno-style admission and provisioning guardrails) that enforces governance without a manual approval queue.
1 — Understanding Developer Experience
Defines developer experience as a first-class platform outcome, not a soft add-on to infrastructure capability.
2 — Measuring DevEx
Measurement approaches for DevEx, from qualitative surveys to the quantitative signals a platform can instrument directly.
3 — Reducing Cognitive Load
Cognitive load reduction as a design goal: what a golden path and a good abstraction are actually optimizing for.
4 — Developer Journeys
Mapping the end-to-end developer journey, from first day on a team to shipping a change to production, to find where the platform actually helps or hinders.
5 — Documentation as a Platform Feature
Treats documentation as a platform feature with its own ownership and freshness contract, not an afterthought bolted onto the wiki.
6 — Platform UX Design
UX design principles for a developer portal, where the user is an engineer under time pressure, not a general consumer audience.
1 — Identity and Access Management
IAM foundations for a platform: how identity, group membership, and service accounts map onto catalog and provisioning permissions.
2 — Platform Security
Security responsibilities that belong to the platform itself, distinct from the security posture of the services running on top of it.
3 — Platform Policies
Policy definition and enforcement points across the platform: what gets checked at request time versus at admission time.
4 — Platform Guardrails
Guardrails as the difference between a self-service platform and an ungoverned free-for-all: constraints that don't require a human in the loop.
5 — Compliance by Default
Building compliance requirements into golden paths and templates so services are compliant by construction, not by later audit.
6 — Auditability
Audit trail requirements for platform actions: who provisioned what, when, and under which approval.
1 — Platform Operations
Day-two operational responsibilities for running the platform itself as a production system.
2 — Platform Reliability
Reliability engineering applied to the platform's own control plane: the platform going down blocks every team behind it, not just one service.
3 — Platform Observability
Observability requirements for the platform's own control plane and workflows, distinct from the observability the platform provides to its tenants.
4 — Platform Support Models
Support models for a platform team, from ticket queues to embedded support to fully self-service, and when each is appropriate.
5 — Incident Management
Incident management specific to platform outages, where the blast radius is every consuming team rather than a single service's users.
6 — Platform Evolution
How a platform evolves after initial adoption: deprecating capabilities, migrating tenants, and avoiding a permanent legacy tax.
1 — Adoption Metrics
Adoption metrics, active users, service coverage, template usage, self-service rate, that show whether the platform is actually being used, not just built.
2 — Productivity Metrics
Productivity metrics, time to first deployment, lead time, developer wait time, deployment velocity, the platform is ultimately accountable for moving.
3 — Platform Reliability Metrics
Reliability metrics for the platform's own APIs and workflows: availability, latency, workflow success rate, provisioning success.
4 — Developer Satisfaction
Developer satisfaction measurement, surveys, NPS, structured feedback loops, as the qualitative complement to the quantitative metrics above.
1 — Portal Without Automation
The anti-pattern of a developer portal that's a pretty UI over the same manual, ticket-driven fulfillment underneath.
2 — Platform Team as Ticket Queue
How a platform team backslides into being a ticket queue with extra steps, and why that failure mode undoes the entire self-service premise.
3 — Too Many Golden Paths
The failure mode of proliferating golden paths until being opinionated becomes as confusing as having no standard at all.
4 — Ignoring Developer Feedback
What happens when a platform team stops listening to the engineers it serves, and the trust cost of getting this wrong once.
5 — Over-Engineered Platforms
Over-engineering, building for hypothetical scale or hypothetical tenants before real ones exist, as a platform-specific waste pattern.
6 — Poor Adoption
Diagnosing poor adoption after launch: is it a discoverability problem, a trust problem, or a real capability gap.
1 — Multi-Team Platforms
Platform design considerations once dozens of independent teams, not one pilot team, depend on the same golden paths.
2 — Multi-Cloud IDPs
IDP design for organizations spanning multiple cloud providers, where the catalog and templates must abstract over provider differences.
3 — Multi-Region Platforms
Multi-region platform design: where the control plane lives relative to the regions it provisions into.
4 — Domain-Oriented Platforms
Domain-oriented platform structuring, where catalog ownership and golden paths are organized around business domains rather than one flat namespace.
5 — Platform Product Management
Product management discipline applied to an internal platform: roadmaps, prioritization, and internal stakeholder management.
6 — Scaling an Internal Developer Platform
What has to change structurally, team topology, catalog scale, template governance, as an IDP scales from one pilot team to the whole engineering org.
1 — Internal Developer Platform System Design
A worked IDP system-design prompt at the Staff/Principal bar: requirements, architecture, and the trade-offs an interviewer will probe.
2 — Designing Self-Service Platforms
A self-service-focused design exercise, distinct from the general IDP prompt, that probes provisioning workflows and approval boundaries specifically.
3 — Backstage Architecture Interview Questions
A question bank on Backstage's own architecture, catalog processing, scaffolder internals, plugin boundaries, for platform-engineering-flavored interviews.
4 — Golden Path Design Exercises
Whiteboard exercises for designing a golden path from scratch for a given workload shape under interview time pressure.
5 — Platform API Design Interviews
API design interview practice specific to platform resource, infrastructure, and event APIs.
6 — Staff/Principal Platform Engineering Case Studies
End-to-end case studies calibrated to the Staff/Principal (L6/L7) bar for platform engineering interviews.
1 — IDP Reference Architecture
Quick-reference version of the IDP reference architecture from Part II, for lookup without re-reading the full chapter.
2 — Backstage Entity Reference
Quick reference for Backstage's built-in entity kinds (Component, API, System, Domain, Resource, User, Group) and their required fields.
3 — Software Catalog Schema Examples
Worked catalog schema examples for the entity types introduced in Part V, as copy-adaptable starting points.
4 — Platform API Design Patterns
A pattern catalog for platform API design: pagination, idempotency keys, async operation status, specific to provisioning-style APIs.
5 — Developer Journey Mapping Templates
Blank developer-journey mapping templates for running the exercise from Part IX with a real team.
6 — IDP Capability Maturity Model
A capability maturity model for scoring an IDP's coverage across self-service, golden paths, catalog, and DevEx.
7 — Platform Engineering Reading List
A curated reading list of books, papers, and engineering blogs that shaped the practice of platform engineering and IDPs.
Internal Developer Platforms
A book-shaped table of contents for Internal Developer Platforms: IDP fundamentals, architecture, self-service, golden paths, software catalogs, Backstage, templates, platform APIs and automation, developer experience, governance, operations, success metrics, anti-patterns, enterprise scale, and MAANG interview preparation — cross-linking existing platform-engineering-fundamentals/sre/observability notes instead of duplicating them.