Backstage and its Place Among Developer Portals: A Technical Architecture Guide

The Internal Developer Portal market has matured fast. But despite all the new vendors, most teams evaluating portals are still making the same underlying decision: What architecture do we want to commit to for the next 5-10 years of developer experience?

Today, there are three distinct paths:

1. Self-hosted Backstage
2. Proprietary portals
3. SaaS portal built on an open standard

Backstage became the Kubernetes of developer portals, not because it's easy to run, but because it's the open standard that solves the portability problem. When you build on Backstage, you're choosing an ecosystem where your data model isn't locked to a single vendor. But this flexibility comes with real operational costs that many teams underestimate.

This guide examines Backstage's technical architecture, specifically its plugin system, entity model, and extension points, and explains where it fits in the modern platform engineering stack. You'll understand the trade-offs between framework flexibility and product convenience, and why SaaS portal built on an open standard represents an architectural evolution rather than just another hosting option.

Deconstructing Backstage: How it Actually Works

Backstage isn't a product you install. It's a collection of TypeScript libraries that you assemble into your own developer portal. This distinction matters because it changes how you think about customization, upgrades, and ownership.

Assembly Required: Backstage as a Framework

When you start with Backstage, you're creating a new Node.js application. You import Backstage packages as dependencies, configure them through code, and deploy the resulting application to your infrastructure. This is fundamentally different from signing into a SaaS portal where the vendor controls the codebase. Backstage is an extensible application framework that you build and tailor to your organization’s needs.

The core Backstage repository provides the foundational packages: @backstage/core-components for React UI elements, @backstage/backend-defaults for the new backend system, and @backstage/catalog-model for the type system. You compose these into your instance by modifying the packages/app and packages/backend directories in your Backstage monorepo.

This architecture gives you the ability to treat your portal as an internal platform product and something you can evolve deeply to match your organization. If you want to adjust navigation patterns, you can modify the React components directly. If your authentication model is complex, you can implement it in your backend package. If your organization has domain concepts that don’t fit predefined schemas, you can extend the entity model to reflect them.

The portal becomes an application you continuously evolve over time. Want to change how the sidebar renders? You edit the React components directly. Need custom authentication logic? You implement it in your backend package.

In proprietary portals, customization typically happens through predefined settings and extension points, which is faster to adopt but structurally more constrained.

The Plugin Architecture: Backstage’s Extensibility Model

In Backstage, even core capabilities like the catalog are implemented as plugins. This isn't just organizational; it's the technical mechanism that makes Backstage an ecosystem rather than a single product.

Plugins are NPM packages that implement specific interfaces. Frontend plugins use createFrontendPlugin from @backstage/frontend-plugin-api and contribute UI through extension points such as pages and entity components (for example via blueprints like PageBlueprint or EntityCardBlueprint). Backend plugins use createBackendPlugin from @backstage/backend-plugin-api with a microservice architecture where plugins operate in complete isolation, communicating only through network calls.

The plugin system is implemented through Backstage's extension API. Installing a plugin is a build-time composition step: you import the NPM package, register it in the app, and Backstage wires it into the portal through defined extension points. Backstage core provides shared platform services like routing, authentication context, configuration, and consistent UI primitives, while plugins focus on domain-specific integration logic.

For example, the Kubernetes plugin provides a frontend component that displays cluster resources witha backend integration that queries Kubernetes APIs. The plugin reuses shared concerns like authentication context, configured proxy settings, and secrets handling rather than re-implementing them.

This plugin-first architecture is what enables the Backstage ecosystem to scale, with over 250 community plugins. Instead of requiring changes to core, integrations can be delivered as modular plugins - connecting to systems like PagerDuty, Datadog, or your CI/CD system - while remaining aligned to a shared extension model.

The Entity Model: The System of Record

Backstage's other foundational concept isthe Software Catalog . At its core, this catalog is a graph of entities that represent your software ecosystem. Entities are commonly defined in catalog-info.yaml files that live alongside your source code.

An entity can represent : a service, a library, a team, an API, or a custom resource type you define. Each entity has a kind (Component, API, Resource, System, Domain, Group, User, Template, or Location), metadata (name, description, annotations), and relationships to other entities.

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: payment-service
  description: Handles payment processing
  annotations:
    github.com/project-slug: company/payment-service
