trip-planner/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

This is a multimodal trip planning service that uses Yandex.Schedules API to provide routing across different transport modes (planes, trains, buses). The service implements lazy graph expansion to work within API quota constraints and provides route visualization on maps.

Technology Stack

• Backend: Go
• Database: PostgreSQL (with PostGIS optional for geometry)
• Cache/Queue: Redis (native TTL)
• Frontend Map: Leaflet + OpenStreetMap tiles
• Task Scheduler: cron (internal cmd/cron or system cron)

Project Structure

/cmd
  /api        — HTTP server
  /cron       — Reference data updates, station status detection
/internal
  /yandex     — Yandex API client, rate limiter, retries, circuit breaker
  /cache      — Interface + Redis implementation (cache-aside)
  /storage    — PostgreSQL repositories
  /routing    — Graph, search algorithm, MCT rules
  /airports   — Neighboring stations, closure detection
  /geo        — GeoJSON assembly for maps

Common Development Commands

Running the API Server

go run ./cmd/api

Running Cron Jobs

go run ./cmd/cron

Running Tests

# Run all tests
go test ./...

# Run tests for a specific package
go test ./internal/routing

# Run tests with coverage
go test ./... -cover

Database Migrations

(Assuming standard Go migration tools)

# Apply migrations
goose up

# Rollback migration
goose down

# Check migration status
goose status

Code Formatting

# Format Go code
go fmt ./...

# Check for formatting issues
go vet ./...

API Endpoints (from specification)

• GET /v1/cities?query= — City autocomplete
• GET /v1/cities/{id}/stations — City stations (including neighbors if main closed)
• POST /v1/routes/search — Search for routes (Pareto-optimal results)
• GET /v1/routes/{search_id}/{route_id}/geojson — Get route geometry for map
• GET /v1/stations/{id}/status — Station status
• POST /internal/admin/stations/{id}/status — Manual station status override (requires auth)

Key Architectural Features

1. Lazy Graph Expansion

Due to Yandex.Schedules API limitations (no full timetable dump), the service uses:

• Hub stations (major transport nodes) as anchor points
• BFS/Dijkstra with depth limiting (4-5 transfers max)
• On-demand /search requests only for relevant station pairs
• Aggressive caching to minimize API calls

2. Caching Strategy

Multi-layer TTL approach:

• City/station directory: 30 days (Postgres + Redis hot cache)
• /nearest_stations: 30 days (static coordinates)
• /search: 2-6 hours (near-term), 7 days (far-term dates)
• /schedule (for closure detection): 1 day
• /thread: Not cached or 1-5 min TTL (real-time status)

3. Multimodal Routing

• Graph edges: Real (actual scheduled trips) and Synthetic (city<74><79>↔airport transfers)
• Transport type stored as attribute for display/filtering
• Transfer rules based on node type, city tier, and check-in type
• Pareto-front ranking (time, transfers, cost) rather than single "optimal" route

4. Station Closure Detection

• Daily cron job checks /schedule for each monitored station
• N consecutive days of zero trips triggers closure status (N=3 recommended)
• Automatic fallback to neighboring stations when closed
• Immediate reactivation when trips resume

5. Map Visualization

• Routes served as pre-built GeoJSON FeatureCollections
• Real segments: Solid lines (color by transport type)
• Synthetic segments: Dashed lines
• Transfer points: Markers with popup info (connection time, type)
• Frontend: Leaflet + OSM tiles (no vendor lock-in)

Development Guidelines

Error Handling

• Use circuit breaker pattern in /internal/yandex for API protection
• Degrade gracefully to stale cache when API unavailable
• Always provide clear error messages to users

Testing

• Unit test routing logic with synthetic timetable fixtures
• Mock external API calls in tests
• Test cache-aside patterns thoroughly
• Validate MCT (Minimum Connection Time) calculations

Performance

• Target: <3-5s for cached routes, <15s for cold cache with multiple segments
• Monitor: Cache hit rates, API quota consumption, circuit breaker trips
• Provide progress indicators for long-running searches

Security

• Validate all inputs (especially for admin endpoints)
• Protect admin endpoints with proper authentication
• Never store API keys or secrets in code/repository