directus/.planning/phase-1-slice-1-schema/README.md

# Phase 1 — Slice 1 schema + deploy pipeline

Stand up a Directus 11 instance with the minimum schema needed to register entries and tie them to devices, plus the schema-as-code pipeline (snapshots + db-init) and Gitea Actions CI. **This is what Rally Albania 2026 needs to run as a test event.**

## Outcome statement

When Phase 1 is done:

- Directus runs locally via `docker compose -f compose.dev.yaml up`, against a Postgres 16 + TimescaleDB + PostGIS container.
- `db-init/` contains three migrations applied at boot: TimescaleDB extension, `positions` hypertable creation, `faulty boolean` column on positions. All idempotent, all guarded by a `migrations_applied` table.
- `snapshots/schema.yaml` contains 12 collections: `organizations`, `users`, `organization_users`, `vehicles`, `organization_vehicles`, `devices`, `organization_devices`, `events`, `classes`, `entries`, `entry_crew`, `entry_devices`. Relations and required fields per [[directus-schema-draft]] (the org-level catalog and event-participation sections).
- The image entrypoint runs db-init, then `directus schema apply --yes`, then `directus start`. All three exit 0 against a fresh Postgres.
- Gitea Actions builds the image on push to `main` (when `snapshots/`, `db-init/`, `extensions/`, `Dockerfile`, or workflow file changes), runs the apply pipeline against a throwaway Postgres in CI, and pushes the image to `git.dev.microservices.al/trm/directus:main` only if the dry-run passes.
- "Motorsport Club Albania" exists as an organization, "Rally Albania 2026" exists as an event under it, and the Rally Albania class catalog is seeded (M-1..M-7, Q-1..Q-3, C-1/C-2/C-A/C-3, S-1/S-2/S-3 from `wiki/sources/rally-albania-regulations-2025.md` §2.2–§2.5). At least one test entry registered with vehicle + crew + devices, used to dogfood the registration workflow.

Phase 1 deliberately stops short of:
- Course definition (stages, segments, geofences, SLZs) — Phase 2.
- Penalty system tables and timing tables — Phase 3.
- Permission policies — Phase 4 (collections are admin-only by default).
- Custom extension code — Phase 5.

## Sequencing

```
1.1 Project scaffold
   └─→ 1.2 db-init runner script
          └─→ 1.3 Initial migrations
                 ├─→ 1.4 Org-level catalog collections (admin UI work)
                 │      └─→ 1.5 Event-participation collections (admin UI work)
                 │             └─→ 1.6 Schema snapshot/apply tooling
                 │                    └─→ 1.7 Image build & entrypoint
                 │                           └─→ 1.8 Gitea CI dry-run
                 │                                  └─→ 1.9 Rally Albania 2026 seed
```

Tasks 1.1 → 1.3 are pure infrastructure and can land before any Directus admin UI work begins. Tasks 1.4 + 1.5 happen against a locally running Directus instance. Tasks 1.6 → 1.8 wire the artifacts together. Task 1.9 is dogfood verification.

## Files modified

Phase 1 produces this layout in `directus/`:

```
directus/
├── .gitea/workflows/build.yml
├── snapshots/
│   └── schema.yaml             # generated; edits via admin UI + pnpm run schema:snapshot
├── db-init/
│   ├── 001_extensions.sql      # CREATE EXTENSION timescaledb (postgis added in Phase 2)
│   ├── 002_positions_hypertable.sql
│   └── 003_faulty_column.sql
├── extensions/                 # empty — Phase 5 fills this
├── scripts/
│   ├── apply-db-init.sh        # numeric-order, guard-table-protected runner
│   ├── schema-snapshot.sh      # wraps `directus schema snapshot --yes`
│   └── schema-apply.sh         # wraps `directus schema apply --yes`
├── entrypoint.sh               # apply-db-init.sh && directus schema apply && directus start
├── Dockerfile                  # FROM directus/directus:11.x + bundled artifacts
├── compose.dev.yaml            # local dev: directus + timescaledb container
├── package.json                # only for the snapshot/apply npm scripts and tooling
├── pnpm-lock.yaml
├── .env.example
├── .dockerignore
├── .gitignore
└── README.md
```

## Tech stack (decided)

- **Directus 11.x** (latest stable on the 11.x line at time of build). Pinned in `Dockerfile` `FROM` line.
- **Postgres 16 + TimescaleDB + PostGIS** as the database (PostGIS extension added in Phase 2; Phase 1 only uses TimescaleDB).
- **pnpm** for any local dev scripts (snapshot wrappers, lint).
- **bash** (POSIX-compatible) for `apply-db-init.sh` and `entrypoint.sh`. No Node dependency at runtime — only Directus needs Node, and that's the upstream image's responsibility.
- **psql** (from `postgresql-client` package) inside the image for db-init application.
- **Gitea Actions** for CI, matching the `processor` and `tcp-ingestion` workflow shape.

If an implementer wants to deviate, they must update the relevant task file first.

## Key design decisions inherited from `processor`

- **Image is bundled, not assembled at runtime.** `snapshots/`, `db-init/`, and `extensions/` are baked into the image, not mounted as volumes. Reproducible across envs.
- **Slim Dockerfile.** Multi-stage if extensions need a build step (Phase 5+); for Phase 1 a single stage is enough.
- **CI workflow** — single-job pattern matching `processor/.gitea/workflows/build.yml`. Use `services:` for the throwaway Postgres in the dry-run step.
- **No `.env` in image.** All env vars come from the deploy stack (Portainer / compose) at runtime.

## Open questions blocking task-level detail

None. The schema draft pinned the org-level catalog and event-participation shape; Phase 1 implements exactly that subset.