Platform Engineering & Internal Developer Platforms

The Platform Engineering page made the core argument: no developer can master the whole stack, so you package the complexity into a paved golden path and let people self-serve a correct setup. That page treated the idea as principle. This one treats it as a product category that exists in 2024–2025 — with named tools, a named org-design theory behind it, and a build-vs-buy decision that sinks more platform teams than any technical problem does. The thread is the same; the question now is how the industry actually ships it.

Platform vs Portal: the distinction that trips everyone

The vocabulary collapsed two different things into the same three-letter acronym, and untangling them is the first real step. IDP is used for both:

Term	What it is	Analogy
Internal Developer Platform	The underlying capabilities — the golden paths, the automation, the wiring that turns “I want a service” into a running, observable, secured deployment	The engine and drivetrain
Internal Developer Portal	The interface on top — a catalog, a UI, a place to find and trigger those capabilities	The dashboard and steering wheel

A portal with no platform behind it is a pretty catalog of buttons that don’t do anything. A platform with no portal is powerful plumbing nobody can find or use. You need both, and confusing them leads teams to buy a shiny portal, wire it to nothing, and wonder why adoption is zero. The platform is the paved road; the portal is the signpost that tells developers the road exists and lets them get on it.

   DEVELOPER
      │  "new service: payments-api"  /  "where do our runbooks live?"
      ▼
   ┌──────────── PORTAL (the interface) ────────────┐
   │  software catalog · templates · docs · scorecards│
   └───────────────────────┬─────────────────────────┘
                           ▼
   ┌──────────── PLATFORM (the capabilities) ────────┐
   │  scaffold repo · CI · deploy · observability ·    │
   │  secrets · policy — the golden path, automated    │
   └───────────────────────┬─────────────────────────┘
                           ▼
                running service, on the paved road

Backstage: the catalog-and-templates pattern

The best-known portal is Backstage, built inside Spotify to tame its own service sprawl, open-sourced in 2020, and donated to the CNCF (where it is an incubating project as of the mid-2020s — check its current maturity level before quoting it). Backstage matters because it crystallized two patterns the platform-engineering page described in the abstract into concrete, copyable features:

• The software catalog — a single registry of every service, who owns it, what it depends on, and how to reach its docs, dashboards, and on-call. It is the cure for the most basic platform failure: nobody knows what we run.
• Software templates — the literal golden path as a feature. A developer fills in a form (“service name, team, language”) and out comes a scaffolded repo with a CI pipeline, a Dockerfile, and observability already wired.

Under the hood — why Backstage is a framework, not an app

The subtlety that surprises adopters: Backstage is not a finished product you install and use. It is a framework you assemble. Out of the box it gives you the catalog model, the template engine, and a plugin architecture — but the plugins that connect it to your CI, your cloud, your incident tool are something you install, configure, or write, and then maintain across upstream upgrades. The catalog stays useful only if every service keeps a small metadata file (its catalog entry) accurate and current; let those rot and the catalog becomes a directory of services that no longer exist. Backstage gives you the shape of a portal. The content, the integrations, and the upkeep are yours. That is exactly where the build-vs-buy question lives.

Team Topologies: the theory underneath

The intellectual backbone of the whole discipline is Team Topologies, the 2019 book by Matthew Skelton and Manuel Pais. Its central claim is the one the platform-engineering page leaned on: cognitive load is a finite team resource, and you should organize teams to manage it. It gives the field its vocabulary:

Team type	Job
Stream-aligned	The product teams — own a slice of the business, ship features, and should carry the least incidental load
Platform	Build the internal platform as a product so stream-aligned teams self-serve
Enabling	Specialists who coach other teams over a hump, then leave
Complicated-subsystem	Own a part too specialized for everyone to learn (e.g. a video codec)

