freemap-v3-react AGENTS.md

Project notes for AI agents

(This file is also exposed as CLAUDE.md via a symlink so Claude Code loads it.)

Reference docs

Deeper format/architecture references live in doc/. Consult them before designing changes in the same area:

• Architecture & code-layout reference — the feature-folder convention, the Redux store wiring (rootReducer.ts / processors.ts), the processor middleware that owns all side effects, state persistence + rehydration, URL-hash sync, the global vs. per-feature i18n split, path aliases, and the layer/tool registries. Read this before adding a feature, a side effect, persisted state, or a new menu/tool/modal — it saves re-reading the tree.
• Drawing feature export/import format mapping — GPX/GeoJSON write+read for drawing points/lines/polygons, the fm:* lossless-shadow design, and the curated Garmin/OsmAnd icon dictionaries. Read this before changing anything in src/features/export/ or in the drawing-conversion processors.
• Track data: import, elevation, colorize, export — the shared elevation-acquisition layer (src/shared/elevation.ts: fetchElevations/enrichElevations/densifyAlong), the shared colorizers (src/shared/colorizers/, isAvailable-gated per feature), the render-only densified geometry that's never exported, the per-consumer elevation policy (route auto-fill vs. track prompt vs. tracking keep-recorded), and KML/KMZ/TCX import + lossless GeoJSON↔GPX transfer. Read this before touching elevation, colorize, the elevation chart, or track-file import/export across routePlanner/dataViewer/tracking/mapFeaturesExport.
• GPS recorder integration — how the PWA drives the standalone Android recorder APK over its 127.0.0.1 HTTP API: the Android-only availability gate, the loopback/Local-Network-Access connection rules, the wire contract (protocol.ts is the single place to change it), the start-via-intent:// flow, how the three failure causes are told apart, and the /track?since= + SSE catch-up. Read this before touching src/features/gpsRecorder/ or anything that talks to the recorder.
• Panorama viewer — the 360° terrain view: why the terrain service is addressed directly (it takes the bearer token and clamps quality itself), why a render is only ever started by an explicit act and must abort the one in flight, the two-pass preview, the split between the store and renderHolder, the repeating-background pan, the label layout, and how a second label source plugs in via the distance buffer. Read this before touching src/features/panorama/.
• Viewshed overlay — the v layer over the terrain service's POST /viewshed: why it is a layer with a toolbar rather than a tool, the radius/scale pair the service validates together, what its alpha means, the render key that decides when Update appears, and the shared render queue. Read this before touching src/features/viewshed/.
• Weather radar layer — the animated R overlay over the two-feed cache.bigware.sk API: why every request must set its own referrerPolicy (the upstream authenticates by Referer, and the app is served no-referrer), the wire contract and per-feed zoom bands, the premium bands on the timeline and why locked frames stay on the track, the transient/persisted slice split, the polling processor's deliberate exceptions, and the per-frame tile-layer pool with its cross-fade and pan-drop rules. Read this before touching src/features/weatherRadar/ or the radar layer's tile source.
• WebMCP agent tools — the tools src/features/webMcp/ registers on document.modelContext so a browser AI agent can drive the running app through the store: the API shape and its traps (it is document, not navigator; secure context; the tools permissions policy), the lazy registration from index.tsx, defineTool's zod → JSON Schema wrapping, and waitForState for the two tools that must await a processor's answer. Read this before adding or changing an agent tool.
• SEO bot-prerender architecture — how crawlers get static HTML snapshots while humans get the SPA: the sitemap-generator/ (homepages, layer/tool hub pages, per-feature POI pages), the nginx /__prerender routing, and the rspack index-<lang> variants. Read this before changing sitemap-generator/, the sitemap/robots wiring, or the bot routing in the nginx vhost.
• Self-hosted Photon geocoder — the search backend on fm5 that replaces nominatim.openstreetmap.org: why the prebuilt photon-db-* tarballs are unusable (four languages only) and we import the JSONL dump ourselves, the -languages set and why widening it costs a re-import, the install layout, the systemd unit and nginx vhost (rate limit, 24 h cache, gzip_types), and the import/re-import runbook. Read this before touching the geocoder host, re-importing a dump, or pointing search at Photon.
• Build & deploy gotchas — the DEPLOYMENT env var (not --mode) selects the prod build, native CSS nesting must be downleveled via LightningCSS, and the nginx cache-header rules (entry HTML no-store, only hashed assets immutable). Read this before changing rspack.config.ts, the CSS pipeline, or the nginx vhosts.
• UI conventions — what each react-bootstrap button variant means by role (dark = dismiss/close, primary = main CTA, secondary = default neutral action, danger = destructive, outline-primary = toggle, warning = upsell). Read this before picking a variant for a new <Button>.
• Feature-announcement log — what has shipped and is worth posting about (with the commits that carry it), and what has already gone out on Facebook / Mastodon. Update the backlog when a user-visible feature lands, and move a topic to Posted once it goes out. Market-intro posts live in the roadmap's Outreach log instead.
• Foreign-growth promotion roadmap — data-driven plan (from Matomo country/language/referrer cuts) for growing usage and premium conversions outside Slovakia: which markets to target (Italy, Poland, Hungary, Austria, …), which UI languages to add next (Slovenian, then French), and the phased outreach steps. Read this before working on foreign promotion, deciding the next UI localization, or interpreting the audience analytics.