directus

trm/directus

Fork 0

Commit Graph

Author	SHA1	Message	Date
julian	e01abfef27	Split db-init into pre-schema and post-schema phases CI dry-run revealed an architectural ordering bug: db-init/004 and db-init/005 ALTER TABLE the Directus-managed tables (organization_users, events, etc.), but db-init runs BEFORE schema-apply creates those tables. On a fresh CI Postgres this fails with "relation does not exist." Local dev never tripped this because we'd created the tables via MCP first. Fix: introduce a post-schema migration phase. Two db-init runs in the entrypoint, with schema-apply in between: 1. apply-db-init.sh db-init/ → positions hypertable + faulty column (tables Directus does NOT manage) 2. schema-apply.sh → creates Directus-managed tables from snapshots/schema.yaml 3. apply-db-init.sh db-init-post/ → composite UNIQUE constraints on the Directus-managed tables 4. directus bootstrap 5. directus start Files moved: db-init/004_junction_unique_constraints.sql → db-init-post/001_junction_unique_constraints.sql db-init/005_event_participation_unique_constraints.sql → db-init-post/002_event_participation_unique_constraints.sql Each ALTER TABLE in the post-schema migrations is now wrapped in a pg_constraint existence guard for idempotency. This handles the dev DB where the constraints already exist (from the original 004/005 runs + the manual psql recovery during task 1.5's destructive-apply incident). Old 004/005 rows in migrations_applied become orphans — harmless. Updates: - Dockerfile: COPY db-init-post into the image - entrypoint.sh: 4-step → 5-step flow with the post-schema run between schema-apply and bootstrap - .gitea/workflows/build.yml: dry-run chains all three pre-boot scripts (pre-schema → schema-apply → post-schema); path filter includes db-init-post/** - Task specs 1.4 and 1.5 Done sections: updated to reference the new db-init-post/ path (db-init/004 → db-init-post/001, etc.) The reusable runner script (apply-db-init.sh) didn't need to change — it already accepts DB_INIT_DIR and uses just the basename for the guard-table key. The two phases share migrations_applied; filenames don't collide because pre-schema and post-schema use distinct descriptive names. Phase 1 is still "done" — this is a Phase 1 architectural correction exposed by the CI dry-run, not a new task.	2026-05-02 10:48:06 +02:00
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
julian	a8e808e71c	Scaffold directus service planning structure Initial commit. Establishes the .planning/ tree mirroring processor's shape (ROADMAP.md as nav hub + per-phase folders with READMEs and granular task files). Six phases: 1. Slice 1 schema + deploy pipeline — what Rally Albania 2026 needs. Org catalog (orgs, users, vehicles, devices) + event participation (events, classes, entries, entry_crew, entry_devices). db-init/ for the positions hypertable + faulty column. snapshot/apply tooling. Gitea CI dry-run. Dogfood seed of Rally Albania 2026. Nine task files with full Goal / Deliverables / Specification / Acceptance criteria / Risks / Done sections. 2. Course definition — stages, segments, geofences, waypoints, SLZs. PostGIS extension introduced here. 3. Timing & penalty tables — co-developed with processor Phase 2. entry_segment_starts, entry_crossings, entry_penalties, stage_results, penalty_formulas. 4. Permissions & policies — Directus 11 dynamic-filter Policies per logical role. Deployment-time work, deferred to keep early phases focused on the data model. 5. Custom extensions — TypeScript hooks/endpoints implementing the cross-plane workflows the schema implies (faulty-flag → Redis stream emit, stage-open materializer, etc.). 6. Future / optional — retroactivity preview UI, command-routing Flows, audit trails, federation rule import. Not committed. Non-negotiable design rules captured in ROADMAP.md: schema authority in Directus + snapshot-as-code + db-init for non-Directus DDL + sequential idempotent migrations + entrypoint apply order + no application logic in Flows + permissions deferred to Phase 4. Architectural anchors point at the wiki at ../docs/wiki/ — the schema draft, the Rally Albania 2025 source page, plus the existing processor/postgres-timescaledb/live-channel pages. Each task file calls out the wiki refs an implementing agent should read first. README.md mirrors the processor service README structure: quick start, local Docker test, prod/stage deployment notes, env vars, CI behavior.	2026-05-01 20:42:44 +02:00

Author

SHA1

Message

Date

julian

e01abfef27

Split db-init into pre-schema and post-schema phases

CI dry-run revealed an architectural ordering bug: db-init/004 and
db-init/005 ALTER TABLE the Directus-managed tables (organization_users,
events, etc.), but db-init runs BEFORE schema-apply creates those
tables. On a fresh CI Postgres this fails with "relation does not
exist." Local dev never tripped this because we'd created the tables
via MCP first.

Fix: introduce a post-schema migration phase. Two db-init runs in the
entrypoint, with schema-apply in between:

  1. apply-db-init.sh   db-init/        → positions hypertable + faulty
                                          column (tables Directus does
                                          NOT manage)
  2. schema-apply.sh                    → creates Directus-managed tables
                                          from snapshots/schema.yaml
  3. apply-db-init.sh   db-init-post/   → composite UNIQUE constraints on
                                          the Directus-managed tables
  4. directus bootstrap
  5. directus start

Files moved:
  db-init/004_junction_unique_constraints.sql →
    db-init-post/001_junction_unique_constraints.sql
  db-init/005_event_participation_unique_constraints.sql →
    db-init-post/002_event_participation_unique_constraints.sql

Each ALTER TABLE in the post-schema migrations is now wrapped in a
pg_constraint existence guard for idempotency. This handles the dev DB
where the constraints already exist (from the original 004/005 runs +
the manual psql recovery during task 1.5's destructive-apply
incident). Old 004/005 rows in migrations_applied become orphans —
harmless.

Updates:
- Dockerfile: COPY db-init-post into the image
- entrypoint.sh: 4-step → 5-step flow with the post-schema run between
  schema-apply and bootstrap
- .gitea/workflows/build.yml: dry-run chains all three pre-boot scripts
  (pre-schema → schema-apply → post-schema); path filter includes
  db-init-post/**
- Task specs 1.4 and 1.5 Done sections: updated to reference the new
  db-init-post/ path (db-init/004 → db-init-post/001, etc.)

The reusable runner script (apply-db-init.sh) didn't need to change —
it already accepts DB_INIT_DIR and uses just the basename for the
guard-table key. The two phases share migrations_applied; filenames
don't collide because pre-schema and post-schema use distinct
descriptive names.

Phase 1 is still "done" — this is a Phase 1 architectural correction
exposed by the CI dry-run, not a new task.

2026-05-02 10:48:06 +02:00

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

julian

a8e808e71c

Scaffold directus service planning structure

Initial commit. Establishes the .planning/ tree mirroring processor's
shape (ROADMAP.md as nav hub + per-phase folders with READMEs and
granular task files).

Six phases:

1. Slice 1 schema + deploy pipeline — what Rally Albania 2026 needs.
   Org catalog (orgs, users, vehicles, devices) + event participation
   (events, classes, entries, entry_crew, entry_devices). db-init/
   for the positions hypertable + faulty column. snapshot/apply
   tooling. Gitea CI dry-run. Dogfood seed of Rally Albania 2026.
   Nine task files with full Goal / Deliverables / Specification /
   Acceptance criteria / Risks / Done sections.

2. Course definition — stages, segments, geofences, waypoints, SLZs.
   PostGIS extension introduced here.

3. Timing & penalty tables — co-developed with processor Phase 2.
   entry_segment_starts, entry_crossings, entry_penalties,
   stage_results, penalty_formulas.

4. Permissions & policies — Directus 11 dynamic-filter Policies per
   logical role. Deployment-time work, deferred to keep early phases
   focused on the data model.

5. Custom extensions — TypeScript hooks/endpoints implementing the
   cross-plane workflows the schema implies (faulty-flag → Redis
   stream emit, stage-open materializer, etc.).

6. Future / optional — retroactivity preview UI, command-routing
   Flows, audit trails, federation rule import. Not committed.

Non-negotiable design rules captured in ROADMAP.md: schema authority
in Directus + snapshot-as-code + db-init for non-Directus DDL +
sequential idempotent migrations + entrypoint apply order + no
application logic in Flows + permissions deferred to Phase 4.

Architectural anchors point at the wiki at ../docs/wiki/ — the schema
draft, the Rally Albania 2025 source page, plus the existing
processor/postgres-timescaledb/live-channel pages. Each task file
calls out the wiki refs an implementing agent should read first.

README.md mirrors the processor service README structure: quick start,
local Docker test, prod/stage deployment notes, env vars, CI behavior.

2026-05-01 20:42:44 +02:00

3 Commits