Platform Architecture

System Architecture Diagram

┌─────────────────────────────────────────────────────────────────────────┐
│                          Backstage Catalog                               │
│  Domain    System      Component          Resource                       │
│  payments  gateway     gateway-api        gcp-payments-prod-cloudsql     │
│                        ├── k8s tab  →  health per env per cluster        │
│                        ├── argo tab →  sync status per env               │
│                        └── deps    →  cloudsql ← READY/SYNCED via k8s   │
└──────────┬──────────────────────────────┬───────────────────────────────┘
           │ k8s + argocd plugins          │ k8s plugin (Claim CRD)
┌──────────▼──────────────┐       ┌────────────▼─────────────────────────┐
│         ArgoCD           │       │          Kubernetes clusters          │
│  AppProject: payments ───┼───────┼► payments-{env}-api (per cluster)    │
│  AppProject: platform ───┼───────┼► platform-{env}-monitoring           │
│  AppSet: crossplane   ───┼───────┼► payments-prod-infra/cloudsql-main   │
│    -claims               │       │                                      │
└──────────┬───────────────┘       └──────────────────┬────────────────────┘
           │ syncs                                     │ Crossplane reconciles
┌──────────▼───────────────────────────────────────────▼───────────────────┐
│                           Git Repositories                                │
│  platform-gitops/               {domain}-gitops/                         │
│  ├── argocd/                    ├── k8s/{env}/{service}/                 │
│  ├── crossplane/                ├── crossplane/claims/{env}/{type}/      │
│  ├── k8s/rbac/                  └── catalog/                             │
│  └── backstage-templates/                                                │
│                                        Cloud Providers                   │
│                                 ────►  GCP / AWS / Azure / IBM           │
└──────────────────────────────────────────────────────────────────────────┘

Cluster Topology

Cluster	Role	Hosts
cluster-mgmt	Management	ArgoCD, Crossplane, platform Tier B services
cluster-dev	Dev workloads	Domain dev Applications, platform Tier A services
cluster-staging	Staging workloads	Domain staging Applications, platform Tier A services
cluster-prod	Production	Domain prod Applications, platform Tier A services

Semantic Key

The entire platform is addressed via a single three-segment key:

{project} - {env} - {service}

payments  - prod  - api
│           │        └── Kubernetes: namespace payments-prod-api
│           │            Backstage:  Component gateway-api (env-agnostic)
│           └── ArgoCD:  Application gateway-api-prod
└── ArgoCD:    AppProject payments
    Backstage: Domain payments

Service Deployment Flow

Developer runs create-service template
  → Scaffolds App Repo (CI/CD, TechDocs) and opens two GitOps PRs
  → Platform PR merged → ApplicationSet element added
  → Domain PR merged  → k8s manifests pushed to {domain}-gitops
  → ArgoCD detects new Application via ApplicationSet matrix generator
  → ArgoCD syncs to cluster-dev
  → Namespace, Deployment, Service, Policies created
  → Backstage k8s plugin surfaces pod health across all clusters

Cloud Resource Provisioning Flow

Developer runs create-resource template
  → One PR opened on domain-gitops
  → PR merged → Claim YAML at crossplane/claims/prod/{type}-{name}.yaml
  → ArgoCD git-directory generator detects new file → creates Application
  → Application synced to cluster-mgmt
  → Crossplane reconciles Claim → provisions resource on GCP/AWS/Azure/IBM
  → Connection secret written to {domain}-prod-infra namespace
  → Backstage Resource page shows READY: True, SYNCED: True