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

<!-- _class: title -->
<!-- _paginate: false -->

# 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>

---

# Four frictions slow every team

![w:1100](assets/png/platform-works-02-frictions.png)

- **Cognitive load** — services inconsistent in security and observability
- **Operational work** — manual promotion scaling with the system
- **Red tape** — tickets and handoffs scaling with the organization
- **Scalability** — throughput without scaling platform engineers

---

# The platform at a glance

![w:1100](assets/png/platform-architecture.png)

- **Consumer surfaces** — technical dev or citizen dev; both produce a contract
- **Central pipeline** — fixed stages, identical for every deployment: validate → resolve → security → plan → policy → confidence → evidence → apply
- **Module catalog + engine adapter** — security-reviewed blocks; the adapter is the only engine-specific code (Terraform today)
- **HITL gates + evidence stream** — human attestation for qa/prod/dr; every deployment writes a hash-chained event (RPO = 0)

---

# Declare intent; the platform delivers safe production

![w:1100](assets/png/platform-works-03-north-star.png)

- A merged change progresses **without a ticket or thread**
- A **non-technical consumer** ships by declaring intent
- Every production change is **traceable to a human attestation**

---

# ACDL owns infrastructure, not your app

![w:1100](assets/png/platform-works-03-scope-boundary.png)

- **Upstream is anything** — IDE, agentic SDLC, or vibe coding
- **ACDL is infrastructure only** — provisions and governs AWS resources
- **Not a general-purpose AI** — autonomy is narrow, policy-bounded
- **Not a permissive highway** — no escape hatches

---

# One YAML file. The platform owns everything else.

![w:850](assets/png/platform-works-01-contract-driven.png)

- **Module** — pre-built, security-reviewed building blocks
- **Environment** — `dev`, `qa`, `prod`, `dr`; bar rises with sensitivity
- **Inputs** — cpu, memory, port, desired_count
- Consumer provides **no AWS account, no VPC, no state backend**

---

# Same stages, same checks, every deployment

![w:1100](assets/png/platform-works-02-end-to-end-flow.png)

- **Security and policy checks run *before* any infra is created**
- **Every stage produces a record** — no "unchecked" path

---

# No long-lived credentials. Blast radius contained.

![w:1100](assets/png/platform-works-07-zero-trust.png)

- **OIDC federation** — short-lived token per job, no stored credential <span class="badge planned">Planned: all runners</span>
- **ABAC, not role-based** — repo identity + resource tags scope every action
- **A consumer can only touch its own tagged resources.** One consumer can never affect another.

---

# Safety is a measurable signal, not a black box

![w:900](assets/png/platform-works-04-confidence-signal.png)

- **Six weighted inputs** — manually tuned, auditable per-input breakdown

| Environment | Threshold | Attester |
|---|---|---|
| dev | ≥ 0.50 | No one — autonomous |
| qa | ≥ 0.75 | QA <span class="badge planned">Planned</span> |
| prod | ≥ 0.90 | SRE <span class="badge planned">Planned</span> |

- **A single critical finding hard-blocks** — not averaged away

---

# Every change traceable to a human attestation

![w:1100](assets/png/platform-works-05-attestation-flow.png)

- **Dev is fully autonomous** — confidence signal is the only gate
- **qa, prod, dr require human attestation** — contract + plan + evidence <span class="badge planned">Planned</span>
- **Separation of duties** — QA approver ≠ prod approver; platform **blocks on a match** <span class="badge planned">Planned</span>
- **Hash-chained evidence event** — tampering breaks the chain. **RPO = 0**

---

<!-- _class: title -->
<!-- _paginate: false -->

# The vision realized

- **Velocity without sacrificing safety** — speed in ergonomics, safety in unbypassable gates
- **Security, observability, compliance as platform defaults** — not per-team effort
- **Auditability as a byproduct, not a project** — every change traceable to a human attestation
- **Blast radius contained by design** — OIDC + ABAC, only your own tagged resources
- **Infrastructure as a utility, not a craft** — consume, don't maintain
- **A path to the citizen developer** — same envelope, senior engineer or non-technical

---

<!-- _class: title -->
<!-- _paginate: false -->

# Appendix

**Contents:**

1. Platform-Managed Environments (detail)
2. Observability Built In (detail)
3. Security by Construction (the full defaults inventory)
4. The Road to the North Star (phased roadmap)
5. Testing vs. Planned (full inventory)
6. Glossary
7. Operating Model & Cost (real AWS spend + pre-mortem)
8. Verified by Construction (the v1.11 architecture)

---

# 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 it 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). <span class="badge planned">Self-service: planned</span>

---

# A2 — Observability Built In

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

- **Uptime monitoring deployed automatically with every stack** — separate state, 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
- **Roadmap:** deeper observability bootstrap (dashboards, runbooks, on-call bindings) <span class="badge planned">Planned</span>

---

# A3 — Security by Construction

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

- **Policy checks** (Checkov, Wiz, Kyverno) — secrets, public ingress, IAM wildcards, **required tagging** — all run *before* infra is created
- **Encryption on every resource** — at-rest on by default; per-stack CMKs 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**

---

<!-- _class: title -->
<!-- _paginate: false -->

# A4 — The Road to the North Star

*Proposed phasing — not formally planned.*

![w:1100](assets/png/road-to-north-star.png)

---

<!-- _class: title -->
<!-- _paginate: false -->

# A5 — Testing vs. Planned (Full Inventory)

<style>
section { font-size: 18px; }
td { font-size: 16px; 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).

<table style="width: 100%; border: none;">
<tr>
<td style="width: 52%; border: none; padding-right: 12px;">

**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
- 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

</td>
<td style="width: 48%; border: none; padding-left: 12px;">

**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)
- Pattern recognition compounds value over time
- Additional engine adapters (OpenTofu, Pulumi, Kubernetes CRDs)
- Deeper observability bootstrap (dashboards, runbooks, on-call)

</td>
</tr>
</table>

---

# A6 — 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 |

---

# A7 — Operating Model & Cost

<style>
section { font-size: 20px; }
table { font-size: 18px; }
</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 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
- **Live-AWS verification is milestone-scoped, then torn down.** 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`):** 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).

---

<!-- _class: title -->
<!-- _paginate: false -->

# A8 — Verified by Construction

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

Two architectural pillars make "Verified" a structural property, not a claim:

- **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.