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.