🚲 BikeTrack Project Wiki & Knowledge Base

Welcome to the BikeTrack technical wiki. This workspace serves as a centralized, high-signal, Obsidian-style repository of knowledge mapping the entire system architecture, features, database structure, and visual use cases of the bicycle route planner app.

---

🗺️ Portal Navigation

1. 🏗️ Architecture & Core Design

• WIKI Home — You are here!
• Database Schema Guide — Relational structure of PostGIS tables, columns, constraints, and indices.
• API Contract Reference — High-fidelity backend REST routes (Hono) and Drizzle integrations.
• Architect's Ledger — System tenets, folder structure, coding conventions, and critical regressions checklist.
• Ultimate Navigator Specifications — Deep philosophical and technical background on bicycle navigation systems.

2. 🧩 Core Product Features

The current supported application capabilities are categorized into focused functional modules:

• Features Index — Unified features roadmap.
• Feature 01: Route Planning — Waypoints, routing profiles, telemetry calculation via BRouter.
• Feature 02: Garage & Component Wear — Virtual components, dual wear models, service checklists.
• Feature 03: Track Library & Archiving — Cloud storage, soft deletes, favorite collections, library dashboard.
• Feature 04: Cue Sheets — Turn-by-turn directions, maneuver indexing, GPX extensions.
• Feature 05: Points of Interest (POI) — Emoji map markers, right-click placements, distance and visibility controls.
• Feature 06: Undo & Redo States — Stack-based state history, drag atomicity protection.

3. 📚 Visual Use Cases & Scenarios

Over 35 edge scenarios mapping real-world rider requirements are fully specified and cataloged:

• Visual Use Cases Map — Interactive grouping.
• Core Planning Use Cases (e.g. Out & Back, Route Auto-healing, Offgrid planning).
• Advanced Utilities (e.g. Smart Coordinate Thinning, Route Cropping for Anti-Doxing).

4. 🔎 Active UX/UI Audits

• Main Map Canonical Audit — July 2026 — Reconciled findings, raw evidence, release blockers, phased remediation plan, and the mandatory retest matrix for the full-screen planning map.

5. 🔐 Operations & Third-Party Compliance

• Strava API 2026 Compliance — Canonical product rules, access tiers, privacy, AI prohibition, data lifecycle, readiness blockers, release gate, and coding-agent guardrails.
• Strava Review Submission Runbook — Public URLs, form-answer template, screenshot package, and production verification checklist.

---

🛠️ The Tech Stack

Layer	Technologies Used	Key Responsibilities
Frontend Map	MapLibre GL JS	Core canvas rendering, vector styles, terrain overlay, interactive markers.
Frontend Framework	React 18 + Vite 6 + Zustand	Dynamic single-page client, modular components, reactive telemetry store.
Backend Framework	Hono API + Node Server	Ultra-fast endpoint serving, route crop computations, Strava synchronizer.
Database	PostgreSQL + PostGIS	Geographic coordinate projection, geometry lines, fast spatial lookups.
Object-Relational	Drizzle ORM	Schema definition, SQL migrations, nested transactions for route updates.
Auth	Firebase Admin + Client SDK	Secure token check, email/Google SSO authentication.
Routing	BRouter Public Engine	Point-to-point path calculation with custom bike profiles.

---

📦 Directory Map & Monorepo Layout

bike-maps/
├── apps/
│   ├── api/                      # Hono backend with Drizzle ORM
│   │   ├── src/
│   │   │   ├── app.ts            # Hono application setup
│   │   │   ├── db/               # PostgreSQL & Drizzle schemas and connections
│   │   │   ├── routes/           # REST endpoints grouped by resource
│   │   │   └── services/         # External integrations (Strava, Firebase)
│   └── web/                      # React frontend following Feature-Sliced Design (FSD)
│       ├── src/
│       │   ├── app/              # Setup, providers, router
│       │   ├── entities/         # Zustand Stores (route, user, components)
│       │   ├── features/         # Complex user interactions (build-route, crop-route)
│       │   ├── widgets/          # Major layout pieces (MapCanvas, PlannerSidebar)
│       │   └── shared/           # Common components, styles, utility hook libraries
├── packages/
│   ├── shared/                   # Common core dependencies
│   │   └── src/
│   │       └── geo/              # Geo-math formulas (RDP, Haversine, GPX parsing)
│   └── test-utils/               # Standardized fixtures and unit test helpers
└── docs/                         # Extensive technical markdown wiki

---

🧭 Core Tenets for Developers

1. Strict Spatial Standard: Coordinates must always be stored and handled in strict GeoJSON format: [longitude, latitude] (LNG first, LAT second).
2. Immutable Geometry Updates: When performing path manipulation (crop, split, simplification), execute updates within database transactions to ensure route telemetry (distance, elevation_gain) remains strictly in sync with coordinate geometry arrays.
3. Fail-Safe Routing: The application must remain functional even when BRouter is slow. Implement a 10s request timeout, with automatic cancellation/abort of stale queries on map click.
4. No Direct DOM Mutation: Let React handle marker instances and render layers through declarative Zustand stores. Map coordinates are synchronized in real-time without expensive full map canvas refreshes.