docs: overhaul repo documentation and workflow guides

2026-04-21 09:28:55 +10:00
parent 020d6ecb79
commit c7dd9f2229
13 changed files with 539 additions and 174 deletions
@@ -0,0 +1,37 @@
+# Repository Structure
+
+This page explains where to find authoritative files quickly.
+
+## Top-level directories
+
+- `core/` — core platform/security services (Traefik, Authelia, CrowdSec, error pages).
+- `apps/` — user/business applications (Nextcloud, Passbolt, Gitea, Gramps, SearXNG).
+- `monitoring/` — observability and operational tooling (Prometheus, Grafana, InfluxDB, Node-RED, etc.).
+- `infrastructure/terraform/` — brownfield Terraform inventory/reconciliation layers.
+- `docs/` — repository-level architecture and workflow documentation.
+- `archive/` — historical compose/config artifacts not part of active runtime composition.
+- `secrets/` — local secret material and templates; never commit real values.
+
+## Key top-level files
+
+- `services-up.sh` — runtime composition entrypoint for multi-compose environment.
+- `default-network.yml` — shared docker network definitions used across compose files.
+- `default-environment.env` — non-secret default env values for compose rendering.
+- `DEPLOYMENT.md` — prerequisite setup before runtime operations.
+- `SECURITY_SECRETS_INVENTORY.md` — tracked secret-variable inventory and usage map.
+
+## Terraform layout
+
+- `infrastructure/terraform/README.md` — Terraform purpose and boundaries in this repo.
+- `infrastructure/terraform/proxmox/` — imported/reconciled Proxmox VM resources and host metadata.
+- `infrastructure/terraform/docker/` — selective Docker container documentation mirrors.
+- `infrastructure/terraform/bootstrap/` — backend/provider bootstrap scaffolding.
+- `infrastructure/terraform/scripts/reconcile_from_plan.sh` — helper for `terraform plan -generate-config-out` reconciliation workflow.
+
+## Fast path for future Codex runs
+
+1. Read [README.md](../README.md).
+2. Read [docs/source-of-truth.md](source-of-truth.md).
+3. Read [docs/docker-environment.md](docker-environment.md).
+4. Read [docs/terraform-workflows.md](terraform-workflows.md).
+5. Only then edit Compose/Terraform files.