Pre-web changes

docs/VEHICLES-API.md

@@ -19,27 +19,30 @@ This document explains the end‑to‑end Vehicles API architecture after the pl
 
 Idempotent constraints/indexes added where applicable (e.g., unique lower(name), unique(model_id, year), guarded `CREATE INDEX IF NOT EXISTS`, guarded trigger).
 
-### API Endpoints (Bearer auth required)
-Prefix: `/api/platform`
-- `GET /api/platform/years` → `[number]` distinct years (desc)
-- `GET /api/platform/makes?year={year}` → `{ makes: { id, name }[] }`
-- `GET /api/platform/models?year={year}&make_id={make_id}` → `{ models: { id, name }[] }`
-- `GET /api/platform/trims?year={year}&make_id={make_id}&model_id={model_id}` → `{ trims: { id, name }[] }`
-- `GET /api/platform/engines?year={year}&make_id={make_id}&model_id={model_id}&trim_id={trim_id}` → `{ engines: { id, name }[] }`
+### Dropdown API (Bearer auth required)
+Prefix: `/api/vehicles/dropdown`
+- `GET /years` → `[number]` (latest to oldest model years)
+- `GET /makes?year={year}` → `{ id, name }[]` (makes available in that year)
+- `GET /models?year={year}&make_id={make}` → `{ id, name }[]` (models filtered by year + make)
+- `GET /trims?year={year}&make_id={make}&model_id={model}` → `{ id, name }[]` (trims for the selection)
+- `GET /engines?year={year}&make_id={make}&model_id={model}&trim_id={trim}` → `{ id, name }[]` (engines for the trim)
+- `GET /transmissions?year={year}&make_id={make}&model_id={model}` → `{ id, name }[]` (`Automatic`, `Manual`)
 
-Notes:
-- `make_id` is maintained for a consistent query chain, but engines are enforced by `(year, model_id, trim_id)`.
-- Trims/engines include `id` to enable the next hop in the UI.
+Selection order is enforced: each endpoint requires the IDs returned by the previous stage, so users never see invalid combinations (e.g., 2023 Chevrolet excludes the S-10, 1999 GMC trims exclude AT4X, etc.).
+
+### Platform module (internal bridge)
+Prefix: `/api/platform`
+- Same hierarchical endpoints as above, but responses are wrapped (`{ makes: [...] }`, `{ models: [...] }`) for service-to-service integrations.
+- VIN decode endpoint: `GET /api/platform/vehicle?vin={vin}`
 
 ### Authentication
-- Auth0 JWT via `Authorization: Bearer ${JWT_TOKEN}` (required for all platform endpoints)
+- Auth0 JWT via `Authorization: Bearer ${JWT_TOKEN}` (required for both `/api/vehicles/*` and `/api/platform/*`)
 - Configured in backend: `src/core/plugins/auth.plugin.ts` with JWKS validation
 
 ### Caching (Redis)
-- Keys: `dropdown:years`, `dropdown:makes:{year}`, `dropdown:models:{year}:{make}`, `dropdown:trims:{year}:{model}`, `dropdown:engines:{year}:{model}:{trim}`
-- Dropdown data TTL: 6 hours (21600 seconds)
-- VIN decode cache TTL: 7 days (604800 seconds)
-- Cache key format for VIN decodes: `vin:decode:{vin}`
+- Keys: `platform:years`, `platform:vehicle-data:makes:{year}`, `platform:vehicle-data:models:{year}:{make}`, `platform:vehicle-data:trims:{year}:{model}`, `platform:vehicle-data:engines:{year}:{model}:{trim}`
+- Dropdown TTL: 6 hours (`21600s`)
+- VIN decode TTL: 7 days (`604800s`) via `platform:vin-decode:{vin}`
 - Implementation: `backend/src/features/platform/domain/platform-cache.service.ts`
 
 ### Seeds & Specific Examples
@@ -56,22 +59,12 @@ Clear platform cache:
 ## MotoVaultPro Backend (Application Service)
 
 ### Proxy Dropdown Endpoints
-Prefix: `/api/vehicles/dropdown`
-- `GET /years` → `[number]` (calls platform `/years`)
-- `GET /makes?year=YYYY` → `{ id, name }[]`
-- `GET /models?year=YYYY&make_id=ID` → `{ id, name }[]`
-- `GET /trims?year=YYYY&make_id=ID&model_id=ID` → `{ id, name }[]`
-- `GET /engines?year=YYYY&make_id=ID&model_id=ID&trim_id=ID` → `{ id, name }[]`
+Vehicles service simply re-emits the data returned by `Platform VehicleDataService`, normalizing it to `{ id, name }[]` arrays for frontend consumption. Redis caching and Postgres lookups all remain centralized in the platform module.
 
-Changes:
-- Engines route now requires `trim_id`.
-- New `/years` route for UI bootstrap.
-
-### Platform Client & Integration
-- `PlatformVehiclesClient`:
-  - Added `getYears()`
-  - `getEngines(year, makeId, modelId, trimId)` to pass trim id
-- `PlatformIntegrationService` consumed by `VehiclesService` updated accordingly.
+### Platform Integration
+- `VehiclesService` lazily instantiates `VehicleDataService` via `getVehicleDataService()`, guaranteeing a shared cache.
+- Each dropdown call passes the shared Postgres pool (`getPool()`) and propagates selection context (year/make/model/trim).
+- Transmission dropdown is intentionally static (`Automatic`, `Manual`) until richer metadata is available.
 
 ### Authentication (App)
 - Auth0 JWT enforced via Fastify + JWKS. No mock users.
@@ -94,6 +87,7 @@ Changes:
 - APIs used:
   - `/api/vehicles/dropdown/years`
   - `/api/vehicles/dropdown/makes|models|trims|engines`
+  - `/api/vehicles/dropdown/transmissions`
 
 ## Add Vehicle Form – Change/Add/Modify/Delete Fields (Fast Track)
 
@@ -135,7 +129,7 @@ VIN/License rule
 - Backend (includes platform module): `docker compose up -d --build backend`
 
 ### Logs & Health
-- Backend: `/health` – shows status/feature list, including platform readiness
+- Backend: `https://motovaultpro.com/api/health` – shows status/feature list, including platform readiness
 - Logs: `make logs-backend`, `make logs-frontend`
 
 ### Common Reset Sequences