Spatial.Properties is a pack-first geospatial platform. It combines a command-line toolkit for building and publishing versioned spatial data bundles with a web application for AI-powered spatial analysis. The system is designed around three principles: data is immutable and versioned, pipelines are deterministic, and every AI interaction is logged and auditable.
This page describes the major system components and how they connect. For visual walkthroughs of the two core data flows — building packs and querying data with AI — see Data Flow.
spatialpack CLI
Python CLI for building, validating, publishing, and querying Spatial Packs. The Pipeline engine processes YAML definitions into versioned pack artifacts containing GeoParquet, PMTiles, and Cloud Optimized GeoTIFF layers. Supports offline operation — the only network-dependent command is publish.
Web Application
React and TypeScript single-page application with Kepler.GL map visualization. The chat interface accepts natural-language spatial questions and renders answers directly on the map. Redux manages all map state, and the application preserves WebGL context across view switches for smooth interaction.
API Server
FastAPI backend handling authentication, AI gateway routing, credit management, and pack metadata. All database operations use async transactions against PostgreSQL. The credit system uses an append-only ledger — balances are computed from the sum of transactions, never stored as a mutable value.
AI Gateway
Unified interface to language models for both the CLI and web application. Supports multiple providers including Anthropic and OpenRouter. Every AI call is logged with token count, cost, latency, and session identifier. Model routing is configured in the database, not in environment variables, enabling runtime changes without redeployment.
Object Storage + CDN
Immutable versioned storage for published packs. Each version publishes to a unique path — no file is ever overwritten. A CDN distributes packs globally with long cache TTLs and HTTP range request support, enabling clients to fetch individual tiles or row groups without downloading entire files.
Database
PostgreSQL (via Supabase) for user accounts, organizations, credit ledger, AI call logs, and pack metadata. The credit system enforces NUMERIC(12,2) precision for all monetary values. Role-based access control supports owner, admin, and member roles per organization.
Spatial Packs standardize on cloud-native formats optimized for both analytics and visualization.
| Format | Purpose | Why it matters |
|---|---|---|
| GeoParquet | Columnar vector data storage | Query specific columns without reading entire files. 5—10x smaller than Shapefiles. |
| PMTiles | Single-file vector tile archive | Serve map tiles via HTTP range requests — no tile server required. |
| Cloud Optimized GeoTIFF | Raster data with internal tiling | Read specific regions of large rasters over the network. |
| spatialpack.json | Pack manifest | Source of truth for layers, provenance, license, and integrity hashes. |
For a detailed comparison of formats and when to use each, see Data Formats.
Immutability. Every Spatial Pack version publishes to a unique path. Consumers pin to a version and trust that the data behind it will not change. Updates produce new versions alongside existing ones.
Offline-first CLI. The spatialpack CLI works without a network connection. Building, validating, converting, and querying packs all happen locally. Publishing is the only command that requires connectivity.
Schema-driven validation. JSON Schema definitions enforce pack structure before publish. The CLI validates manifests against these schemas automatically, and CI pipelines can run the same checks to prevent malformed packs from reaching consumers.
Deterministic pipelines. Given the same Pipeline YAML and the same source data, the build produces identical output. No hidden timestamps, random seeds, or environment-dependent behavior. This makes pipelines suitable for CI/CD and reproducible research.
Auditable AI. Every AI call — whether from the web chat or the CLI — routes through a single gateway that logs tokens, cost, latency, and session context. Credit consumption is tracked per-call and per-organization with append-only ledger semantics.
