terasky-oss/backstage-plugins

1. This repository is a monorepo of Backstage plugins and modules, not a single app. The dominant architecture is “plugin family” based: each integration usually has a frontend package, a backend package, and sometimes a shared common package plus optional ingestor/auth/module packages.

2. The runtime split is consistent across the repo. Frontend packages are React/TypeScript Backstage plugins that render catalog pages, cards, tabs, field extensions, or app modules. Backend packages are Node/TypeScript Backstage backend plugins or modules that expose HTTP routes, permissions, catalog providers, scaffolder actions, or auth integrations.

3. Most feature flows follow the same path: Backstage UI component or field extension calls a generated client/API wrapper, which talks to a backend route in the matching backend plugin. The backend then either proxies to an external SaaS API, queries Kubernetes, or performs action logic. Permission-aware features usually gate the frontend with shared permission definitions and enforce them again on the backend.

4. Several packages are catalog ingest sources rather than UI. The ingestor/provider plugins discover external resources or Kubernetes resources and publish Backstage entities into the catalog. This is especially important for Kubernetes Ingestor, SpectroCloud Ingestor, VCF Automation Ingestor, and the cluster providers, which turn external platform state into catalog entities and relationships.

5. There is a strong “shared library” boundary. Packages named *-common hold shared types, permission constants, and utilities used by both frontend and backend halves of a feature. That keeps policy definitions and domain types aligned without coupling the UI directly to backend internals.

6. Kubernetes is a major integration boundary. The Kubernetes Ingestor reads cluster workloads and Crossplane/KRO resources and emits catalog entities. The Kubernetes Resources, Crossplane Resources, and KRO Resources plugins visualize Kubernetes-owned infrastructure. The corresponding backend permission packages sit between the UI and cluster-derived data to control what can be viewed.

7. AI/automation support is a second major architectural theme. MCP-enabled backends expose structured actions for AI agents over catalog, RBAC, scaffolder, ScaleOps, AI rules, and other domains. These backends are not UI-driven; they publish machine-consumable operations for querying, auditing, or mutating Backstage-adjacent state.

8. Authentication is handled as pluggable auth modules. SpectroCloud SSO, VCF SSO, and related Kubernetes auth modules plug into the Backstage auth stack and, in some cases, the Kubernetes integration. The pattern is: frontend auth client initiates OAuth/OIDC, backend auth module performs token exchange or claim transformation, and downstream plugins reuse the resulting identity for sign-in or cluster access.

9. Some plugins are “editor” or “builder” tools rather than dashboards. Template Builder is a full visual editor for Backstage software templates, synchronizing a graph canvas, YAML editor, validation, and field-extension discovery. Terraform Scaffolder and Spring Initializer are field extensions/actions that enrich software templates by discovering and configuring external generation targets.

10. The repository also includes platform-level modules that affect how Backstage loads plugins. Module Federation CDN Backend injects dynamic frontend plugins from a CDN, while the Global Sign-In Page module configures sign-in behavior from YAML. These sit at the app/platform layer rather than in a domain integration.

11. packages/app and packages/backend are the reference host application. They provide the Backstage shell used to assemble and exercise the plugins, but the individual plugins are the primary units of deployment and reuse.

12. site/ is a separate documentation system, built from Markdown into a plugin catalog site. It reflects the repo’s packaging model: each plugin has install/configure/about docs, matching the frontend/backend/module split and making the documentation a parallel architecture map for consumers.

13. Tooling reinforces the monorepo boundaries: Yarn 4 workspaces, Backstage 1.50.3 compatibility, per-package tests, and GitHub workflows for publishing, docs, and version bumps. The build/release process is organized around independently publishable plugin packages rather than one consolidated artifact.