Initial public release

docs/MIGRATION_PLAN.md

@@ -0,0 +1,82 @@
+# Database Migration Plan
+
+## Migration tool
+
+Use Alembic for all schema migrations.
+
+## Migration principles
+
+- Every database schema change must be represented by an Alembic migration.
+- Geometry columns must use PostGIS types.
+- Migrations must be safe to rerun in development after database reset.
+- Never modify old migrations after they have been used as a release baseline.
+
+## Initial migration sequence
+
+### 0001_enable_postgis
+
+Creates the PostGIS extension.
+
+```sql
+CREATE EXTENSION IF NOT EXISTS postgis;
+```
+
+### 0002_core_tables
+
+Creates:
+
+- projects
+- areas
+- datasets
+- layers
+- analysis_runs
+- metrics
+- exports
+
+### 0003_geoai_tables
+
+Creates:
+
+- detections
+- segmentations
+- quality_checks
+- quality_check_items
+
+### 0004_jobs_and_events
+
+Creates:
+
+- jobs
+- domain_events
+
+## Geometry columns
+
+Use SRID 4326 for persisted canonical geometries unless a specific processing table requires another CRS.
+
+Recommended columns:
+
+```text
+areas.geometry: POLYGON/MULTIPOLYGON, SRID 4326
+detections.geometry: POLYGON, SRID 4326
+quality_check_items.geometry: GEOMETRY, SRID 4326
+```
+
+Area measurements must not be calculated directly in EPSG:4326. Use projected CRS transformations in services.
+
+## Indexes
+
+Every geometry column that is queried spatially needs a GIST index.
+
+Core indexes:
+
+- projects.created_at
+- areas.project_id
+- datasets.project_id
+- layers.dataset_id
+- analysis_runs.project_id
+- detections.analysis_run_id
+- quality_checks.analysis_run_id
+
+## Development reset
+
+Development reset may drop and recreate the database. Production-style migrations must still remain valid.