acdl/docs/presentations/how-the-platform-works-marp.md

marp, theme, paginate, size, header, footer, style

marp	theme	paginate	size	header	footer	style
true	default	true	16x9	How The Platform Works	Internal	section { font-family: "Akkurat Pro", "Helvetica Neue", "Arial", sans-serif; font-size: 22px; color: #1B1B1B; } h1 { color: #D6002A; font-size: 34px; margin-bottom: 0.3em; } h2 { color: #D6002A; font-size: 26px; margin-bottom: 0.2em; } section.title { background: #1B1B1B; color: #fff; border-top: 8px solid #D6002A; } section.title h1 { color: #fff; } table { font-size: 18px; width: 100%; } th { background: #F0F0F0; } blockquote { border-left: 4px solid #D6002A; color: #2E2E2E; font-size: 20px; } img { display: block; margin: 0 auto; max-height: 300px; } em.story { color: #6B7280; font-size: 16px; font-style: italic; } .badge { display: inline-block; padding: 2px 8px; border-radius: 4px; font-size: 14px; font-weight: 600; } .testing { background: #DBEAFE; color: #1E3A5F; } .planned { background: #fef3c7; color: #78350f; } .agentic { background: #EDE9FE; color: #4C1D95; }

How The Platform Works

Agentic Cloud Delivery Platform

<style> section.title h1 { font-size: 44px; margin-bottom: 0.1em; } section.title h3 { color: #F0F0F0; font-weight: 400; font-size: 22px; margin-top: 0; } </style>

---

The Problem & The North Star

Here's the problem we're solving and where we're going.

Four frictions slow every team:

• Cognitive load — authoring infrastructure correctly; the long tail of services inconsistent in security and observability
• Operational work — promoting a change from "merged" to "running in production." Manual work that scales with the system, not the change
• Red tape — tickets, approvals, and handoffs that scale with the organization. A merged change waits in a queue
• Scalability without increasing headcount — throughput scales without linearly scaling platform engineers

Consumers declare intent; the platform delivers safe production deployment — automatically, safely, with a complete audit trail.

• A merged change progresses without a platform engineer joining a thread or approving a ticket
• A non-technical consumer ships by declaring intent — no workflow, no config file, no infrastructure module
• Every production change is traceable to a human attestation and an immutable evidence stream

---

Where ACDL Sits in Your World

Now that we know the problem, here's where ACDL fits — and where it doesn't.

• Upstream is anything — your IDE, an agentic SDLC, or a citizen developer vibe coding on a laptop. ACDL doesn't care how the contract was produced.
• ACDL is infrastructure only — it provisions and governs AWS resources. It does not build, test, or deploy your application code. That's upstream.
• Not a general-purpose AI — autonomy is narrow, scoped to delivery, bounded by strict policy
• Not a permissive delivery highway — no escape hatches to bypass the confidence framework

---

The Contract-Driven Model

The contract is the boundary between upstream and ACDL. It's all a consumer writes.

A single YAML contract — module, environment, inputs. The platform owns everything else.

• Which module — a catalog of pre-built, security-reviewed building blocks
• Which environment — the platform raises the safety bar automatically as sensitivity rises
• Which inputs — infrastructure values that vary per deployment (cpu, memory, port, desired_count)
• The consumer provides no AWS account, no VPC, no state backend — the platform owns the blast radius

---

The End-to-End Flow

Once the contract is written, here's what the platform does with it — every time.

Every deployment runs the same stages, in the same order, with the same checks — no team-specific pipelines, no tribal runbooks.

• Security and policy checks run before any infrastructure is created
• Every stage produces a record that feeds the confidence signal and the evidence stream — there is no "unchecked" path

---

Zero-Trust by Default

Before any infrastructure is created, here's how access is scoped.

Consumer repositories hold no long-lived cloud credentials. Ever.

• Authentication — OIDC federation. Each job mints a short-lived token; no credential is stored in the consumer repo or in a runner secret. Testing (GitHub Actions) Planned: all runners
• Authorization — attribute-based (ABAC), not role-based. Two attribute classes scope every action:
  • Repository identity — the role's trust policy binds to the exact consumer repo + branch
  • Resource tags — every resource is tagged acdl:owner + acdl:contract; the session policy grants access only to matching tags

The effect: a consumer can only touch the resources it created. Blast radius is contained. One consumer can never affect another.

---

Safety is Computed, Not Assumed

Now let's look at how the platform decides whether a deployment is safe.

Every delivery action produces a measurable, explainable confidence signal — a weighted sum of observable facts, not a black box. Agentic

• Six weighted inputs — manually tuned, auditable. If a consumer asks "why 0.62?", the platform answers with a per-input breakdown
• Per-environment thresholds that rise with sensitivity:

Environment	Threshold	Attester
dev	≥ 0.50	No one — autonomous Testing
qa	≥ 0.75	QA Planned
prod	≥ 0.90	SRE Planned

• A single critical finding hard-blocks — critical findings are not averaged away

---

Security by Construction

Beyond the confidence signal, security defaults are on by construction — not by opt-in.

Security defaults that do not require a team to opt in. Checks run on every deployment, normalized to a single schema. Testing

• Policy checks (Checkov, Wiz, Kyverno) — secrets in plaintext, public ingress, IAM wildcards, required tagging standards — all run before infra is created
• Encryption on every resource — at-rest encryption on by default; per-stack customer-managed keys with 90-day rotation, no shared keys across stacks
• Deletion protection on by default — prevent_destroy on unless explicitly disabled via a documented flag
• Safe decommission — a 2-step pipeline with two SRE attestation gates and a change-request validated against the CMDB

---

Accountability & Audit

Computed safety handles the gate. But humans still matter — here's how accountability works.

• Dev is fully autonomous. The confidence signal (≥ 0.50) is the only gate. Testing Agentic
• qa, prod, dr require human attestation — the approver reviews the contract, the planned Terraform changes, and the accumulated evidence Planned
• QA attests to infrastructure readiness, not application code — the contract, the plan, and the evidence. Application code review is upstream
• Separation of duties — the QA approver cannot be the prod approver. The platform blocks on a match. Planned
• Every deployment writes a hash-chained evidence event — tampering breaks the chain. RPO = 0 Testing

---

Testing vs. Planned

Let's be honest about what works today and what's on the roadmap.

<style> section { font-size: 20px; } </style>

22/22 Verified via lifecycle pipeline + regression gate:

• Contract-driven deploys · Module catalog · Zero-trust OIDC + ABAC
• Security + policy checks before infra creation · Confidence signal gating
• Hash-chained evidence outbox (RPO = 0) · Encryption by default + per-stack CMKs
• Deletion protection + safe decommission · Uptime monitoring
• Platform-managed environments · Engine-agnostic core + VCS-agnostic ingestion

9 planned (production path):

• HITL wiring for qa/prod/dr · All-runner OIDC · Full regulatory ledger
• Compliance milestone (GDPR, SOX, SOC2, DORA) · Environment self-service
• Dynamic module creation Agentic · Pattern recognition Agentic
• Additional engine adapters · Deeper observability bootstrap

22/22 Verified — the v1.11 lifecycle pipeline ran apply→modify→destroy against live AWS, then tore down to zero-cost (D-096). The v1.10 "6 deploy-unverified (IAM drift)" status is closed.

Full inventory + phased roadmap in the appendix.

---

The Vision Realized

Here's what success looks like when the North Star is reached.

• Velocity without sacrificing safety. Speed is in the ergonomics (a simple contract, a one-line uses:); safety is in the gates the consumer cannot bypass.
• Security, observability, and compliance as platform defaults — not per-team effort, not post-hoc remediation.
• Auditability as a byproduct, not a project. Every production change is traceable to a human attestation and a tamper-evident evidence event.
• Blast radius contained by design. Zero-trust OIDC + ABAC means a consumer can only touch its own tagged resources.
• Infrastructure as a utility, not a craft. Teams consume infrastructure, they don't maintain it.
• A path to the citizen developer. The same safety envelope that serves a senior engineer will serve a non-technical consumer. Agentic

---

Appendix

For deep dives — these slides cover details omitted from the main 10.

Contents:

1. Platform-Managed Environments (detail)
2. Observability Built In (detail)
3. The Road to the North Star (phased roadmap)
4. Testing vs. Planned (full inventory)
5. Glossary
6. Operating Model & Cost
7. Verified by Construction

---

A1 — Platform-Managed Environments

A consumer provides no AWS account, no VPC, no subnet, no state backend, no runner key. The platform owns the blast radius.

A named environment is a platform-owned bundle of:

• An AWS account (or a scoped partition of one)
• A network (VPC + subnets)
• A state backend (S3 + DynamoDB for state + locking)
• An IAM role surfaced via ABAC, scoped to the consumer's identity and resource tags

The consumer selects an environment by name in their contract. The platform resolves the name to the underlying resources at run time. The consumer never sees raw credentials.

Friendly onboarding: the first run detects no environment and emits a guided prompt (not an opaque failure). Testing Self-service: planned

---

A2 — Observability Built In

Monitoring is a platform default, not a per-team project. Testing

• Uptime monitoring deployed automatically with every stack — a dedicated monitoring instance is provisioned after any module deploy, in a separate state, with a feature flag to disable
• Monitored endpoints passed from the deployment's own outputs — no manual endpoint registration
• Alert channels: Microsoft Teams webhook, email, SMS, and GitHub issues
• The uptime URL is published to the developer via a PR comment — they don't hunt for it
• Roadmap: deeper observability bootstrap (dashboards, runbooks, on-call bindings) as first-class contract fields Planned

---

A3 — The Road to the North Star

Proposed phasing — not formally planned.

---

A4 — Testing vs. Planned (Full Inventory)

<style> section { font-size: 15px; } td { font-size: 14px; vertical-align: top; } ul { margin: 0; padding-left: 1.2em; } li { margin-bottom: 2px; } </style>

22/22 Verified — the v1.11 lifecycle pipeline ran apply→modify→destroy against live AWS for every L1 + L2 module, then tore down to zero-cost (D-096). The v1.10 "6 deploy-unverified (IAM drift)" status is closed (CAP-013 fixed in P67).

Testing (22/22 Verified — works internally, dev pilot-ready) Contract-driven deploys with a versioned reusable workflow Module catalog (primitives + modules) with validated examples Zero-trust OIDC + ABAC on GitHub Actions runners Security + policy checks before infra creation (Checkov; Wiz + Kyverno ready) Confidence signal (6 inputs, per-env thresholds) gating promotion Agentic Hash-chained, tamper-evident evidence outbox (RPO = 0) Encryption by default + per-stack customer-managed keys Deletion protection by default + safe decommission with SRE gates Uptime monitoring deployed automatically with every stack Platform-managed environments + friendly onboarding Engine-agnostic core (1 adapter: Terraform) + VCS-agnostic ingestion

Planned (on the roadmap) Real OIDC federation on all platform runners HITL wiring for qa / prod / dr environments Full regulatory ledger: S3 Object Lock + JWS signatures + daily checkpoints Compliance milestone: GDPR, SOX, SOC2, DORA extension points Environment self-service provisioning Dynamic module creation from a contract (agentic citizen-developer flow) Agentic Pattern recognition compounds value over time Agentic Additional engine adapters (OpenTofu, Pulumi, Kubernetes CRDs) Deeper observability bootstrap (dashboards, runbooks, on-call)

---

A5 — Glossary

Term	Meaning
OIDC	OpenID Connect — federation protocol for short-lived tokens, no long-lived credentials
ABAC	Attribute-Based Access Control — access scoped by resource tags + repo identity, not roles
CMK	Customer-Managed Key — per-stack encryption key, 90-day rotation, no shared keys
CMDB	Configuration Management Database — validates change requests for decommission
RPO	Recovery Point Objective — RPO = 0 means evidence is written synchronously, no data loss
HITL	Human-in-the-Loop — deliberate human attestation required for qa/prod/dr environments
VCS	Version Control System — the git hosting platform (GitHub, Gitea, GitLab)
NFR	Non-Functional Requirement — encryption, tagging, observability standards
IR	Intermediate Representation — the engine-agnostic stack definition between contract and Terraform

---

A6 — Operating Model & Cost

<style> section { font-size: 18px; } table { font-size: 16px; } </style>

ACDL runs at zero cloud cost for day-to-day development. AWS spend was measured via Cost Explorer (COST.md, 2026-07-28):

Metric	Value
Total spend (8 days)	$0.001883
Daily average	$0.000235
Projected monthly	~$0.007
Peak day	2026-07-27 ($0.000867)

• S3 dominates (98.8%, terraform state bucket) — no compute (ECS/Lambda) ran because v1.0→v1.10 was plan-only for IAM-gated capabilities
• Local emulators are the primary tier — the full pipeline runs in-process, no AWS credentials, no Checkov, no DynamoDB. Testing
• Live-AWS verification is milestone-scoped, then torn down. The v1.11 lifecycle pipeline ran apply→modify→destroy for every module, then tore down to zero-cost (D-096). The pipeline now defaults to plan-only on every PR; ACDL_LIFECYCLE_MODE=full overrides to apply→destroy for milestone verification (REQ-134, v1.12).
• Cost drivers are spike-scoped: Terraform plan reads (free), S3 state storage (cents), DynamoDB outbox (cents). Any spike > $1/day is an anomaly.

Pre-mortem (PRE_MORTEM.md): failure modes were pre-mortemed before the leadership pitch. The v1.10 decay incident (diff-scoped VERIFY missed 7 adapter defects) is the root pattern: a claim outruns the verification that backs it. Four forward failure modes + structural mitigations (regression-tested IAM baseline, mandatory teardown, verified-only deck claims, honest scope).

---

A7 — Verified by Construction

The v1.11 architecture makes "Verified" a structural property, not a claim.

<style> section { font-size: 18px; } </style>

Two architectural pillars:

• The stateless adapter (918 → ~80 lines). The Terraform adapter was a 918-line monolith with 3 constant tables and 39 type-specific branches. It is now a ~80-line stateless assembler: it owns no module content — no resource shape, no nested HCL blocks, no defaults. Each L1 module ships a real terraform/ module dir owning its shape, nested blocks, and defaults. The adapter reads the registry and emits module "x" { source = ... } blocks. A new module is a new terraform dir, not a code change. (The v1.12 P67 fix closed a dedup defect for multi-resource L1s — ecs-service, alb; CAP-013 now Verified.)
• Pipeline-driven lifecycle testing. A modules-lifecycle pipeline matrix-runs each L1 and L2 module's examples/{simple,complex}.yml contracts through apply→modify→destroy against live AWS. The "test" = the pipeline cell going green. Defaults to plan-only on every PR (fast, no AWS mutation, no cost); ACDL_LIFECYCLE_MODE=full overrides to the real apply→destroy for milestone verification (REQ-134, v1.12). The regression gate (D-091) re-runs all 22 capabilities at milestone completion — 22/22 Verified as of v1.12.

The v1.10 lesson is the negative space: a 918-line adapter with type-specific branches decayed silently. The ~80-line stateless adapter + the milestone regression gate are the structural fix.