# broadinstitute/backstage architecture

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

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

## Overview

This repository runs Broad Institute’s Backstage developer portal. Users sign in, then search and browse the service catalog, open entity documentation, or use software templates to scaffold resources; dedicated pages also expose Kubernetes catalog entities. The frontend assembles Backstage plugins and custom navigation, pages, and template fields, while a separately configured backend registers catalog, authentication, scaffolder, documentation, and integration plugins. README-described capabilities such as Soundcheck, Skill Exchange, Insights, and MCP are represented at their supported integration boundary; their internal implementation is not shown in the sampled source.

Main entry points: [`backstage/packages/app/src/App.tsx`](https://github.com/broadinstitute/backstage/blob/main/backstage/packages/app/src/App.tsx) (Portal frontend), [`backstage/packages/backend/src/index.ts`](https://github.com/broadinstitute/backstage/blob/main/backstage/packages/backend/src/index.ts) (Portal extensions), [`backstage/packages/app/src/scaffolder/GcpResourcePicker/GcpResourcePicker.tsx`](https://github.com/broadinstitute/backstage/blob/main/backstage/packages/app/src/scaffolder/GcpResourcePicker/GcpResourcePicker.tsx) (Template fields), [`backstage/packages/app/src/scaffolder/GithubTeamPicker/GithubTeamPicker.tsx`](https://github.com/broadinstitute/backstage/blob/main/backstage/packages/app/src/scaffolder/GithubTeamPicker/GithubTeamPicker.tsx) (GitHub team picker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_portal["Portal experience"]
  node_frontend["Portal frontend<br/>[App.tsx]"]
  node_navigation["Portal navigation<br/>[Sidebar.tsx]"]
  node_home["Home dashboard<br/>[HomePage.tsx]"]
  node_techdocs["TechDocs add-ons<br/>[index.tsx]"]
  node_search["Search<br/>[index.ts]"]
end

subgraph group_identity["Identity and catalog"]
  node_catalog_ui["Catalog entity views<br/>[index.tsx]"]
  node_auth["Authentication setup<br/>[index.ts]"]
  node_catalog_backend["Catalog services<br/>[index.ts]"]
  node_catalog_data[("Catalog entities")]
end

subgraph group_delivery["Developer workflows"]
  node_scaffolder["Template creation<br/>[App.tsx]"]
  node_custom_fields["Template fields"]
  node_scaffold_backend["Scaffolder backend<br/>[index.ts]"]
  node_github_team["GitHub team picker"]
  node_gcp_resource["GCP resource picker"]
  node_gcp_billing["GCP billing picker"]
end

subgraph group_integrations["Platform integrations"]
  node_kubernetes["Kubernetes browser"]
  node_kubernetes_backend["Kubernetes integration<br/>[index.ts]"]
  node_extensions["Portal extensions<br/>[index.ts]"]
end

node_user(("Developer"))
node_google{{"Google identity and APIs"}}
node_github{{"GitHub"}}

node_user -->|"uses"| node_frontend
node_frontend -->|"configures"| node_navigation
node_frontend -->|"loads"| node_home
node_frontend -->|"registers"| node_catalog_ui
node_frontend -->|"registers"| node_techdocs
node_frontend -->|"renders"| node_scaffolder
node_frontend -->|"routes"| node_kubernetes
node_user -->|"signs in"| node_auth
node_auth -->|"authenticates"| node_google
node_auth -->|"resolves user"| node_catalog_data
node_catalog_backend -->|"manages"| node_catalog_data
node_search -->|"indexes"| node_catalog_data
node_scaffolder -->|"renders"| node_custom_fields
node_scaffolder -->|"submits templates"| node_scaffold_backend
node_custom_fields -->|"includes"| node_github_team
node_custom_fields -->|"includes"| node_gcp_resource
node_custom_fields -->|"includes"| node_gcp_billing
node_gcp_resource -->|"searches projects"| node_google
node_gcp_billing -->|"lists accounts"| node_google
node_github_team -.->|"queries teams"| node_github
node_kubernetes -->|"queries entities"| node_catalog_data
node_kubernetes_backend -->|"supplies metadata"| node_catalog_data
node_extensions -->|"extends catalog"| node_catalog_backend
node_extensions -->|"registers plugins"| node_search
node_extensions -->|"registers plugins"| node_scaffold_backend
node_extensions -->|"registers plugin"| node_kubernetes_backend

click node_frontend "https://github.com/broadinstitute/backstage/blob/main/backstage/packages/app/src/App.tsx"
click node_navigation "https://github.com/broadinstitute/backstage/blob/main/backstage/packages/app/src/modules/nav/Sidebar.tsx"
click node_home "https://github.com/broadinstitute/backstage/blob/main/backstage/packages/app/src/components/home/HomePage.tsx"
click node_techdocs "https://github.com/broadinstitute/backstage/blob/main/backstage/packages/app/src/modules/techdocs/index.tsx"
click node_catalog_ui "https://github.com/broadinstitute/backstage/blob/main/backstage/packages/app/src/modules/catalog/index.tsx"
click node_auth "https://github.com/broadinstitute/backstage/blob/main/backstage/packages/backend/src/index.ts"
click node_catalog_backend "https://github.com/broadinstitute/backstage/blob/main/backstage/packages/backend/src/index.ts"
click node_search "https://github.com/broadinstitute/backstage/blob/main/backstage/packages/backend/src/index.ts"
click node_scaffolder "https://github.com/broadinstitute/backstage/blob/main/backstage/packages/app/src/App.tsx"
click node_custom_fields "https://github.com/broadinstitute/backstage/blob/main/backstage/packages/app/src/scaffolder/GcpResourcePicker/GcpResourcePicker.tsx"
click node_scaffold_backend "https://github.com/broadinstitute/backstage/blob/main/backstage/packages/backend/src/index.ts"
click node_github_team "https://github.com/broadinstitute/backstage/blob/main/backstage/packages/app/src/scaffolder/GithubTeamPicker/GithubTeamPicker.tsx"
click node_gcp_resource "https://github.com/broadinstitute/backstage/blob/main/backstage/packages/app/src/scaffolder/GcpResourcePicker/GcpResourcePicker.tsx"
click node_gcp_billing "https://github.com/broadinstitute/backstage/blob/main/backstage/packages/app/src/scaffolder/GcpBillingAccountPicker/GcpBillingAccountPicker.tsx"
click node_kubernetes "https://github.com/broadinstitute/backstage/blob/main/backstage/packages/app/src/components/kubernetes/KubernetesLandingPage.tsx"
click node_kubernetes_backend "https://github.com/broadinstitute/backstage/blob/main/backstage/packages/backend/src/index.ts"
click node_extensions "https://github.com/broadinstitute/backstage/blob/main/backstage/packages/backend/src/index.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend,node_navigation,node_home,node_techdocs,node_search toneBlue
class node_catalog_ui,node_auth,node_catalog_backend,node_catalog_data toneAmber
class node_scaffolder,node_custom_fields,node_scaffold_backend,node_github_team,node_gcp_resource,node_gcp_billing,node_google toneMint
class node_kubernetes,node_kubernetes_backend,node_extensions toneRose
class node_user,node_github toneIndigo
```

## Components

### Portal experience

- [Portal frontend](https://github.com/broadinstitute/backstage/blob/main/backstage/packages/app/src/App.tsx): `backstage/packages/app/src/App.tsx`
- [Portal navigation](https://github.com/broadinstitute/backstage/blob/main/backstage/packages/app/src/modules/nav/Sidebar.tsx): `backstage/packages/app/src/modules/nav/Sidebar.tsx`
- [Home dashboard](https://github.com/broadinstitute/backstage/blob/main/backstage/packages/app/src/components/home/HomePage.tsx): `backstage/packages/app/src/components/home/HomePage.tsx`
- [TechDocs add-ons](https://github.com/broadinstitute/backstage/blob/main/backstage/packages/app/src/modules/techdocs/index.tsx): `backstage/packages/app/src/modules/techdocs/index.tsx`
- [Search](https://github.com/broadinstitute/backstage/blob/main/backstage/packages/backend/src/index.ts): `backstage/packages/backend/src/index.ts`

### Identity and catalog

- [Catalog entity views](https://github.com/broadinstitute/backstage/blob/main/backstage/packages/app/src/modules/catalog/index.tsx): `backstage/packages/app/src/modules/catalog/index.tsx`
- [Authentication setup](https://github.com/broadinstitute/backstage/blob/main/backstage/packages/backend/src/index.ts): `backstage/packages/backend/src/index.ts`
- [Catalog services](https://github.com/broadinstitute/backstage/blob/main/backstage/packages/backend/src/index.ts): `backstage/packages/backend/src/index.ts`
- **Catalog entities**

### Developer workflows

- [Template creation](https://github.com/broadinstitute/backstage/blob/main/backstage/packages/app/src/App.tsx): `backstage/packages/app/src/App.tsx`
- [Template fields](https://github.com/broadinstitute/backstage/blob/main/backstage/packages/app/src/scaffolder/GcpResourcePicker/GcpResourcePicker.tsx): `backstage/packages/app/src/scaffolder/GcpResourcePicker/GcpResourcePicker.tsx`
- [Scaffolder backend](https://github.com/broadinstitute/backstage/blob/main/backstage/packages/backend/src/index.ts): `backstage/packages/backend/src/index.ts`
- [GitHub team picker](https://github.com/broadinstitute/backstage/blob/main/backstage/packages/app/src/scaffolder/GithubTeamPicker/GithubTeamPicker.tsx): `backstage/packages/app/src/scaffolder/GithubTeamPicker/GithubTeamPicker.tsx`
- [GCP resource picker](https://github.com/broadinstitute/backstage/blob/main/backstage/packages/app/src/scaffolder/GcpResourcePicker/GcpResourcePicker.tsx): `backstage/packages/app/src/scaffolder/GcpResourcePicker/GcpResourcePicker.tsx`
- [GCP billing picker](https://github.com/broadinstitute/backstage/blob/main/backstage/packages/app/src/scaffolder/GcpBillingAccountPicker/GcpBillingAccountPicker.tsx): `backstage/packages/app/src/scaffolder/GcpBillingAccountPicker/GcpBillingAccountPicker.tsx`

### Platform integrations

- [Kubernetes browser](https://github.com/broadinstitute/backstage/blob/main/backstage/packages/app/src/components/kubernetes/KubernetesLandingPage.tsx): `backstage/packages/app/src/components/kubernetes/KubernetesLandingPage.tsx`
- [Kubernetes integration](https://github.com/broadinstitute/backstage/blob/main/backstage/packages/backend/src/index.ts): `backstage/packages/backend/src/index.ts`
- [Portal extensions](https://github.com/broadinstitute/backstage/blob/main/backstage/packages/backend/src/index.ts): `backstage/packages/backend/src/index.ts`

### Other components

- **Developer**
- **Google identity and APIs**
- **GitHub**

## Connections

- Developer → Portal frontend: uses
- Portal frontend → Portal navigation: configures
- Portal frontend → Home dashboard: loads
- Portal frontend → Catalog entity views: registers
- Portal frontend → TechDocs add-ons: registers
- Portal frontend → Template creation: renders
- Portal frontend → Kubernetes browser: routes
- Developer → Authentication setup: signs in
- Authentication setup → Google identity and APIs: authenticates
- Authentication setup → Catalog entities: resolves user
- Catalog services → Catalog entities: manages
- Search → Catalog entities: indexes
- Template creation → Template fields: renders
- Template creation → Scaffolder backend: submits templates
- Template fields → GitHub team picker: includes
- Template fields → GCP resource picker: includes
- Template fields → GCP billing picker: includes
- GCP resource picker → Google identity and APIs: searches projects
- GCP billing picker → Google identity and APIs: lists accounts
- GitHub team picker → GitHub: queries teams
- Kubernetes browser → Catalog entities: queries entities
- Kubernetes integration → Catalog entities: supplies metadata
- Portal extensions → Catalog services: extends catalog
- Portal extensions → Search: registers plugins
- Portal extensions → Scaffolder backend: registers plugins
- Portal extensions → Kubernetes integration: registers plugin