Backstage can feel overwhelming at first—tons of features, a monolithic architecture, and documentation that’s kinda there, kinda not. But once you break it down into frontend, backend, and plugins, it actually makes sense. Let’s demystify Backstage’s architecture and make it digestible.
...my “What the Heck is This?” Moment
The first time I tried setting up Backstage, I was excited. A single pane of glass for all our services? Centralized documentation? A developer portal that actually makes sense? Sign me up!
Then reality hit...
Backstage, despite its brilliance, is a huge project. It comes with:
✅ A monolithic frontend, which can feel bloated.
✅ A backend that runs plugins and needs setup.
✅ Documentation that explains some things well, and others… well, let’s just say I had to dig through GitHub issues for answers.
So, to save you from my initial frustration, this article will break down the core architecture of Backstage and explain it in the simplest way possible.
The Three Pillars of Backstage Architecture
Backstage is essentially three major parts working together:
1️⃣ Frontend – The React-based app that users interact with.
2️⃣ Backend – Node.js-based server that handles API calls, authentication, and plugin execution.
3️⃣ Plugins – Extend Backstage’s functionality for service catalogs, CI/CD dashboards, Kubernetes, and more.
🖼️ Backstage High-Level Architecture
1️⃣ The Frontend: A React App with Monolithic Roots
The Backstage frontend is a single-page React application. It provides the UI for developers to navigate service catalogs, documentation, Kubernetes dashboards, and more.
📌 Key facts:
- Built with React and Material-UI.
- Monolithic by default, but extensible with plugins.
- Uses app-config.yaml to determine what’s displayed.
💡 Why it matters: The frontend is just the view layer—it doesn’t fetch data or store anything itself. That’s all handled by the backend.
2️⃣ The Backend: Node.js API Gateway
The backend is where the real magic happens. This is a Node.js server that acts as:
✅ A proxy to fetch data from external services (GitHub, Jenkins, Kubernetes, etc.).
✅ An authentication layer.
✅ A plugin host (more on this next).
📌 Key facts:
- Runs in Node.js (Express-based server).
- Handles API requests from the frontend.
- Manages authentication via providers like OAuth or LDAP.
💡 Why it matters: Backstage is designed to integrate with existing infrastructure—your CI/CD pipelines, service catalogs, monitoring tools—all through this backend.
3️⃣ Plugins: The Secret Sauce
Backstage without plugins is just an empty shell. The power comes from its plugin ecosystem, allowing teams to extend it with:
- Service Catalog – Tracks ownership and dependencies.
- TechDocs – In-repo Markdown-based documentation.
- Kubernetes Plugin – Displays pod health/status.
- CI/CD Dashboards – Pulls build statuses from Jenkins/GitHub Actions.
📌 Key facts:
- Plugins run on the backend but provide frontend UI components.
- Modular design – You can enable only the ones you need.
- Can be custom-built for organization-specific needs.
💡 Why it matters: Plugins make Backstage adaptable to any org—you can mix and match functionality to fit your DevOps stack.
Understanding app-config.yaml: The Heart of Backstage Setup
Everything in Backstage is controlled by app-config.yaml. This file dictates:
📌 What plugins are enabled.
📌 How the frontend connects to the backend.
📌 API integrations (GitHub, Kubernetes, etc.).
You can find more detailed example right here (or if you like me you can look up configuration example directly from Github)
Conclusion: Backstage Is Complex, But Manageable
Backstage feels huge at first, but once you break it down into its core frontend, backend, and plugins, it becomes much easier to understand.
If you’re just getting started:
✅ Don’t panic about the monolith – you don’t need to customize everything at once.
✅ Focus on enabling key plugins first – Service Catalog, TechDocs, and CI/CD.
✅ Master app-config.yaml – It controls everything.
Next up in this series: How to Set Up Backstage in Your Organization Without Losing Your Mind – a step-by-step guide to deployment. Stay tuned! 🚀