directus/.planning/phase-1-slice-1-schema/04-org-catalog-collections.md

Task 1.4 — Org-level catalog collections

Phase: 1 — Slice 1 schema + deploy pipeline Status: ⬜ Not started Depends on: 1.3 (db-init applied so Directus can boot) Wiki refs: docs/wiki/synthesis/directus-schema-draft.md (Org-level catalog section), docs/wiki/sources/rally-albania-regulations-2025.md

Goal

Create the durable, org-level collections in the Directus admin UI: organizations, users (using Directus's built-in users with custom fields), organization_users, vehicles, organization_vehicles, devices, organization_devices. These are the resources that exist independently of any single event.

This task happens against a locally running Directus instance (from pnpm dev). The output is a snapshot YAML that captures the collection definitions; that snapshot lands in git in task 1.6.

Deliverables

Create the following collections via the admin UI (Settings → Data Model). Field shapes per directus-schema-draft. Required-field columns marked *.

organizations

Field	Type	Notes
id *	UUID	primary key, auto-generated
name *	string	display name
slug *	string	URL-friendly identifier, unique
created_at	timestamp	Directus standard
updated_at	timestamp	Directus standard

Singleton: false. Sort: name asc.

users (extending Directus built-in directus_users)

Use the built-in user collection. Add custom fields (Settings → Data Model → directus_users):

Field	Type	Notes
phone	string	optional
birth_date	date	optional, used for age-derived class eligibility (M-5/M-6/M-7)
nationality	string	ISO 3166-1 alpha-2 country code

Do NOT add an organization_id here — multi-tenancy goes through organization_users.

organization_users (junction)

Field	Type	Notes
id *	UUID
organization_id *	M2O → organizations
user_id *	M2O → directus_users
role *	string (dropdown)	enum: org-admin, race-director, marshal, timekeeper, participant, viewer
joined_at	timestamp	default now()

Unique constraint: (organization_id, user_id) — a user can only have one row per org. Multiple roles per user in same org → not yet (single role per tenant; revisit if needed).

vehicles

Field	Type	Notes
id *	UUID
make *	string	"Toyota"
model *	string	"Land Cruiser 70"
year	integer
engine_cc	integer	engine displacement, used for class assignment
vin	string	optional
plate_number	string	optional
notes	text

No owner_user_id / owner_team_id — vehicles are org-scoped only, ownership is not modeled (per directus-schema-draft decision).

organization_vehicles (junction)

Field	Type	Notes
id *	UUID
organization_id *	M2O → organizations
vehicle_id *	M2O → vehicles
registered_at	timestamp	default now()

Unique constraint: (organization_id, vehicle_id).

devices

Field	Type	Notes
id *	UUID
imei *	string	unique, the canonical device identifier
model *	string	"FMB920", "FMB003", etc. — drives IO mapping in processor
serial_number	string	optional
notes	text

imei UNIQUE — same IMEI can't be registered twice anywhere in the system.

organization_devices (junction)

Field	Type	Notes
id *	UUID
organization_id *	M2O → organizations
device_id *	M2O → devices
registered_at	timestamp	default now()

Unique constraint: (organization_id, device_id).

Specification

• Use UUIDs for all primary keys (Directus offers UUID v4 generation natively). Avoids leaking row counts and simplifies cross-env data sync.
• All M2O relations have ON DELETE set to RESTRICT by default — accidentally deleting an org or vehicle should require the operator to clean up dependents first. Override per-relation only with explicit reason.
• No permission policies — Phase 4 territory. Set every collection to "All Access" → none (admin only) for now.
• No interface customization beyond defaults — the SPA isn't using these collections directly yet, and admin UI usability for operators happens after Phase 4 (when policies define what they see).
• Do not commit .env or any secrets. This task only modifies Directus schema, which is captured in the snapshot.

Acceptance criteria

• All seven collections exist in the admin UI with the fields listed above.
• Required fields are flagged required.
• All unique constraints are enforced (test by trying to create a duplicate row — should error).
• M2O relations are visible and clickable in the admin UI's relational fields.
• No permission policies attached (admin-only).
• Manually create one organization, one user, one organization_user row → the relationships work end-to-end.
• pnpm run schema:snapshot produces a snapshots/schema.yaml with all seven collections present (verified by grep).
• Booting a brand-new Directus instance (fresh DB, fresh containers) and running directus schema apply --yes snapshots/schema.yaml recreates the seven collections identically.

Risks / open questions

• directus_users field additions — Directus does allow adding fields to its built-in user collection, but the snapshot/apply behavior for those additions has historically been finicky across versions. Verify on the pinned Directus version that custom user fields round-trip cleanly via schema snapshot + schema apply. If they don't, fall back to a separate user_profiles collection M2O'd to directus_users.
• Slug uniqueness on organizations — Directus enforces this at the field level. Confirm it generates a unique-index DDL in the snapshot.

Done

Implementation landed and live-verified 2026-05-02. All 7 collections live in Directus, snapshot captured at 53,450 bytes / 2,159 lines.

Driven via the directus-local MCP server rather than the admin UI — same canonical result (directus_collections / directus_fields / directus_relations rows + actual Postgres tables), captured cleanly by directus schema snapshot. This was the API-driven path the spec hinted at; sub-agents can't inherit MCP from the parent conversation, so this work was driven directly without delegation.

Created:

• organizations — 5 fields (id UUID PK, name, slug unique, date_created, date_updated).
• vehicles — 10 fields (id UUID PK, make, model, year, engine_cc, vin, plate_number, notes, date_created, date_updated). No ownership fields.
• devices — 7 fields (id UUID PK, imei UNIQUE, model, serial_number, notes, date_created, date_updated).
• directus_users — 3 custom fields added (phone, birth_date, nationality).
• organization_users — 7 fields (id UUID PK, organization_id M2O, user_id M2O, role enum dropdown with 6 values, joined_at, date_created, date_updated).
• organization_vehicles — 6 fields (id UUID PK, organization_id M2O, vehicle_id M2O, registered_at, date_created, date_updated).
• organization_devices — 6 fields (id UUID PK, organization_id M2O, device_id M2O, registered_at, date_created, date_updated).
• 6 M2O relations on the junctions, all with ON DELETE RESTRICT.

Composite unique constraints landed via db-init/004_junction_unique_constraints.sql because Directus's snapshot YAML format does not capture composite unique constraints (only single-column ones via is_unique). The migration adds:

• organization_users (organization_id, user_id)
• organization_vehicles (organization_id, vehicle_id)
• organization_devices (organization_id, device_id)

Boot logs confirm: [db-init] apply 004_junction_unique_constraints.sql → [db-init] done 004_junction_unique_constraints.sql → assertion block passes.

Snapshot review (snapshots/schema.yaml):

• 8 collections registered (the 7 above + positions and migrations_applied as ghost entries — Directus auto-discovers tables in the public schema and registers minimal metadata for them, even though they're owned by db-init/processor not Directus). The ghost entries are harmless: schema apply against a fresh DB sees them already created by db-init and skips DDL.
• directus_users custom fields round-trip correctly (no need for the spec's fallback user_profiles workaround).
• All 6 M2O relations present in the relations section.
• File size 53,450 bytes — well under the 200KB sanity threshold.

Acceptance criteria status:

• ✅ All seven collections exist with the fields specified.
• ✅ Required fields flagged (organizations.name/slug, devices.imei/model, vehicles.make/model, junction org/target/role).
• ✅ Single-column unique constraints (organizations.slug, devices.imei) enforced.
• ✅ Composite unique constraints on junctions enforced via db-init/004 (assertion block confirms).
• ✅ M2O relations clickable in admin UI (Directus auto-resolves the dropdowns from the relation metadata).
• ✅ No permission policies attached — admin-only by default.
• ✅ pnpm run schema:snapshot produces snapshots/schema.yaml with all 7 collections present.
• ⏳ End-to-end test (manually create org → user → org_user via admin UI) — pending user.
• ⏳ Apply-to-fresh-DB roundtrip — pending CI dry-run in task 1.8.

Phase 5 follow-up note (not blocking): boot logs still WARN about positions lacking a PK. Already documented in task 1.7's Done section.