FormBD-Geo

Geospatial extension for FormBD - spatial indexing without compromising auditability.

Location-aware evidence tracking for investigative journalism.

Contents

• Overview
  • Use Cases
• Architecture
  • Key Principle: Projection, Not Storage
• Features
  • Spatial Query Types
  • Supported Geometry Types
  • Coordinate Systems
• API
  • Endpoints
  • Example Queries
  • Response Format
• Installation
  • Prerequisites
  • Build
  • Configuration
  • Run
• Technology Stack
• Non-Goals
• Project Structure
• Roadmap
  • v0.1.0: Core Indexing (MVP)
  • v0.2.0: Advanced Queries
  • v0.3.0: Performance
  • v0.4.0: Integration
• Related Projects
• License

Overview

FormBD-Geo adds geospatial capabilities to FormBD while preserving the core guarantees:

• Auditability preserved - Spatial operations are projections, source data remains in FormBD

• Reversibility maintained - Spatial index is derived, can be rebuilt from journal

• Provenance tracked - "Where did this location data come from?"

Use Cases

• Investigative journalism: Map evidence locations, track movement patterns

• Compliance: Geographic jurisdiction tracking, data sovereignty

• Cultural archives: Historical location mapping, site preservation

Architecture

┌─────────────────────────────────────────────────────────────┐
│  FormBD-Geo API                                              │
│  REST endpoints for spatial queries                          │
├─────────────────────────────────────────────────────────────┤
│  Spatial Index (R-tree)                                      │
│  Materialized projection of FormBD data                      │
│  Rebuilt on demand from FormBD journal                       │
├─────────────────────────────────────────────────────────────┤
│  FormBD HTTP API (reads)                                     │
│  All writes go through FormBD (provenance preserved)         │
└─────────────────────────────────────────────────────────────┘

Key Principle: Projection, Not Storage

FormBD-Geo does NOT store source data. It:

1. Reads documents from FormBD via HTTP API

2. Extracts location fields (lat/lon, GeoJSON, WKT)

3. Builds spatial index as materialized view

4. Serves spatial queries against the index

5. Returns FormBD document IDs for full provenance

FormBD Journal (source of truth)
    │
    ├── doc_123: { location: { lat: 51.5, lon: -0.1 }, ... }
    ├── doc_456: { location: { lat: 48.8, lon: 2.3 }, ... }
    │
    ▼
FormBD-Geo R-tree Index (derived)
    │
    ├── Point(51.5, -0.1) → doc_123
    ├── Point(48.8, 2.3) → doc_456
    │
    ▼
Spatial Query: "within 10km of London"
    │
    ▼
Result: [doc_123] (with full FormBD provenance)

Features

Spatial Query Types

• Point queries: Find documents at exact coordinates

• Bounding box: Documents within rectangular region

• Radius search: Documents within distance of point

• Polygon containment: Documents within arbitrary shape

• Nearest neighbor: K closest documents to point

Supported Geometry Types

• Point (lat/lon)

• LineString

• Polygon

• MultiPoint, MultiLineString, MultiPolygon

• GeometryCollection

Coordinate Systems

• WGS84 (EPSG:4326) - default

• Web Mercator (EPSG:3857)

• Custom CRS via PROJ

API

Endpoints

GET  /geo/within-bbox?minLat=...&minLon=...&maxLat=...&maxLon=...
GET  /geo/within-radius?lat=...&lon=...&radius=...&unit=km
GET  /geo/within-polygon?geojson=...
GET  /geo/nearest?lat=...&lon=...&k=10
POST /geo/reindex                    # Rebuild from FormBD
GET  /geo/health                     # Index status

Example Queries

# Find evidence within 50km of London
curl "http://localhost:8081/geo/within-radius?lat=51.5074&lon=-0.1278&radius=50&unit=km"

# Find evidence in bounding box (UK)
curl "http://localhost:8081/geo/within-bbox?minLat=49.9&minLon=-6.4&maxLat=55.8&maxLon=1.8"

