Backstage Architecture Deep Dive

High-Level Architecture

Frontend (App)

• Single-page React application (TypeScript, Material UI)
• Plugin-based: each feature is a plugin (catalog, scaffolder, techdocs, kubernetes, etc.)
• App package (@backstage/app) composes plugins, configures routing, theming, auth
• Runs as static files (nginx, S3+CloudFront, Vercel) or served by backend
• Communicates with backend via REST (proxy) and WebSocket (real-time)

Backend

• Node.js/Express service (TypeScript)
• Plugin architecture: each backend plugin registers routes, middleware, database access
• Core plugins: catalog, scaffolder, auth, proxy, permissions, search, techdocs
• Database: PostgreSQL (required for catalog, scaffolder, auth sessions)
• Runs as container (Docker, Kubernetes) — single replica for dev, HA for prod

Database

• PostgreSQL 13+ required (catalog, scaffolder, auth, permissions, search index)
• Schema managed by Knex migrations (auto-run on startup)
• Connection pooling via pg-pool (configure pool size for load)
• Backup: Point-in-time recovery (PITR) or pg_dump + WAL-G
• Read replicas for scaling catalog queries (search, listing)

Authentication & Authorization

# packages/backend/src/plugins/permissions.ts
import { PermissionPolicy, AuthorizeResult } from '@backstage/plugin-permission-node';
import { stringifyEntityRef } from '@backstage/catalog-model';

export class CustomPermissionPolicy implements PermissionPolicy {
  async handle(request: PermissionRequest): Promise<AuthorizeResult> {
    const { userEntityRef, permission, resource } = request;

    // Allow users to read all catalog entities
    if (permission.name === 'catalog.entity.read') {
      return AuthorizeResult.ALLOW;
    }

    // Allow users to modify entities they own
    if (permission.name === 'catalog.entity.update' || permission.name === 'catalog.entity.delete') {
      const owner = resource.entity?.metadata?.annotations?.['backstage.io/owned-by'];
      if (owner && userEntityRef === `user:${owner}`) {
        return AuthorizeResult.ALLOW;
      }
      // Check if user is member of owning team
      const userTeams = await this.getUserTeams(userEntityRef);
      if (owner && userTeams.includes(owner)) {
        return AuthorizeResult.ALLOW;
      }
      return AuthorizeResult.DENY;
    }

    return AuthorizeResult.DENY;
  }
}

Plugin System

• Frontend plugins: React components, routes, API clients (e.g., @backstage/plugin-catalog)
• Backend plugins: Express routers, database access, external integrations (e.g., @backstage/plugin-catalog-backend)
• Plugin packages: Published to npm, versioned independently
• Core plugins: Catalog, Scaffolder, TechDocs, Auth, Proxy, Permissions, Search, Kubernetes
• Community plugins: ArgoCD, Grafana, PagerDuty, Jira, SonarQube, Dependabot, etc.
• Custom plugins: Org-specific integrations (platform API, internal tools, compliance)

Deployment Options