Natural-Language Geospatial Query Platform

Architecture

1. Question

   plain English, via web app or SDK
2. LLM

   schema-aware SQL generation
3. Validation

   allow-listed schemas · constrained query
4. PostGIS

   spatial execution
5. Answer

   text · chart · map · analytics

The query engine

The engine is a FastAPI service over PostgreSQL/PostGIS holding public datasets at federal, state and city level: campaign finance, census demographics, business registries and licences, permits, crime, taxes. The hard part of text-to-SQL over data like this is not the model; it is giving the model a schema it can reason about. I designed the data layer: how jurisdictions at different levels relate, how geometries are exposed and simplified, which columns carry meaning, and how all of it is described so the generated SQL is right on the first attempt more often than not. Fuzzy matching on names uses trigram similarity in the database, so misspelled places and candidates still resolve.

A question becomes a SQL candidate, is validated and constrained (schemas are allow-listed per conversation, internal schemas can never be queried), executed, and summarised back into language. The LLM backend is pluggable: one implementation on OpenAI models through LangChain, another on Google's agent framework with Gemini, both behind the same REST contract with conversation history, so comparing providers was configuration rather than a rewrite. An analytics mode adds a bounded agent loop over freshly fetched data with per-query timeouts, retry caps and an end-to-end deadline, producing percentages, rankings, charts and maps.

The product around it

A query engine is not a product. I also led the platform that turns it into one: an Express and PostgreSQL/PostGIS API with a controllers/services/repositories layout, a React web app for chat and conversation management, TypeScript and Python SDKs for programmatic access, organisations and teams, API keys, usage tracking and rate limiting, a webhook system for event notifications, subscription billing through Stripe, and a documentation site.

Infrastructure

Everything runs as Docker Compose stacks behind Traefik, with separate development, beta and production environments, automated image updates, a metrics and BI layer, and Sentinel watching the whole thing. Secrets are scoped per service and loaded from a single environment file so configuration stays readable as the stack grows. Calls that carry customer data to external model endpoints resolve their targets fail-closed: production refuses to run without an explicit endpoint and never falls back to a public one.