Developer Portal & Backstage Vocabulary: 20 Terms for Platform Teams
Backstage architecture, software catalog, TechDocs, scaffolder templates, plugins, and developer portal vocabulary.
Platform engineering has transformed the way organisations manage internal developer tooling. At the centre of this movement is Backstage — an open-source framework created by Spotify and now a CNCF project — along with the broader concept of the developer portal. If you work on or alongside a platform team, you will encounter a dense vocabulary of terms that rarely appear in standard IT English courses. This guide covers 20 essential terms, with real conversation examples to help you use them naturally.
Core Architecture Terms
Backstage — an open-source framework for building internal developer portals. It provides a unified interface where engineers can discover services, read documentation, scaffold new projects, and track technical health — all in one place.
“We evaluated Port and Cortex, but ultimately went with Backstage because the plugin ecosystem is far larger.”
“Backstage gave us a single pane of glass — before that, half the team didn’t even know which services existed.”
Software catalog — the heart of Backstage: a centralised registry of all software components, APIs, systems, and teams in your organisation. It answers the question “what do we own and who owns it?”
“The software catalog is finally up to date — every service has an owner and a link to its runbook.”
“Before we had the catalog, onboarding took a week just to figure out which repos to clone.”
Catalog entity — a single item registered in the software catalog. Each entity has a kind field that classifies what it represents. Common kinds include:
- Component — a deployable unit such as a microservice, library, or website
- API — a published interface (REST, GraphQL, gRPC, or Async)
- System — a collection of related components that form a product boundary
- Domain — a high-level business area grouping multiple systems together
“We model each microservice as a Component, then group them into a System per product area.”
“The Payments domain contains three systems: checkout, invoicing, and reconciliation.”
catalog-info.yaml — the manifest file placed in a repository’s root that registers that repo as a catalog entity. It declares the entity’s kind, owner, lifecycle stage, and links to documentation or APIs.
“Every new repo must include a
catalog-info.yaml— the platform team won’t onboard you without it.”
“I just updated our
catalog-info.yamlto mark the service aslifecycle: deprecatedso people stop depending on it.”
Documentation and Templates
TechDocs — Backstage’s built-in docs-as-code solution. Technical documentation is written in Markdown, lives alongside the code in the same repository, and is rendered inside the portal. The phrase docs-as-code means documentation follows the same workflows as code: pull requests, reviews, version control.
“We migrated our Confluence wiki to TechDocs last quarter — now docs live next to the code and stay in sync.”
“TechDocs means I can update the readme and the portal documentation in the same commit.”
Scaffolder — the Backstage feature that lets platform teams define and publish reusable project templates. Developers fill in a short form and the scaffolder generates a new repository pre-configured with CI pipelines, linting, and catalog registration.
“The scaffolder cut our new-service setup time from two days to about fifteen minutes.”
“We locked the scaffolder templates behind an approval step because some teams were spinning up services without telling anyone.”
Service template (also golden path template) — a scaffolder template that encodes the organisation’s preferred way to build a particular type of service. It is called a golden path because it guides engineers towards the approved, well-maintained approach rather than letting every team invent its own toolchain.
“Our golden path template comes with Dockerfile, GitHub Actions pipeline, and Datadog dashboards already wired up.”
“If you want to build a new Node.js API, just use the golden path template — it handles all the boilerplate.”
Plugin — a self-contained extension that adds new functionality to a Backstage instance. Plugins are the primary way both Spotify and the community extend the portal. There are two sub-types:
Frontend plugin — a React-based UI component that renders a new tab, card, or page inside the Backstage web application.
“We built a frontend plugin to show on-call rotation directly on the service page — no more digging through PagerDuty.”
Backend plugin — a server-side extension that exposes new API routes, integrates with external tools, or processes data before it reaches the UI.
“The cost plugin has a backend that queries AWS Cost Explorer every hour and caches the results.”
Ownership, Quality, and Adoption
Entity ownership — the assignment of a team or group as the responsible party for a catalog entity. Ownership is declared in catalog-info.yaml via the spec.owner field and is used to route alerts, filter dashboards, and enforce accountability.
“Entity ownership is what makes the catalog actually useful — if nobody owns a service, nobody fixes it when it breaks.”
“We made ownership mandatory in our
catalog-info.yamllint rule; PRs without an owner field are blocked.”
Tech radar — a visual tool (pioneered by ThoughtWorks and integrated into Backstage as a plugin) that categorises technologies into four rings: Adopt, Trial, Assess, and Hold. Platform teams use it to communicate which tools are approved, which are being evaluated, and which should be phased out.
“According to our tech radar, Kafka is in Adopt and NATS is still in Trial — use Kafka for anything production-critical.”
“Before you pick a new observability tool, check the tech radar — we already have Grafana in Adopt.”
Scorecard — a structured set of checks applied to catalog entities to measure their health and compliance. Common scorecard checks include: does the service have an owner, does it have on-call coverage, is its documentation up to date, and does it pass security scanning?
“Our scorecard failed us on two points: missing runbook link and no SLO defined.”
“The platform team sends a weekly digest of scorecard results — teams with red services get a nudge to fix them.”
Portal adoption metric — a measurement used to track how widely the developer portal is being used across the organisation. Common metrics include: percentage of services registered in the catalog, weekly active users, number of scaffolder runs, and documentation coverage.
“Our portal adoption metric sits at 68% — about a third of services are still not in the catalog.”
“The platform team reports portal adoption to leadership every quarter; it’s one of the key KPIs for platform engineering.”
How to Use These Terms in Conversation
Learning vocabulary is only half the work — the other half is knowing when and how to deploy it. Here are a few patterns platform engineers use regularly.
Proposing work:
“We should wire up the cost plugin to our catalog entities and expose it as a frontend plugin on each service page.”
Explaining onboarding:
“To get your service into the catalog, add a
catalog-info.yaml, set an owner, and link your TechDocs. The scaffolder has a migration template if you want a head start.”
Discussing quality gates:
“Our scorecard now checks for TechDocs coverage and entity ownership — anything below 80% triggers an automated Slack reminder.”
Talking about standards:
“The tech radar says GraphQL is in Assess, so don’t use it for a new public API without discussing it with the architecture group first.”
Reporting to management:
“Portal adoption is up to 75% this sprint. Our golden path templates reduced new-service setup time by 70%, and scaffolder usage doubled after we added the Python template.”
Quick Reference Table
| Term | In Plain English |
|---|---|
| Backstage | Open-source framework for building an internal developer portal |
| Software catalog | Central registry of all services, APIs, and teams |
| Catalog entity | One item in the catalog (Component, API, System, or Domain) |
| catalog-info.yaml | Manifest file that registers a repo in the catalog |
| TechDocs | Docs-as-code: Markdown documentation rendered inside the portal |
| Scaffolder | Tool for generating new projects from approved templates |
| Golden path template | Pre-approved project blueprint encoding best practices |
| Plugin | Extension that adds new UI or backend functionality to Backstage |
| Scorecard | Automated health checks applied to catalog entities |
| Tech radar | Visual guide to approved, trial, and deprecated technologies |
Mastering this vocabulary will help you contribute more confidently in platform team stand-ups, architecture reviews, and documentation. The next step is to explore how these concepts connect: a service template creates a Component entity with TechDocs enabled, which then appears in the software catalog with an owner, gets evaluated by a scorecard, and is surfaced to leadership through portal adoption metrics. Once you see the full picture, the terminology clicks into place.