nova-platform/docs/architecture.md

# Architecture

> **Status:** v1.0 (current). This document mirrors `.ciagent/ARCHITECTURE.md`.
> Where the two conflict, `.ciagent/ARCHITECTURE.md` wins.

## 0. Purpose

Nova Platform is the **infrastructure-delivery core**. A consumer declares
intent in a YAML contract; the platform resolves it to a stack, compiles it
through the Terraform adapter, and applies it. The DevSecOps, identity,
audit-ledger, and central CI-pipeline-contract machinery of the Nova
reference are intentionally removed — see the OOS list below.

## 1. Layers (4)

```
┌──────────────────────────────────────────────────────┐
│  1. Contract Surface      schemas/contract.schema.json
│                           contracts/*.yml (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. The `infrastructure` field is an
**array** (D-015), not a map:

```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 beyond local file reads
for module metadata (D-011). No engine terms.

`core/environment_check.py` validates that the named environment exists in
`core/environments/*.json` and returns its definition. Environments are
platform-managed (consumers provide no AWS account, VPC, or state bucket).

Interpolation (D-016): the resolver expands `${env.<field>}` and
`${contract.<field>}` tokens after the environment is loaded. Unknown tokens
raise `ValueError`.

### 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 (D-031):
`--check-only` (offline, structure validation), `--plan-only` (no apply),
full (apply). `--quiet` suppresses streaming.

## 2. 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`,
scope per D-034: `.py` files in `core/`, `schemas/`, `contracts/`,
`tests/`, `scripts/`, root — excluding `adapters/terraform/`, `modules/`,
`.tf`/`.md`/`.json` data files).

## 3. What is NOT here (intentionally removed vs the reference)

Nova Platform is a simplified, infrastructure-only platform. The following
reference features are **out of scope** for v1.0:

- No confidence signal — no score gating apply.
- No audit outbox — no hash-chained evidence events.
- No policy engine / policy adapter — no policy checks.
- No identity layer, no attribute-based authorization, no human-in-the-loop
  approval gates.
- No reusable CI workflow — local shell only (`scripts/run_ci.sh`).
- No central pipeline contract — no `pipelines/` directory.
- No platform telemetry / metrics.
- No decommission transform, env-transition transform, or onboarding flow
  beyond bootstrap.
- No leadership decks or slide rendering.

## 4. 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 — 13):** `s3`, `vpc`, `ecs-cluster`, `ecs-service`,
`iam-role`, `alb`, `ecr`, `cloudfront`, `waf`, `rds`, `kms-key`,
`dynamodb`, `uptime`.

**L2 (patterns — 2):**

| Module | Composes (D-038) | Description |
|--------|------------------|-------------|
| `microservice` | vpc + ecs-cluster + ecs-service + iam-role + ecr + alb (6 L1s) | Container microservice with a public ALB |
| `static-assets` | s3 + cloudfront + kms-key (3 L1s) | Static site fronted by CloudFront |

L2 modules are opaque stack entries (D-012): the resolver does not expand
their children. The L2's `terraform/main.tf` composes L1 modules internally
via `module` blocks. See [`docs/modules/index.md`](modules/index.md) for the
full catalog and each module's README.