144 lines
4.5 KiB
Markdown
144 lines
4.5 KiB
Markdown
# 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
|
||
```bash
|
||
go run ./cmd/api
|
||
```
|
||
|
||
### Running Cron Jobs
|
||
```bash
|
||
go run ./cmd/cron
|
||
```
|
||
|
||
### Running Tests
|
||
```bash
|
||
# 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)*
|
||
```bash
|
||
# Apply migrations
|
||
goose up
|
||
|
||
# Rollback migration
|
||
goose down
|
||
|
||
# Check migration status
|
||
goose status
|
||
```
|
||
|
||
### Code Formatting
|
||
```bash
|
||
# 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 |