# Find 10 nearest documents to a location
curl "http://localhost:8081/geo/nearest?lat=48.8566&lon=2.3522&k=10"

Response Format

{
  "query": {
    "type": "within-radius",
    "center": { "lat": 51.5074, "lon": -0.1278 },
    "radius_km": 50
  },
  "results": [
    {
      "formbd_id": "doc_123",
      "location": { "lat": 51.5, "lon": -0.1 },
      "distance_km": 0.82,
      "provenance_url": "http://formbd:8080/documents/doc_123"
    }
  ],
  "index_timestamp": "2026-01-16T12:00:00Z",
  "total_indexed": 15234
}

Installation

Prerequisites

• Rust 1.75+ (stable)

• FormBD running with HTTP API enabled

Build

git clone https://github.com/hyperpolymath/formbd-geo
cd formbd-geo
cargo build --release

Configuration

# formbd-geo.toml
[formbd]
api_url = "http://localhost:8080"
collection = "evidence"           # Collection to index
location_field = "location"       # Field containing coordinates

[server]
host = "127.0.0.1"
port = 8081

[index]
# Rebuild interval (0 = manual only)
auto_rebuild_minutes = 0
# Memory limit for R-tree
max_memory_mb = 512

Run

# Start the server
./target/release/formbd-geo --config formbd-geo.toml

# Build initial index
curl -X POST http://localhost:8081/geo/reindex

Technology Stack

Component	Technology	Rationale
Core	Rust	Performance, memory safety, no GC pauses
Spatial Index	rstar (R-tree)	Pure Rust, no C dependencies
HTTP Server	axum	Async, tower ecosystem
Geometry	geo crate	Rust-native geometry primitives
Serialization	serde + GeoJSON	Standard formats

Non-Goals

• Not a PostGIS replacement - Use PostGIS for heavy GIS workloads

• Not a tile server - Use Martin/pg_tileserv for map tiles

• Not storing source data - FormBD is the source of truth

• Not real-time tracking - Batch indexing from FormBD journal

Project Structure

formbd-geo/
├── src/
│   ├── main.rs              # Entry point
│   ├── lib.rs               # Library root
│   ├── index/
│   │   ├── mod.rs
│   │   ├── rtree.rs         # R-tree implementation
│   │   └── projection.rs    # FormBD → spatial projection
│   ├── api/
│   │   ├── mod.rs
│   │   ├── routes.rs        # HTTP endpoints
│   │   └── queries.rs       # Spatial query handlers
│   ├── formbd/
│   │   ├── mod.rs
│   │   └── client.rs        # FormBD HTTP client
│   └── config.rs            # Configuration
├── spec/
│   └── spatial-queries.adoc # Query specification
├── Cargo.toml
├── README.adoc
├── ECOSYSTEM.scm
├── STATE.scm
├── META.scm
└── LICENSE

Roadmap

v0.1.0: Core Indexing (MVP)

• ❏ R-tree spatial index

• ❏ FormBD HTTP client

• ❏ Bounding box queries

• ❏ Radius queries

• ❏ Manual reindex endpoint

v0.2.0: Advanced Queries

• ❏ Polygon containment

• ❏ Nearest neighbor (k-NN)

• ❏ LineString queries (route intersection)

v0.3.0: Performance

• ❏ Incremental index updates (watch FormBD journal)

• ❏ Index persistence (avoid full rebuild on restart)

• ❏ Query result caching

v0.4.0: Integration

• ❏ FormBD Studio integration (map view)

• ❏ GeoJSON export

• ❏ Bulk import from external GIS

Related Projects

• FormBD - The narrative-first database (source of truth)

• FormBD Studio - GUI (map visualization target)

• FormBD Analytics - OLAP analytics engine

• BoFIG - Evidence graph (potential consumer)

License

PMPL-1.0-or-later