# Phase 2 — Course definition

**Status:** ⬜ Not started — depends on Phase 1
**Outcome:** A complete data layer for defining the spatial and procedural shape of an event: stages, segments (typed: liaison / special-stage / parc-ferme), geofences (PostGIS polygons), waypoints, and speed_limit_zones. Operators can populate the full course before each stage from the roadbook. No processor logic yet — Phase 2 of [[processor]] consumes this data and writes crossings/penalties.

## Why this is a separate phase

- **Phase 1 ships a usable system.** Live tracking + entry registration is enough for the Rally Albania 2026 dogfood. Course definition adds operator workload but no live functionality until [[processor]] Phase 2 ships.
- **PostGIS introduction.** Phase 2 is where `CREATE EXTENSION postgis` lands in `db-init/`. Geometry columns require it; no other Phase 1 work does.
- **Scope creep risk.** Course definition has surprising depth (geofence editing UX, polygon validation, segment ordering UX). Isolating it as its own phase prevents Phase 1 from ballooning.

## Tasks (sketched, not detailed)

These tasks will get full task files when Phase 2 starts. For now, this is the planned shape:

| # | Task | Notes |
|---|------|-------|
| 2.1 | PostGIS extension migration | `db-init/004_postgis.sql` adds the extension. Idempotent. |
| 2.2 | `stages` collection | Per [[directus-schema-draft]]: `event_id`, `name`, `sort_order`, `role`, `starts_at`, `start_interval_seconds`, `start_order_strategy`, `start_order_strategy_params`, `start_order_input_stage_id`. |
| 2.3 | `segments` collection | `stage_id`, `sort_order`, `type` (liaison/special-stage/parc-ferme), `entry_geofence_id`, `exit_geofence_id`, `target_duration_seconds`. |
| 2.4 | `geofences` collection | PostGIS polygon column. `event_id`, `name`, `kind`, `geometry`, `manual_verification`, `retroactive`. |
| 2.5 | `waypoints` collection | PostGIS point. `segment_id`, `location`, `tolerance_meters`, `sort_order`. |
| 2.6 | `speed_limit_zones` collection | PostGIS polygon. `segment_id`, `geometry`, `max_speed_kmh`, `evaluation_window_meters`, `retroactive`. |
| 2.7 | Geometry editor evaluation | Directus's built-in map interface vs. a custom extension panel. Decide based on usability for operators authoring real geofences from a roadbook. |
| 2.8 | Snapshot regeneration + CI verification | All new collections in the snapshot; CI dry-run still passes. |

## Open questions blocking task-level detail

(These get answered when Phase 2 starts.)

1. Is Directus's built-in map interface adequate for authoring geofence polygons, or does Phase 2 need a custom extension with a richer editor (drawing tools, vertex snapping, polygon validation)?
2. How are roadbook coordinates (typically WGS84 lat/lon) imported — bulk upload, copy-paste, manual click-to-place?
3. Are checkpoint geofences a separate `kind` value or is `manual_verification = true` enough to identify them?
4. Should `start_order_strategy_params` be a JSON field (flexible) or a dedicated table (queryable)? JSON is the schema-draft default; revisit if querying is needed.