PostGIS Spatial Query Adapter
Component Detail
Description
Utility layer that converts Flutter LatLngBounds and coordinate objects into PostGIS-compatible SQL spatial queries executed via Supabase RPC functions. Handles serialization of geography point types and parsing of Supabase spatial response formats.
postgis-spatial-adapter
Summaries
The PostGIS Spatial Query Adapter eliminates a critical translation gap between the mobile app's mapping interface and the organization's geospatial database infrastructure. By standardizing how geographic coordinates are converted into database queries, this component ensures that location-based features — such as finding nearby resources or defining service areas — work reliably and accurately across all user interactions. Without this layer, each developer would implement ad-hoc translations prone to inconsistency and data errors, increasing support costs and degrading the quality of location-sensitive features that users depend on. It directly protects data integrity and reduces the risk of costly spatial query bugs reaching production.
This is a medium-complexity utility component with no external dependencies, making it relatively low-risk to schedule. It must be delivered before any feature that performs spatial queries via Supabase RPC, so it sits on the critical path for all location-based functionality. Testing requires access to a PostGIS-enabled Supabase instance with sample geography data, which should be provisioned early to avoid blocking integration testing. The four defined interfaces are stable contracts — changes to Supabase RPC signatures or PostGIS response formats will require updates here, so the team should monitor Supabase changelog for breaking changes.
Allocate time for edge-case testing around coordinate boundary conditions and WKT parsing errors.
This utility class handles bidirectional serialization between Flutter's google_maps_flutter LatLng/LatLngBounds types and PostGIS geography/geometry SQL representations. `boundsToEnvelopeParams` maps a LatLngBounds to the four double parameters expected by ST_MakeEnvelope (minX, minY, maxX, maxY, SRID). `coordToGeographyPoint` produces a GEOGRAPHY(Point,4326) literal string. `parseGeographyPoint` parses WKT like `POINT(lng lat)` back to LatLng — note PostGIS returns longitude first.
`buildSpatialRpcCall` wraps the assembled params into a Supabase `rpc()` call returning a PostgrestFilterBuilder for chaining. No state is held; all methods are pure functions or static helpers. Watch for coordinate order inversion bugs (PostGIS is x/y = lng/lat) and handle null geography responses from RPC gracefully.
Responsibilities
- Convert LatLngBounds to PostGIS ST_MakeEnvelope parameters
- Serialize coordinate pairs to PostGIS geography points
- Parse PostGIS geography response into Dart model objects
- Wrap spatial queries as Supabase RPC calls
Interfaces
boundsToEnvelopeParams(LatLngBounds bounds) → Map<String, double>
coordToGeographyPoint(double lat, double lng) → String
parseGeographyPoint(String wkt) → LatLng
buildSpatialRpcCall(String functionName, Map<String, dynamic> params) → PostgrestFilterBuilder
Used Integrations (1)
External integrations and APIs this component relies on