T

julian 52524eb72d Task 1.5 — Event-participation collections

Five collections + 10 relations + 5 composite unique constraints,
captured into snapshots/schema.yaml (now 105 KB, up from 53 KB).

Collections:
- events       — 11 fields incl. organization_id M2O, discipline enum
                  (rally / time-trial / regatta / trail-run / hike),
                  starts_at/ends_at required.
- classes      — 8 fields incl. event_id M2O, code unique within event.
- entries      — 11 fields incl. event_id/vehicle_id (nullable for foot
                  races) /class_id M2O, race_number, status enum with
                  8 lifecycle values, archive on `withdrawn`.
                  team_id deliberately omitted (Phase 2+).
- entry_crew   — junction with role enum
                  (pilot/co-pilot/navigator/mechanic/rider/runner/hiker).
- entry_devices — junction with optional assigned_user_id (panic button
                  body-wear); ON DELETE SET NULL on that field since
                  user removal shouldn't block the device record.

10 M2O relations wired, all ON DELETE RESTRICT except
entry_devices.assigned_user_id (SET NULL).

db-init/005_event_participation_unique_constraints.sql adds composite
UNIQUE on:
  events (organization_id, slug)
  classes (event_id, code)
  entries (event_id, race_number)
  entry_crew (entry_id, user_id)
  entry_devices (entry_id, device_id)

---

Destructive-apply incident (recovered):

First attempt at this task hit a real foot-gun. After creating the 5
collections via MCP, we ran `compose build && up -d`. The image rebuild
baked in the snapshot from task 1.4 (only 7 collections). Boot's
schema-apply step ran `directus schema apply --yes` against that stale
snapshot — saw the 5 new collections in the DB but not in the snapshot
— DELETED THEM, taking the constraints with them.

Recovery: re-created the 5 collections + 10 relations via MCP, ran the
ALTER TABLE statements directly via psql to restore the constraints,
ran schema:snapshot BEFORE any further restart so the YAML reflects
the live state. Documented the operator rule (never rebuild with
uncommitted schema changes) inline in the task spec and in the
directus wiki entity page (separate commit in trm/docs).

Phase 3 hardening on the radar: DIRECTUS_SCHEMA_APPLY_MODE env var
with auto/dry-run/skip modes so dev environments default to non-
destructive behavior.

ROADMAP marks 1.5 done. Phase 1 progress: 7/9 tasks complete (1.1–1.7);
1.8, 1.9 remain.

2026-05-02 09:55:17 +02:00

.planning

Task 1.5 — Event-participation collections

2026-05-02 09:55:17 +02:00

db-init

Task 1.5 — Event-participation collections

2026-05-02 09:55:17 +02:00

extensions

Task 1.1 — Project scaffold

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

scripts

Tasks 1.6 + 1.7 — schema tooling + real entrypoint flow

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

snapshots

Task 1.5 — Event-participation collections

2026-05-02 09:55:17 +02:00

.dockerignore

Task 1.1 — Project scaffold

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

.env.example

Task 1.1 — Project scaffold

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

.gitattributes

Task 1.2 — db-init runner script

2026-05-01 22:35:17 +02:00

.gitignore

Task 1.1 — Project scaffold

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

compose.dev.yaml

Task 1.1 — Project scaffold

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

Dockerfile

Task 1.2 — db-init runner script

2026-05-01 22:35:17 +02:00

entrypoint.sh

Tasks 1.6 + 1.7 — schema tooling + real entrypoint flow

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

package.json

Task 1.1 — Project scaffold

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

pnpm-lock.yaml

Task 1.1 — Project scaffold

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

README.md

Task 1.1 — Project scaffold

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

README.md

directus

The TRM business plane. Directus 11 instance owning the relational schema (organizations, users, events, entries, course definition, penalty system, timing tables), exposing it through auto-generated REST/GraphQL APIs and the admin UI, and enforcing role-based permissions.

