# backstage/demo architecture

> Architecture diagram of the GitHub repository backstage/demo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/backstage/demo
- Repository: https://github.com/backstage/demo

## Overview

##### Main components
- Frontend UI (“packages/app”)
– A React SPA built with Create React App and Backstage’s app scaffolding.
– Loads custom theme (aperture.ts) and renders core & plugin pages (catalog, search, home, TechDocs, etc.).
- Backend system (“packages/backend”)
– A new Backstage backend system based on Express/Koa, configured in src/index.ts.
– Hosts API routes for catalog, search, TechDocs, and third-party plugins.
– Uses extension points (docsBuildStrategy, entity providers).
- Plugins
– Core plugins (catalog, search, techdocs, scaffolder) installed via packages.json.
– Custom plugins in “plugins/…”, e.g. notifications-tester-backend, catalog-backend-module-backstage.
- Template engine (“demo-template”)
– Yeoman templates used by the scaffolder.
- CI/CD & Deployment
– GitHub workflows (.github/workflows/*.yml) for build, deploy, version bumps.
– Dockerfile builds both frontend and backend into a single container.
- Configuration & Docs
– YAML configs (app-config.yaml, app-config.heroku.yaml, backstage.json).
– MkDocs for Markdown-based docs in “docs/” folder.
- External Services
– GitHub (source for catalog entities, CI).
– Docker registry (image storage).
– Optional: Kubernetes (via plugin), TechDocs build uses MkDocs.

##### Relationships & data flows
1. Developer/browser → HTTP → Frontend UI
- Loads static assets from Docker container (served by Node).
2. Frontend UI → REST/GraphQL → Backend API
- Catalog queries, search, scaffold requests, TechDocs requests.
3. Backend → Internal modules
- Routes handled by core backend plugins and custom providers.
4. Backend ↔ Catalog data sources
- Reads entity definitions from GitHub via the catalog-backend plugin.
5. TechDocs build
- Backend uses docsBuildStrategy to build docs on demand (calls MkDocs).
6. CI/CD pipeline
- On GitHub push, workflows build Docker image, run tests (playwright, Jest), and deploy.

##### Architectural patterns & design principles
- Monorepo with Yarn 4 and Plug’n’Play.
- Plugin-based architecture (both frontend and backend).
- Single Docker container houses both services (can be split if needed).
- Configuration-as-code via YAML + environment overrides.
- Automated version-bump and dependency updates via GitHub Actions & Renovate.

##### Essential elements
- Frontend (packages/app): React SPA, Theme, Plugins
- Backend (packages/backend): API server, Plugin modules, DocsBuildStrategy
- Plugins folder: custom backend & frontend plugin modules
- Template engine (demo-template) used by the scaffolder
- CI/CD block: GitHub Actions, Renovate, Docker build & deploy
- Configuration: YAML files, environment override
- External: GitHub (entity source), Docker Registry, MkDocs process
- Data flows:
– User → Frontend → Backend → Data sources
– CI/CD → Build → Docker Registry → Deploy

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers
    subgraph "Frontend Layer"
        direction TB
        UI["React SPA<br/>(packages/app)"]:::core
        entry["Index.tsx"]:::core
        pluginsReg["plugins.ts"]:::core
        theme["aperture.ts (Theme)"]:::core
        catalogComp["EntityPage.tsx"]:::core
        searchComp["SearchPage.tsx"]:::core
        homeComp["HomePage.tsx<br/>CustomizableHomePage.tsx"]:::core
        rootLayout["Root.tsx<br/>Logos"]:::core
    end

    subgraph "Backend Layer"
        direction TB
        API["API Server"]:::core
        docsExt["docsBuildStrategy.ts"]:::core
        catalogMod["catalog-backend-module"]:::custom
        notifMod["notifications-tester-backend"]:::custom
    end

    subgraph "Plugins & Template"
        direction TB
        scaffolder["Scaffolder Plugin"]:::core
        demoTemp["demo-template"]:::custom
    end

    subgraph "CI/CD & Deployment"
        direction TB
        workflows["GitHub Workflows"]:::cicd
        dockerBuild["Dockerfile"]:::cicd
    end

    subgraph "Configuration"
        direction TB
        configs["YAML/JSON Configs"]:::config
    end

    subgraph "External Services"
        direction TB
        GH["GitHub"]:::external
        Registry["Docker Registry"]:::external
        MkDocsProc["MkDocs Process"]:::external
    end

    %% Relationships
    User["Developer/Browser"]:::external -->|HTTP| UI
    UI -->|REST/GraphQL| API
    API -->|uses| docsExt
    API -->|routes| catalogMod
    API -->|routes| notifMod
    scaffolder -->|uses| demoTemp
    docsExt -->|calls| MkDocsProc
    workflows -->|build| dockerBuild
    dockerBuild -->|push| Registry
    Registry -->|deploy| API
    configs --> UI
    configs --> API
    GH -->|source| API
    GH -->|CI triggers| workflows

    %% Click Events
    click UI "https://github.com/backstage/demo/tree/master/packages/app"
    click entry "https://github.com/backstage/demo/blob/master/packages/app/src/index.tsx"
    click pluginsReg "https://github.com/backstage/demo/blob/master/packages/app/src/plugins.ts"
    click theme "https://github.com/backstage/demo/blob/master/packages/app/src/theme/aperture.ts"
    click catalogComp "https://github.com/backstage/demo/blob/master/packages/app/src/components/catalog/EntityPage.tsx"
    click searchComp "https://github.com/backstage/demo/blob/master/packages/app/src/components/search/SearchPage.tsx"
    click homeComp "https://github.com/backstage/demo/blob/master/packages/app/src/components/home/HomePage.tsx"
    click homeComp "https://github.com/backstage/demo/blob/master/packages/app/src/components/home/CustomizableHomePage.tsx"
    click rootLayout "https://github.com/backstage/demo/blob/master/packages/app/src/components/Root/Root.tsx"
    click API "https://github.com/backstage/demo/blob/master/packages/backend/src/index.ts"
    click docsExt "https://github.com/backstage/demo/blob/master/packages/backend/src/extensions/docsBuildStrategy.ts"
    click catalogMod "https://github.com/backstage/demo/blob/master/plugins/catalog-backend-module-backstage/src/index.ts"
    click catalogMod "https://github.com/backstage/demo/blob/master/plugins/catalog-backend-module-backstage/src/module.ts"
    click catalogMod "https://github.com/backstage/demo/blob/master/plugins/catalog-backend-module-backstage/src/provider/BackstageEntityProvider.ts"
    click notifMod "https://github.com/backstage/demo/blob/master/plugins/notifications-tester-backend/src/plugin.ts"
    click notifMod "https://github.com/backstage/demo/blob/master/plugins/notifications-tester-backend/src/router.ts"
    click notifMod "https://github.com/backstage/demo/blob/master/plugins/notifications-tester-backend/src/index.ts"
    click demoTemp "https://github.com/backstage/demo/tree/master/demo-template"
    click workflows "https://github.com/backstage/demo/blob/master/.github/workflows/master.yml"
    click workflows "https://github.com/backstage/demo/blob/master/.github/workflows/pull.yml"
    click workflows "https://github.com/backstage/demo/blob/master/.github/workflows/techdocs.yml"
    click workflows "https://github.com/backstage/demo/blob/master/.github/workflows/version-bump.yml"
    click dockerBuild "https://github.com/backstage/demo/tree/master/Dockerfile"
    click configs "https://github.com/backstage/demo/blob/master/app-config.yaml"
    click configs "https://github.com/backstage/demo/blob/master/app-config.heroku.yaml"
    click configs "https://github.com/backstage/demo/blob/master/backstage.json"
    click configs "https://github.com/backstage/demo/blob/master/catalog-info.yaml"
    click MkDocsProc "https://github.com/backstage/demo/blob/master/mkdocs.yml"
    click MkDocsProc "https://github.com/backstage/demo/tree/master/docs/"

    %% Styles
    classDef core fill:#cce5ff,stroke:#3399ff,color:#000;
    classDef custom fill:#d5f5e3,stroke:#27ae60,color:#000;
    classDef cicd fill:#fddcc4,stroke:#e67e22,color:#000;
    classDef external fill:#f2f2f2,stroke:#ccc,color:#000;
    classDef config fill:#fcf8e3,stroke:#f1c40f,color:#000;
```
