Stsezhka

Appearance

📜 The Architect's Ledger: BikeTrack Project Reference ​

This document serves as a high-signal reference for the current architecture, critical use cases, and regression testing checklist. Use this to ensure every commit maintains the project's high standards.

🏗 Core Architecture (FSD + Clean Arch) ​

  • Frontend (apps/web): Follows Feature-Sliced Design (FSD).
    • Entities: route, poi, user, track (Domain data and basic state).
    • Features: build-route (User scenarios, interaction between entities and API).
    • Widgets: map-canvas, planner-sidebar, elevation-chart, auth (Complex standalone UI blocks).
    • Shared: Common API clients, types, geo-logic, firebase-lib.
  • Backend (apps/api): Powered by Encore.dev.
    • Dependency Inversion: Use factories (makeCalculateRouteHandler) to inject providers.
    • Adapters: External APIs (BRouter) are isolated behind interfaces (IRoutingProvider).
    • Services: poi, track (Encore services with PostgreSQL/PostGIS).
  • Shared Package (packages/shared): Single source of truth for:
    • Types: Coord, BikeProfile, Poi, Route.
    • Validation: Zod schemas for external/internal boundaries.
    • Logic: haversineKm, pathDistanceKm, gpx-utils, calculateElevationStats.
    • Config: SURFACE_COLORS, BROUTER_PROFILE_MAP.

🚲 Critical Use Cases (Regression Checklist) ​

1. Routing & Planning ​

  • [ ] Map Interaction: Clicking the map adds waypoints and displays a blue marker.
  • [ ] Calculation: >= 2 waypoints triggers a POST to /routing/calculate.
  • [ ] Surface Coloring: The route line must be colored according to the surface property (Green=Asphalt, Amber=Gravel, Red=Dirt).
  • [ ] Resilience: If the routing server is slow, the 10s timeout triggers a RoutingError. New clicks during calculation must abort the previous request.

2. Point of Interest (POI) ​

  • [ ] Creation: Right-click (context menu) on the map opens the "Add POI" popup.
  • [ ] Persistence: Saving a POI adds it to the poiStore and renders an emoji on the map.
  • [ ] Filtering: Changing filters in the sidebar/state correctly hides/shows POIs via selectVisiblePois.

3. Map-Chart Synchronization ​

  • [ ] Hover Sync: Hovering over the ElevationChart must show a highlighted marker on the MapCanvas at the exact geographic location.
  • [ ] Surface breakdown: The ElevationChart must display a color-coded bar matching SURFACE_COLORS defined in shared config.

4. Performance & Stability ​

  • [ ] Marker Diffing: Adding a waypoint should NOT remove and re-add all existing markers (check MapCanvas.tsx reconciliation logic).
  • [ ] Stale Closures: Map event handlers must use store.getState() to access the latest waypoints/profile without re-mounting the map.
  • [ ] Types: No any types on boundaries; all API responses must pass through Zod validation.

5. Data Export & Persistence ​

  • [ ] GPX Generation: Exported GPX must contain both the track segments and all user-created POIs as wpt nodes.
  • [ ] Save Track: Users can save their planned route and POIs to the backend database (requires Auth).

🧪 Testing Strategy ​

  • Unit: Test all logic in packages/shared.
  • Integration: Test Zustand stores, complex hooks (useBuildRoute), and widgets.
  • Visual/UI: Use Playwright for layout stability and end-to-end "Happy Path" verification.
  • Boundary: Always test the BRouterPublicAdapter with mock 500/timeout responses.

Last Updated: April 2026 by Senior Architect Agent