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: 320px; } .badge { display: inline-block; padding: 2px 8px; border-radius: 4px; font-size: 14px; font-weight: 600; } .today { background: #c6f6d5; color: #22543d; } .planned { background: #fef3c7; color: #78350f; }

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 We Solve

Software delivery scales with the coordination surface around it, not the engineering inside it.

Two frictions slow every team:

• Cognitive load — authoring the infrastructure that runs a service correctly. The long tail of services that are difficult to deploy, inconsistent in security and observability posture.
• Operational work — moving a merged change from "merged" to "running in production with policy, observability, and security enforced." Manual work that scales with the system, not with the change.

The platform absorbs both frictions.

---

The North Star

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

Success looks like:

• A merged change progresses through lower environments without a platform engineer joining a thread, approving a ticket, or triggering a stage.
• A non-technical consumer ships a production deployment by declaring intent — without authoring a workflow, a configuration file, or an infrastructure module.
• Every production change is traceable to a human attestation and an immutable evidence stream.

---

The Contract-Driven Model

One small YAML file is all a consumer writes. The platform owns everything else.

The contract names three things:

• 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 — the handful of values that vary per deployment

---

The End-to-End Flow

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

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. Available today (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

Every delivery action produces a measurable, explainable confidence signal — the platform's certified answer to "is this safe to proceed?"

• Six weighted inputs: policy conformance, validation, freshness, source provenance, history, NFRs
• Per-environment thresholds that rise with sensitivity:

Environment	Threshold	Attester
dev	≥ 0.50	No one — autonomous
qa	≥ 0.75	QA
prod	≥ 0.90	SRE
dr	≥ 0.95	SRE + DR drill

• A single critical finding hard-blocks the deployment — critical findings are not averaged away
• When the platform halts, it gives a measured reason — never an opaque debugging exercise

---

Policy & Security Enforcement

Checks run on every deployment, normalized to a single schema regardless of which engine produced them.

• Infrastructure policy (Checkov) — secrets in plaintext, public ingress, IAM wildcards, KMS references, required tagging standards (acdl:owner, acdl:contract, acdl:environment, acdl:cost-center) Available today
• Cloud security posture (Wiz adapter) — translates cloud security findings into the same normalized record Adapter ready
• Kubernetes-native policy (Kyverno adapter) — ready for the GitOps reconciler Adapter ready

Every check produces a record with severity, rule ID, pass/fail status, and a human-readable message — consumed uniformly by the confidence signal.

---

Secure by Default

Security defaults that do not require a team to opt in. Available today

• Encryption on every resource — at-rest encryption on by default for every primitive (S3, RDS, ECR, ECS, and more)
• Per-stack customer-managed keys — one key per deployment, 90-day rotation, no shared keys across stacks
• Managed-key fallback with a loud warning — silent use of cloud-managed keys is a security gap we refuse to hide
• Deletion protection on by default — prevent_destroy on unless a consumer explicitly disables it via a documented flag
• Safe decommission — a 2-step pipeline (disable protection → zero counts → destroy) with two SRE attestation gates and a change-request validated against the CMDB

---

Immutable Audit & Evidence

Version control is a coordination tool, not an evidentiary fortress. True compliance requires an immutable, externally-stored ledger.

• Every deployment writes a hash-chained evidence event — each event links to the previous via a cryptographic hash; tampering breaks the chain Available today
• Tiered storage: cold, tamper-proof source of truth (S3 Object Lock, 7-year retention) + a hot query index Outbox shipped Full ledger: planned
• RPO = 0 — the evidence write is synchronous; a deployment is not acknowledged until the evidence event is durably recorded
• Every production change is traceable to a human attestation — approver identities are the only durable record outside the forge's audit log

---

Human-in-the-Loop Where It Matters

Autonomy and accountability are not in tension — they apply at different environments.

• Dev is fully autonomous. The confidence signal (≥ 0.50) is the only gate. Queue-based handoffs are eliminated from lower environments.
• qa, prod, and dr require deliberate human attestation — not rubber stamps, but policy-mandated acts of accountability via protected deployment approvals.
• Separation of duties is enforced — the QA approver cannot be the prod approver. The platform reads both identities from the outbox and blocks on a match. Design shipped Wiring: planned
• Timeout discipline — 1 business day = warn + escalate; 2 business days = auto-freeze + re-submit

---

Observability Built In

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

• 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

---

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). Available today Self-service: planned

---

Portability & Future-Proofing

The platform is opinionated, but not painted into a corner.

• Substrate-agnostic core. The contract, the resolved stack, the policy results, the confidence signal, and the evidence stream are all defined without reference to any specific infrastructure tool. 1 adapter: Terraform OpenTofu / Pulumi / K8s
• Forge-agnostic contract ingestion. The platform Lambda reads a configurable API base for GitHub or Gitea. Available today
• Portable contracts. A second forge needs a forge adapter + a workflow translator — no change to modules, contracts, confidence, or audit
• Pattern recognition compounds value over time. As the platform observes recurring patterns, it can synthesize reusable modules. Future capability

---

Roadmap: Shipped vs. Planned

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

Available today

• 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
• Local reproducibility + forge-agnostic contract 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)
• Additional substrate adapters (OpenTofu, Pulumi, Kubernetes CRDs)