spec:
  type: service
  lifecycle: production
  owner: payments-team
  system: checkout
  providesApis:
    - payment-api
  consumesApis:
    - fraud-detection-api

The model is declarative and versioned. Your entity definitions live in git, versioned alongside your code. Over time, the catalog becomes a structured system of record for: ownership, lifecycle state, dependencies, API relationships and the context required to power templates, scorecards, and automation.

The catalog backend continuously processes these YAML files through entity providers, plugins that discover and ingest entities from different sources. For example, the GitHub provider scans your repositories for catalog-info.yaml files and the Kubernetes provider can generate entities from cluster resources. This extensibility means you control what gets cataloged and how.

The result is that Backstage is more than a developer portal UI. It is a structured model of your engineering organization, which the portal then uses as context for workflows, integrations, and governance.

The Landscape: Three Ways to Adopt a Developer Portal

Once you understand Backstage’s architecture, the market becomes easier to reason about.

Organizations evaluating developer portals are typically choosing between three distinct models:

1. Self-hosted Backstage (framework ownership)
2. Proprietary SaaS portals (closed product ownership)
3. SaaS portals built on the Backstage standard (productized standard)

The differences are not primarily about features. They’re about ownership, extensibility, and where your system of record lives.

Self-Hosted Backstage: You Own the Framework

In this model, you adopt the Backstage standard directly and operate it yourself. You control the React frontend, the Node backend, the plugin surface area, the entity model and schema evolution as well as the upgrade and migration lifecycle.

This maximizes architectural control, but you also comes with responsibility for maintaining a rapidly evolving framework. The portal becomes an internally operated software product. For organizations with strong platform engineering capacity, this can be a deliberate and strategic choice.

Proprietary Portals: The Vendor Owns the Model

In a closed SaaS model, the vendor owns the application, the schema and the extension model.

These tools are typically optimized for rapid setup. You connect your Source Control and your CI system, and a catalog is generated. You configure scorecards and workflows through predefined interfaces. This speed comes from removing choices. However, the catalog and workflow layer usually live inside a vendor-defined schema. Even when APIs are available, the data model is product-defined. Over time, your service metadata and automation logic become coupled to that model.

Extensibility typically happens through predefined extension points: custom fields, webhooks, workflow builders, or API integrations. That can be sufficient for many teams. But if your organization’s domain model diverges significantly from the product’s assumptions, deeper customization often requires vendor support or roadmap alignment.

The trade-off is clear: faster time-to-value, but less control over how the system evolves.

SaaS portal built on an open standard: Productizing the Architecture

In this hybrid approach, the vendor owns the application, operational lifecycle (upgrades, migrations, infrastructure), and schema evolution. However, the architecture remains aligned to Backstage principles and ecosystem patterns.

The key distinction is extensibility. Rather than limiting integrations to a fixed set of vendor-defined connectors, the system is built around a plugin-oriented model. Integrations are modular, scoped, and composable. Teams can extend the portal to integrate internal systems, domain-specific tooling, or custom workflows without modifying core application code.

The difference from closed SaaS portals is architectural. Instead of limiting extensibility to configuration, webhooks, or predefined workflow builders, this model treats extensibility as a first-class concern. New capabilities can be introduced as modular integrations, rather than requiring changes to the core product.

This approach exists because many organizations want the architectural advantages of the Backstage standard like modular integrations, catalog-driven context, and workflow extensibility, without taking on the responsibility of operating and upgrading a framework deployment themselves.

The Data Model Trade-off

Over time, a developer portal becomes less about UI and more about context: ownership, dependencies, lifecycle state, maturity standards, and the metadata needed to power workflows. Where that context lives, and who controls how it evolves, has long-term implications.

In a self-hosted Backstage deployment, the context model is defined in code and declarative descriptors (often versioned in Git). The organization controls how the model evolves and how relationships are represented.

In a closed SaaS portal, the context model typically lives inside a vendor-managed database with a product-defined schema. Even when APIs exist, the shape of the model and its evolution are governed by the vendor.

In a SaaS portal built on open standard, the vendor owns the application and the evolution of the model, but the portal is still built around catalog-driven context and modular extensibility rather than a fixed set of vendor-only connectors.

The trade-off isn’t theoretical. Once ownership, automation, and governance are encoded into a portal, migrating between models is rarely just a data export. It involves re-mapping relationships, workflows, and assumptions embedded in how that context is represented.