For the architectural specification see ../docs/wiki/entities/directus.md. For the work plan and task status see .planning/ROADMAP.md.

This service is part of the TRM (Time Racing Management) platform.

Schema management — at a glance

Schema is defined and migrated through Directus, with two artifact directories:

snapshots/schema.yaml — Directus collections, fields, relations. Generated locally via directus schema snapshot, applied at container startup via directus schema apply.
db-init/*.sql — schema Directus does not manage: the postgres-timescaledb positions hypertable, the faulty column, PostGIS-specific DDL, etc. Sequential numbered files (001_, 002_, …) applied by scripts/apply-db-init.sh with a migrations_applied guard table to skip already-run files.

Apply order at boot: db-init first, then directus schema apply, then directus start. Any failure halts boot.

Quick start (local)

Prerequisites: Docker, the directus/directus:11.17.4 image (pulled automatically by compose), a running Postgres 16 + TimescaleDB + PostGIS instance (provided by compose.dev.yaml).

git clone <repo-url>
cd directus
cp .env.example .env
# Edit .env — at minimum set DB_HOST, DB_USER, DB_PASSWORD, DB_DATABASE, KEY, SECRET
docker compose -f compose.dev.yaml up --build

Admin UI lands at http://localhost:8055. Default admin credentials are read from ADMIN_EMAIL / ADMIN_PASSWORD in .env.

After making schema changes in the admin UI, snapshot before commit:

pnpm run schema:snapshot
git add snapshots/schema.yaml && git commit

Test the image locally

compose.dev.yaml builds the image from source and runs it next to a TimescaleDB+PostGIS container. Useful for verifying Dockerfile changes, db-init migrations, or snapshot apply behavior before pushing.

docker compose -f compose.dev.yaml down -v   # wipe volumes for a fresh run
docker compose -f compose.dev.yaml up --build

The entrypoint runs db-init, then directus schema apply, then directus start. Watch the logs to confirm each step exits 0.

Production / stage deployment

This service is not deployed standalone. It runs as part of the platform stack defined in the deploy/ repo, which Portainer pulls and runs on the stage and production hosts.

The image itself is published to git.dev.microservices.al/trm/directus:main on every push to main (see CI behavior below). The deploy/ repo's compose.yaml references that image.

To pin a specific commit in production, set DIRECTUS_TAG=<sha> in the deploy stack's environment variables.

Note: The deploy/compose.yaml will need a directus service entry referencing this image, plus a TimescaleDB+PostGIS service if not already present, before this service can run in stage/production. See .planning/phase-1-slice-1-schema/07-image-and-dockerfile.md.

Environment variables

See .env.example for the full list. Required for boot:

Variable	Description
`DB_CLIENT`	`pg` (always)
`DB_HOST` / `DB_PORT` / `DB_DATABASE` / `DB_USER` / `DB_PASSWORD`	Postgres connection
`KEY`	Directus instance key (random UUID)
`SECRET`	Directus JWT signing secret (random)
`ADMIN_EMAIL` / `ADMIN_PASSWORD`	Bootstrap admin (only used on first init)
`PUBLIC_URL`	External-facing URL of the instance

All other Directus envs (cache, logging, CORS, etc.) follow upstream defaults unless overridden.

CI behavior

Gitea Actions workflow lands at .gitea/workflows/build.yml in Phase 1 task 1.8 — not yet present.

When the workflow exists:

Push to main (only when snapshots/, db-init/, extensions/, Dockerfile, or the workflow file itself changes): builds the image, spins up a throwaway Postgres + TimescaleDB + PostGIS via services:, runs apply-db-init.sh and directus schema apply --yes against it as a dry-run, then publishes the image tagged :main if the dry-run exits 0. Auto-deploys to stage if a Portainer webhook is configured via secrets.PORTAINER_WEBHOOK_URL.
Manual trigger (workflow_dispatch): same flow, run on demand.

The dry-run is non-negotiable — it catches snapshot drift, broken db-init scripts, and incompatible schema changes before they touch any real DB.