Skip to main content

Backstage Application

The Backstage application is the core of the DevEx Platform, providing a unified developer portal with custom plugins for GCP, GitHub, Vault, and more.

Directory Structure​

backstage/
├── packages/
│   ├── app/                    # Frontend React application
│   │   └── src/
│   │       ├── App.tsx         # Main app component
│   │       └── components/     # UI components
│   │
│   └── backend/                # Backend API server
│       └── src/
│           ├── index.ts        # Entry point
│           └── plugins/        # Plugin integrations
│
├── plugins/                    # 13 custom plugins
│   ├── homepage-links/         # Dashboard customization
│   ├── claude-flow/            # AI development
│   ├── vault-secrets/          # Secret management
│   ├── terraform-cloud/        # TFC integration
│   ├── mockup/                 # UI mockups
│   └── *-backend/              # Backend counterparts
│
├── docs/                       # Backstage-specific docs
├── tests/                      # E2E and integration tests
└── CLAUDE.md                   # Development rules

Plugin Overview​

Frontend Plugins​

PluginPackagePurposeDocs
Homepage Links@internal/plugin-homepage-linksCustomizable dashboardDetails
Claude Flow@internal/plugin-claude-flowAI development integrationDetails
Vault Secrets@internal/backstage-plugin-vault-secretsSecret management UIDetails
Terraform Cloud@internal/plugin-terraform-cloudTFC integration UIDetails
Mockup@internal/plugin-mockupUI mockup canvasDetails

See Plugins Overview for detailed documentation.

Backend Plugins​

PluginPackagePurposeDocs
Homepage Links Backend@internal/plugin-homepage-links-backendUser preferencesDetails
Homepage Repos Backend@internal/plugin-homepage-repos-backendGitHub reposDetails
Homepage GCP Projects Backend@internal/plugin-homepage-gcp-projects-backendGCP projectsDetails
Claude Flow Backend@internal/plugin-claude-flow-backendAI sessionsDetails
Vault Secrets Backend@internal/backstage-plugin-vault-secrets-backendVault integrationDetails
Terraform Cloud Backend@internal/plugin-terraform-cloud-backendTFC operationsDetails
Terraform State Backend@internal/plugin-terraform-state-backendState managementDetails
Mockup Backend@internal/plugin-mockup-backendMockup persistenceDetails

Application Architecture​

Authentication​

The application supports multiple authentication providers:

ProviderUse Case
GitHub OAuthDeveloper login, PR operations
Google OAuthGCP access, user identity
GCP IAPProduction access control
GuestDevelopment environment

Dual Authentication Pattern​

Important

User-initiated actions (PR reviews, comments) MUST use the user's OAuth token, not the backend service account.

Configuration​

Base Configuration​

# app-config.yaml
app:
  title: DevEx Backstage
  baseUrl: http://localhost:3001

backend:
  baseUrl: http://localhost:7007
  listen:
    port: 7007
  database:
    client: pg
    connection:
      host: ${POSTGRES_HOST}
      port: ${POSTGRES_PORT}
      user: ${POSTGRES_USER}
      password: ${POSTGRES_PASSWORD}

Local Development​

# app-config.local.yaml
backend:
  database:
    connection:
      host: localhost
      port: 5432
      user: postgres
      password: postgres

cors:
  origin: http://localhost:3001
  allowedHeaders:
    - X-Gcp-Access-Token
    - X-GitHub-Token

Production​

The app-config.production.yaml.tpl template is processed during deployment with environment variables from Terraform outputs.

Database​

Connection​

  • Engine: PostgreSQL 15
  • ORM: Knex.js
  • Migrations: Per-plugin migrations in migrations/ directories

Pool Configuration​

database:
  pool:
    min: 5
    max: 20

Development​

Prerequisites​

  • Node.js 20+ (22 recommended)
  • Yarn 4.4.1
  • PostgreSQL 15
  • Docker (for Claude Flow)

Quick Start​

cd backstage
yarn install
yarn dev

Useful Commands​

CommandPurpose
yarn devStart frontend and backend
yarn startStart frontend only
yarn start-backendStart backend only
yarn tscTypeScript compilation
yarn lintRun ESLint
yarn testRun all tests
yarn build:backendProduction build

Ports​

ServicePort
Frontend3001
Backend7007

Testing​

Unit Tests​

yarn test

E2E Tests (Playwright)​

cd tests
npx playwright test
See Also

For Backstage-specific development rules, see /backstage/CLAUDE.md