How backstage/demo works
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