Document spatial infrastructure setup and RLS policies

epic-geographic-peer-mentor-map-data-infrastructure-task-014 — Write developer documentation covering: how to run the PostGIS migrations locally, how the bounding-box RPC works and its parameters, the RLS policy structure and how to test it, the LocationPrivacyConfig fields and how to configure per organisation, and the MapProviderIntegration abstraction layer usage guide including how to swap providers. Place documentation in the project wiki or a docs/ folder.

medium priority low complexity documentation pending documentor Tier 7

Acceptance Criteria

Documentation includes a step-by-step guide for running PostGIS migrations locally using supabase start and supabase db push

Documentation describes the bounding-box RPC function name, all input parameters (min_lng, min_lat, max_lng, max_lat), return schema, and a working example curl/SQL call

Documentation explains the RLS policy structure for mentor_location: which policies exist, what auth context they check, and how organisation isolation is enforced

Documentation includes a section on how to test RLS locally with two test users from different organisations, including exact SQL commands

Documentation describes all fields in LocationPrivacyConfig, their data types, default values, and what each controls (consent expiry, precision level, retention days)

Documentation includes a usage guide for MapProviderIntegration showing how to consume it via Riverpod, how to register a new provider implementation, and a code snippet example

Documentation is placed in docs/spatial-infrastructure.md (or equivalent) and linked from the main README or project wiki index

Documentation is reviewed for accuracy against the implemented code before merge — no placeholder TODOs remain

Technical Requirements

frameworks

Flutter

Supabase CLI

PostGIS

apis

Supabase RPC

Supabase Auth

security requirements

Documentation must not include real API keys, service role keys, or production credentials — use placeholder values only

Documentation must explicitly warn that service role key bypasses RLS and must never be used in the mobile client

Execution Context

Execution Tier

Tier 7

Tier 7 - 84 tasks

Can start after Tier 6 completes

View Full Execution Plan

Implementation Notes

Structure the document with these sections: Prerequisites, Local Setup, Database Schema & Migrations, Bounding-Box RPC Reference, RLS Policy Reference & Testing, LocationPrivacyConfig Reference, MapProviderIntegration Usage Guide, Swapping Map Providers, Troubleshooting. Use fenced code blocks for all SQL and Dart examples. For the RLS testing section, provide exact psql commands using set role and set request.jwt.claims. Keep the document under 600 lines — link to source files for full implementation detail rather than duplicating code.

Ensure GDPR notes are included in the LocationPrivacyConfig section (location data = personal data under Norwegian GDPR implementation, precision reduction to municipality level is a privacy requirement).

Testing Requirements

Documentation review only — no automated tests. Peer review checklist: (1) a developer unfamiliar with the spatial system can follow the local setup guide and successfully run the PostGIS migration; (2) all code snippets are syntactically valid Dart/SQL; (3) RLS test instructions produce the expected access-denied result when tested; (4) all LocationPrivacyConfig fields match the implemented class. Optionally, add a CI step that validates code snippets using dart analyze on extracted Dart blocks.

Component

Mentor Location Repository

data high

Dependencies (3)

Write unit tests for LocationPrivacyConfig covering: loading config from Supabase, default fallback values when org config is absent, consent expiry date calculation, and retention policy enforcement logic. Use flutter_test and mock the Supabase client with Mockito. Verify that each organisation receives isolated config and that missing fields fall back to safe defaults. epic-geographic-peer-mentor-map-data-infrastructure-task-012 Write widget and unit tests for MapProviderIntegration verifying: map widget renders without error with zero markers, onBoundsChanged callback fires after pan/zoom, getBoundsFromController returns a valid LatLngBounds, and the abstraction boundary holds (no flutter_map types leak into callers). Use flutter_test with pumpWidget and MapController. epic-geographic-peer-mentor-map-data-infrastructure-task-013 Integrate the PostgisSpatialAdapter into MentorLocationRepository.findMentorsInBounds() replacing any stub implementations. Write integration tests against a local Supabase instance (supabase start) that seed mentor_location rows, call findMentorsInBounds with known bounding boxes, and assert correct results are returned and cross-org rows are excluded by RLS. epic-geographic-peer-mentor-map-data-infrastructure-task-011

Epic Risks (3)

high impact medium prob integration

Supabase's hosted PostGIS extension behaviour may differ from the local emulator for spatial RPC functions, causing bounding-box queries to return incorrect results or fail in production while passing locally.

Mitigation & Contingency

Mitigation: Write integration tests against the Supabase emulator from the start and run the same test suite against a staging Supabase project before merging. Use ST_DWithin and ST_MakeEnvelope in plain SQL first, validate with psql, then wrap as RPC.

Contingency: If PostGIS RPC proves unreliable, fall back to client-side bounding box filtering on a full fetch of consented mentor locations (acceptable for up to ~200 mentors per chapter) until the spatial query is stabilised.

medium impact low prob dependency

OpenStreetMap tile usage may require attribution handling and rate limiting. Switching to Google Maps Flutter plugin mid-implementation would require significant rework of the map-provider-integration abstraction.

Mitigation & Contingency

Mitigation: Define the map-provider-integration abstraction interface before selecting the SDK so that the concrete implementation is swappable. Implement OSM first with correct attribution. Document Google Maps as the alternate with its API key setup steps.

Contingency: If OSM tiles are rejected by stakeholders or tile server limits are hit, activate the Google Maps Flutter plugin implementation behind the same interface without touching any UI or service code.

high impact low prob security

Incorrect RLS configuration could allow a coordinator to query mentor locations from a different organisation, constituting a GDPR data breach.

Mitigation & Contingency

Mitigation: Write dedicated RLS integration tests with two isolated test organisations and assert that cross-organisation queries return zero rows. Include these tests in CI. Have a second developer review all RLS policy SQL before migration is applied.

Contingency: If a cross-organisation data leak is discovered post-deployment, immediately disable the map feature via the organisation feature flag, revoke the affected Supabase RLS policy, and notify the data protection officer per the organisation's GDPR incident response procedure.

Quick Links

All Tasks Execution Plan