Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/danizd/GeoSentinel/llms.txt

Use this file to discover all available pages before exploring further.

GeoSentinel is a real-time geospatial intelligence platform that collects events from multiple open-data sources, normalizes them to a canonical model, clusters related events into unified incidents, and exposes everything through a clean REST API. Operators monitor the live picture through a React/Mapbox dashboard with 2D and 3D map layers.

Quickstart

Stand up the full stack — database, API, and frontend — in under 10 minutes.

Architecture

Understand the five-layer pipeline from raw ingestion to API delivery.

API Reference

Explore every endpoint: incidents, AOIs, corrections, military flights, and more.

Data Sources

See how GDELT, ACLED, FIRMS, USGS, OpenSky, and AISStream feed the platform.

​
What GeoSentinel Does

GeoSentinel solves the hardest part of real-time situational awareness: turning a noisy stream of heterogeneous reports into a clean, deduplicated, prioritised feed of incidents you can act on.

Multi-Source Ingestion

Polls GDELT, ACLED, FIRMS, and USGS on configurable schedules with automatic retry and exponential backoff.

Canonical Normalization

Every event is mapped to a common schema — UTC timestamps, WGS84 coordinates, severity 0–10, and typed categories.

Spatio-Temporal Clustering

DBSCAN groups nearby, concurrent events from different sources into single deduplicated incidents.

Incident Lifecycle

A full state machine tracks incidents from open through updated, stale, and closed, with human override support.

Areas of Interest

Define polygon AOIs with per-category severity thresholds. All spatial queries use PostGIS ST_Intersects.

Human-in-the-Loop

Operators can reclassify, relocate, merge, or mark incidents as false positives via the corrections API with a full audit trail.

​
Get Started in Four Steps

1

Start PostgreSQL + PostGIS

docker compose up -d
Waits for the pg_isready healthcheck before the backend can connect.
2

Run database migrations

cd backend && uv run alembic upgrade head
Creates all tables: events_canonical, incidents, aoi, corrections_audit, events_quarantine, sources_metadata.
3

Start the API and frontend

# Terminal 1 — API on :8000
cd backend && uv run uvicorn backend.api.main:app --reload --host 0.0.0.0 --port 8000

# Terminal 2 — Frontend on :5173
cd frontend && npm run dev
4

Seed test data and run your first ingestor

# Seed 3 sample incidents
curl http://localhost:8000/v1/seed

# Pull live earthquakes ≥ 4.0
cd backend && uv run python backend/scripts/run_usgs.py
Visit http://localhost:5173 to see incidents appear on the map.
You need API keys for GDELT Cloud, ACLED, FIRMS NASA, and Mapbox before real data will flow. See the Environment Variables reference for the full list.

Build docs developers (and LLMs) love

Get started for freeTalk to us