Implement platform product improvement backlog

.github/workflows/platform-iac-ci.yml

@@ -5,6 +5,8 @@ on:
     branches: [ main ]
     paths:
       - 'platform/**'
+      - 'packages/**'
+      - 'applications/examples/**'
       - 'lib/**'
       - 'bin/**'
       - 'test/**'
@@ -51,8 +53,19 @@ jobs:
           output_file_path: console,results.sarif
           quiet: true
 
-      - name: Upload Checkov SARIF report
+      - name: Check for Checkov SARIF report
+        id: checkov-sarif
         if: always()
+        run: |
+          if [ -f results.sarif ]; then
+            echo "exists=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "exists=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Upload Checkov SARIF report
+        if: always() && steps.checkov-sarif.outputs.exists == 'true'
+        continue-on-error: true
         uses: github/codeql-action/upload-sarif@v4
         with:
           sarif_file: results.sarif

CONTRIBUTING.md

@@ -0,0 +1,34 @@
+# Contributing
+
+## Platform API compatibility
+
+The platform construct APIs are treated as internal product contracts.
+
+- Additive optional props are minor-compatible changes.
+- Changing defaults that affect deployed infrastructure requires a migration note.
+- Removing props, changing required props, or replacing resources requires a deprecation cycle.
+
+## Deprecation policy
+
+Deprecated construct props and behavior remain available for at least one release train before removal.
+
+Every deprecation must include:
+
+- replacement guidance,
+- migration steps,
+- target removal release,
+- test coverage for both old and new behavior during the deprecation window.
+
+## Pull request expectations
+
+Platform changes must include:
+
+- `npm run build`
+- `npm test`
+- `npm run synth`
+- focused tests for new constructs, policies, or environment behavior
+- documentation updates when the consumer contract changes
+
+## Ownership
+
+The platform team owns reusable constructs, configuration contracts, policy packs, and CI gates. Application teams own service-specific code and configuration that consumes those platform APIs.

Makefile

@@ -9,7 +9,7 @@ help:
 	@echo "make build                      # Build TypeScript"
 	@echo "make test                       # Run tests"
 	@echo "make synth                      # CDK synth"
-	@echo "make platform-check             # Build + synth + lint placeholder"
+	@echo "make platform-check             # Build + test + synth"
 	@echo "make platform-plan ENV=dev      # Plan platform changes"
 	@echo "make platform-apply ENV=dev     # Apply platform changes"
 	@echo "make app-bootstrap SERVICE=name # Bootstrap app from template"
@@ -26,8 +26,8 @@ test:
 synth:
 	npx cdk synth
 
-platform-check: build synth
-	@echo "[platform-check] add checkov/tfsec/cdk-nag in CI"
+platform-check: build test synth
+	@echo "[platform-check] build, tests, and synth completed"
 
 platform-plan:
 	@echo "[platform-plan] ENV=$(ENV)"

README.md

@@ -121,6 +121,7 @@ graph TB
 │   ├── 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)
@@ -132,8 +133,10 @@ graph TB
 │       ├── 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 — all AWS resources
+│   ├── 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
@@ -153,6 +156,7 @@ graph TB
 │   ├── 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.
