Learn Backstage - Core Concepts & Main Architecture

#Introduction

In episode 1, you understood Backstage's history and background: from the DevOps era and the microservices explosion to the birth of platform engineering and IDPs. Episode 2 answers the next question — what does Backstage's architecture actually look like? You'll see the monorepo structure that forms its foundation, the core primitives that make up its functionality, and the two major systems that compose its frontend and backend.

#The Monorepo Architecture

Backstage is built as a monorepo — one large repository that houses many packages at once. The workspace and package concepts you learned in episode 0 are put into practice right here. The most important structure is two main packages plus one configuration file:

The monorepo workspace is defined through the root package.json:

{
  "private": true,
  "workspaces": [
    "packages/*",
    "plugins/*"
  ]
}

With workspaces like this, Yarn manages all packages under a single lockfile — a new dependency only needs to be added once and stays in sync across all packages.

#packages/app — React Frontend

packages/app is the React application that serves as Backstage's face. This is where users interact with the catalog, scaffolder, TechDocs, and other plugins. At its core, this frontend is a shell that combines all plugins into one consistent navigation experience.

#packages/backend — Node.js Backend

packages/backend is the Node.js server that brings all backend services together. It's responsible for running backend plugins, providing service APIs, and connecting to external data sources such as GitHub, GitLab, or databases. This backend is where the integration configuration is assembled.

#app-config.yaml

Almost all Backstage settings live in a single file named app-config.yaml. This file controls the application title, public URL, backend port, and integration credentials. Here's a snippet:

app:
  title: Backstage Example App
  baseUrl: http://localhost:3000
 
backend:
  baseUrl: http://localhost:7007
  listen:
    port: 7007

You'll dissect app-config.yaml more deeply during the bootstrap in episode 3.

#Core Primitives

Behind Backstage's interface lie five primitives that form the backbone of nearly all functionality:

#Software Catalog

The Software Catalog is the center of everything — a single inventory for services, libraries, websites, and other software assets. Each entry stores metadata such as the owner, relationships between services, and status. You'll learn the details in episode 4.

#Software Templates (Scaffolder)

Software Templates, also known as the Scaffolder, let engineers create new services from approved templates. Instead of filling out a ticket and waiting, a developer simply picks a template, fills in a few parameters, and a new service gets scaffolded complete with its repository, pipeline, and catalog entry. That's episode 6.

#TechDocs

TechDocs brings the docs-as-code concept into the portal. Documentation is written as Markdown inside the repository, then built and displayed within Backstage — always in sync with the code because they're managed together. Episode 7 covers it.

#Search

Search unifies the entire portal content: the catalog, documentation, and plugins. One search box to find services, explore docs, or surface related entities. Search is the glue that keeps a large portal feeling light.

#Plugins

Plugins are how Backstage is extended. Everything you see — catalog, scaffolder, TechDocs — is actually a plugin. Organizations can build internal plugins for their own tooling or install plugins from the ecosystem. This capability is what makes Backstage more than just a finished application.

#Frontend and Backend Systems

Beyond the primitives, Backstage has two major systems that govern how the frontend and backend are assembled.

#New Frontend System

The New Frontend System has been the default since 2026. This system is based on extensions — every part of the frontend UI is declared as an extension that can be added, replaced, or rearranged. Plugins are created with the createFrontendPlugin function, which registers all extensions at once. The result: a more modular frontend that's easier to customize without writing lots of boilerplate.

#New Backend System

On the backend side, the New Backend System brings a modular architecture based on service APIs. Each feature is registered through a backend.add() call from the module in question. Instead of assembling code by hand, you simply add the modules you want, and the backend provides the services you need automatically.

#Conclusion

In this episode 2, you mapped out Backstage's architecture: the monorepo with packages/app and packages/backend, the central app-config.yaml configuration, the five core primitives (Software Catalog, Software Templates, TechDocs, Search, and Plugins), and the New Frontend System and New Backend System that form its modern foundation.

The key takeaways:

• The monorepo is the main pattern — frontend and backend live as separate packages in one repository.
• app-config.yaml is the configuration source for the entire installation.
• The Software Catalog is the most central primitive — almost everything else connects to the catalog.
• The frontend and backend are now modular — extensions for the UI, service APIs for the backend.

In the next episode, episode 3, you'll run it all: installation and initial bootstrap — creating your first Backstage application with create-app and seeing it run on your machine.