Your IDP is the face of your organisation, not a scaffolding tool

Internal Developer Platforms — Backstage being the obvious one — usually get sold on bootstrapping: click a template, scaffold a new service, get a repo with CI already wired up. That’s a nice party trick. It’s also the least interesting thing an IDP does, because you scaffold a service maybe a handful of times a year.

The real value shows up somewhere else entirely: when the IDP becomes the face of your organisation — the single, accurate map of everything you run, who owns it, what it depends on, and where the docs are.

The catalog is the product

Backstage’s software catalog models your world as components, systems, APIs, resources and the people who own them. On paper that’s just a directory. In practice it’s the thing that answers the questions teams waste hours on every week:

• Who owns this service?
• What breaks if I change this API?
• Where are the docs and the runbook?
• Who’s on call for it?

A catalog that can answer those reliably is worth more than any amount of scaffolding. The catch is the word reliably.

Accuracy is enforced, not hoped for

Every IDP I’ve seen fail, failed the same way: the catalog rotted. Someone stood it up, it was great for a quarter, then ownership drifted, services got renamed, half the entries pointed at dead repos, and people stopped trusting it. A map you can’t trust is worse than no map.

The fix is to stop treating catalog metadata as documentation and start treating it as code with gates. The catalog-info.yaml lives next to the service, and you enforce it the same way you enforce everything else — through GitOps and CI:

• A component can’t merge without declaring an owner, a lifecycle and a system.
• Dependencies and the APIs it provides or consumes are declared, and checked.
• Docs are wired in as TechDocs so they live with the code and can’t silently go stale.

Once metadata is a merge requirement rather than a good intention, the catalog stops drifting. It becomes a source of truth because the pipeline won’t let it become anything else — the same discipline that makes GitOps trustworthy for infrastructure, applied to the map of your org.

Then it gets genuinely powerful

Map it all properly — components, systems, ownership, APIs, TechDocs, dashboards, runbooks — and the IDP turns into your organisation’s nervous system. Onboarding stops being tribal knowledge. Incident response starts with “the catalog already told me who owns this and where the runbook is.”

And here’s where it gets interesting: once your platform is a complete, accurate, machine-readable map, you can put an MCP in front of it and hand it to an AI agent. Developer self-service stops being a portal full of forms and becomes a conversation — “scaffold a service in the payments system that talks to the ledger API,” “who owns this and what depends on it,” “spin me a dev environment for X” — grounded in the IDP’s real data and guarded by its real ownership rules. The IDP becomes the context layer that makes AI self-service safe instead of a guessing game.

Worth being honest about

Backstage is a framework, not a product you switch on — it takes real investment to build and run, and it earns its keep slowly. Start with ownership and accuracy before any shiny plugin. An IDP with a rotting catalog is just a nicer-looking wiki.

But get the metadata discipline right and you don’t just have a developer portal. You have an honest, queryable map of your whole organisation — exactly the foundation everything else, including AI, needs.

I hold the Certified Argo Project and Backstage Associate certifications, and this is the kind of platform foundation I help teams build. Get in touch.