Backstage Architecture

In this guide, we’ll walk through Backstage’s architecture by comparing it to a typical web application. You’ll learn how Backstage’s frontend, backend, and plugin system interconnect to form a unified developer portal.

Typical Web Architecture

A standard web application consists of two main parts:

• Frontend: Runs in the browser, handling UI rendering and user interactions.
• Backend: Exposes REST APIs, implements business logic, and communicates with a database.

When the browser needs data, it issues an HTTP request:

GET http://backend-url/products

The flow looks like this:

1. Browser requests /products.
2. API server queries the database.
3. Database returns product data.
4. API responds with JSON.
5. Frontend displays the product list.

Backstage Core Architecture

Backstage follows the same front end/back end pattern:

1. Frontend sends:

   GET http://<backstage-backend>/catalog
   

2. Backend plugin queries the storage (database).
3. Database returns catalog entries.
4. Backend responds with JSON.
5. Frontend renders the catalog in the browser.

Plugin-Based Extension

Every feature in Backstage is implemented as a plugin. A plugin can include:

For the Catalog plugin:

1. Frontend requests /catalog.
2. Backend plugin queries its database.
3. Storage returns catalog entries.
4. Backend sends JSON response.
5. Frontend displays the catalog.

A GitLab plugin’s backend, by contrast, would fetch data from GitLab’s REST API instead of a local database.

Plugin URLs and Navigation

Backstage stitches all plugins into one React-based UI. Each plugin is mapped to its own route:

Visiting /lighthouse in the browser loads the Lighthouse audit plugin’s interface.

Monorepo Structure

A new Backstage project uses a monorepo with two main folders:

• packages/app: Frontend application (React).
• packages/backend: Backend service (Node.js).

You can develop, test, and deploy each part independently.

Frontend with React

Backstage’s UI is built on React, allowing you to compose reusable components that bundle HTML, CSS, and JavaScript.

Example of a simple button component:

import React from 'react';

export const Button = () => {
  const handleClick = () => {
    alert('Button clicked!');
  };

  return (
    <div>
      <h1>Don't Click The Button!!!</h1>
      <button onClick={handleClick}>
        Click Me
      </button>
    </div>
  );
};

Components can be composed into larger UIs:

import React from 'react';
import { Button } from './Button';

export const MyForm = () => (
  <div>
    <input id="login" type="text" />
    <input id="password" type="password" />
    <Button />
  </div>
);

Design System with Material-UI

To ensure consistent styling and accessibility, Backstage uses Material-UI (MUI). MUI offers a suite of pre-styled React components—buttons, cards, tables, menus—that adhere to Material Design guidelines.

Summary

• Backstage features are implemented as modular plugins (frontend + optional backend).
• The project is organized as a monorepo with app and backend packages.
• The frontend leverages React and Material-UI for a consistent, component-driven UI.

Links and References

• Backstage Documentation
• Backstage Plugin Development
• React Official Site
• Material-UI Documentation