Files

T

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

4.7 KiB

Raw Blame History

Task 1.1 — Project scaffold

Phase: 1 — Slice 1 schema + deploy pipeline Status: ⬜ Not started Depends on: None Wiki refs: docs/wiki/entities/directus.md, docs/wiki/synthesis/directus-schema-draft.md

Goal

Initialize the directus/ service folder with the directory layout from the Phase 1 README, the config files needed for local Docker compose dev, and a minimal compose.dev.yaml that boots Directus + TimescaleDB so the next tasks have something to iterate against. No Directus collections are created in this task — that starts in 1.4.

Deliverables

directus/Dockerfile — FROM directus/directus:11.x, copies snapshots/, db-init/, scripts/, entrypoint.sh, extensions/ into the image. Sets ENTRYPOINT ["/directus/entrypoint.sh"]. (Concrete entrypoint contents land in task 1.7; for now create a placeholder that just execs the upstream entrypoint.)
directus/compose.dev.yaml — two services:
- db: timescale/timescaledb-ha:pg16-latest (or equivalent), volume-mapped Postgres data dir, healthcheck.
- directus: built from local Dockerfile, depends on db healthy, env vars for DB connection + KEY + SECRET + admin bootstrap, port 8055 exposed.
directus/package.json — minimal, only for npm scripts (no runtime deps). Scripts:
- schema:snapshot — bash scripts/schema-snapshot.sh (script body lands in 1.6)
- schema:apply — bash scripts/schema-apply.sh
- db:init — bash scripts/apply-db-init.sh
- dev — docker compose -f compose.dev.yaml up --build
- dev:down — docker compose -f compose.dev.yaml down
- dev:reset — docker compose -f compose.dev.yaml down -v && docker compose -f compose.dev.yaml up --build
directus/.env.example — full list of env vars with descriptions and defaults. Required: DB_HOST, DB_PORT, DB_DATABASE, DB_USER, DB_PASSWORD, KEY, SECRET, ADMIN_EMAIL, ADMIN_PASSWORD, PUBLIC_URL. Plus optional: LOG_LEVEL, LOG_STYLE, CACHE_ENABLED, CORS_ENABLED, CORS_ORIGIN, WEBSOCKETS_ENABLED.
directus/.gitignore — node_modules/, .env, .env.local, *.log, directus-data/ (the local Postgres volume mount, if used).
directus/.dockerignore — .git/, .planning/, node_modules/, .env*, *.md except README.md, compose.dev.yaml (compose isn't part of the image), directus-data/.
Empty placeholder directories with .gitkeep:
- snapshots/ (1.6 fills it)
- db-init/ (1.3 fills it)
- scripts/ (1.2, 1.6 fill it)
- extensions/ (Phase 5)
directus/entrypoint.sh — placeholder that simply exec /directus/cli.js start (or whatever the upstream image's start command is). Real wrapper lands in 1.7.
directus/README.md already exists from this scaffold pass — verify it's accurate.

Specification

Postgres image choice. Pin to a TimescaleDB image that includes PostgreSQL 16. PostGIS will be installed via db-init/ in Phase 2; the base image must support CREATE EXTENSION postgis (most TimescaleDB-HA images do). Document the pinned tag in compose.dev.yaml.
Volume policy in compose.dev.yaml. Use a named volume (directus-pg-data) so dev:down preserves data and dev:reset wipes it.
No secrets committed. .env is gitignored. .env.example carries placeholder values only.
No bind mounts of snapshots/ or db-init/ in compose.dev.yaml. The image bakes them in. (Implementer can override with a bind mount during local iteration but the committed file does not.)
Entrypoint is a placeholder in this task. Real flow (db-init → schema apply → start) lands in 1.7. Keep the placeholder simple to unblock 1.4 testing.

Acceptance criteria

pnpm install succeeds (no runtime deps; lockfile generated).
docker compose -f compose.dev.yaml up --build boots Directus successfully against a fresh TimescaleDB container.
http://localhost:8055 serves the Directus admin login.
First-time bootstrap with ADMIN_EMAIL / ADMIN_PASSWORD from .env works.
pnpm dev:down stops the stack, preserves the volume.
pnpm dev:reset wipes the volume and reboots clean.
No collection definitions exist yet — the Directus instance is empty by design.

Risks / open questions

TimescaleDB-HA image PostGIS support. Verify the chosen tag includes postgis extension binaries (or document the alternative — e.g. switching to postgis/postgis:16-master with manual TimescaleDB install). Capture the answer in this task's Done section.
Directus 11.x patch version. Pin a specific tag (e.g. 11.5.1) rather than 11.x for reproducible builds. Update the pin via PR when bumping.

Done

(Fill in commit SHA + one-line note when this lands.)

4.7 KiB Raw Blame History