And three ways teams interact: collaboration (work closely, temporarily), X-as-a-Service (one team consumes another’s product with minimal back-and-forth — the platform relationship), and facilitating (an enabling team helps). The whole framework exists to minimize the cognitive load on stream-aligned teams so they spend their finite budget on the product, not the plumbing. A platform team that adds load — a portal so confusing it needs its own training course — has inverted its own reason to exist.

The platform’s job is subtraction, not addition

It is tempting to measure a platform team by what it adds: features shipped, plugins built, services in the catalog. The Team Topologies lens says measure what it subtracts — the cognitive load lifted off product teams. A platform that gives developers ten new powerful knobs has often made things worse, because now there are ten knobs to understand. The best golden path is the one a developer doesn’t have to think about at all.

The build-vs-buy cost nobody budgets for

Here is the decision that determines whether a platform initiative survives, and it is economic, not technical. You can build your portal/platform (typically on Backstage or by stitching together your own automation) or buy a commercial one (Spotify’s own hosted Backstage offering, or independent products such as Port, Cortex, OpsLevel, and Humanitec — all real, all evolving; verify their current shape before choosing). The honest framing:

• Build gives you total fit and no licence fee, but a platform is a product you must staff permanently — not a project you finish. Someone owns upgrades, plugins, the catalog’s accuracy, support, and onboarding, forever. The “free” open-source tool is free like a puppy.
• Buy gives you a faster start and someone else’s upgrade treadmill, but a licence cost, less fit, and a dependency on a vendor’s roadmap.

By the numbers — the “free” platform’s real price

