# betelabs/platform-engineering-idp architecture

> Architecture diagram of the GitHub repository betelabs/platform-engineering-idp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/betelabs/platform-engineering-idp
- Repository: https://github.com/betelabs/platform-engineering-idp

## Overview

This repository describes an internal developer platform centered on a Backstage self-service portal: developers discover services and launch templates for new services or databases. The documented platform combines catalog and scaffolder services, Crossplane infrastructure APIs, Argo CD GitOps delivery, admission policies, and Terraform-managed cloud infrastructure. The graph preserves these major capabilities using README-documented relationships; source excerpts verify the Backstage home page, catalog processor, and scaffolder setup, but do not establish their wiring to the unsampled infrastructure and delivery configurations.

Main entry points: [`backstage/packages/backend/src/plugins/scaffolder.ts`](https://github.com/betelabs/platform-engineering-idp/blob/main/backstage/packages/backend/src/plugins/scaffolder.ts) (Template Scaffolder), [`gitops/argocd/appsets/workloads.yaml`](https://github.com/betelabs/platform-engineering-idp/blob/main/gitops/argocd/appsets/workloads.yaml) (Argo CD), [`backstage/packages/app/src/components/HomePage.tsx`](https://github.com/betelabs/platform-engineering-idp/blob/main/backstage/packages/app/src/components/HomePage.tsx) (Backstage Portal), [`backstage/packages/backend/src/plugins/catalog.ts`](https://github.com/betelabs/platform-engineering-idp/blob/main/backstage/packages/backend/src/plugins/catalog.ts) (Service Catalog)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_portal["Developer Portal"]
  node_portal["Backstage Portal<br/>[HomePage.tsx]"]
  node_catalog["Service Catalog<br/>[catalog.ts]"]
  node_catalogdata["Catalog Records<br/>[all.yaml]"]
  node_teams["Teams and Systems<br/>[groups.yaml]"]
end

subgraph group_provision["Self-Service Provisioning"]
  node_scaffolder["Template Scaffolder<br/>[scaffolder.ts]"]
  node_microtemplate["Microservice Template<br/>[template.yaml]"]
  node_dbtemplate["Database Template<br/>[template.yaml]"]
  node_claims["Infrastructure Claims"]
  node_crossplane["Crossplane API"]
  node_compositions["Resource Compositions"]
end

subgraph group_delivery["GitOps Delivery"]
  node_argocd["Argo CD<br/>[workloads.yaml]"]
  node_workloads["Workload AppSets<br/>[workloads.yaml]"]
  node_platformapps["Platform AppSets"]
  node_cluster["Kubernetes Cluster"]
  node_helm["Application Helm Chart<br/>[Chart.yaml]"]
end

subgraph group_governance["Policy Enforcement"]
  node_policies["Admission Policies"]
  node_kyverno["Kyverno Rules"]
  node_opa["OPA Rules"]
end

subgraph group_infrastructure["Cloud Infrastructure"]
  node_terraform["Terraform Provisioning<br/>[main.tf]"]
  node_cloud["Cloud Infrastructure"]
end

node_developer(("Developer"))

node_developer -->|"uses"| node_portal
node_portal -->|"launches templates"| node_scaffolder
node_portal -->|"browses catalog"| node_catalog
node_catalog -->|"catalogs entities"| node_catalogdata
node_catalog -->|"processes entities"| node_teams
node_scaffolder -->|"runs template"| node_microtemplate
node_scaffolder -->|"runs template"| node_dbtemplate
node_scaffolder -->|"creates infrastructure claim"| node_claims
node_claims -->|"requests resources"| node_crossplane
node_crossplane -->|"resolves claims"| node_compositions
node_argocd -->|"manages applications"| node_workloads
node_argocd -->|"manages applications"| node_platformapps
node_argocd -->|"syncs workloads"| node_cluster
node_cluster -->|"enforces at admission"| node_policies
node_policies -->|"includes rules"| node_kyverno
node_policies -->|"includes rules"| node_opa
node_terraform -->|"provisions infrastructure"| node_cloud
node_helm -.->|"packages workloads"| node_cluster

click node_portal "https://github.com/betelabs/platform-engineering-idp/blob/main/backstage/packages/app/src/components/HomePage.tsx"
click node_catalog "https://github.com/betelabs/platform-engineering-idp/blob/main/backstage/packages/backend/src/plugins/catalog.ts"
click node_catalogdata "https://github.com/betelabs/platform-engineering-idp/blob/main/backstage/catalog/all.yaml"
click node_teams "https://github.com/betelabs/platform-engineering-idp/blob/main/backstage/catalog/groups.yaml"
click node_scaffolder "https://github.com/betelabs/platform-engineering-idp/blob/main/backstage/packages/backend/src/plugins/scaffolder.ts"
click node_microtemplate "https://github.com/betelabs/platform-engineering-idp/blob/main/catalog-templates/microservice/template.yaml"
click node_dbtemplate "https://github.com/betelabs/platform-engineering-idp/blob/main/catalog-templates/database/template.yaml"
click node_claims "https://github.com/betelabs/platform-engineering-idp/tree/main/crossplane/claims/examples"
click node_crossplane "https://github.com/betelabs/platform-engineering-idp/tree/main/crossplane/xrds"
click node_compositions "https://github.com/betelabs/platform-engineering-idp/tree/main/crossplane/compositions"
click node_argocd "https://github.com/betelabs/platform-engineering-idp/blob/main/gitops/argocd/appsets/workloads.yaml"
click node_workloads "https://github.com/betelabs/platform-engineering-idp/blob/main/gitops/argocd/appsets/workloads.yaml"
click node_platformapps "https://github.com/betelabs/platform-engineering-idp/blob/main/gitops/argocd/appsets/platform-components.yaml"
click node_policies "https://github.com/betelabs/platform-engineering-idp/tree/main/policies"
click node_kyverno "https://github.com/betelabs/platform-engineering-idp/tree/main/policies/kyverno"
click node_opa "https://github.com/betelabs/platform-engineering-idp/tree/main/policies/opa"
click node_terraform "https://github.com/betelabs/platform-engineering-idp/blob/main/terraform/aws/main.tf"
click node_helm "https://github.com/betelabs/platform-engineering-idp/blob/main/helm/app-template/Chart.yaml"

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_portal,node_catalog,node_catalogdata,node_teams toneBlue
class node_scaffolder,node_microtemplate,node_dbtemplate,node_claims,node_crossplane,node_compositions toneAmber
class node_argocd,node_workloads,node_platformapps,node_cluster,node_helm toneMint
class node_policies,node_kyverno,node_opa toneRose
class node_terraform,node_cloud,node_developer toneIndigo
```

## Components

### Developer Portal

- [Backstage Portal](https://github.com/betelabs/platform-engineering-idp/blob/main/backstage/packages/app/src/components/HomePage.tsx): `backstage/packages/app/src/components/HomePage.tsx`
- [Service Catalog](https://github.com/betelabs/platform-engineering-idp/blob/main/backstage/packages/backend/src/plugins/catalog.ts): `backstage/packages/backend/src/plugins/catalog.ts`
- [Catalog Records](https://github.com/betelabs/platform-engineering-idp/blob/main/backstage/catalog/all.yaml): `backstage/catalog/all.yaml`
- [Teams and Systems](https://github.com/betelabs/platform-engineering-idp/blob/main/backstage/catalog/groups.yaml): `backstage/catalog/groups.yaml`

### Self-Service Provisioning

- [Template Scaffolder](https://github.com/betelabs/platform-engineering-idp/blob/main/backstage/packages/backend/src/plugins/scaffolder.ts): `backstage/packages/backend/src/plugins/scaffolder.ts`
- [Microservice Template](https://github.com/betelabs/platform-engineering-idp/blob/main/catalog-templates/microservice/template.yaml): `catalog-templates/microservice/template.yaml`
- [Database Template](https://github.com/betelabs/platform-engineering-idp/blob/main/catalog-templates/database/template.yaml): `catalog-templates/database/template.yaml`
- [Infrastructure Claims](https://github.com/betelabs/platform-engineering-idp/tree/main/crossplane/claims/examples): `crossplane/claims/examples`
- [Crossplane API](https://github.com/betelabs/platform-engineering-idp/tree/main/crossplane/xrds): `crossplane/xrds`
- [Resource Compositions](https://github.com/betelabs/platform-engineering-idp/tree/main/crossplane/compositions): `crossplane/compositions`

### GitOps Delivery

- [Argo CD](https://github.com/betelabs/platform-engineering-idp/blob/main/gitops/argocd/appsets/workloads.yaml): `gitops/argocd/appsets/workloads.yaml`
- [Workload AppSets](https://github.com/betelabs/platform-engineering-idp/blob/main/gitops/argocd/appsets/workloads.yaml): `gitops/argocd/appsets/workloads.yaml`
- [Platform AppSets](https://github.com/betelabs/platform-engineering-idp/blob/main/gitops/argocd/appsets/platform-components.yaml): `gitops/argocd/appsets/platform-components.yaml`
- **Kubernetes Cluster**
- [Application Helm Chart](https://github.com/betelabs/platform-engineering-idp/blob/main/helm/app-template/Chart.yaml): `helm/app-template/Chart.yaml`

### Policy Enforcement

- [Admission Policies](https://github.com/betelabs/platform-engineering-idp/tree/main/policies): `policies`
- [Kyverno Rules](https://github.com/betelabs/platform-engineering-idp/tree/main/policies/kyverno): `policies/kyverno`
- [OPA Rules](https://github.com/betelabs/platform-engineering-idp/tree/main/policies/opa): `policies/opa`

### Cloud Infrastructure

- [Terraform Provisioning](https://github.com/betelabs/platform-engineering-idp/blob/main/terraform/aws/main.tf): `terraform/aws/main.tf`
- **Cloud Infrastructure**

### Other components

- **Developer**

## Connections

- Developer → Backstage Portal: uses (evidence: `README.md`)
- Backstage Portal → Template Scaffolder: launches templates (evidence: `README.md`)
- Backstage Portal → Service Catalog: browses catalog (evidence: `README.md`)
- Service Catalog → Catalog Records: catalogs entities (evidence: `backstage/packages/backend/src/plugins/catalog.ts`)
- Service Catalog → Teams and Systems: processes entities (evidence: `backstage/packages/backend/src/plugins/catalog.ts`)
- Template Scaffolder → Microservice Template: runs template (evidence: `README.md`)
- Template Scaffolder → Database Template: runs template (evidence: `README.md`)
- Template Scaffolder → Infrastructure Claims: creates infrastructure claim (evidence: `README.md`)
- Infrastructure Claims → Crossplane API: requests resources (evidence: `README.md`)
- Crossplane API → Resource Compositions: resolves claims (evidence: `README.md`)
- Argo CD → Workload AppSets: manages applications (evidence: `README.md`)
- Argo CD → Platform AppSets: manages applications (evidence: `README.md`)
- Argo CD → Kubernetes Cluster: syncs workloads (evidence: `README.md`)
- Kubernetes Cluster → Admission Policies: enforces at admission (evidence: `README.md`)
- Admission Policies → Kyverno Rules: includes rules (evidence: `README.md`)
- Admission Policies → OPA Rules: includes rules (evidence: `README.md`)
- Terraform Provisioning → Cloud Infrastructure: provisions infrastructure (evidence: `README.md`)
- Application Helm Chart → Kubernetes Cluster: packages workloads
