“Who owns this service?” shouldn’t require Slack archaeology. Backstage gave us a single place for service catalogues, documentation, and developer workflows. The portal became the starting point for everything.

The Problem

Tribal knowledge dominated. Which team owns the payment service? Where’s the runbook for database failover? What APIs does the recommendation engine expose? Answers existed in someone’s head, scattered wikis, or buried Slack threads.

Onboarding was painful. New developers spent weeks learning where things lived. Every team had different documentation approaches, different repository structures, different ways of defining ownership.

Tooling sprawled. CI in GitHub Actions. Monitoring in Grafana. Logs in Elasticsearch. Deployments in ArgoCD. Each tool had its own URL, authentication, and mental model. Context-switching consumed developer time.

Our Solution

Backstage as the developer portal. Spotify’s open-source platform provided the foundation. We customised it for our environment rather than building from scratch.

Software catalogue defined every service. YAML files in repositories describe ownership, dependencies, documentation links, and API specifications. The catalogue aggregates this into a searchable interface.

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: payment-service
  description: Handles payment processing
spec:
  type: service
  owner: team-payments
  lifecycle: production
  dependsOn:
    - component:user-service

TechDocs integrated documentation. Markdown in repositories renders in Backstage. Documentation lives with code, versioned together, but presented in a unified interface.

Plugin ecosystem connected existing tools. Kubernetes, GitHub Actions, PagerDuty, Grafana—plugins surface relevant information in service context. No tool-hopping to understand a service’s status.

Software Templates standardised creation. Need a new microservice? Use the template. It creates the repository, CI pipeline, Kubernetes manifests, and Backstage catalogue entry. Golden paths enforced automatically.

The Benefits

Time to first commit for new developers dropped dramatically. The portal shows where everything is, who to ask, and how to get started. Onboarding became self-service.

Service ownership is explicit and discoverable. Incidents route to correct teams immediately. No more guessing or escalation chains to find owners.

Documentation improved through proximity. Developers update docs alongside code because they’re in the same repository. Out-of-date documentation became less common.

Cognitive load decreased. One URL to start any investigation. Context about a service lives together rather than scattered across tools.

Backstage isn’t magic—it requires investment in catalogue maintenance and plugin configuration. But the return on that investment compounds as the organisation grows.