Technical Reference Architecture

The path from developer to production

Developer
PlatformBox Golden Path
Source / CI/CD
Infrastructure + Policy
AWS / Kubernetes
Production

The components

What each layer does — and who owns it.

Terraform

Infrastructure lifecycle

All infrastructure is defined as versioned Terraform modules, reviewed and applied through CI. Changes are auditable and reversible.

Proofe-iac-plan

Kubernetes / EKS

Application runtime

Workloads run on EKS with least-privilege RBAC, per-team namespaces, autoscaling, and a monitoring baseline.

Proofe-cluster-proof

GitLab

Source and workflow

Repositories, merge requests, and approvals stay in GitLab. PlatformBox wires them into the golden path.

CI/CD

Application delivery

A standard pipeline builds, scans (Trivy), and promotes each service from commit to production — no per-team pipeline maintenance.

Proofe-pipeline-green

GitOps

Declared desired state

The cluster reconciles to the state declared in Git (ArgoCD, cluster-level proven per ADR-016). Deployments are pull-based, reviewable, and auditable.

Proofe-promotion-digest

IAM

Least-privilege access

Scoped roles for humans and workloads. Keyless CI-to-AWS auth via OIDC — no static credentials. Separate IAM roles per environment tier (dev, qa/uat, preview, prod) — environment separation by default, enforced by AWS STS.

Proofe-oidc-proof

Security

Built into the path

Trivy scanning in CI, GuardDuty threat detection, encrypted storage and state, and automated checks run on every change.

Proofe-scan-blocking

Observability

See what's running

Prometheus + Grafana — metrics and dashboards, live-proven across both services and all three tiers (ADR-018).

Proofe-scrape-targets

Platform ownership

You own it all

Everything lives in your accounts and repositories. No proprietary runtime, no lock-in.

Verified vs. planned

What's actually built today.

Drawn from applied Terraform state, not the roadmap. Solid green marks what's built and checked today; dashed blue is verified but on-demand; dashed grey is target state we haven't built yet. Every verified claim traces to a decision record in the reference implementation — pre-rendered from it, not a snapshot.

Golden path — automated flow

Production-proven

A gate blocking a bad build

Provisioning / control

Fig. 1Golden Path — Developer FlowHover or focus a node · Enter to pin

A developer's commit flows through the pipeline and the security gate to preview and the dev, QA and UAT tiers — and a bad build is blocked at the gate, never promoted.

Fig. 2Platform InfrastructureHover or focus a node · Enter to pin

Six platform layers on AWS, all declared as Terraform modules and composed by per-environment stacks.

Fig. 3Security & Auth FlowHover or focus a node · Enter to pin

Humans sign in through IAM Identity Center; CI reaches AWS keyless through OIDC, assuming scoped per-environment roles — no static credentials.

Fig. 4Promotion Sequence — Dev Push to ReleaseHover or focus a node · Enter to pin

A feature branch deploys to preview; merging to main builds once and promotes the same digest through dev, QA and UAT — with a human approver gating UAT.

Source: architecture.md — drawn inline from the reference implementation, not a pre-rendered snapshot.

Inspect the Implementation

Real code. Real infrastructure.

Click through the actual Terraform, YAML, and pipeline manifests that the reference implementation applies on Day 14. Every snippet comes from a working, inspected repository.

Security & Identity
IAM OIDC — CI → AWS without credentials
GitLab CI assumes an AWS IAM role via OIDC federation. No static keys, scoped per environment tier.
terraform
Platform & Compute
EKS Karpenter Provisioner
Karpenter auto-selects optimal instance types. Idle clusters cost $0 — ephemeral nodes self-destroy.
yaml
Security & Governance
Kyverno ClusterPolicy — immutable digests
Rejects any workload referencing mutable tags. Enforces SHA256 digests; does not warn.
yaml
Delivery & CI/CD
CI/CD Golden Path — .gitlab-ci.yml
Standard pipeline: lint, test, scan, build, promote through IAM-enforced staging gates.
yaml
GitOps & Delivery
ArgoCD GitOps Application — reconcile, don't push
The cluster reconciles to the state declared in Git. No direct kubectl, no drift.
yaml

Security & Identity—IAM OIDC — CI → AWS without credentials

terraform

resource "aws_iam_openid_connect_provider" "gitlab" {
  url             = "https://gitlab.com"
  client_id_list  = ["https://gitlab.com"]
}

resource "aws_iam_role" "ci" {
  for_each = var.environments
  name     = "platformbox-ci-${each.key}"
  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect = "Allow"
      Principal = { Federated = aws_iam_openid_connect_provider.gitlab.arn }
      Action = "sts:AssumeRoleWithWebIdentity"
    }]
  })
}

Proof, not promises

Verify it yourself.

Everything below links to the actual reference implementation — Terraform modules, decision records, and live evidence — not a marketing snapshot. The diagrams above are pre-rendered from that repository.

The repository

The full reference implementation — Terraform, CI/CD, and documentation. Public and inspectable.

Live evidence

Real Terraform plan output, GuardDuty findings, cost breakdown, and dated end-to-end proof files for the golden path, preview, promotion, GitOps, observability, production, and rollback.

Decision records

32 ADRs explaining each architecture choice — and what was rejected.

Architecture source

The single source of truth for the diagrams above — pre-rendered from this file.

