Nova Platform

Nova Platform — infrastructure delivery, simplified. A consumer declares intent in a YAML contract; the platform resolves it to a stack, compiles it through the Terraform adapter, and applies it. Every deployment is reproducible from the shell, not just in CI.

Nova Platform is the infrastructure-delivery core of the Nova model. The DevSecOps, identity, audit-ledger, and central CI-pipeline-contract machinery of the reference are intentionally removed. What remains: a consumer writes a small YAML contract that names one or more modules by name + version, selects an environment, and supplies module-specific inputs. The platform resolves the contract to a stack instance, compiles it through the Terraform adapter, and applies it.

• Consumer guide: docs/consumer-guide.md
• Contracts: docs/contracts/
• Environments: docs/environments/
• Architecture: docs/architecture.md
• Modules: docs/modules/

How to run

Quick start (offline, no AWS required)

The fastest way to verify the platform works — no AWS credentials, no bootstrap, no cost.

# Install test dependencies
pip install -r requirements-test.txt

# 1. Run the test suite (all offline)
python3 -m pytest tests/ -q

# 2. Run the platform in check-only mode (offline — contract -> resolve ->
#    adapter -> structure validation). Uses the default sample contract.
bash scripts/run_platform.sh --check-only contracts/static-assets.yml
# Expected: "=== PLATFORM CHECK OK ==="

# 3. Reproduce the full CI pipeline locally (lint -> test -> check-only)
bash scripts/run_ci.sh
# Expected: "=== CI PIPELINE OK ==="

# Show all run_platform.sh flags:
bash scripts/run_platform.sh --help

Run against live AWS (requires credentials + bootstrap)

Prerequisites: a platform-managed environment (see docs/environments/; core/environments/dev.json is the sample), AWS credentials for dev (in .ciagent/.env.secrets, gitignored; see Credentials), terraform (pin >= 1.9, < 1.10), python3 + boto3 + jsonschema + pyyaml.

# 1. Bootstrap the AWS state backend + runner IAM user (one-time, idempotent)
#    See terraform/bootstrap/README.md for the full runbook.
export NOVA_BOOTSTRAP_AWS_ACCESS_KEY_ID="<root key>"
export NOVA_BOOTSTRAP_AWS_SECRET_ACCESS_KEY="<root secret>"
export AWS_DEFAULT_REGION="us-east-1"
python3 terraform/bootstrap/create_state_backend.py
python3 terraform/bootstrap/create_iam_user.py   # prints the initial key
bash scripts/rotate_spike_key.sh                  # writes .ciagent/.env.secrets

# 2. Run the full platform pipeline (contract -> environment check -> stack ->
#    adapter -> terraform init/validate/plan -> apply).
bash scripts/run_platform.sh contracts/microservice.yml
# Expected: "=== PLATFORM APPLY OK ==="

# Or plan-only (contract -> stack -> adapter -> terraform plan; no apply):
bash scripts/run_platform.sh --plan-only contracts/static-assets.yml

# Add --quiet to suppress streaming (output to log files only):
bash scripts/run_platform.sh --quiet contracts/static-assets.yml

run_platform.sh flags (D-031)

Flag	Mode	AWS required	Description
--check-only	offline	no	contract → resolve → adapter → structure validation
--plan-only	AWS	yes	above + terraform init/validate/plan (no apply)
--quiet	any	—	suppress streaming output
-h, --help	—	—	show usage
(none)	apply	yes	full path: above + terraform apply -auto-approve

Repository layout

Path	Purpose	Status
core/	Platform code: contract resolver, environment check, environments	active
schemas/	JSON Schemas (draft 2020-12): contract, stack, environment	active
adapters/terraform/	The Terraform adapter — the only engine-specific code	active
terraform/	State backend (S3 + DynamoDB) + bootstrap scripts + platform/onboarding/ci-vpc	active
modules/	L1 primitives (13) + L2 patterns (2) + registry.json. Each module has interface.json + terraform/	active
contracts/	Sample consumer contracts (static-assets.yml, microservice.yml) + per-env variants	active
scripts/	run_platform.sh (pipeline runner), run_ci.sh (local CI mirror), rotate_spike_key.sh	active
tests/	Pytest suite (all offline — resolver, adapter, schemas, engine boundary, environment check)	active
docs/	Documentation: consumer guide, contracts, environments, architecture, modules	active
.ciagent/	CIAgent config + locked decisions (ARCHITECTURE.md, PROJECT.md, CLARIFY.md)	active

Credentials

Nova Platform uses a static AWS key for dev/local operation. There is no zero-trust federation layer in v1.0 — that is out of scope.

• The runner key is stored in .ciagent/.env.secrets (gitignored, chmod 600) using the NOVA_AWS_* prefix (D-032): NOVA_AWS_ACCESS_KEY_ID, NOVA_AWS_SECRET_ACCESS_KEY.
• scripts/run_platform.sh copies NOVA_AWS_* to the standard AWS_* env vars before invoking Terraform, then unsets the NOVA_* copies.
• Bootstrap uses a one-shot root key via NOVA_BOOTSTRAP_AWS_* env vars (never committed, never echoed). See terraform/bootstrap/README.md for the full bootstrap runbook (state backend + runner IAM user + key rotation).
• Onboarding creates a per-consumer IAM role (cross-account assume-role pattern, D-025) — not a user, not federation. See terraform/onboarding/main.tf.

Consumer guide

A step-by-step guide for a consumer to create a repo, write a contract, validate it offline, and run it against AWS is at docs/consumer-guide.md. The guide is generic across all modules; static-assets is the worked example.