The Operational Layer: Running Backstage Is Real Engineering Work

Backstage’s power comes from the fact that it’s an open source framework, but that also means you are running a real software system. A self-hosted Backstage deployment is not a static tool. It’s:

• A Node.js backend with multiple plugins and integrations
• A React frontend composed from independently versioned packages
• A PostgreSQL database backing the catalog and metadata
• Authentication, authorization, and secrets management and the lifecycle of ongoing dependency and framework upgrades

This is infrastructure-level responsibility.

Backstage releases happen monthly , on the Tuesday before the third Wednesday of each month. Individual packages follow semantic versioning, but Backstage releases explicitly don't adhere to semver. Breaking changes are documented with **BREAKING**: prefix in changelogs - but the practical reality is that staying current requires consistent engineering attention.

The TypeScript tax is real. Plugins evolve quickly, and compatibility issues do happen: plugin updates can introduce breaking changes, and deep customizations can conflict with upstream changes. Running Backstage well requires engineers who understand the Backstage framework architecture, can debug the plugin composition model, and can keep upgrades from turning into periodic migrations.

Security is your responsibility. You configure authentication, implement authorization rules, and manage secrets. RBAC in Backstage requires implementing permission policies as code through the permission framework, which means you need someone who actually understands the permission model to secure your instance correctly as the portal grows

Operationa complexity compounds at scale. You need to monitor the backend, tune database queries, and keep frontend bundle sizes from drifting. When the portal is down, you handle the incident response. And because the portal becomes a daily surface for developer workflows, reliability expectations tend to climb quickly.

Many teams understaff Backstage operations. They assume that because it's "just a developer portal," it doesn't need dedicated ownership. Then they struggle with upgrades, accumulate technical debt, and lose confidence in the platform.

The complexity isn’t a flaw, it's the cost of adopting a highly extensible standard. When ownership is vague, upgrades get deferred, incompatibilities pile up, and confidence erodes. When it’s staffed like a core platform service, it behaves like one. That pattern shows up in Backstage’s own community reporting too: organizations with larger, dedicated portal teams consistently report modestly higher satisfaction.

Roadie: SaaS Delivery Without Closed-System Tradeoffs

Backstage established the architectural standard for developer portals: a plugin-first model, a structured software catalog, and an ecosystem of integrations. But consuming a standard doesn’t require operating the framework directly.

Roadie is a SaaS developer portal built on the open standard and inspired by its ecosystem. It enables the architectural advantages that made Backstage the default framework like a plugin-based architecture, a catalog-driven context and an ecosystem integration model, then elevates them into a product designed for long-term context stability, governance, and scale.

This matters because most organizations don’t want to become framework maintainers, but they also don’t want their portal to become a closed system with a vendor-owned schema. Roadie offers this alternative: the architectural upside of the standard, with a SaaS product delivery.

Architecture: SaaS Built on the Open Standard (Not a Hosted Distribution)

Roadie is a SaaS developer portal built on the open standard, but it isn’t simply a hosted version of Backstage.

Roadie delivers a SaaS portal experience with hosting, databases, monitoring, security controls, and upgrades, while retaining the Backstage ecosystem approach that made extensibility and integration portability possible in the first place. Roadie can absorb ecosystem change, improve workflow UX, and provide enterprise operational guarantees, including SOC 2 Type 2, without requiring customers to become framework maintainers.

What Roadie Optimizes (and Why It’s a Distinct Third Model)

Roadie is designed for teams who want the architectural upside of the Backstage standard without turning the portal itself into an internally operated framework.

From the Backstage ecosystem, Roadie inherits the most valuable properties: an extensible integration model and a large body of community and partner plugins. Teams can adopt integrations incrementally and extend the portal over time, instead of being limited to a fixed set of vendor-owned connectors.

Importantly, extensibility isn’t restricted to pre-approved marketplace integrations. Teams can build their own plugins and integrations using the same plugin-oriented model to connect internal systems, domain-specific tooling, and organization-specific workflows. Extensibility also applies to automation: platform teams can also extend self-service workflows through Scaffolder templates, including custom actions that integrate directly with internal tooling and automation systems. This means the portal can evolve alongside your architecture and operating model, rather than being constrained by a vendor-defined capabilities.

