Platform IDP — Reference Architecture
This page is the visual companion to the Platform IDP project page. It is the architectural source-of-truth for the 9 ADRs surfaced on that page's Architecture tab.
Source: extracted verbatim from the original research material (previously downloads/PlatformOpsProject/mermaid-diagrams.md) and merged into the docs site so Docusaurus renders the diagrams natively. The downloads/ source has been archived to tmp/adlc-framework/archived-inputs/PlatformOpsProject-2026-04-30/ — this page is now the SSOT.
Architectural thesis: Backstage and DataHub are not interchangeable. Backstage owns the delivery control plane (services, golden paths, runbooks, ownership). DataHub owns the data control plane (lineage, contracts, glossary, classification). Using one to replace the other creates a blind spot.
C4 Container View — Platform-IDP Cockpit with Backstage, DataHub OSS, ADLC, and Claude Agents
Platform-IDP Cockpit — Backstage + DataHub OSS + ADLC + Runtime Platforms
A more boardroom-readable flowchart of the same architecture, grouping each layer for at-a-glance comprehension. Each subsystem has its own colour band; relationship arrows are colour-coded to the originating actor or system.
How this maps to the project page
- The Architecture tab on
/project?id=platform-idplists the 9 ADRs (ADR-001 through ADR-009). - ADR-001 ("Backstage front door + DataHub metadata brain — split, not merged") is exactly the diagrams above.
- ADR-002 through ADR-009 are textual decisions consistent with the layers shown.
- Talent Bench (
/project?id=platform-idpTeam tab) maps roles 1:1 to the Claude Agents + ADLC box.
Key architectural rules enforced by this design
| Rule | Where it lives | Why |
|---|---|---|
| Backstage owns the delivery control plane | Backstage layer in diagram | Service ownership + golden paths is its core competency |
| DataHub owns the data control plane | DataHub layer in diagram | Lineage + contracts + glossary cannot be modelled inside Backstage entities |
| Claude agents read context — never guess | AI layer with arrow into Backstage | Grounded recommendations cite Backstage entities + DataHub lineage |
| HITL approves every production change | HITL → Backstage arrow | ADLC Principle I (acceptable agency) — agents prepare, humans decide |
| Jira/JSM remains the workflow gate | Runtime layer (Jira/JSM/Confluence) | Existing system of record for change approval |
| Snowflake/S3 lineage is contract-driven | DataHub → Runtime arrow | Data contracts formalise candidate/application/metering schemas |
Cross-links
- Project page: /project?id=platform-idp
- Talent Bench: /talent-bench
- ADLC Governance pillar: /pillars/adlc-governance
- Acceptable Agency rule:
.claude/rules/governance/principle-i-acceptable-agency.md - Pentagon Portfolio: /project — Platform · IDP is the center of the pentagon constellation
DDD Bounded-Context Map — Sprint 1 + Forward References
In Domain-Driven Design, a bounded context is a logical boundary within which a domain model is consistent and authoritative (Evans 2003; Fowler bliki/BoundedContext). Where two bounded contexts must communicate, an Anti-Corruption Layer (ACL) translates between their models without leaking concepts across the boundary. In this platform, the PI-005 Golden-Path Scaffolder acts as the primary ACL: it normalises owner, lifecycle, and cost-centre metadata from the Local Development context into the canonical forms expected by Service Catalog, Workflow, and FinOps.
The map below shows all eight bounded contexts for Platform-IDP. Contexts delivered in Sprint 1 are marked PI-00N ✓; forward references show the sprint in which each context will be activated.
Golden Path Sequence — PI-005 ECS Service Scaffolder
JSM Change-Gate Sequence — PI-008 Production Change Workflow
Port Mapping (configurable via env vars)
| Service | Default host port | Container port | Env var | What HITL hits |
|---|---|---|---|---|
| Backstage frontend (UI) | :3001 | :3000 | BACKSTAGE_FRONTEND_PORT | http://localhost:3001 |
| Backstage backend (API) | :7007 | :7007 | BACKSTAGE_BACKEND_PORT | http://localhost:7007/api/* |
| PostgreSQL (DB) | :5432 | :5432 | (none — pinned) | psql -h localhost -p 5432 (NOT curl) |
| ADLC Docusaurus | :3000 | :3000 | ADLC_DOCS_PORT | http://localhost:3000 |
Why ports differ from defaults: Backstage's default frontend port is :3000, but adlc-framework's Docusaurus also runs on :3000. Both are configurable via env vars with backwards-compatible defaults. To run Backstage on its conventional :3000, set export ADLC_DOCS_PORT=3010 first.
:5432 is NOT HTTP — PostgreSQL uses its own wire protocol. curl http://localhost:5432 returns ERR_EMPTY_RESPONSE because PostgreSQL is not an HTTP server. Use psql -h localhost -p 5432 -U idp to connect.
:7007 is API-only — there is no browser UI at http://localhost:7007/. The React UI lives at http://localhost:3001. To verify the backend is healthy: curl http://localhost:7007/.backstage/health/v1/readiness → 200 OK.