motovaultpro/docs/VEHICLES-API.md

Vehicles API – Platform Rebuild, App Integration, and Operations

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 Vehicles Service (FastAPI + Postgres + Redis).
• Goal: Predictable year→make→model→trim→engine cascades, production‑only workflow, AI‑friendly code layout and docs.

Platform Vehicles Service

Database Schema (Postgres schema: vehicles)

• make(id, name)
• model(id, make_id → make.id, name)
• model_year(id, model_id → model.id, year)
• trim(id, model_year_id → model_year.id, name)
• engine(id, name, code, displacement_l, cylinders, fuel_type, aspiration)
• trim_engine(trim_id → trim.id, engine_id → engine.id)
• Optional (present, not exposed yet): transmission, trim_transmission, performance

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 }[] }

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.

Authentication

• Header: Authorization: Bearer ${API_KEY}
• API env: API_KEY
• Backend env (consumer): PLATFORM_VEHICLES_API_KEY

Caching (Redis)

• Keys: dropdown:years, dropdown:makes:{year}, dropdown:models:{year}:{make}, dropdown:trims:{year}:{model}, dropdown:engines:{year}:{model}:{trim}
• Default TTL: 6 hours

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)

Reapply seeds on an existing volume:

• docker compose exec -T mvp-platform-vehicles-db psql -U mvp_platform_user -d vehicles -f /docker-entrypoint-initdb.d/005_seed_specific_vehicles.sql
• Clear platform cache: docker compose exec -T mvp-platform-vehicles-redis sh -lc "redis-cli FLUSHALL"

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 }[]

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.

Authentication (App)

• Auth0 JWT enforced via Fastify + JWKS. No mock users.

Migrations (Production‑Quality)

• Migrations packaged in image under /app/migrations/features/[feature]/migrations.
• Runner (backend/src/_system/migrations/run-all.ts):
  • Reads base dir from MIGRATIONS_DIR (env in Dockerfile)
  • Tracks executed files in _migrations (idempotent)
  • Wait/retry for DB readiness to avoid flapping on cold starts
• Auto‑migrate on backend container start: node dist/_system/migrations/run-all.js && npm start
• Manual: make migrate (runs runner inside the container)

Frontend Changes

• Vehicles form cascades: year → make → model → trim → engine.
  • Engines load only after a trim is selected (requires trim_id).
• Validation updated: user must provide either a 17‑char VIN or a non‑empty license plate.
  • VIN Decode button still requires a valid 17‑char VIN.
• APIs used:
  • /api/vehicles/dropdown/years
  • /api/vehicles/dropdown/makes|models|trims|engines

Add Vehicle Form – Change/Add/Modify/Delete Fields (Fast Track)

Where to edit

• UI + validation: frontend/src/features/vehicles/components/VehicleForm.tsx
• Frontend types: frontend/src/features/vehicles/types/vehicles.types.ts
• Backend controller/service/repo: backend/src/features/vehicles/api/vehicles.controller.ts, domain/vehicles.service.ts, data/vehicles.repository.ts, types in domain/vehicles.types.ts
• App DB migrations: backend/src/features/vehicles/migrations/*.sql (auto‑migrated on backend start)

Add a new field (example: bodyStyle)

1. DB: ALTER TABLE vehicles ADD COLUMN IF NOT EXISTS body_style VARCHAR(100); in a new migration file.
2. Backend: add bodyStyle?: string; to types; include in repository insert/update mapping as body_style.
3. Frontend: add bodyStyle to Zod schema and a new input bound via register('bodyStyle').
4. Rebuild frontend/backend and verify in Network + logs.

Modify an existing field

• Update labels/placeholders in VehicleForm.
• Update Zod schema for new validation rules; mirror on the server if desired.
• Adjust service logic only if business behavior changes.

Delete a field (safe path)

• Remove from VehicleForm and frontend types.
• Remove from backend types/repository mapping.
• Optional migration to drop the column later.

Dropdown ordering

• Implemented in VehicleForm; current order is Year → Make → Model → Trim → Engine → Transmission (static).
• Engine select is enabled only after a Trim is selected.

VIN/License rule

• Frontend Zod: either 17‑char VIN or non‑empty license plate; if no plate, VIN must be 17.
• Backend controller enforces the same rule; service decodes/validates only when VIN is present.
• Repository normalizes empty VIN to NULL to avoid unique collisions.

Operations

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-vehicles-api

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-vehicles-api

Common Reset Sequences

• Platform seed reapply (non‑destructive): apply 005_seed_specific_vehicles.sql and flush Redis cache.
• Platform reset (destructive only to platform DB/cache):
  • docker compose rm -sf mvp-platform-vehicles-db mvp-platform-vehicles-redis
  • docker volume rm motovaultpro_platform_vehicles_data motovaultpro_platform_vehicles_redis_data
  • docker compose up -d mvp-platform-vehicles-db mvp-platform-vehicles-redis mvp-platform-vehicles-api

Security Summary

• Platform: Authorization: Bearer ${API_KEY} required on all /api/v1/vehicles/* endpoints.
• App Backend: Auth0 JWT required on all protected /api/* routes.

CI Summary

• Workflow .github/workflows/ci.yml builds backend/frontend/platform API.
• Runs backend lint/tests in a builder image on a stable network.

Troubleshooting

• Frontend shows generic “Server error” right after login:
  • Check backend /api/vehicles 500s (migrations not run or DB unavailable).
  • Run make migrate or ensure backend container auto‑migrate is succeeding; check docker compose logs backend.
• Dropdowns not updating after seed:
  • Run specific seed SQL (see above) and redis-cli FLUSHALL on platform Redis.
• Backend flapping on start after rebuild:
  • 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/*
• Backend dropdown proxy: backend/src/features/vehicles/api/*
• Backend platform client: backend/src/features/vehicles/external/platform-vehicles/*
• Backend migrations runner: backend/src/_system/migrations/run-all.ts
• Frontend vehicles UI: frontend/src/features/vehicles/*