Internal Developer Platform Design
What Is an Internal Developer Platform
An Internal Developer Platform (IDP) is everything your platform team stitches together so developers can ship faster with fewer headaches. It is not a single tool you install and walk away from. Think of it as a curated set of self-service capabilities that hide infrastructure complexity but still let engineers peek under the hood when they need to debug or optimize something.
The Three-Layer Model
Developer Interface Layer. This is what engineers touch every day: a developer portal (Backstage, Port, Cortex), a CLI, or a set of GitHub Actions workflows. This layer should be opinionated about how things get done, but transparent about what is happening underneath. If developers cannot tell what the platform just did on their behalf, you have hidden too much.
Integration & Orchestration Layer. APIs, webhooks, and controllers that wire your tools together. Argo CD reconciles desired state here. Crossplane provisions cloud resources. Policy engines like OPA enforce guardrails. This layer translates developer intent into infrastructure reality, and it is where most of the hard engineering happens.
Resource Layer. The actual compute, storage, networking, and observability primitives. Kubernetes clusters, databases, message queues, monitoring stacks. The platform does not replace any of these. It wraps them with sensible defaults and self-service provisioning so developers stop filing tickets to get a database.
Build vs Assemble
The biggest trap platform teams fall into is building from scratch. The strategy that actually works is assembly: pick best-in-class open-source tools, configure them with opinionated defaults, and glue them together with thin integration code. Spotify did not build Backstage as a monolith. They built a plugin framework and let teams extend it. Your IDP should follow the same principle. Write the glue, not the engine.
Product Thinking for Platforms
Treat your platform like a product with real users. Conduct user interviews with developers every quarter. Track NPS or CSAT scores. Maintain a public roadmap. Run betas before forcing migrations. The teams that skip product management end up with a platform nobody uses and a mandate nobody follows. You can spot these teams because their developers have already built shadow infrastructure to work around the "official" platform.
When to Start
You probably need an IDP when you have more than 5 teams and you keep seeing the same infrastructure patterns copy-pasted across repositories. Start small. Pick the single highest-friction workflow (usually environment provisioning or CI/CD setup) and make it self-service. Expand only after you have validated adoption on that first capability. If nobody uses the first thing you build, building a second thing will not help.
Key Points
- •An IDP is a product, not a project. It requires product management, user research, and iterative delivery.
- •Layer architecture: developer interface (portal/CLI), integration layer (APIs/webhooks), resource layer (infrastructure primitives)
- •Build the thinnest possible platform that solves real friction. Resist building abstractions nobody asked for.
- •Assemble from existing tools (Backstage, Argo, Crossplane) rather than building from scratch. Composition over creation.
- •Measure success by developer adoption rate and time-to-production, not by number of features shipped
Common Mistakes
- ✗Building an IDP as a top-down mandate without understanding actual developer pain points. Always start with user research.
- ✗Over-abstracting infrastructure so developers lose visibility into what is actually running underneath
- ✗Treating the platform as a one-time project rather than a continuously evolving product with a roadmap
- ✗Forcing adoption through policy instead of making the platform genuinely easier than the alternative