Stage 7 · Master
Developer Portal & Software Catalog
Software Catalog Design
Model entities (services, APIs, resources, systems), relationships, and metadata. Define ownership, lifecycle, and dependencies.
Entity Model
The software catalog is a graph database of your software ecosystem. Entities (nodes) represent software components; relationships (edges) represent dependencies, ownership, and hierarchy. Backstage's entity model is the industry standard.
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
name: payment-service
description: "Processes customer payments"
annotations:
github.com/project-slug: myorg/payment-service
backstage.io/techdocs-ref: dir:.
backstage.io/kubernetes-id: payment-service
backstage.io/kubernetes-namespace: payments
labels:
team: payments
platform/capabilities: postgresql,kafka
tags:
- go
- microservice
- payments
spec:
type: service
lifecycle: production
owner: team:payments
system: payments-system
providesApis:
- payment-api
consumesApis:
- user-api
dependsOn:
- resource:postgresql-payments
- resource:kafka-cluster
Every service entity has type, lifecycle, owner, system, and explicit dependencies. This enables impact analysis, on-call routing, and compliance scoring.
Entity Kinds
| Kind | Purpose | Examples |
|---|---|---|
| Component | Software artifact: service, library, website, ML model | payment-service, user-lib, marketing-site |
| API | Contract between components (OpenAPI, AsyncAPI, GraphQL) | payment-api, user-api |
| Resource | Infrastructure: database, bucket, queue, cluster | postgresql-payments, s3-assets, kafka-cluster |
| System | Collection of components working together | payments-system, identity-system |
| Domain | Business domain grouping systems | finance, identity, notifications |
| Group | Team or organizational unit | team:payments, team:platform |
| User | Individual person | alice, bob |
| Location | Physical or logical location | aws:us-east-1, datacenter:nyc |
Relationships
Relationships enable powerful queries: 'What services depend on this database?' 'Who owns the downstream services of payment-api?' 'What's the blast radius of this change?'
# Ownership
spec:
owner: team:payments
# System membership
spec:
system: payments-system
# API contracts
spec:
providesApis: [payment-api]
consumesApis: [user-api, fraud-api]
# Infrastructure dependencies
spec:
dependsOn:
- resource:postgresql-payments
- resource:kafka-cluster
# Deployment topology
spec:
deployedTo:
- resource:k8s-cluster-prod
- resource:k8s-cluster-staging
# Library dependencies (for libraries)
spec:
dependsOn:
- component:shared-go-lib
Explicit relationships power impact analysis, on-call routing, and compliance checks.
Essential Metadata
- Annotations: Machine-readable pointers (GitHub repo, techdocs, Kubernetes, ArgoCD, PagerDuty)
- Labels: Queryable tags (team, language, capabilities, environment, compliance)
- Tags: Human-readable categories (go, microservice, payments, critical)
- Links: External URLs (dashboard, runbook, repo, Slack, Jira)
Lifecycle & Ownership
| Lifecycle | Meaning | Portal Behavior |
|---|---|---|
| experimental | Early stage, not for production | Hidden from general search, no scorecard |
| production | Actively maintained, production-ready | Full scorecard, on-call required, SLOs |
| maintenance | Minimal maintenance, no new features | Scorecard shows warnings, migration path |
| deprecated | Should not be used, migration in progress | Prominent deprecation banner, migration guide link |
| end-of-life | No longer supported | Archived, read-only, removed from search |
Every entity MUST have an owner (team). No owner = no accountability = no one fixes it when it breaks. Enforce at scaffold time and admission control.
Data Ingestion
- GitOps: Entity YAML files in repo (
.catalog/entity.yaml) → synced via GitHub App - Static: YAML files in catalog repo (for infrastructure, teams, domains)
- Discovery: Kubernetes controller annotates resources → creates/updates entities
- API: CI/CD, ArgoCD, Terraform push entity updates via REST/GraphQL
- Plugins: Backstage plugins for GitHub, GitLab, Kubernetes, ArgoCD, PagerDuty, etc.
Begin with: services (from GitHub repos), teams (from GitHub org), systems (manual). Add APIs, resources, dependencies incrementally. Don't model everything upfront.
Mark this lesson complete to store local progress and unlock a cleaner resume path the next time you visit.