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 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 Module

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).

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)

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 both /api/vehicles/* and /api/platform/*)
• Configured in backend: src/core/plugins/auth.plugin.ts with JWKS validation

Caching (Redis)

• 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

Platform seed migrations (TypeScript backend):

• Schema definition (backend/src/features/platform/migrations/001_create_platform_schema.sql)
• Constraints and indexes (backend/src/features/platform/migrations/002_create_indexes.sql)
• Sample vehicle data (backend/src/features/platform/migrations/003_seed_vehicles.sql) Seeds are auto-migrated on backend container start via backend/src/_system/migrations/run-all.ts.

Clear platform cache:

• docker compose exec -T mvp-redis sh -lc "redis-cli FLUSHALL"
• Or restart containers: make rebuild

MotoVaultPro Backend (Application Service)

Proxy Dropdown Endpoints

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.

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.

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 table and skips already executed files
  • Idempotent at file level: Safe to re-run migration system multiple times
  • 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
  • /api/vehicles/dropdown/transmissions

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 (includes platform module): docker compose up -d --build backend

Logs & Health

• Backend: https://motovaultpro.com/api/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-backend
  • Note: This will destroy ALL application data, not just platform data, as database and cache are shared

Security Summary

• Platform Module: Auth0 JWT via Authorization: Bearer ${JWT_TOKEN} required on all /api/platform/* endpoints.
• Vehicles Feature: Auth0 JWT required on all protected /api/vehicles/* routes.
• Health Check: /api/health is unauthenticated (Traefik readiness probe).

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 shared Redis (mvp-redis).
• Backend flapping on start after rebuild:
  • Ensure Postgres is up; the runner now waits/retries, but confirm logs.

Notable Files

• 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 module: backend/src/features/platform/*
• Backend migrations runner: backend/src/_system/migrations/run-all.ts
• Frontend vehicles UI: frontend/src/features/vehicles/*