File size: 4,829 Bytes
4851501 |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 |
# 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
|