From 9e4ccab080229e62468c845cc2be025f0f9e507a Mon Sep 17 00:00:00 2001
From: zv <zv@zvcloud.net>
Date: Tue, 23 Jun 2026 19:21:12 +0200
Subject: [PATCH] docs: add project readme

---
 README.md | 96 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 96 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b08f190
--- /dev/null
+++ b/README.md
@@ -0,0 +1,96 @@
+# MapSift
+
+Explore OpenStreetMap data without writing queries.
+
+MapSift is an interactive OpenStreetMap data explorer powered by the Overpass API. It lets users choose what they want to find on a map, refine the search with tags, add nearby conditions, and inspect the generated Overpass QL when needed.
+
+## Features
+
+- Interactive Leaflet map as the main workspace.
+- Large categorized preset catalog for OSM tags.
+- Search by the current map viewport or a named area.
+- Optional refinement filters for selected presets.
+- Custom tag search for advanced OSM exploration.
+- Nearby search conditions, such as benches near shops.
+- Generated Overpass QL preview.
+- Copy query and open it in Overpass Turbo.
+- Results shown as map markers and a linked result list.
+- List result selection centers the matching marker on the map.
+
+## Tech Stack
+
+- Vite
+- React
+- TypeScript
+- Leaflet and React Leaflet
+- Vitest
+- Plain CSS
+
+MapSift is a frontend-only SPA. It does not include a backend, database, authentication, user accounts, or saved projects.
+
+## Project Structure
+
+```text
+src/
+  app/
+    App.tsx
+  features/
+    map/
+      MapView.tsx
+    results/
+      ResultsList.tsx
+    search/
+      buildOverpassQuery.ts
+      overpassClient.ts
+      parseOverpassResponse.ts
+      presets.ts
+      types.ts
+  shared/
+    types.ts
+```
+
+## Overpass Architecture
+
+Overpass-specific logic is intentionally kept outside React components:
+
+- `buildOverpassQuery(state)` generates Overpass QL from a typed search state.
+- `fetchOverpass(query)` sends the request to the Overpass API.
+- `parseOverpassResponse(response)` converts Overpass elements into map/list results.
+
+React components handle user interaction and display, not manual query string assembly.
+
+## Getting Started
+
+Install dependencies:
+
+```bash
+npm install
+```
+
+Start the development server:
+
+```bash
+npm run dev
+```
+
+Run tests:
+
+```bash
+npm test
+```
+
+Build for production:
+
+```bash
+npm run build
+```
+
+Preview the production build:
+
+```bash
+npm run preview
+```
+
+## Notes
+
+MapSift uses the public Overpass API. Large viewport searches are blocked in the UI to avoid irresponsible requests. If a query returns too much data or the API is busy, zoom in, reduce filters, or try again later.