A production-hardened Internal Developer Platform (IDP) reference implementation built with AWS CDK (TypeScript). This repository demonstrates modern Platform Engineering practices: infrastructure-as-code, GitOps, policy-as-code, observability, FinOps, and self-service developer workflows — all wired together with enterprise-grade security defaults.
This repository is packaged as a practical consulting accelerator for organizations moving from fragmented infrastructure delivery to a measurable platform-as-a-product model.
| Client Problem | Consulting Outcome | Repository Evidence |
|---|---|---|
| Teams ship services through inconsistent project setup and manual infrastructure handoffs. | Standardized golden paths reduce time to first deployment and make ownership visible. | Backstage templates, service catalog metadata, reusable CDK constructs, onboarding guide |
| Security and compliance checks arrive late in delivery. | Guardrails shift policy feedback into pull requests without blocking developer flow unnecessarily. | OPA/Conftest rules, Checkov and Trivy workflows, CDK security aspects |
| Platform, application, and environment responsibilities are unclear. | Operating model clarifies ownership, release cadence, intake, and measurable adoption. | Platform product operating model, environment config, platform/application folder split |
| Reliability and cost issues are detected after customer impact. | Default telemetry and FinOps controls make operational health visible from the first service. | CloudWatch dashboards, alarms, structured logs, X-Ray tracing, AWS Budgets, Cost Explorer |
| Leadership needs a roadmap, not only implementation detail. | Current-state assessment, target-state architecture, maturity scorecard, and phased engagement plan. | Case study, scorecard, progress tracker, architecture diagrams |
Engagement offer: assess the current platform, define the target operating model, implement practical CDK/Terraform/GitOps foundations, and leave the client with scorecards and adoption metrics that connect engineering work to business outcomes.
| Skill Area | What's Implemented |
|---|---|
| AWS CDK (TypeScript) | Complex infrastructure as code with KMS, VPC, Lambda, API Gateway, DynamoDB, CloudWatch, SNS, SQS, WAF, Budgets & Cost Explorer |
| Platform Engineering | Clear separation of platform vs. application layers, Backstage scaffolder templates, product-oriented operating model |
| GitOps & CD | Argo CD-ready manifests, env overlays (dev/stage/prod), kubeconform validation in CI |
| Policy-as-Code | OPA/Conftest rules enforcing runAsNonRoot, no-privilege-escalation, resource limits, immutable image tags |
| CI/CD Security | Dual GitHub Actions pipelines with Checkov (CloudFormation/Terraform/GHA) and Trivy (IaC misconfig) scanning |
| Observability | CloudWatch dashboard (golden signals), structured JSON logging with correlation IDs, X-Ray tracing, SNS alarm fan-out (Lambda errors, p95 latency, API 5XX) |
| FinOps | AWS Budgets (configurable monthly), Cost Explorer anomaly detection with daily email subscriptions, finops-managed resource tagging |
| Secure-by-Default | CMK encryption on all data services, VPC-isolated Lambda, IAM auth on API Gateway, encrypted log groups (2yr retention), ALB-WAF enforcement guardrail (CDK Aspect validation) |
| Developer Experience | Makefile DX targets, Backstage self-service templates, typed environment config with fail-fast validation |
- A target platform architecture with:
- Amazon EKS for workload runtime
- GitOps with Argo CD
- Backstage as the developer portal
- Secure-by-default guardrails and policy checks
- Repository structure for multi-team and multi-environment operation
- Backstage software template example for self-service service creation
- CI pipeline for platform IaC quality gates (build/test/synth + Checkov + Trivy security scans)
- GitOps-oriented app delivery guardrails
- OPA/Conftest policy bundle for Kubernetes deployment security checks
- Day-2 DX helpers via
Makefile
| Technical Feature | Practical Implementation | Consulting Outcome |
|---|---|---|
| AWS CDK constructs | ApiLambdaDynamoService and typed environment config |
Repeatable infrastructure patterns reduce bespoke project delivery |
| Terraform Vault baseline | Minimal Vault policy and secret provisioning example | Shows how secrets ownership can be standardized without overbuilding a full secrets platform |
| GitOps manifests | Argo CD-ready sample application and Kustomize structure | Creates an auditable deployment model with clear promotion boundaries |
| OPA/Conftest policies | Kubernetes security rules checked in CI | Converts compliance expectations into fast developer feedback |
| Backstage scaffolder templates | Recommended-path service template with catalog metadata | Enables self-service onboarding and platform adoption tracking |
| Observability defaults | CloudWatch dashboard, alarms, structured logs, X-Ray | Reduces mean time to detect and gives teams a first operational baseline |
| FinOps controls | Budgets, anomaly detection, governance tags | Makes cost accountability part of the platform contract |
flowchart LR
subgraph Current["Current state: project-led delivery"]
A1["Application teams"]
A2["Manual repo setup"]
A3["Single-stack IaC patterns"]
A4["Late security review"]
A5["Limited shared telemetry"]
A1 --> A2 --> A3 --> A4 --> A5
end
subgraph Target["Target state: platform-led delivery"]
B1["Backstage self-service"]
B2["Golden-path templates"]
B3["CDK and Terraform modules"]
B4["GitOps promotion"]
B5["Policy, observability, FinOps by default"]
B1 --> B2 --> B3 --> B4 --> B5
end
Current -->|"consulting engagement: assess, design, implement, enable"| Target
flowchart TB
subgraph ClientOutcomes["Consulting outcomes"]
O1["Faster onboarding"]
O2["Lower delivery risk"]
O3["Clearer ownership"]
O4["Operational visibility"]
O5["Measurable maturity"]
end
subgraph PlatformCapabilities["Technical capabilities"]
C1["Backstage templates"]
C2["CDK constructs"]
C3["Terraform Vault baseline"]
C4["GitOps and policy checks"]
C5["Dashboards, alarms, cost controls"]
end
C1 --> O1
C2 --> O2
C3 --> O2
C4 --> O3
C4 --> O2
C5 --> O4
C1 --> O5
C4 --> O5
%%{init: {"themeVariables": {"fontFamily": "monospace"}}}%%
graph TB
subgraph Platform["Platform Layer (CDK Stack)"]
KMS[("KMS CMK<br/>Platform-DataKey")]
VPC[("VPC<br/>2 AZs · Public + Private")]
SQS[("SQS<br/>KMS-encrypted")]
subgraph Compute["Serverless Compute"]
Lambda["Lambda (Node.js 18)<br/>VPC · SQS · X-Ray<br/>Reserved Concurrency: 10<br/>Env vars KMS-encrypted"]
end
subgraph API["API Gateway (REST)"]
Routes["Routes:<br/>GET / · GET /health<br/>GET/POST /items<br/>GET /platform<br/>GET /platform/recommended-path"]
APIConfig["IAM Auth · CORS<br/>0.5GB Cache · Access Logs<br/>Data Trace · X-Ray"]
end
subgraph Storage["Storage"]
DDB[("DynamoDB<br/>CMK encrypted · PITR<br/>PAY_PER_REQUEST · GSI")]
end
subgraph Observability["Observability & FinOps"]
CW_DB["CloudWatch Dashboard<br/>(4 widgets: Lambda errors,<br/>invocations, duration, API 5xx)"]
CW_AL["Alarms → SNS Topic<br/>1. Lambda Errors<br/>2. Lambda Duration p95<br/>3. API 5XX Rate"]
BUDGET["AWS Budgets<br/>(configurable monthly amount)"]
CE["Cost Explorer<br/>Anomaly Monitor + Subscription"]
end
KMS --- VPC
VPC --- Lambda
Lambda --> DDB
Lambda --> SQS
API --> Lambda
Lambda --> CW_DB
Lambda --> CW_AL
end
subgraph AppLayer["Application Layer"]
GITOPS["GitOps Manifests<br/>base/ + overlays/ (dev/stage/prod)"]
POLICY["OPA/Conftest Policies<br/>· runAsNonRoot<br/>· no privilege escalation<br/>· resource limits<br/>· no :latest tags"]
end
subgraph Backstage["Developer Portal"]
TEMPLATE["Backstage Template<br/>(recommended-path-k8s-service)"]
CATALOG["Catalog Registration<br/>(catalog-info.yaml)"]
end
subgraph CICD["CI/CD (GitHub Actions)"]
IAACI["platform-iac-ci.yml<br/>build → test → synth<br/>→ Checkov → Trivy"]
GITOPS_CI["app-gitops-guardrails.yml<br/>kubeconform → Conftest"]
end
subgraph Terraform["Terraform (HashiCorp Vault)"]
VAULT["Vault Policy + Secrets<br/>(jenkins-read policy)"]
end
Developer --> Backstage
Backstage --> TEMPLATE
TEMPLATE --> |scaffolds| AppLayer
AppLayer --> CICD
Platform --> CICD
CICD --> IAACI
CICD --> GITOPS_CI
Terraform --> VAULT
classDef aws fill:#FF9900,color:#232F3E,font-weight:bold
classDef platform fill:#1B3A5C,color:#fff
classDef app fill:#2D5A27,color:#fff
classDef cicd fill:#6B3FA0,color:#fff
classDef backstage fill:#1E1E1E,color:#9bf,stroke:#9bf
class KMS,VPC,SQS,Compute,API,Storage,Observability aws
class Platform,GITOPS,POLICY platform
class AppLayer app
class CICD,IAACI,GITOPS_CI cicd
class Backstage,TEMPLATE,CATALOG backstage
.
├── platform/ # Platform team-owned infrastructure
│ ├── modules/ # Reusable building blocks (network, EKS, observability)
│ ├── services/ # Platform services (Argo CD, Backstage, monitoring)
│ └── environments/ # Per-environment composition (dev/stage/prod)
├── applications/ # Developer/App team owned
│ ├── examples/orders-service/ # Canonical CDK consumer of platform constructs
│ ├── gitops/ # Kubernetes manifests + Kustomize overlays
│ │ ├── base/ # Reference: Namespace, Deployment, Service
│ │ └── overlays/ (dev/stage/prod)
│ ├── policy/ # OPA/Conftest policy bundle
│ │ └── deployment-security.rego # Enforces security context, resource limits
│ └── templates/ # Golden-path app templates
├── backstage/ # Developer portal integration
│ └── templates/recommended-path-service/
│ ├── template.yaml # Backstage scaffolder v1beta3
│ └── scaffold/ # Scaffold files (CI, observability, policy)
├── templates/service-catalog/ # Additional Backstage template (multi-language)
├── packages/platform-constructs/ # Reusable golden-path CDK constructs
│ └── src/api-lambda-dynamo-service/ # API Gateway + Lambda + DynamoDB construct
├── lib/ # CDK application source
│ ├── cdk-app-stack.ts # Main stack composing platform constructs
│ ├── function.ts # Lambda handler (Node.js 18)
│ ├── platform-config.ts # Typed env config with validation
│ └── security-guardrails.ts # ALB-WAF CDK Aspect validation
├── bin/app.ts # CDK app entry point
├── terraform/ # HashiCorp Vault provisioning
│ ├── main.tf / providers.tf / variables.tf
│ └── versions.tf # Terraform >= 1.6, Vault provider ~> 4.0
├── test/ # Jest test suite
│ ├── cdk-app-stack.test.ts # Resource count + governance tag tests
│ ├── stack.test.ts # FinOps + security guardrail tests
│ └── function.test.ts # Lambda handler unit tests
├── .github/workflows/
│ ├── platform-iac-ci.yml # Build → Test → Synth → Checkov → Trivy
│ └── app-gitops-guardrails.yml # kubeconform + Conftest on PRs
├── docs/ # Comprehensive documentation
│ ├── platform-product-architecture.md
│ ├── platform-product-operating-model.md
│ ├── platform-engineering-consulting-profile.md
│ ├── observability-as-a-service.md
│ ├── onboarding/first-service.md
│ └── oaas-implementation-flow.md
├── catalog-info.yaml # Backstage entity registration
├── Makefile # DX: platform-check, app-deploy, policy-test, etc.
├── cdk.json / jest.config.js / tsconfig.json
└── package.json # CDK 2.99.1, TypeScript, esbuild, ts-jest
The deployed API exposes the platform's value proposition directly:
| Endpoint | Purpose |
|---|---|
GET / |
Platform metadata + available routes |
GET /health |
Liveness check |
GET /platform |
Platform product contract — lists capabilities, golden paths, and SLIs |
GET /platform/recommended-path |
Recommended service delivery stages + template metadata |
GET /items |
Paginated DynamoDB query (cursor-based, ordered by createdAt) |
POST /items |
Create item |
| Control | Implementation |
|---|---|
| Data at rest | Customer-managed KMS key encrypts DynamoDB, Lambda env vars, SQS, CloudWatch log groups |
| Network isolation | Lambda deployed in VPC private subnets across 2 AZs |
| API auth | IAM authorization on all endpoints (default), CORS configured |
| Policy guardrails | CDK Aspect fails synth if any ALB lacks a WAFv2 association |
| Logging | API access logs (2yr retention), Lambda app logs (1mo retention), both KMS-encrypted |
- CloudWatch Dashboard: 4 widgets tracking Lambda invocations, errors, duration, API 5XX rate, and latency
- 3 Operational Alarms: Lambda errors → SNS, Lambda p95 duration → SNS, API 5XX rate → SNS
- Structured JSON logging: Correlation IDs propagated through API Gateway → Lambda → DynamoDB
- AWS X-Ray: Active tracing on Lambda and API Gateway
- SNS Alarm Topic: KMS-encrypted, ready for integration with PagerDuty, Slack, email
- AWS Budgets: Configurable monthly budget (default $50, set via
--context monthlyBudgetAmount) - Cost Explorer: Service-level anomaly monitor + daily email anomaly subscription
- Resource tagging:
finops-managed,cost-center,environment,project,owner,data-classificationtags applied at stack level
Two Backstage scaffolder templates are provided:
-
recommended-path-k8s-service(primary): Scaffolds a complete Kubernetes service repo with:- CI pipeline + container image delivery
- Argo CD app definition + Kustomize overlays (dev/stage/prod)
- Prometheus rules + Grafana dashboard
- Conftest policy checks baked in
- Runtime selection (Node.js, Python, Go), criticality tier, environment selection
-
recommended-path-service: Lighter-weight template for service scaffolding with Backstage.
PR (app changes) → kubeconform validation → Conftest policy check → Merge to main
↓
Argo CD reconciles
↓
Deployed to EKS cluster
Rules enforced in CI on every PR touching applications/:
# deployment-security.rego
deny[msg] { not input.spec.template.spec.securityContext.runAsNonRoot }
deny[msg] { input.spec.template.spec.containers[_].securityContext.allowPrivilegeEscalation }
deny[msg] { not input.spec.template.spec.containers[_].resources.requests.cpu }
deny[msg] { not input.spec.template.spec.containers[_].resources.limits.memory }
deny[msg] { contains(image, ":latest") }| Resource | Configuration |
|---|---|
| KMS Key | Symmetric CMK, key rotation enabled |
| VPC | 2 AZs, 1 public + 1 private subnet per AZ, NAT Gateway, DNS support |
| DynamoDB | PAY_PER_REQUEST, PITR enabled, KMS CMK, GSI for createdAt pagination |
| Lambda | Node.js 18, esbuild bundling, VPC placement, reserved concurrency: 10, memory: 1024 MB, timeout: 30s, X-Ray active |
| API Gateway | REST API, IAM auth, CORS, 0.5GB cache, access logging, data trace, X-Ray |
| SQS | KMS-encrypted |
| CloudWatch | Dashboard (4 widgets), 3 alarms → SNS topic, log groups with KMS encryption |
| AWS Budgets | Monthly cost budget (configurable), email alert threshold |
| Cost Explorer | DIMENSIONAL/SERVICE anomaly monitor, DAILY anomaly subscription |
# Prerequisites
node >= 18
npm >= 9
aws-cdk >= 2.99.1
AWS CLI configured with appropriate credentials
# Install & build
npm ci
npm run build
# Test
npm test # Jest: resource count, governance tags, guardrails, handler logic
# Synthesize (dry-run)
npm run synth # defaults to env=dev
PLATFORM_ENV=stage npm run synth
# Deploy
npm run cdk -- deploy --context platformEnv=dev \
--context finOpsAlertEmail=finops@example.com \
--context monthlyBudgetAmount=250
# Developer experience
make platform-check # Validate platform config
make platform-plan ENV=dev # CDK diff
make platform-apply ENV=dev # CDK deploy
make app-policy-test # Run Conftest against sample manifests
make app-deploy ENV=dev SERVICE=my-api TAG=v1.2.3 # Full deploy pipelineTriggers on PRs to main modifying platform/, lib/, bin/, or test/:
npm ci → TypeScript build → Jest tests → CDK synth → Checkov scan → Trivy IaC scan
Triggers on PRs to main modifying applications/:
kubeconform validation → Conftest OPA policy checks
| Document | What It Covers |
|---|---|
docs/platform-product-architecture.md |
Target IDP architecture (5 planes: control, runtime, delivery, governance, observability) |
docs/platform-product-operating-model.md |
Product mission, ownership matrix, capabilities, intake/prioritization, KPIs, rituals |
docs/platform-product-progress.md |
Client engagement plan with phases, workstreams, KPIs, and next milestones |
docs/platform-consulting-case-study.md |
Case study narrative for a platform engineering transformation engagement |
docs/platform-maturity-scorecard.md |
Scorecard for assessing platform product maturity and prioritizing improvement work |
docs/platform-product-repository-review-2026-04-08.md |
Comprehensive audit with risks, gaps, and prioritized 8-item improvement backlog |
docs/platform-engineering-consulting-profile.md |
Portfolio framing: strategy → architecture → implementation → adoption |
docs/observability-as-a-service.md |
OaaS maturity assessment + baseline implementation |
docs/oaas-implementation-flow.md |
End-to-end OaaS flow with ownership model and definition of done |
docs/onboarding/first-service.md |
30-minute first-service onboarding path using the golden-path construct |
docs/code-review-resolution.md |
Audit trail of how review feedback was addressed |
packages/platform-constructs/README.md |
Reusable CDK construct contract and consumer example |
CONTRIBUTING.md |
Compatibility, deprecation, ownership, and PR expectations |
PLATFORM_PRODUCT_SETUP.md |
Full platform transformation guide (905 lines) |
applications/policy/README.md |
OPA policy bundle documentation |
terraform/README.md |
HashiCorp Vault setup guide |
- Infrastructure-as-Code: Full AWS CDK (TypeScript) stack — 15+ AWS resources across 6 service categories, all defined programmatically with strong typing
- Security Posture: 100% KMS encryption coverage on data services, VPC-isolated compute, IAM-auth-only API, CI-enforced security scanning (Checkov + Trivy)
- Observability: 4 golden-signal dashboard widgets, 3 operational alarms, X-Ray tracing, structured logging with correlation IDs
- FinOps Visibility: Budget alerts + anomaly detection at the service level, governance-tagged resources for cost allocation
- Developer Velocity: Self-service Backstage templates scaffold production-ready services with CI/CD, monitoring, and policy baked in
- Policy Enforcement: 5 OPA rules enforce Kubernetes security best practices at CI time — no insecure deployments reach the cluster
- Platform Maturity: Clear separation of concerns (platform vs. application), environment isolation (dev/stage/prod), documented operating model with KPIs and adoption metrics
- AWS CDK 2.99.1 (TypeScript) — Cloud Development Kit
- AWS Lambda (Node.js 18) — Serverless compute
- Amazon API Gateway — REST API management
- Amazon DynamoDB — NoSQL database
- AWS KMS — Encryption key management
- Amazon VPC — Network isolation
- Amazon SQS — Queue service
- Amazon CloudWatch — Monitoring, logging, dashboards, alarms
- Amazon SNS — Alert notifications
- AWS Budgets & Cost Explorer — Cost management
- AWS WAFv2 — Web application firewall (guardrail)
- Backstage — Developer portal (scaffolder templates + catalog)
- Argo CD — GitOps deployment
- OPA/Conftest — Policy-as-code
- GitHub Actions — CI/CD pipelines
- HashiCorp Vault + Terraform — Secrets management
- esbuild — Lambda bundling
- Jest + ts-jest — Testing framework