# FablePool: Open Kite Map 🪁

**An open-source web app that answers one question: "Where and when can I fly my kite today?"**

Open Kite Map combines an interactive map of community-curated kite-flying spots with live wind and weather data, and distills it into a single, kite-type-aware **Flyability Score**. Think "Google Maps, but for kites" — built entirely on open data and open infrastructure, with no paid-API lock-in.

## Project status

**Milestone 1 — Product Design Doc & Technical Architecture** (this repository state).

This milestone delivers the complete design package that all subsequent build milestones implement against:

| Document | Contents |
|---|---|
| [`docs/01-personas.md`](docs/01-personas.md) | Product vision, target users, three detailed personas with jobs-to-be-done |
| [`docs/02-feature-spec.md`](docs/02-feature-spec.md) | Full feature specification with priorities, acceptance criteria, and release phasing |
| [`docs/03-wireframes.md`](docs/03-wireframes.md) | Described wireframes: map view, spot detail, forecast panel, mobile layouts |
| [`docs/04-data-sources.md`](docs/04-data-sources.md) | Evaluation and selection of map tiles, geodata, and weather/wind providers |
| [`docs/05-flyability-scoring.md`](docs/05-flyability-scoring.md) | The Flyability Score rubric: wind bands per kite type, gust ratio, precipitation, obstacles |
| [`docs/06-database-schema.md`](docs/06-database-schema.md) + [`db/schema.sql`](db/schema.sql) | PostgreSQL + PostGIS schema with rationale |
| [`docs/07-api-contract.md`](docs/07-api-contract.md) + [`api/openapi.yaml`](api/openapi.yaml) | REST API contract (OpenAPI 3.0) |
| [`docs/08-architecture.md`](docs/08-architecture.md) | Technical architecture: components, caching, deployment topology |
| [`CHARTER.md`](CHARTER.md) | Open-source project charter, governance, license rationale |
| [`CONTRIBUTING.md`](CONTRIBUTING.md) | Contribution guidelines |
| [`LICENSE`](LICENSE) | AGPL-3.0 (code); spot data under ODbL — see charter for rationale |

## The one-paragraph pitch

A kite flyer opens the app and sees a map of nearby flying spots, each badged with a color-coded score (0–100) for *their* kite type — single-line, stunt/sport, power/traction, or kiteboarding. Tapping a spot shows current wind speed, direction, and gusts; a 7-day forecast highlighting flyable windows; spot metadata (terrain, obstacles, hazards, legal notes) maintained by the community; and recent condition reports from other flyers. Everything runs on OpenStreetMap, MapLibre, and Open-Meteo/NOAA — free, open, and self-hostable.

## Selected stack (decided in this milestone)

- **Map tiles & geodata:** OpenStreetMap via raster/vector tiles, rendered with **MapLibre GL JS** (Leaflet as documented fallback)
- **Weather/wind:** **Open-Meteo** (primary, global) with **NOAA NWS API** (secondary, US precision) behind a provider abstraction
- **Backend:** Rust (Axum) REST API — chosen for cheap self-hosting; see architecture doc
- **Database:** PostgreSQL 15+ with PostGIS
- **Frontend:** TypeScript + React + MapLibre GL JS
- **License:** AGPL-3.0-or-later (code), ODbL (community spot database)

## Generating a lockfile

This milestone is documentation-only; no buildable code is included yet. When implementation milestones begin, lockfiles (`Cargo.lock`, `package-lock.json`) must be generated by the first maintainer build — never hand-written.