Files

T

julian 6f376a479f Task 1.4 — Org-level catalog collections

Seven collections + 3 directus_users custom fields, captured as
snapshots/schema.yaml (53 KB, 2,159 lines).

Collections:
- organizations          — UUID PK, name, slug UNIQUE
- vehicles               — UUID PK, make/model required, year/cc/vin/plate optional
- devices                — UUID PK, imei UNIQUE, model required
- organization_users     — junction with role enum (org-admin, race-director,
                            marshal, timekeeper, participant, viewer)
- organization_vehicles  — junction with registered_at
- organization_devices   — junction with registered_at
- directus_users         — extended with phone, birth_date, nationality

Six M2O relations on the junctions, all ON DELETE RESTRICT (matching
the schema-draft decision: deletion of an org/vehicle/device/user
requires explicit cleanup of dependents).

db-init/004_junction_unique_constraints.sql adds the composite UNIQUE
constraints on the three junctions:
  organization_users  (organization_id, user_id)
  organization_vehicles (organization_id, vehicle_id)
  organization_devices (organization_id, device_id)

Composite uniqueness lives in db-init rather than the Directus snapshot
because Directus's snapshot YAML format only captures single-column
unique constraints (the field-level is_unique flag). The migration file
documents the split inline.

Driven via the directus-local MCP server rather than admin-UI clicking
— programmatic create-collection/create-field/create-relation calls
against the running Directus instance, then `pnpm run schema:snapshot`
to capture the canonical YAML.

Live-verified: db-init/004 applies cleanly on container restart
(0 rows in the empty junctions, no constraint violations); schema-apply
against a snapshot-empty boot still skips correctly; all seven new
collections show up in the admin UI's data model navigation.

Snapshot includes positions and migrations_applied as auto-discovered
ghost entries (Directus introspects all public-schema tables). Harmless
— db-init creates them before schema-apply runs, so snapshot apply just
finds them already present.

ROADMAP marks 1.4 done. Phase 1 progress: 6/9 tasks complete (1.1, 1.2,
1.3, 1.4, 1.6, 1.7); 1.5, 1.8, 1.9 remain.

2026-05-02 09:41:01 +02:00

.gitkeep

Task 1.1 — Project scaffold

2026-05-01 21:29:13 +02:00

README.md

Tasks 1.6 + 1.7 — schema tooling + real entrypoint flow

2026-05-02 09:40:53 +02:00

schema.yaml

Task 1.4 — Org-level catalog collections

2026-05-02 09:41:01 +02:00

README.md

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:

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

How schema.yaml is applied

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

Skips silently if schema.yaml does not exist or is empty (safe for first-boot before any collections are defined).
Runs a dry-run preview (directus schema apply --dry-run) and prints the diff to container logs.
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