System Architecture & Core Concepts
Disha is a geospatial-first, AI-native desktop IDE structured specifically for urban and regional planners. It unifies an interactive MapLibre GL spatial map canvas with a multi-domain AI reasoning engine running locally on your machine.
Electron main (apps/desktop/src/main/index.ts)
├─ spawns FastAPI backend on :8765 (PyInstaller-frozen in prod, uvicorn in dev)
└─ creates BrowserWindow → loads renderer (React)
Renderer (apps/desktop/src/renderer/) talks to:
├─ Backend over WebSocket ws://localhost:8765/api/chat/ws (streaming chat + tool calls)
├─ Backend over HTTP /api/files /api/artifacts /api/reports
└─ Electron IPC (file dialogs, read directory, switch model)
Backend (packages/backend/) talks to:
└─ OpenAI HTTPS (key from OPENAI_API_KEY env)
+ Overpass, Nominatim, OSRM, Open-Meteo, GEE, WorldPop (free/keyless + Google)
The Three Communication Channels
Communication between the React renderer and the local system is partitioned across three distinct channels to prevent blocking the UI thread:
| Channel | Protocol & Endpoint | Responsibility |
|---|---|---|
| WebSocket | ws://localhost:8765/api/chat/ws | Streaming token generation, agent tool calls, live layer additions, fly-to map viewport movements, and cancelation tokens. |
| HTTP REST | http://localhost:8765/api/... | Workspace file listing, CRUD operations on artifacts, PDF/Markdown report generation, and raster tile proxies. |
| Electron IPC | preload / contextBridge | Native OS operations: file picker dialogs, reading directory trees, persistent window state, and model provider configuration. |
Geospatial Conventions
- Coordinates Everywhere EPSG:4326: All geometries exchanged across WebSocket, HTTP, and tools are strictly in WGS84 Lat/Lng. No planar distortion or reprojection artifacts occur.
- Ellipsoidal Geodesic Math: All area and perimeter calculations use pyproj.Geod(ellps="WGS84") rather than planar Euclidean math, maintaining survey-grade precision at all latitudes.
- Free Raster XYZ Basemaps: Built-in support for OpenStreetMap, CartoDB Positron/Dark Matter, Esri World Imagery, and OpenTopoMap without API keys or token requirements.
- Turf.js Client Operations: Instant client-side bbox union, point-in-polygon verification, and coordinate formatting on the MapLibre canvas.
Installation & Getting Started
Disha is distributed both as pre-built native desktop binaries for macOS and Windows, and as an open-source development monorepo.
Option A: Native Desktop Installers
Download the latest release from the official GitHub Releases hub:
- macOS (Apple Silicon & Intel): Download Disha-v0.3.0-arm64.dmg or x64.dmg. Drag Disha to your Applications folder.
- Windows 10 / 11: Download Disha-Setup-v0.3.0.exe or the portable .zip archive. Extract all contents before running.
Option B: Building from Source
For developers contributing to the AI hubs, frontend tools, or map engine:
# 1. Clone repository git clone https://github.com/geoailabs/disha.git cd disha # 2. Install Node dependencies pnpm install # 3. Setup Python virtual environment cd packages/backend python3 -m venv .buildenv source .buildenv/bin/activate pip install -r requirements.txt cd ../.. # 4. Set OpenAI API key and launch export OPENAI_API_KEY='your-key-here' pnpm dev
Workspace Selection
Upon initial launch, select any local folder on your workstation as your project workspace. Disha creates an isolated .disha/ folder inside it to persist project settings, custom layers, chat history, and generated analysis artifacts without locking your data to a remote cloud server.
The 7+1 Domain Hubs & Tool Reference
Tools in Disha are architected into 7 Domain Hubs plus 1 Cross-Cutting Utility Hub. Each hub inherits from BaseDomainHub and returns a typed ToolResult payload containing LLM data, optional map actions, and persistent markdown artifacts.
Core vector algorithms, geodetic geometry calculations, administrative boundary queries, and centralized polygon registry management.
| Tool | Parameters | Description |
|---|---|---|
| gis_buffer | layer_id, distance_m, resolution | Computes an ellipsoidal buffer polygon around points, lines, or polygons on WGS84 ellipsoid. |
| gis_clip | target_layer, mask_layer | Clips target vector geometries against boundary mask polygons. |
| gis_intersection | layer_a, layer_b | Calculates geometric intersection and merges feature properties. |
| gis_dissolve | layer_id, by_attribute | Merges adjacent polygons sharing attribute values into unified features. |
| calculate_land_budget | boundary_layer, zoning_layer | Computes total area, parcel counts, and percentage distribution across land-use types. |
| osm_boundary | place_name, admin_level | Fetches authoritative administrative boundaries from OpenStreetMap Overpass with fallback. |
Street network topological analysis, routing, Origin-Destination (OD) matrix traffic flow assignment, and GTFS transit stop queries.
| Tool | Parameters | Description |
|---|---|---|
| compute_route | origin, destination, profile | Calculates driving, walking, or freight route with turn-by-turn geometry and duration via OSRM. |
| analyze_street_network | bbox, metric | Computes intersection density, circuity, betweenness centrality, and street connectivity metrics. |
| assign_traffic_flows | od_matrix, road_network | Simulates multi-link traffic distribution to identify road network congestion bottlenecks. |
| query_gtfs_transit | corridor, agency_id | Extracts transit routes, headways, stop frequency, and corridor coverage buffers. |
Satellite remote sensing, Google Earth Engine LULC/NDVI analysis, live air quality indexes, weather forecasts, and solar radiation potential.
| Tool | Parameters | Description |
|---|---|---|
| query_gee_satellite | bbox, product, year | Fetches Sentinel-2 or Landsat surface reflectance composites from Google Earth Engine. |
| compute_ndvi_lulc | boundary, start_date, end_date | Measures Normalized Difference Vegetation Index (NDVI) and land cover changes over time. |
| get_air_quality | lat, lng | Retrieves real-time PM2.5, PM10, NO2, and AQI readings via Open-Meteo European Air Quality API. |
| calculate_solar_potential | building_layer, dsm_source | Computes rooftop solar irradiance and annual renewable energy yield estimates. |
Zoning parcel classification, compliance audits, masterplan PDF vision georeferencing, and raster digitization.
| Tool | Parameters | Description |
|---|---|---|
| classify_zoning | parcel_layer, standard | Normalizes localized zoning designations into standard land use categories (FAR, setback, use). |
| audit_zoning_compliance | parcels, building_footprints | Audits Floor Area Ratio (FAR) and building footprint coverage limits against municipal guidelines. |
| georeference_document | image_path, ground_control_points | Computes polynomial coordinate transformation to project static masterplan scans onto map coordinates. |
WorldPop 100m population density queries, cohort-component forecasts, and employment density estimates.
| Tool | Parameters | Description |
|---|---|---|
| query_worldpop_density | boundary_geom, year | Aggregates gridded population counts from WorldPop 100m resolution rasters within study boundaries. |
| forecast_demographic_cohort | base_population, horizon_years, fertility_rate | Projects age-sex cohort population distributions forward across 5, 10, or 20-year horizons. |
Overture Maps DuckDB spatial queries for 3D buildings, Google Places search, and POI classification.
| Tool | Parameters | Description |
|---|---|---|
| query_overture_buildings_duckdb | bbox, min_height | Executes serverless DuckDB queries directly against Overture S3 Parquet partitions for 3D building polygons. |
| search_places | query, location_bias | Retrieves verified amenities, businesses, and public facilities with operating metadata. |
Multi-Criteria Decision Analysis (MCDA), alternative zoning scenario generation, and trade-off comparison.
| Tool | Parameters | Description |
|---|---|---|
| generate_scenario | type, corridor, target_density | Creates zoning alternative layouts (TOD, Compact Infill, Green Buffer) with modified parcel attributes. |
| score_scenario_mcda | scenario_id, weights | Scores scenarios across walkability, transit access, green space ratio, and infrastructure load metrics. |
Geocoding, internet knowledge verification, distance measurement, and persistent markdown report storage.
| Tool | Parameters | Description |
|---|---|---|
| geocode_address | query | Resolves civic addresses or place names to WGS84 coordinates and bounding box extents via Nominatim. |
| save_artifact | title, content, artifact_type | Persists formatted Markdown summaries, demographic profiles, and reports into workspace artifacts. |
AI Prompt Engineering Handbook
Disha's agent is trained to interpret natural conversational requests and translate them into multi-step geodetic operations. Below are production prompt patterns:
"Buffer the designated flood hazard polygon by 500 meters and clip all intersecting local road segments. Calculate the affected road length in kilometers."
"Query Overture Maps S3 Parquet via DuckDB for all building footprints in this viewport with height > 20 meters. Color them with a graduated cyan ramp."
"Generate 3 TOD alternative scenarios around the proposed metro transit nodes. Upzone parcels within 800 meters to Mixed-Use High Density and score transit accessibility."
"Fetch WorldPop 100m density for this municipality boundary and run a 10-year demographic cohort projection assuming a 1.2% annual growth rate."
Centralized Spatial & Polygon Registry
A core challenge in autonomous GIS agents is avoiding redundant polygons, duplicate map layers, and overlapping geometries. Disha resolves this through its Centralized Spatial Registry (packages/backend/tools/spatial_registry.py).
IoU Deduplication (≥ 90%)
Whenever a boundary query or polygon tool runs, Disha evaluates the Intersection-over-Union (IoU) ratio against all active layers. If overlap exceeds 90%, it reuses and focuses the existing layer rather than spawning a duplicate.
Geodesic Metric Calculations
Every registered feature automatically computes and caches true geodesic surface area (m2, hectares, km2), true centroid coordinates, and bounding boxes via WGS84 pyproj Geod.
Real-Time WebSocket Layer Sync
The spatial registry continuously reconciles map context with the active frontend layers on every conversational turn, ensuring the agent always knows exactly what is visible on the canvas.
Data Connectors & Live Cloud Engines
Disha integrates directly with cloud-native spatial data sources without requiring local PostGIS database installations or commercial subscriptions.
SELECT id, names.primary AS name, ST_AsGeoJSON(geometry) AS geojson
FROM read_parquet('s3://overturemaps-us-west-2/release/2024-08-20.0/theme=places/type=place/*')
WHERE bbox.xmin >= -122.45 AND bbox.xmax <= -122.38
AND bbox.ymin >= 37.74 AND bbox.ymax <= 37.80
LIMIT 100;
| Engine / Provider | Access Method | Authentication | Data Provided |
|---|---|---|---|
| OpenStreetMap Overpass | Overpass QL / JSON | Free · Keyless | Buildings, roads, amenities, waterways, land use polygons. |
| Overture Maps | DuckDB S3 GeoParquet | Free · Keyless | Global building footprints with height attributes and place categories. |
| Google Earth Engine | REST API / Earth Engine SDK | Service Account JSON | Sentinel-2, Landsat, Dynamic World LULC, surface temperature. |
| WorldPop | Direct GeoTIFF Ingestion | Free · Open Access | High-resolution 100m gridded population density estimates. |
| Open-Meteo | REST API | Free · Keyless | Hourly weather forecasts, temperature, precipitation, and AQI readings. |