Backstage Pillar 1: The Software Catalog

The "Where Is Everything?" Problem

In a company with hundreds of microservices, finding information is a nightmare.

• "Who owns the payments-api service?"
• "Where is the documentation for the user-auth library?"
• "Is the shipping-worker service production-ready or experimental?"
• "What does inventory-service depend on — and if it goes down, what breaks?"

Developers rely on tribal knowledge or outdated wikis to answer these questions. New engineers spend their first weeks just mapping the landscape. Senior engineers become human search engines, constantly interrupted to answer "who owns X?"

The Centralized Directory

The Backstage Software Catalog is a centralized, searchable directory of every piece of software in your organization — services, websites, libraries, data pipelines, ML models, and more.

It does not just list names; it manages metadata defined in a catalog-info.yaml file that lives right inside the code repository. This is the key insight: the metadata travels with the code, so it stays accurate. A service's catalog entry typically includes:

• Owner: The team responsible for it (e.g., group:team-checkout).
• Lifecycle: Is it experimental, production, or deprecated?
• Type: Is it a service, library, website, or pipeline?
• Relationships: What APIs does it provide? What other components does it depend on?

Here is a minimal catalog-info.yaml for a service:

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: payments-api
  description: Handles all payment processing for the checkout flow.
  annotations:
    github.com/project-slug: acme-corp/payments-api
    pagerduty.com/integration-key: abc123xyz
spec:
  type: service
  lifecycle: production
  owner: group:team-checkout
  dependsOn:
    - component:fraud-detection-service
    - resource:payments-postgres-db

When Backstage ingests this file, the payments-api service appears in the catalog with its owner, lifecycle status, and dependency graph automatically populated.

The Dependency Graph

One of the most powerful features of the catalog is the System Diagram — a visual graph showing how components relate to each other. When an incident occurs, engineers can immediately see what depends on the failing service, dramatically reducing the time to understand blast radius.