From 4e55b52a862ba77b4afcd8034b232d078578c817 Mon Sep 17 00:00:00 2001
From: Vladimir Zagainov <mrixs@mrixs.ru>
Date: Tue, 18 Aug 2026 12:59:48 +0300
Subject: [PATCH] fix: update CLAUDE.md with missing documentation for new API
 endpoints and architectural features

---
 CLAUDE.md | 42 +++++++++++++++++++++++++++++++++++++++---
 1 file changed, 39 insertions(+), 3 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 425b4d5..a153f19 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -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