autojanet/skills/terrashark/references/structure-and-state.md

Structure and State

Use this guide to choose repo shape, environment segmentation, and state boundaries.

Boundary model

Define boundaries by three factors:

1. Change cadence (what changes together)
2. Blast radius (what can fail together)
3. Ownership (who approves and supports it)

If those differ, split stacks.

Root module patterns

• service-root: one business service and its direct dependencies.
• platform-root: shared platform primitives (network, identity, observability).
• bootstrap-root: backend/state prerequisites and foundational security controls.

Avoid monolithic roots that mix all three.

Environment isolation options

1. Separate root directories per environment.
2. Workspace-per-environment with strict policy and access control.
3. Separate repositories when regulatory or ownership requirements demand hard isolation.

Pick one and document why.

State backend baseline

• remote backend only for collaborative environments
• lock protection for every apply path
• encryption at rest and in transit
• narrow IAM on state and lock stores
• versioned backup and restore test at least once
• load references/conditional/backend-state-safety.md for backend-specific locking, access, and migration guardrails

Cross-stack dependencies

Preferred order:

1. explicit module outputs passed in the same root
2. published interface artifacts (preferred at scale)
3. terraform_remote_state as last-resort coupling

If terraform_remote_state is used, version and ownership of the producer stack must be explicit.

Apply safety gates

Minimum gates:

• fmt and validate
• lint and security scan
• policy checks
• reviewed plan
• approved apply

Change safety for state evolution

• Use moved blocks for renames and address changes.
• For imports, document source of truth and verify idempotency before apply.
• For manual state operations, require peer review and rollback notes.