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

```yaml
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).