Treat a self-built platform as the unit-economics problem it is. Suppose a platform team is 4 engineers at a fully-loaded cost of ~$200k/yr each (salary, benefits, overhead — a rough mid-2020s figure, varies widely by region):

   build cost  =  4 engineers × $200k/yr   =   $800k / yr, ongoing
                  (this never goes to zero — it's a running team)

   to be worth it, it must save more than $800k/yr in developer time:
     payback  =  $800k  ÷  (eng-hours saved × loaded hourly rate)

   if the org has 200 developers and the platform saves each
   ~2 hours/week of plumbing toil:
     200 devs × 2 hr/wk × 48 wk × ~$100/hr  ≈  $1.9M / yr saved
     → net positive, comfortably — IF adoption is real

The arithmetic only works at adoption. The same platform with 20 adopters instead of 200 saves ~$190k/yr against an $800k/yr cost — a large net loss. This is why the platform-as-a-product discipline insists adoption is the success metric: the build cost is fixed and ongoing, so the benefit side has to be earned by usage. A small org often cannot reach the adoption that justifies building, which is exactly when buy wins.

It actually happened — Spotify open-sources Backstage (2020), and a field is named

The platform-engineering wave has a real origin marker. Spotify had grown to thousands of services and the classic failure: nobody could find what existed or how to ship safely. Its internal portal, Backstage, was open-sourced in 2020 and accepted into the CNCF the same year, and within a few years a job title — “platform engineer” — and a discipline had consolidated around the pattern. Industry analysts (e.g. Gartner) went on to predict that a large majority of software organizations would stand up platform teams by the mid-2020s; treat the specific percentage as an analyst forecast, not a measured fact. The durable point is that an internal tool one company built to manage its own cognitive load became a named, foundation-backed discipline — the clearest sign yet that “encode operational knowledge once, expose it as a product” is where the industry is heading.

The thread

The manual, error-prone step this discipline removes is the same one the platform-engineering page named — every team assembling production-readiness by hand, slightly differently — but the frontier adds a second one: finding the right path at all. Before a portal, the knowledge of “how do we ship a service here, and what already exists?” lives in tribal memory, stale wiki pages, and the one senior engineer everyone DMs. A catalog and templated golden paths turn that into a self-service action. Production gets safer structurally: the secure, observable, well-operated setup becomes the default a developer is handed, and the question “do we already run something that does this?” gets an answer instead of a duplicate service.

The cost is the one the by-the-numbers box made concrete and unromantic: a platform is a permanently-staffed product whose value is entirely contingent on adoption. Build it and under-adopt it and you have spent $800k/yr to make things worse. The frontier hasn’t changed the trade — it has just made the tooling (Backstage, the commercial portals) and the theory (Team Topologies) good enough that the technical risk is low and the organizational risk is the whole game. The next frontier discipline puts a number on that risk directly: FinOps, where cost stops being Finance’s problem and becomes an engineering signal.

The architect’s lens

Five questions for an Internal Developer Platform:

• Why does it exist? Because the platform idea grew into a 2024–2025 product category — Internal Developer Platforms (the capabilities) and Portals (the interface) — with named tools (Backstage) and a theory (Team Topologies) behind it.
• What problem does it solve? Beyond assembling production-readiness by hand, it removes finding the right path at all: a software catalog answers “what do we run?” and templates make the golden path a fill-in-a-form action, so the secure, observed setup is the default a developer is handed.
• What are the trade-offs? A platform is a permanently-staffed product (Backstage is a framework you assemble and maintain — “free like a puppy”), and its entire value is contingent on adoption — build it, under-adopt it, and you’ve spent ~$800k/yr to make things worse.
• When should I avoid building it? When the org is too small to reach the adoption that justifies a permanent platform team — exactly when buy (a commercial portal) wins — or when a confusing portal would add cognitive load rather than subtract it.
• What breaks if I remove it? “How do we ship here, and what already exists?” goes back to tribal memory and stale wikis, and teams keep building duplicate, ungoverned snowflakes.

Check your understanding

1. Distinguish an Internal Developer Platform from an Internal Developer Portal. What goes wrong if you buy one without the other?
2. Name the two patterns Backstage crystallized, and explain why Backstage is described as a framework you assemble rather than a finished app.
3. What is the central claim of Team Topologies, and why does it say to measure a platform team by what it subtracts rather than what it adds?
4. Walk through the build-vs-buy economics. Why does the by-the-numbers calculation say adoption is the whole game, and when does “buy” win?
5. Using the book’s thread, what second manual step (beyond assembling production-readiness) does a portal remove, and how does that make production safer?

Show answers

1. The platform is the underlying capabilities — the automation and golden paths that turn a request into a running, observed, secured service (the engine). The portal is the interface on top — catalog, UI, templates (the dashboard). Buy a portal with no platform behind it and you get pretty buttons that do nothing; build a platform with no portal and you get powerful plumbing nobody can find or use. You need both.
2. The software catalog (every service, its owner, deps, and links — curing “nobody knows what we run”) and software templates (the golden path as a fill-in-a-form feature). It’s a framework because out of the box it gives only the catalog model, template engine, and plugin architecture; the integrations to your CI/cloud/incident tools and the catalog’s ongoing accuracy are yours to build and maintain across upgrades.
3. That cognitive load is a finite team resource and teams should be organized to manage it (stream-aligned teams should carry the least incidental load; platform teams exist to lift it via X-as-a-Service). So you measure the platform by the load it subtracts from product teams — adding ten powerful new knobs can make things worse, because each knob is more to understand.
4. A self-built platform is a permanently-staffed team (e.g. ~$800k/yr for 4 engineers), a fixed ongoing cost; the benefit (developer hours saved) scales with how many teams actually use it. At high adoption (200 devs saving ~2 hr/wk) it clears the cost comfortably; at low adoption it’s a large net loss. So adoption is the success metric, and buy wins when an org is too small to reach the adoption that justifies a permanent platform team.
5. It removes finding the right path at all — the tribal-memory, stale-wiki, ask-the-senior-engineer knowledge of “how do we ship here, and what already exists?” Turning that into a self-service catalog + templates makes the secure/observable setup the default a developer is handed, and answers “do we already run this?” so teams stop building duplicate, ungoverned snowflakes.