# Source-of-Truth Boundaries

This repository has multiple layers. Knowing the authority for each layer prevents accidental drift.

## Boundary summary

| Layer | Primary authority | Purpose |
|---|---|---|
| Application/runtime container composition | `services-up.sh` + Compose files under `core/`, `apps/`, `monitoring/` | What runs in the Docker environment and how services are wired. |
| Docker shared baseline inputs | `default-network.yml`, `default-environment.env`, `secrets/stack-secrets.env` | Shared network/env material applied during compose rendering. |
| Infrastructure inventory and reconciliation | Terraform under `infrastructure/terraform/` | Codified inventory of existing infrastructure and relationships, especially Proxmox VMs and selected Docker mirrors. |
| Secret policy and inventory | `docs/security-secrets.md` + `secrets/inventory.json` + local secret files in `secrets/` | What secrets exist, where they are expected, and what automation should parse. |
| Host/device configuration bootstrap (emerging) | Ansible under `infrastructure/ansible/` | Gradual inventory/configuration layer for hosts/devices; validation-first at current stage. |

## Practical meaning

### Docker runtime decisions

Change Compose files and `services-up.sh` when changing runtime behavior.

Do **not** assume Terraform Docker resources are the deployment source for day-to-day service runtime.

### Infrastructure inventory decisions

Use Terraform when documenting/reconciling existing:

- Proxmox VM config and identifiers.
- Physical host metadata.
- Select Docker container details that are intentionally mirrored.

Do **not** treat Terraform as a full replacement for Compose operations in this repo.


### Ansible bootstrap decisions

Use Ansible under `infrastructure/ansible/` to build inventory and configuration structure incrementally.

At the current stage:

- Do **not** treat Ansible as replacement authority for Docker runtime operations.
- Do **not** treat Ansible as replacement authority for Terraform inventory/reconciliation.
- NixOS remains outside Ansible authority unless explicitly adopted in a later phase.

## Declared config vs observed/runtime state

- **Declared config**: files in this repository (Compose, Terraform, docs).
- **Observed/runtime state**: live Docker/Proxmox reality and Terraform state snapshots.

Brownfield workflows reconcile these two safely and incrementally.

## Guardrails for contributors and Codex

- Do not mass-import or mass-reconcile everything at once.
- Keep imports/reconciliation scoped to one object (or small set) at a time.
- Keep `ignore_changes` surgical and justified.
- Prefer shaped outputs (inventory-ready) over raw provider object dumps.
- Do not commit `.tfstate`, real `.tfvars`, or real secret files.

See [docs/terraform-workflows.md](terraform-workflows.md) for step-by-step procedures.