@@ -317,7 +321,10 @@ kubeconform validation → Conftest OPA policy checks
 | `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 |

applications/examples/orders-service/infra/orders-service-stack.ts

@@ -0,0 +1,35 @@
+import * as cdk from 'aws-cdk-lib';
+import { Construct } from 'constructs';
+import { ApiLambdaDynamoService } from '../../../../packages/platform-constructs/src';
+import { PlatformConfig } from '../../../../lib/platform-config';
+
+export interface OrdersServiceStackProps extends cdk.StackProps {
+  readonly platformConfig: PlatformConfig;
+}
+
+export class OrdersServiceStack extends cdk.Stack {
+  public readonly service: ApiLambdaDynamoService;
+
+  constructor(scope: Construct, id: string, props: OrdersServiceStackProps) {
+    super(scope, id, props);
+
+    this.service = new ApiLambdaDynamoService(this, 'OrdersApiService', {
+      serviceName: 'orders-api',
+      stageName: props.platformConfig.environment,
+      catalogEntityRef: 'component:default/orders-service',
+      recommendedPathTemplateName: 'recommended-path-service',
+      recommendedPathTemplatePath: 'backstage/templates/recommended-path-service/template.yaml',
+      handlerEntry: `${__dirname}/../../../../lib/function.ts`,
+      environment: {
+        SERVICE_NAME: 'orders-api',
+      },
+    });
+
+    cdk.Tags.of(this).add('environment', props.platformConfig.environment);
+    cdk.Tags.of(this).add('project', props.platformConfig.project);
+    cdk.Tags.of(this).add('owner', props.platformConfig.owner);
+    cdk.Tags.of(this).add('cost-center', props.platformConfig.costCenter);
+    cdk.Tags.of(this).add('data-classification', props.platformConfig.dataClassification);
+    cdk.Tags.of(this).add('finops-managed', 'true');
+  }
+}

docs/onboarding/first-service.md

@@ -0,0 +1,61 @@
+# First Service Onboarding
+
+This tutorial provisions a service through the platform golden path in less than 30 minutes.
+
+## Prerequisites
+
+- Node.js 20
+- AWS credentials for the target sandbox account
+- CDK bootstrap completed for the target account and region
+
+## 1. Start from the canonical consumer
+
+Use `applications/examples/orders-service/infra/orders-service-stack.ts` as the reference implementation. It consumes `ApiLambdaDynamoService`, which provides:
+
+- IAM-authenticated API Gateway routes
+- VPC-isolated Lambda with tracing, reserved concurrency, encrypted environment variables, and a retry queue
+- KMS-encrypted DynamoDB with point-in-time recovery and the standard pagination index
+- API and application log groups with retention defaults
+
+## 2. Configure the environment
+
+Set the platform environment explicitly:
+
+```bash
+export PLATFORM_ENV=dev
+```
+
+Allowed values are `dev`, `stage`, and `prod`.
+
+## 3. Validate locally
+
+Run the same quality gates used in CI:
+
+```bash
+npm run build
+npm test
+npm run synth
+```
+
+## 4. Register ownership
+
+Set the service catalog reference in the construct props:
+
+```ts
+catalogEntityRef: 'component:default/orders-service'
+```
+
+The value must match the Backstage entity for the service.
+
+## 5. Promote through environments
+
+Create one stack instance per environment and keep promotion artifact-based:
+
+1. Merge to `main` after build, test, synth, and policy checks pass.
+2. Deploy to `dev`.
+3. Promote the same reviewed change to `stage`.
+4. Promote to `prod` after smoke tests and approval.
+
+## Done
+
+The service is onboarded when it has a catalog entity, passes CI quality gates, emits logs and traces by default, and uses the platform construct instead of hand-rolled API/Lambda/DynamoDB resources.

docs/platform-product-progress.md

@@ -6,11 +6,11 @@ _Last updated: 2026-04-01_
 
 | Workstream | Status | Progress | Notes |
 |---|---|---:|---|
-| Repository product model (platform vs applications) | ✅ Complete | 100% | Baseline folder model and docs are in place. |
+| Repository product model (platform vs applications) | ✅ Complete | 100% | Baseline folder model, platform construct package, and canonical consumer example are in place. |
 | Golden-path scaffolding (Backstage template) | ✅ Complete | 100% | Template + runnable repo structure added and parameterized org support enabled. |
 | Platform IaC CI guardrails | ✅ Complete | 100% | Build/synth/checkov workflow configured. |
 | App GitOps guardrails | ✅ Complete | 100% | kubeconform validation enabled and fail-fast behavior enforced. |
-| Secure-by-default CDK sample hardening | ✅ Complete | 100% | KMS, VPC, Lambda retry queue, IAM auth, caching, encrypted logs implemented. |
+| Secure-by-default CDK sample hardening | ✅ Complete | 100% | KMS, VPC, Lambda retry queue, IAM auth, caching, encrypted logs implemented through the reusable API/Lambda/Dynamo construct. |
 | Environment overlays (dev/stage/prod) | 🟡 In Progress | 40% | Structure exists; env-specific manifests and policy sets pending. |
 | Policy-as-code enforcement (OPA/Kyverno) | 🟡 In Progress | 60% | Conftest policy bundle and CI enforcement added for deployment security/image/resource guardrails. |
 | Observability productization | 🟡 In Progress | 60% | CloudWatch dashboard, alerts, and structured logging baseline implemented; Prometheus/Grafana/Loki/OTel deployments pending. |
@@ -25,6 +25,7 @@ _Last updated: 2026-04-01_
 - Developer command interface established through `Makefile` targets.
 - Backstage self-service template now executable from a real scaffold repo structure.
 - Sample GitOps base manifests added for validation and onboarding reference.
+- First golden-path CDK construct added under `packages/platform-constructs` with `applications/examples/orders-service` as a canonical consumer.
 
 ## Current quarter priorities
 
@@ -41,6 +42,7 @@ _Last updated: 2026-04-01_
   - Encrypted SNS-backed alarm fan-out for Lambda and API failures/latency.
   - Structured Lambda JSON logging and correlation-ID propagation.
 - See `docs/observability-as-a-service.md` for assessment details and rollout recommendations.
+- Productized the API/Lambda/DynamoDB baseline as `ApiLambdaDynamoService`, added a first-service onboarding guide, and defined contribution/deprecation expectations in `CONTRIBUTING.md`.
 
 ## Definition of done for next milestone