Developer Portal & IDP

A single, self-service web application that gives engineers access to the tools, services, documentation, and workflows they need — replacing tribal knowledge and Slack-based discovery with a structured, searchable interface. Reduces cognitive load by surfacing the software catalog, golden paths, deployment pipelines, and on-call schedules in one place.

"Before the IDP, onboarding a new service required reading 12 Confluence pages, asking three Slack channels, and tracking down the platform team. The IDP consolidated this: new service creation, CI pipeline setup, monitoring configuration, and TechDocs are all triggered through a single wizard that completes in 20 minutes."

An open-source developer portal framework built and open-sourced by Spotify, now donated to the CNCF. Provides a plugin-based architecture for building an IDP — including a software catalog, TechDocs documentation system, software templates, and a rich plugin ecosystem for integrating CI/CD, cloud, monitoring, and on-call tools.

"We adopted Backstage as our IDP foundation rather than building from scratch — the plugin ecosystem meant we could integrate PagerDuty, ArgoCD, Datadog, and GitHub Actions in 2 weeks rather than 6 months of custom development. The Spotify-originated software catalog model mapped well to our microservice architecture."

A registry of all software components in an organisation — services, libraries, pipelines, websites, APIs — with metadata about ownership, dependencies, documentation, deployment status, and on-call contacts. In Backstage, the catalog is driven by YAML entity descriptor files maintained in source control by owning teams.

"Our software catalog has 847 registered entities: 340 services, 210 libraries, 180 pipelines, and 117 websites. Every entity shows the owning team, on-call engineer, deployment status, documentation link, and open incidents. New engineers find the service they need in seconds rather than asking in Slack."

A visual framework for communicating technology choices and standards within an organisation — categorising technologies into four rings: Adopt (use confidently), Trial (explore with caveats), Assess (investigate), Hold (avoid or migrate away from). Pioneered by ThoughtWorks and widely implemented in engineering organisations via Backstage.

"Our tech radar publication last quarter moved GraphQL from Trial to Adopt and Kubernetes from Assess to Adopt. It also moved three legacy technologies to Hold — this gives every engineer clear guidance without requiring them to track dozens of ADRs. The radar is reviewed and published by the Architecture Council quarterly."

An opinionated, pre-configured route to creating and deploying a new service or component — a template that includes the recommended language, framework, CI/CD setup, monitoring, logging, and security baseline. Golden paths reduce decision fatigue and cognitive load by making the right way also the easy way.

"Our golden path for a new Node.js service provides: a Backstage template that scaffolds the repo, CI pipeline, Dockerfile, Helm chart, Datadog dashboards, PagerDuty escalation policy, and TechDocs skeleton in one wizard. A new service is production-ready in 45 minutes rather than 2 days of manual configuration."

A team that builds and maintains the internal platform — the toolchain, abstractions, and infrastructure that other teams use to build and operate their products. In Team Topologies vocabulary, the platform team is an enabling team that reduces cognitive load for stream-aligned teams by providing self-service capabilities.

"The platform team owns the golden paths, the IDP, the CI/CD framework, the observability stack, and the Kubernetes clusters. Their mission is to make the right way the easy way — measuring success by developer NPS scores and the time it takes a new engineer to deploy their first production change."

From Team Topologies: a team organised around a continuous flow of work aligned to a business domain or user journey — owning end-to-end delivery of a product or service with minimal hand-offs to other teams. The primary team type; platform, enabling, and complicated-subsystem teams exist to support stream-aligned teams.

"We reorganised from functional silos (frontend, backend, QA, ops) into stream-aligned teams: each owns a customer-facing product area end-to-end. The checkout team owns frontend, backend, database, and deployment for the checkout journey — this eliminated the hand-off delays that were adding 3 days to every feature release."

The ability for engineers to provision resources, configure services, and access tooling without requiring manual intervention from a platform or operations team. A core goal of internal developer portals — eliminating ticket-driven workflows that create bottlenecks and frustration. Measured by how many standard tasks require zero platform team involvement.

"We track the self-service ratio: what percentage of standard requests (new service, database, environment, access) are completed without a ticket to the platform team. We are at 78% today — up from 23% a year ago. The remaining 22% are non-standard requests that will drive the next phase of the portal roadmap."

In a platform engineering context, the total mental effort required for a stream-aligned team to understand and use the underlying platform infrastructure. Reducing cognitive load is the primary mandate of platform teams — the best platform is one that a developer can use correctly without deep infrastructure knowledge.

"We measured cognitive load through quarterly developer surveys and onboarding time analysis. Before the platform investment, new engineers needed 8 weeks to feel confident deploying and monitoring their service. After the golden paths, IDP, and TechDocs work, that dropped to 3 weeks — a quantified cognitive load reduction."

A Backstage plugin and documentation system that renders Markdown documentation stored alongside source code (docs-as-code) directly within the developer portal — making technical documentation discoverable in the same place as the software catalog entries it describes. Follows the "docs like code" principle.

"TechDocs let us sunset the fragmented Confluence wiki by moving all service documentation into the repo alongside the code. Docs are now versioned with the service, reviewed in PRs alongside code changes, and rendered in Backstage directly on the service catalog page — documentation and service are always in sync."

In Backstage, a YAML-defined workflow that scaffolds a new software component from a template — prompting the user for inputs (service name, owner, language) and then creating a repository, CI pipeline, catalog entry, and any other resources defined in the template. The mechanism by which golden paths are implemented.

"Our 'Python microservice' software template creates: a GitHub repo from a skeleton, a GitHub Actions workflow for CI/CD, a Kubernetes Helm chart, a Datadog monitor, a PagerDuty service, and a Backstage catalog entry — all pre-configured with the team's name as the owner. The entire setup runs in 8 minutes."

A registered item in the Backstage software catalog, described by a YAML `catalog-info.yaml` file committed to source control. Entity kinds include: Component (service, website, library), API (OpenAPI, AsyncAPI), Resource (database, S3 bucket), System (a collection of components), and Domain (business capability grouping).

"Every service in our organisation has a `catalog-info.yaml` file at the root of its repository. When merged to main, it auto-registers the entity in Backstage. The entity file declares: kind, owner, system membership, API dependencies, and links to dashboards and runbooks — all surfaced on the catalog page without manual portal management."