Roadie productizes areas where a framework deployment typically requires code-first implementation. For example, access control and governance can be configured through product workflows rather than requiring teams to implement RBAC policy logic directly in code. Secrets and integration configuration can be managed through dedicated interfaces instead of being pushed into environment variables and bespoke deployment pipelines.

From an operational perspective, Roadie owns the lifecycle that comes with self-hosting Backstage: framework upgrades, compatibility testing, security patching, infrastructure operations, and production monitoring. In a self-hosted model, each of these becomes ongoing internal engineering work - work that competes directly with building new developer workflows, improving golden paths, or investing in higher-leverage platform initiatives.

This goes beyond “hosting”. Roadie tracks changes across the Backstage ecosystem, including core framework releases and plugin-level updates, which are evaluated and incorporated into the Roadie product lifecycle. Platform teams don’t need to plan and execute backend migrations, reconcile plugin API changes, or coordinate dependency upgrades across their portal deployment as the ecosystem evolves.

In practical terms: self-hosted Backstage makes your team responsible for maintaining the framework itself. Roadie shifts that responsibility boundary: your team focuses on extending and using the portal, not operating it.

The result is a SaaS-delivered portal that remains aligned with Backstage’s extensibility model and ecosystem approach, without requiring customers to maintain the framework itself.

Technical Detail: Addressing Backend System Migration and Upgrade Burden

Backstage's architecture evolved significantly with the introduction of the new backend system , which reached stable 1.0 in 2024. For self-hosted teams, this wasn’t a minor version bump. It was a migration-class change that touched plugin wiring, backend dependencies, and integration compatibility.

Plugin registration changed from imperative setup to declarative backend.add() calls. The legacy @backstage/backend-common package was deprecated in favor of @backstage/backend-defaults. Service-to-service communication patterns shifted to dependency injection. Configuration structure changed. In practice, this meant reviewing custom plugins, updating imports, reconciling breaking changes, and validating that integrations continued to function correctly.

For teams running Backstage themselves, migrations like this become internal engineering projects. They require planning, testing, staged rollouts, and often temporary freezes on other platform work. This aligns with findings from the 2025 State of Backstage report: "Teams running Backstage themselves describe a very different day to day reality compared to those using managed platforms, especially around stability and upgrades."

Roadie evaluates changes in the core Backstage framework and plugin ecosystem, tests them against supported integrations and configurations, and implements the necessary adjustments within the platform itself.

In this case, Roadie absorbed this migration into the product lifecycle. Changes in the core Backstage framework and plugin ecosystem were evaluated, tested against supported integrations and real customer plugin combinations, and the necessary compatibility work was implemented within the platform itself. Customers did not need to refactor backend code, reconcile plugin API changes, or coordinate dependency upgrades across their portal deployment. Upgraded instances were delivered without requiring each team to manage the migration work.

This approach scales. As Backstage evolves, SaaS providers can absorb the upgrade complexity without customers modifying their configurations or code.

Conclusion: Choosing Your Architecture

The choice between frameworks and products isn't about features. It's about ownership and long-term flexibility.

Proprietary portals offer speed: you get a working portal quickly andavoid operational complexity.But that speed usually comes from a vendor-owned model: the schema, workflow layer, and extensibility boundaries are defined by the product. If your organization fits those assumptions, this can be a great trade.

Self-hosted Backstage offers portability and control: your data model isn't locked to a vendor and you can integrate with any tool through the plugin system. But you also take on the full cost of ownership: upgrades, migrations, security, scaling, plugin compatibility, and the ongoing work of maintaining a rapidly changing framework.The operational burden is real. For many teams, it becomes the limiting factor. Not because Backstage is flawed, but because running it well requires sustained platform engineering investment.

Roadie represents a third model: a SaaS portal experience aligned with Backstage’s architectural principles, without requiring customers to operate the framework. Roadie carries forward the architectural lineage of Backstage, including plugin-based extensibility, ecosystem familiarity, a catalog-driven foundation, and workflow flexibility, while taking responsibility for upgrades, migrations, infrastructure, and long-term lifecycle management. It’s a different responsibility boundary: teams keep the architectural upside of the standard, while offloading the operational and upgrade burden that makes self-hosting expensive over time.

The portal you choose becomes part of your platform architecture, and the decisions you make about extensibility, portability, and ownership will shape your strategy for years. Choose a model aligned with how you want your engineering organization to operate.