| # GeoQuery Documentation Index | |
| Welcome to the GeoQuery technical documentation. | |
| --- | |
| ## 🚀 Getting Started | |
| New to GeoQuery? Start here: | |
| 1. **[README.md](../README.md)** - Project overview and quick start | |
| 2. **[SETUP.md](../SETUP.md)** - Development environment setup | |
| 3. **[ARCHITECTURE.md](../ARCHITECTURE.md)** - System architecture and design | |
| --- | |
| ## 📚 Available Documentation | |
| ### System Overview | |
| - **[ARCHITECTURE.md](../ARCHITECTURE.md)** - High-level system design, components, and data flow | |
| - **[DATA_FLOW.md](DATA_FLOW.md)** - End-to-end request processing walkthrough | |
| - **[SETUP.md](../SETUP.md)** - Local development setup and troubleshooting | |
| ### Backend | |
| - **[Core Services](backend/CORE_SERVICES.md)** - LLMGateway, GeoEngine, DataCatalog, QueryExecutor, and all backend services | |
| - **[API Endpoints](backend/API_ENDPOINTS.md)** - REST API reference with SSE streaming | |
| - **[LLM Integration](backend/LLM_INTEGRATION.md)** - Prompt engineering and Gemini API integration | |
| - **[Data Ingestion Scripts](backend/SCRIPTS.md)** - Scripts for downloading and processing datasets | |
| ### Frontend | |
| - **[Component Architecture](frontend/COMPONENTS.md)** - React components (ChatPanel, MapViewer, DataExplorer) | |
| ### Data | |
| - **[Dataset Sources](data/DATASET_SOURCES.md)** - 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](backend/SCRIPTS.md) for detailed guide | |
| ### "I want to understand how queries work" | |
| 1. Read [DATA_FLOW.md](DATA_FLOW.md) - Step-by-step walkthrough from user query to map rendering | |
| 2. Read [backend/CORE_SERVICES.md](backend/CORE_SERVICES.md) - Service interactions and methods | |
| 3. Read [backend/LLM_INTEGRATION.md](backend/LLM_INTEGRATION.md) - Prompt system and LLM calls | |
| ### "I want to modify the frontend" | |
| 1. Read [frontend/COMPONENTS.md](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](backend/API_ENDPOINTS.md) for backend integration | |
| ### "I want to extend the LLM capabilities" | |
| 1. Read [backend/LLM_INTEGRATION.md](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](../LICENSE)** for details. | |
| --- | |
| **Last Updated**: 2026-01-10 | |