Platform Engineering 06 - Developer Portals and Service Catalogs

The "Where Do I Find That?" Problem

As organizations grow, information starts to scatter. Documentation lives in Confluence, runbooks in Google Docs, API specs in Swagger, and deployment details in a wiki that nobody has updated since 2023. The most critical knowledge ends up existing only inside specific people's heads.

When a new developer joins this kind of environment, they spend their first two weeks just figuring out where things are. A developer portal is a systematic answer to this problem — it provides a single point of access for every service, tool, and document in the organization.

What a Portal Does

A developer portal serves as the front door to the platform. Its core purpose is making services, owners, documentation, health status, and tools discoverable from a single location. What previously required visiting twenty different places is consolidated into one. That consolidation is deceptively simple, but the impact on developer productivity is substantial.

Backstage

Backstage is a developer portal framework that Spotify built internally and open-sourced in 2020. It is currently the most widely adopted option, but it is important to understand that Backstage is not a finished product — it is a framework that each organization customizes to fit its own needs.

Backstage's core functionality is composed of three pillars.

The first is the Service Catalog, which serves as a registry for every component in the organization. Services, libraries, APIs, and pipelines are all registered, with ownership, lifecycle status, and metadata tracked for each.

The second is Software Templates. By selecting a template, developers receive a production-ready skeleton with CI/CD, monitoring, and documentation pre-configured. This eliminates the old pattern of copying an existing repository and deleting the parts that are not needed to start a new project.

The third is TechDocs, which renders Markdown files from repositories directly within the portal. Because documentation lives right next to the code, it avoids the common problem of documentation drifting out of sync with the actual implementation.

Plugins

The real strength of Backstage lies in its plugin ecosystem. Kubernetes visibility, CI/CD status from GitHub Actions, Jenkins, or ArgoCD, cloud cost monitoring, API documentation, incident management, and security scanning can all be added through plugins.

Rather than purchasing a monolithic tool, organizations can compose a portal from the specific capabilities they actually need. This composability is what makes the framework adaptable across very different organizational contexts.

Alternatives

Backstage offers the highest degree of flexibility, but that flexibility comes with a corresponding engineering investment. SaaS products trade customization breadth for faster time-to-value — a tradeoff that makes sense depending on the organization's capacity and priorities.

When You Need One

Does every organization need a developer portal? Not necessarily. If you have 5 services and 10 developers, a well-maintained README is more than sufficient.

However, when services exceed 30 and ownership starts becoming ambiguous, when onboarding takes more than a week just for context-gathering, when teams duplicate work because they cannot find existing solutions — these are the signals that the pain is real. That is the point at which investing in a portal begins to make sense.

A developer portal transforms tribal knowledge into structured, searchable, always-current information. Getting it right is not easy, but when it works, the difference is unmistakable.

In the next post, we look at treating the platform as a product.