Terraform modules

Network, security, EKS, IAM, and CI runner — versioned, reviewed, and reproducible.

Demo runbook

The full lifecycle as a repeatable runbook — local → preview → dev → qa → uat → prod → rollback. Every step individually proven; not yet rehearsed end-to-end.

The proof surface

Each capability claim links to the evidence behind it.

The 19 evidence keys below are the delivery standard's proof contract — named in the standard, produced on a fixed working day, and each resolved to a public file in the reference implementation. Click any key to read the actual artifact, not a summary of it.

Hash-linked & verifiable

Every attestation is chained by hash to the one before it, in the control plane at /admin. A tampered record breaks the chain and is detectable, not silent.

Public-safe

Real customer evidence is tenant-scoped and never exposed. The files below come from the reference engagement only — no engagement ids, no proven_with data.

Customer Zero

PlatformBox is deliberately its own first customer. The proof you can read is our own reference implementation, built and verified in public.

Derived

Generated from tool output — a terraform plan, a CI log, a scan report. Anyone can re-run the command and see the same result.

Attested

Recorded in the audit chain — a human-signed fact about the engagement, linked by hash to what came before it.

Week 1 — Foundation

e-scope-statementattestedDOCUMENT

Confirmed scope statement

The scope statement as acknowledged by the customer.

Week 1 · Day 1Read evidence

e-assessmentattestedDOCUMENT

Assessment findings

What was found, and what it implies for scope. Customer-specific — attested inside the engagement, not published.

Week 1 · Day 2Customer-scoped

e-access-verifiedderivedCONFIGURATION

Access verification output

Recorded output of the access verification runbook.

Week 1 · Day 3Read evidence

e-architectureattestedDOCUMENT

Architecture summary and diagram

The agreed architecture as presented at the review.

Week 1 · Day 4Read evidence

e-iac-planderivedIAC_PLAN

Infrastructure plan showing zero drift

Plan output against live infrastructure.

Proves: AWS foundation, Infrastructure as Code (Terraform), Networking

Week 1 · Day 5Read evidence

e-cluster-proofderivedDEPLOYMENT

Cluster reachable

Authenticated API call against the provisioned cluster.

Proves: AWS foundation, Kubernetes / EKS

Week 1 · Day 5Read evidence

Week 2 — Delivery

e-oidc-proofderivedCONFIGURATION

OIDC trust verification

Proof that CI assumed a role with no stored credential.

Proves: IAM & least privilege

Week 2 · Day 6Read evidence

e-scan-blockingderivedSECURITY_SCAN

Security scan blocking a build

A pipeline that failed on a deliberately introduced vulnerability.

Proves: Security scanning

Week 2 · Day 6Read evidence

e-pipeline-greenderivedCI_RUN

First green pipeline

Pipeline URL and result.

Proves: Container registry, CI/CD

Week 2 · Day 7Read evidence

e-tiersderivedDEPLOYMENT

Tiers provisioned and reachable

Per-tier deployment record.

Proves: Preview environments

Week 2 · Day 8Read evidence

e-gate-blocksderivedCONFIGURATION

Gated tier refused an unapproved promotion

Evidence that the gate is enforcing, not decorative.

Proves: Production promotion & controls

Week 2 · Day 8Read evidence

e-generated-servicederivedCI_RUN

Generated service pipeline

The pipeline for a service produced by the generator.

Proves: Golden Path (build -> production), Self-service (service creation)

Week 2 · Day 9Read evidence

e-promotion-digestderivedDEPLOYMENT

Identical digest across tiers

Digest recorded per tier, proving promotion without rebuild.

Proves: Golden Path (build -> production), GitOps / declarative deployment, Production promotion & controls

Week 2 · Day 9Read evidence

e-rollbackderivedROLLBACK

Rollback rehearsal

Rollback executed and the prior digest confirmed restored.

Proves: Golden Path (build -> production)

Week 2 · Day 9Read evidence

e-scrape-targetsderivedMONITORING

Scrape targets up across all tiers

Target list with tier and cluster labels.

Proves: Metrics

Week 2 · Day 10Read evidence

Week 3 — Production & handover

e-costattestedCOST

Cost breakdown

Per-tier cost with assumptions stated.

Proves: Cost control (FinOps)

Week 3 · Day 11Read evidence

e-reproductionderivedTEST_OUTPUT

Reproduction executed

Output of rebuilding from the written procedure.

Week 3 · Day 12Read evidence

e-runbooksattestedDOCUMENT

Operational runbooks

The runbook set as delivered.

Week 3 · Day 12Read evidence

e-handover-packderivedDOCUMENT

Handover pack

The generated pack as delivered.

Proves: Documentation & handover

Week 3 · Day 14Read evidence

Browse the full evidence tree in the reference implementation:docs/evidence Delivery standard v1.2.0 — 19 keys across 14 working days.

Start with the Platform Readiness Assessment.

€2,500 · Mandatory first step · Independent recommendation before implementation. Talk to Roberto first if you have questions.

Start Assessment — €2,500 Talk to Roberto

The PlatformBox reference architecture.

The path from developer to production

What each layer does — and who owns it.

What's actually built today.

Real code. Real infrastructure.

Verify it yourself.

Each capability claim links to the evidence behind it.

Start with the Platform Readiness Assessment.