Building Internal Developer Platforms: The Architecture Behind Engineering Velocity

A reference guide for designing IDPs with Backstage, Terraform modules, Crossplane, and ArgoCD that actually get adopted.

Covers platform architecture decisions, golden path design for heterogeneous service portfolios, Backstage configuration and catalog governance, policy-as-code with OPA Gatekeeper, self-service infrastructure provisioning with Crossplane, and DORA metrics integration. Includes a platform team operating model and adoption playbook.

EDITION · Q3 2024 · 38 PAGES

PLATFORM ENGINEERING

Building Internal Developer Platforms

CELESDEV Solutions · celesdev.com

Executive Summary

Multiple golden paths, one platform

Internal Developer Platforms succeed when they reduce cognitive load for the engineers who use them. They fail when they become either too rigid (one golden path that doesn't fit most workloads) or too flexible (a menu of options requiring expertise to navigate).

This guide documents the architecture decisions we've made across IDP engagements serving 200 to 1,200 engineers on 40 to 340 services.

1

Design service archetypes, not a single golden path

Six archetypes (HTTP API, event consumer, batch job, ML endpoint, frontend, infrastructure module) cover 95% of service types with appropriate defaults for each.

2

Policy-as-code replaces approval gates

OPA Gatekeeper and Azure Policy deny effects enforce standards structurally. Compliance becomes invisible to compliant teams and automatic for non-compliant resources.

3

Backstage catalog accuracy requires automation

CI validation of catalog-info.yaml and weekly drift reports are necessary to maintain catalog quality. An inaccurate catalog erodes trust faster than no catalog.

4

Connect cost, reliability, and deployment in one view

Backstage integrations showing cost, DORA metrics, and open alerts per service eliminate context switching and increase platform adoption organically.

Platform Architecture

IDP Reference Stack

IDP Component Architecture

Developer Portal · Backstage (Software Catalog + Templates)

GitOps Layer · ArgoCD + Kustomize

IaC Self-Service · Crossplane + Terraform Cloud

Policy Engine · OPA Gatekeeper + Azure Policy

Observability · Prometheus + Grafana + Datadog

Author: CELESDEV Solutions — Cloud & Platform Practice.

Applicable contexts: Engineering organisations of 100–5,000 developers; multi-cloud Kubernetes environments; organisations targeting DORA Elite or High performer tier.

Full document includes Backstage plugin evaluation matrix, Crossplane composition examples, and platform team OKR templates.

CELESDEV Solutions | celesdev.com | business@celesdev.com

2 of 3 - Executive Summary

Building Internal Developer Platforms

CELESDEV Solutions | celesdev.com

Service Archetype Map

Six archetypes, one platform

ARCHETYPE	DEFAULT STACK	SCALING MODEL
HTTP API	Kubernetes Deployment + HPA + Ingress	Replica-based, CPU/RPS triggered
Event consumer	KEDA + Kafka consumer group	Lag-based autoscaling
Batch job	CronJob + spot node pool	Node provisioning on schedule
ML endpoint	GPU node pool + KNative serving	Request-based, scale to zero
Frontend	Static build + CDN + edge cache	CDN-native, serverless origin
IaC module	Terraform module + Crossplane XRD	Declarative, GitOps-driven

Coverage: These six archetypes account for 95%+ of service types across IDP deployments serving 200-1,200 engineers. Each archetype has a Backstage scaffolder template, an ArgoCD app template, and a pre-wired observability configuration.

Platform Adoption and DORA Metrics

Adoption phases and performance targets

PHASE 1 - FOUNDATION (months 1-3)

Core platform team formed. Backstage deployed, catalog seeded from existing repos. First two service archetypes available via scaffolder templates.

PHASE 2 - GROWTH (months 4-9)

All six archetypes available. Cost, DORA, and alert data surfaced in Backstage. Early adopter feedback incorporated. Catalog accuracy maintained via CI validation.

PHASE 3 - SCALE (months 10+)

80%+ of new services use platform. Self-service provisioning covers 100% of standard infrastructure. Platform team OKRs measured against DORA Elite targets.

DORA METRIC	HIGH	ELITE
Deploy frequency	1/week - 1/day	Multiple/day
Lead time	1 day - 1 week	< 1 hour
Change failure rate	16-30%	< 5%
Recovery time	1 day - 1 week	< 1 hour

CELESDEV Solutions | celesdev.com | business@celesdev.com

3 of 3 - Technical Reference