Mrixs/trip-planner
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: update CLAUDE.md with missing documentation for new API endpoints and architectural features

Browse Source
This commit is contained in:
Vladimir Zagainov
2026-08-18 12:59:48 +03:00
parent 8aecaf1468
commit 4e55b52a86
1 changed files with 39 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

42
CLAUDE.md
View File

@@ -22,11 +22,12 @@ This is a multimodal trip planning service that uses Yandex.Schedules API to pro
/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
/cache — Interface + Redis implementation (cache-aside), user preferences
/storage — PostgreSQL repositories, transfer rules, station neighbors
/routing — Graph, search algorithm, MCT rules, search cache, route status
/airports — Neighboring stations, closure detection
/geo — GeoJSON assembly for maps
/metrics — Observability metrics (cache hits/misses, API quota, circuit breaker, search duration)
```
## Common Development Commands
@@ -83,6 +84,12 @@ go vet ./...
- `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)
- `GET /v1/preferences/saved-cities?user_id=` — Get user's saved cities
- `POST /v1/preferences/saved-cities?user_id=` — Add a city to user's saved cities
- `DELETE /v1/preferences/saved-cities/{city_code}?user_id=` — Remove a city from user's saved cities
- `GET /v1/preferences/search-history?user_id=` — Get user's search history
- `POST /v1/preferences/search-history?user_id=` — Add a search to user's history
- `GET /metrics` — Get observability metrics (cache hit rates, API quota, circuit breaker trips, search duration)
## Key Architectural Features
@@ -120,6 +127,35 @@ Multi-layer TTL approach:
- Transfer points: Markers with popup info (connection time, type)
- Frontend: Leaflet + OSM tiles (no vendor lock-in)
### 6. User Preferences Cache
- Saved cities and search history stored per user in Redis
- 7-day TTL for preference data
- Accessed via `/v1/preferences/` endpoints
### 7. Observability Metrics
- Cache hit/miss counts per layer (cache, search, cache_aside)
- API quota remaining tracking
- Circuit breaker trip counts
- Search count and duration histogram (avg in milliseconds)
- Available via `GET /metrics` endpoint
### 8. Search Cache Service
- Cache-aside pattern for Yandex `/search` API calls
- Near-term dates: 3-hour TTL
- Far-term dates: 7-day TTL
- Reduces API quota consumption through aggressive caching
### 9. Transfer Rules / MCT System
- Minimum Connection Time rules stored in `transfer_rules` table
- Rule keys include: `airport_internal`, `airport_internal_through`, `airport_internal_separate`, `station_internal`, `airport_to_city`
- Base MCT is 30 minutes (1800 seconds)
- Rule keys with suffixes (e.g., `_through`, `_separate`) match base keys
### 10. Route Change Notifications
- `CheckAndRescheduleRoute` checks for significant route changes
- Detects cancellations (edge duration > 1 day) or major delays (duration > 2x normal)
- Re-searches route when changes detected, returns updated itinerary
## Development Guidelines
### Error Handling