Architecture Overview
The DevEx Backstage Platform is a comprehensive developer experience solution deployed on Google Cloud Platform, built on the Backstage framework.
High-Level Architecture
Component Layers
1. Presentation Layer
The frontend is a React application built with Material-UI, providing:
- Homepage Dashboard - Customizable sections for onboarding, team links, repos, GCP projects, and PRs
- Catalog Browser - Service catalog with entity relationships
- Scaffolder - Template-based project creation
- Plugin UIs - Terraform, Vault, Claude Flow, and Mockup interfaces
2. API Layer
The backend API server handles:
- Authentication - Multi-provider OAuth (GitHub, Google, GCP IAP)
- Authorization - Role-based access via Backstage permissions
- Plugin APIs - RESTful endpoints for each plugin
- Proxy - Secure external API access
3. Plugin Layer
13 custom plugins extend Backstage functionality:
| Category | Plugins |
|---|---|
| Homepage | homepage-links, homepage-repos-backend, homepage-gcp-projects-backend |
| Infrastructure | terraform-cloud, terraform-state-backend |
| Security | vault-secrets, vault-secrets-backend |
| Development | claude-flow, claude-flow-backend |
| Design | mockup, mockup-backend |
4. Data Layer
- Cloud SQL - PostgreSQL 15 for application data
- HashiCorp Vault - Secrets management with GCP KMS auto-unseal
- Cloud Storage - TechDocs and Vault configuration
5. Infrastructure Layer
- Cloud Run - Containerized deployment with VPC connector
- Private VPC - Internal networking with Cloud NAT
- IAP - Secure external access to Vault
Authentication Architecture
Dual Authentication Pattern
| Flow | Use Case | Token Type |
|---|---|---|
| User OAuth | PR reviews, comments, user actions | User's GitHub/Google token |
| Service Auth | Backend-to-backend, catalog ingestion | Vault JWT or ADC |
Deployment Architecture
CI/CD Pipeline
- Semantic Versioning - Automatic version calculation
- Terraform Apply - Infrastructure provisioning via TFC
- Docker Build - Multi-stage build with caching
- Cloud Run Deploy - Zero-downtime deployment
Network Architecture
Technology Stack
| Layer | Technology |
|---|---|
| Frontend | React 18, TypeScript, Material-UI |
| Backend | Node.js 22, TypeScript, Express |
| Database | PostgreSQL 15 (Cloud SQL) |
| Secrets | HashiCorp Vault with GCP KMS |
| Infrastructure | Terraform, Google Cloud Platform |
| CI/CD | GitHub Actions, Terraform Cloud |
| Container | Docker, Cloud Run |
| Documentation | Docusaurus 3 |
Related Documentation
- Infrastructure Details - Terraform and GCP resources
- Backstage Application - Plugins and configuration
- GitHub Workflows - CI/CD pipeline details
- Scripts - Utility script documentation