# snapshots/

This directory holds the Directus schema snapshot for the TRM directus service.

## What lives here

- `schema.yaml` — the authoritative Directus schema: all collections, fields,
  and relations. Committed to git and applied at every container boot.
- `.gitkeep` — present until the first real snapshot lands (task 1.4/1.5/1.6).
  Once `schema.yaml` is committed, `.gitkeep` is no longer needed and can be
  removed.

## Do NOT hand-edit schema.yaml

`schema.yaml` is generated programmatically. Its format is tightly coupled to
the version of Directus that produced it. Hand-editing produces subtle breakage
(key-order drift, missing internal fields, format violations) that `schema apply`
will reject or silently misinterpret.

**The only supported workflow for schema changes is:**

1. Edit the schema in the Directus admin UI (local dev stack).
2. Run `pnpm run schema:snapshot` from the `directus/` repo root.
3. Review the diff in `snapshots/schema.yaml`.
4. Commit and open a PR.

## How schema.yaml is applied

`entrypoint.sh` calls `scripts/schema-apply.sh` at every container boot.
The apply script:

1. Skips silently if `schema.yaml` does not exist or is empty (safe for
   first-boot before any collections are defined).
2. Runs a dry-run preview (`directus schema apply --dry-run`) and prints the
   diff to container logs.
3. Applies the snapshot (`directus schema apply --yes`). This is idempotent —
   Directus computes the diff against the live DB and applies only what has
   changed. A clean re-deploy where the DB already matches the snapshot is a
   no-op.

## Snapshot/apply lifecycle

```
edit in admin UI
      │
      ▼
pnpm run schema:snapshot   ←── writes snapshots/schema.yaml
      │
      ▼
git commit + PR
      │
      ▼
CI: directus schema apply --dry-run  (fails PR if snapshot is broken)
      │
      ▼
container boot: entrypoint.sh → schema-apply.sh → directus start
```