nova-platform/.ciagent/ARCHITECTURE.md

Nova Platform — Architecture

Simplified from the Nova reference. The reference's six cross-cutting concerns (security, policy, confidence, outbox/audit, identity, CI pipeline contract) are removed. What remains is the four-layer infrastructure-delivery core.

Layers (4)

┌──────────────────────────────────────────────────────┐
│  1. Contract Surface      schemas/contract.schema.json
│                           contracts/*.yaml (samples)
├──────────────────────────────────────────────────────┤
│  2. Resolution            core/contract_resolver.py
│                           core/environment_check.py
│                           schemas/stack.schema.json
├──────────────────────────────────────────────────────┤
│  3. Engine Adapter        adapters/terraform/ (the only
│  (only engine-specific)   engine-specific code)
├──────────────────────────────────────────────────────┤
│  4. Apply                 terraform/ (bootstrap, modules)
│                           scripts/run_platform.sh
└──────────────────────────────────────────────────────┘

Layer 1 — Contract Surface

A consumer writes a small YAML contract:

id: stsi
name: My Static Site
environment: dev
infrastructure:
  - module: static-assets
    version: "1.0.0"
    inputs:
      bucket_name: my-static-site-assets
      index_document: index.html

Validated against schemas/contract.schema.json. The contract is the only consumer-facing surface. It is engine-agnostic — no aws_* terms.

Layer 2 — Resolution

core/contract_resolver.py resolves a validated contract to a Stack instance (a typed structure conforming to schemas/stack.schema.json). Resolution is pure: contract in, stack out. No I/O, no engine terms.

core/environment_check.py validates that the named environment exists in core/environments/*.json and that the caller is permitted to use it. Environments are platform-managed (consumers provide no AWS account, VPC, or state bucket).

Layer 3 — Engine Adapter

adapters/terraform/ is the only engine-specific code. It takes a Stack and emits Terraform (module "x" { source = "../../modules/..." } blocks). The adapter is a stateless assembler — lifecycle ownership belongs to Terraform via the shell orchestrator. This is the only place aws_* / Terraform terms appear.

Layer 4 — Apply

scripts/run_platform.sh orchestrates: contract → resolve → adapter → terraform init → terraform plan → terraform apply. Modes: --check-only (offline, structure validation), --plan-only (no apply), full (apply). --quiet suppresses streaming.

Engine Boundary (Enforced)

The engine boundary is strict. Code outside adapters/terraform/ MUST NOT contain engine-specific terms (aws_s3_bucket, aws_*, Terraform HCL). This invariant is verified by tests (tests/test_engine_boundary.py).

What is NOT here (intentionally removed vs the reference)

• No core/confidence_signal.py — no score gating apply.
• No core/outbox_writer.py — no hash-chained evidence events.
• No core/policy_engine.py / adapters/kyverno-json/ / adapters/wiz/ — no policy checks.
• No core/abac_evaluator.py / core/auth_store.py / core/jws_attestation.py / core/kms_signing.py / core/pat_lifecycle.py / core/separation_of_duties.py / core/hitl_gates.py / core/attestation_matrix.py / core/submission_readiness.py — no identity/ABAC/HITL.
• No adapters/checkov/ custom rules — no Checkov.
• No .github/workflows/ — no CI pipeline (local shell only).
• No pipelines/ — no central pipeline contract.
• No schemas/pipeline.schema.json / schemas/deploy-pipeline.schema.json / schemas/policy_check_result.schema.json / schemas/metrics_*.schema.json — those schemas are dropped.
• No metrics/ — no platform telemetry.
• No core/regression_verify*.py / core/metrics/ — no regression or metrics modules.
• No leadership decks, PPTX rendering, marp slides.
• No core/env_transition.py / core/decommission_transform.py / core/mode_resolver.py / core/onboarding.py — no env transition, decommission, mode resolution, or onboarding flow beyond bootstrap.

Module Catalog

L1 primitives (single resources) + L2 patterns (composites of primitives). Each module has an interface.json (inputs/outputs, no engine terms) and a terraform/ directory. modules/registry.json indexes every module + version.

L1 (primitives): s3, vpc, ecs-cluster, ecs-service, iam-role, alb, ecr, cloudfront, waf, rds, kms-key, dynamodb, uptime.

L2 (patterns): microservice (vpc + ecs-cluster + ecs-service + iam-role + ecr + alb — locked D-038), static-assets (s3 + cloudfront + kms-key — locked D-038, drops waf from reference).