Docs Cleanup

docs/VEHICLES-API.md

@@ -3,10 +3,10 @@
 This document explains the end‑to‑end Vehicles API architecture after the platform service rebuild, how the MotoVaultPro app consumes it, how migrations/seeding work, and how to operate the stack in production‑only development.
 
 ## Overview
-- Architecture: MotoVaultPro Application Service (Fastify + TS) consumes the MVP Platform service (FastAPI) with shared Postgres and Redis.
+- Architecture: MotoVaultPro backend (Fastify + TypeScript) includes an integrated platform module that shares Postgres and Redis with the rest of the stack.
 - Goal: Predictable year→make→model→trim→engine cascades, production‑only workflow, AI‑friendly code layout and docs.
 
-## Platform Vehicles Service
+## Platform Vehicles Module
 
 ### Database Schema (Postgres schema: `vehicles`)
 - `make(id, name)`
@@ -20,12 +20,12 @@ 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/v1/vehicles`
-- `GET /years` → `[number]` distinct years (desc)
-- `GET /makes?year={year}` → `{ makes: { id, name }[] }`
-- `GET /models?year={year}&make_id={make_id}` → `{ models: { id, name }[] }`
-- `GET /trims?year={year}&make_id={make_id}&model_id={model_id}` → `{ trims: { id, name }[] }`
-- `GET /engines?year={year}&make_id={make_id}&model_id={model_id}&trim_id={trim_id}` → `{ engines: { id, name }[] }`
+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 }[] }`
 
 Notes:
 - `make_id` is maintained for a consistent query chain, but engines are enforced by `(year, model_id, trim_id)`.
@@ -41,14 +41,13 @@ Notes:
 - **Configurable**: Set via `CACHE_TTL` environment variable in seconds
 
 ### Seeds & Specific Examples
-Seed files under `mvp-platform-services/vehicles/sql/schema/`:
-- `001_schema.sql` – base tables
-- `002_constraints_indexes.sql` – constraints/indexes
-- `003_seed_minimal.sql` – minimal Honda/Toyota scaffolding
-- `004_seed_filtered_makes.sql` – Chevrolet/GMC examples
-- `005_seed_specific_vehicles.sql` – requested examples:
-  - 2023 GMC Sierra 1500 AT4x → Engine L87 (6.2L V8)
-  - 2017 Chevrolet Corvette Z06 Convertible → Engine LT4 (6.2L V8 SC)
+Legacy FastAPI SQL seed scripts covered:
+- Base schema (`001_schema.sql`)
+- Constraints/indexes (`002_constraints_indexes.sql`)
+- Minimal Honda/Toyota scaffolding (`003_seed_minimal.sql`)
+- Chevrolet/GMC examples (`004_seed_filtered_makes.sql`)
+- Targeted sample vehicles (`005_seed_specific_vehicles.sql`)
+Contact the data team for access to these archival scripts if reseeding is required.
 
 Reapply seeds on an existing volume:
 - `docker compose exec -T mvp-postgres psql -U mvp_user -d mvp_db -f /docker-entrypoint-initdb.d/005_seed_specific_vehicles.sql`
@@ -133,22 +132,18 @@ VIN/License rule
 
 ### Rebuild a single service
 - Frontend: `docker compose up -d --build frontend`
-- Backend: `docker compose up -d --build backend`
-- Platform API: `docker compose up -d --build mvp-platform`
+- Backend (includes platform module): `docker compose up -d --build backend`
 
 ### Logs & Health
-- Backend: `/health` – shows status/feature list
-- Platform: `/health` – shows database/cache status
-- Logs:
-  - `make logs-backend`, `make logs-frontend`
-  - `docker compose logs -f mvp-platform`
+- Backend: `/health` – shows status/feature list, including platform readiness
+- Logs: `make logs-backend`, `make logs-frontend`
 
 ### Common Reset Sequences
 - Platform seed reapply (non‑destructive): apply `005_seed_specific_vehicles.sql` and flush Redis cache.
 - Platform reset (WARNING - DESTRUCTIVE to shared resources):
   - `docker compose rm -sf mvp-postgres mvp-redis`
   - `docker volume rm motovaultpro_postgres_data motovaultpro_redis_data`
-  - `docker compose up -d mvp-postgres mvp-redis mvp-platform`
+  - `docker compose up -d mvp-postgres mvp-redis mvp-backend`
   - Note: This will destroy ALL application data, not just platform data, as database and cache are shared
 
 ## Security Summary
@@ -169,9 +164,9 @@ VIN/License rule
   - Ensure Postgres is up; the runner now waits/retries, but confirm logs.
 
 ## Notable Files
-- Platform schema & seeds: `mvp-platform-services/vehicles/sql/schema/001..005`
-- Platform API code: `mvp-platform-services/vehicles/api/*`
+- Platform schema & seeds: maintained by database admins (legacy FastAPI scripts available on request)
+- Platform API integration: `backend/src/features/platform/api/*`
 - Backend dropdown proxy: `backend/src/features/vehicles/api/*`
-- Backend platform client: `backend/src/features/vehicles/external/platform-vehicles/*`
+- Backend platform module: `backend/src/features/platform/*`
 - Backend migrations runner: `backend/src/_system/migrations/run-all.ts`
 - Frontend vehicles UI: `frontend/src/features/vehicles/*`