Backstage, Spotify’s open-source internal developer portal, has become the default answer to “how do we catalog our services?” That’s understandable — it’s well-documented, actively maintained, and used at scale by recognizable companies. But recommendation bias toward the most prominent tool in a category is worth examining.
Backstage is a platform, not a tool. It provides a framework for building internal developer portals, with service catalog, TechDocs, and a plugin ecosystem. For an organization of 500+ engineers wanting to build a full internal platform, it’s the right choice. For a team of 15–50 engineers that needs to know what calls what and who owns it, it’s significant infrastructure complexity in service of a documentation problem.
What Backstage Actually Requires
- A running Node.js backend
- A PostgreSQL database
- Authentication configuration (OAuth, SAML, or similar)
- An infrastructure environment to deploy and maintain it
- Ongoing plugin configuration and updates
- An engineer (often a platform team) to own it
This is a real infrastructure project. Teams at large companies have platform teams whose job is to run Backstage. Smaller teams are asking a product or backend engineer to absorb this on top of their existing responsibilities. That’s often where Backstage adoption stalls: half-configured, maintained by no one, used by no one.
What Most Teams Actually Need
When you ask engineering teams what they want from a service catalog, the core use cases are:
- See all services and their owners
- See what depends on what (dependency graph)
- Filter by team, tech stack, or status
- Share a specific view with a link
These are visualization and query features, not backend features. They don’t require a database. They don’t require authentication infrastructure. They require a structured service definition format (YAML) and a static visualization layer that reads it.
The Lightweight Alternative Pattern
Define services in YAML. Commit to the repository. Build a static visualization layer that reads the YAML and renders an interactive dependency graph. Deploy to any static host. Total infrastructure: zero. Total maintenance: YAML file updates on dependency changes.
This pattern covers the four core use cases above. It doesn’t cover Backstage’s more advanced features: TechDocs, scaffolder, custom plugins, deep GitHub integrations. If you need those, Backstage is the right tool. If you need service dependency visualization, you probably don’t need all of that.
Service Map is the lightweight alternative: YAML service definitions, interactive dependency graph, filter-by-team and tech-stack, shareable URLs, self-hosted static files. One-time €99, deploys in an afternoon, no backend to maintain.
