# 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