docs/INDEX.md

GeoQuery Documentation Index

Welcome to the GeoQuery technical documentation.

---

🚀 Getting Started

New to GeoQuery? Start here:

1. README.md - Project overview and quick start
2. SETUP.md - Development environment setup
3. ARCHITECTURE.md - System architecture and design

---

📚 Available Documentation

System Overview

• ARCHITECTURE.md - High-level system design, components, and data flow
• DATA_FLOW.md - End-to-end request processing walkthrough
• SETUP.md - Local development setup and troubleshooting

Backend

• Core Services - LLMGateway, GeoEngine, DataCatalog, QueryExecutor, and all backend services
• API Endpoints - REST API reference with SSE streaming
• LLM Integration - Prompt engineering and Gemini API integration
• Data Ingestion Scripts - Scripts for downloading and processing datasets

Frontend

• Component Architecture - React components (ChatPanel, MapViewer, DataExplorer)

Data

• Dataset Sources - Complete dataset catalog with sources and licenses

---

🎯 Common Tasks

"I want to add a new dataset"

1. Download or create GeoJSON file
2. Place in backend/data/ subdirectory
3. Add entry to backend/data/catalog.json
4. Regenerate embeddings: rm backend/data/embeddings.npy && python -c "from backend.core.semantic_search import get_semantic_search; get_semantic_search()"
5. See backend/SCRIPTS.md for detailed guide

"I want to understand how queries work"

1. Read DATA_FLOW.md - Step-by-step walkthrough from user query to map rendering
2. Read backend/CORE_SERVICES.md - Service interactions and methods
3. Read backend/LLM_INTEGRATION.md - Prompt system and LLM calls

"I want to modify the frontend"

1. Read frontend/COMPONENTS.md - Component structure and state management
2. Check component files in frontend/src/components/ for implementation details
3. See backend/API_ENDPOINTS.md for backend integration

"I want to extend the LLM capabilities"

1. Read backend/LLM_INTEGRATION.md - Prompt engineering guide
2. Edit prompts in backend/core/prompts.py
3. Add new methods to backend/core/llm_gateway.py if needed

---

📋 Quick Reference

File Structure

GeoQuery/
├── README.md                    # Project overview
├── ARCHITECTURE.md              # System design
├── SETUP.md                     # Dev setup
├── docs/
│   ├── INDEX.md                 # This file
│   ├── DATA_FLOW.md            # Request pipeline
│   ├── backend/                 # Backend docs
│   │   ├── CORE_SERVICES.md
│   │   ├── API_ENDPOINTS.md
│   │   ├── LLM_INTEGRATION.md
│   │   └── SCRIPTS.md
│   ├── frontend/                # Frontend docs
│   │   └── COMPONENTS.md
│   └── data/                    # Data docs
│       └── DATASET_SOURCES.md
├── backend/                     # Python backend
│   ├── api/                     # FastAPI endpoints
│   ├── core/                    # Core services
│   ├── services/                # Business logic
│   ├── data/                    # GeoJSON datasets + catalog.json
│   └── scripts/                 # Data ingestion
└── frontend/                    # Next.js frontend
    └── src/
        ├── app/                 # Next.js pages
        └── components/          # React components

Key Concepts

• Intent Detection: Classifying user queries (MAP_REQUEST, SPATIAL_OP, etc.)
• Semantic Search: Finding relevant datasets via vector embeddings
• Text-to-SQL: Generating DuckDB queries from natural language
• Lazy Loading: Loading GeoJSON tables on-demand
• SSE Streaming: Real-time response streaming to frontend
• Choropleth: Auto-generated color gradients for polygons
• Point Styles: Icon markers (🏥) vs circle points (⭕)

External Links

• DuckDB Spatial: https://duckdb.org/docs/extensions/spatial
• Gemini API: https://ai.google.dev/
• Leaflet Docs: https://leafletjs.com/reference.html
• Next.js Docs: https://nextjs.org/docs
• FastAPI Docs: https://fastapi.tiangolo.com/

---

📄 License

This project is licensed under the MIT License - see LICENSE for details.

---

Last Updated: 2026-01-10