acdl/.ciagent/ARCHITECTURE.md

ACDL — Architecture (initial)

Initial architecture for the ACDL demo. May be incomplete; refined at phase boundaries.

Overview

The demo is a three-repo, stub-driven system that simulates an autonomous cloud delivery platform. No real cloud or AI is used; every "infrastructure" action is a bash/Python stub that emits structured evidence. The platform is driven by either a developer-supplied contract.yaml (L3A) or a natural-language GitHub Issue parsed by a keyword script (L3B), then flows through an autonomous Dev stage, manual QA and Prod approval gates, and finally publishes a hash-chained audit trail to a Pages site.

                 ┌──────────────── acdl-contracts ─────────────────┐
  Developer ───▶ │ commit contract.yaml      Issue (NL intent)     │
                 └────────────┬───────────────────┬────────────────┘
                              │ (push)            │ (issue opened)
                              ▼                   ▼
                    ┌─────────────────┐  ┌──────────────────────┐
                    │ reusable        │  │ issue workflow →      │
                    │ pipeline        │  │ l3b_agent_stub.py →   │
                    │ (acdl repo)     │  │ contract.yaml → push  │
                    └────────┬────────┘  └──────────────────────┘
                             │
        ┌────────────────────┼────────────────────┐
        ▼                    ▼                    ▼
  Dev (autonomous)     QA (approval)        Prod (approval)
  mock_executor.sh     environment gate     environment gate
  policy_checker.py
  confidence_signal.py
        │
        ▼
  evidence_writer.py ──▶ audit.json (hash-chained) ──▶ acdl-evidence
                                                          │
                                                          ▼
                                                   index.html (Pages)
                                                   timeline UI

Components

Name	Description	Boundaries	Depends On
acdl repo	Platform meta repo: reusable workflows, L1/L2 stub modules, core scripts	Owns workflows + stubs; does not hold contracts or evidence	—
L1 modules	Single-purpose infra primitives (EKS Fargate, IAM, Lambda, API Gateway, EventBridge, SQS, S3, CloudWatch)	One folder per L1; manifest.yaml + mock_apply.sh; do not compose with other L1s	acdl repo
L2 modules	Composed stacks (invoice, commodity-price-feed, energy-analytics-api, regulatory-reporting)	Reference L1s by name; max depth 5; expressed as a composition manifest	L1 modules
mock_executor.sh	Reads an L2 composition, invokes each L1 mock_apply.sh, writes state.json	Bash; reads L2 manifest + L1 manifests	L1/L2 modules
policy_checker.py	Reads contract.yaml; fails on forbidden keys (e.g. public-ingress: true)	Python; emits POLICY_VIOLATION:<REASON> or pass	contract.yaml
confidence_signal.py	Base 0.90; on policy failure drops to 0.40 and echoes reason	Python; calls policy_checker	policy_checker.py
evidence_writer.py	Appends an event to audit.json, links to previous event via SHA-256 chain	Python; canonical-JSON hashing	audit.json
l3b_agent_stub.py	Parses Issue text by keywords, emits contract.yaml	Python keyword map; no external APIs	contract.yaml schema
acdl-contracts repo	Developer + agentic entry surface; holds contracts + issue workflow	Triggers main pipeline on push	acdl reusable workflow
acdl-evidence repo	Pages host for audit.json + index.html timeline	Read-only for the pipeline; written at finalize stage	evidence_writer.py output
Reusable pipeline workflow	Dev → QA → Prod → Finalize stages with environment gates	Gitea Actions; calls core scripts	All core scripts

Data Flow

1. A contract.yaml arrives either by direct push (L3A) or by the issue workflow running l3b_agent_stub.py (L3B).
2. Push to acdl-contracts triggers the reusable pipeline in the acdl repo.
3. Dev stage: policy_checker.py validates the contract; mock_executor.sh applies the L2 composition's L1s; confidence_signal.py computes the score; evidence_writer.py records each step. If score < 0.50, the stage fails and evidence records the rejection.
4. QA stage: the workflow pauses on the qa environment; a human approves.
5. Prod stage: same gate on the prod environment.
6. Finalize: the workflow commits the updated audit.json to acdl-evidence; Pages republishes index.html, which fetches and renders the timeline.

Build Order

1. Repo scaffolding: create acdl-contracts and acdl-evidence in the org; seed acdl directory layout.
2. L1 modules (8 stubs).
3. L2 modules (4 compositions).
4. Core scripts (mock_executor.sh, policy_checker.py, confidence_signal.py, evidence_writer.py, l3b_agent_stub.py).
5. Reusable pipeline workflow (Dev → QA → Prod → Finalize) + environment gates.
6. Issue-triggered L3B workflow in acdl-contracts.
7. Evidence UI (index.html + Pages config).
8. Demo dry-run + the four scripted acts.