MotoVaultPro - Hybrid Platform: Microservices + Modular Monolith

CRITICAL REQUIREMENT: Mobile + Desktop Development

ALL features MUST be implemented and tested on BOTH mobile and desktop. This is a hard requirement that cannot be skipped. Every component, page, and feature needs responsive design and mobile-first considerations.

Architecture Overview

Hybrid platform combining true microservices (MVP Platform Services) with a modular monolithic application. The MotoVaultPro application is a single service containing self-contained feature capsules in backend/src/features/[name]/. Platform services provide shared capabilities with independent deployment and scaling.

Core Principles

• Production-Only Development: All services run in production mode only
• Docker-First: All development in containers, no local installs
• Platform Service Independence: Platform services are completely independent microservices
• Feature Capsule Organization: Application features are self-contained modules within a single service
• Hybrid Deployment: Platform services deploy independently, application features deploy together
• User-Scoped Data: All application data isolated by user_id

Quick Start

Setup Environment

# One-time setup (ensure .env exists, then build and start containers)
make setup

# Start full microservices environment  
make start  # Starts application + platform services

Common Development Tasks

# Run all migrations (inside containers)
make migrate

# Run all tests (backend + frontend) inside containers
make test

# Run specific application feature tests (backend)
make shell-backend
npm test -- features/vehicles

# Run frontend tests only (inside disposable node container)
make test-frontend

# View logs (all services)
make logs

# Container shell access
make shell-backend           # Application service
make shell-frontend
make shell-platform-vehicles # Platform service shell

# Rebuild after code/dependency changes
make rebuild

Architecture Components

MVP Platform Services

Platform Vehicles Service (Primary)

• Architecture: 3-container microservice (DB, ETL, API)
• API: FastAPI with hierarchical endpoints
• Database: PostgreSQL with normalized vehicles schema (port 5433)
• Cache: Dedicated Redis instance (port 6380)
• Cache Strategy: Year-based hierarchical caching
• Key Endpoints:

  GET /vehicles/makes?year={year}
  GET /vehicles/models?year={year}&make_id={make_id}
  GET /vehicles/trims?year={year}&make_id={make_id}&model_id={model_id}
  GET /vehicles/engines?year={year}&make_id={make_id}&model_id={model_id}
  GET /vehicles/transmissions?year={year}&make_id={make_id}&model_id={model_id}
  POST /vehicles/vindecode
  

Platform Tenants Service

• Architecture: Independent microservice for multi-tenant management
• API: FastAPI on port 8001
• Database: Dedicated PostgreSQL (port 5434)
• Cache: Dedicated Redis instance (port 6381)

Application Service (Modular Monolith)

The application is a single Node.js service containing multiple feature capsules. All features deploy together in the admin-backend container but maintain logical separation through the capsule pattern.

Feature Capsule Structure

features/[name]/
├── README.md          # Feature overview & API
├── index.ts           # Public exports only
├── api/               # HTTP layer
├── domain/            # Business logic
├── data/              # Database layer
├── migrations/        # Feature's schema
├── external/          # Feature's external APIs
├── events/            # Event handlers
├── tests/             # All tests
└── docs/              # Documentation

Deployment: All features bundled in single admin-backend container Database: Shared PostgreSQL instance with feature-specific tables Communication: Features access shared resources, not service-to-service calls

Current Features

• vehicles: Consumes MVP Platform Vehicles service via HTTP API
• fuel-logs: Depends on vehicles feature for vehicle validation
• maintenance: Depends on vehicles feature; basic structure implemented
• stations: Partial implementation with Google Maps integration
• tenant-management: Multi-tenant functionality

SSL Configuration for Production Development

• Place motovaultpro.com.crt and motovaultpro.com.key in ./certs
• Application Frontend: https://admin.motovaultpro.com (requires DNS or hosts file entry)
• Platform Landing: https://motovaultpro.com (marketing site)
• Hosts file setup: Add 127.0.0.1 motovaultpro.com admin.motovaultpro.com to /etc/hosts
• Generate self-signed certs:

  openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
    -keyout certs/motovaultpro.com.key \
    -out certs/motovaultpro.com.crt \
    -subj "/CN=motovaultpro.com"
  

Authentication & Security

• Backend: Auth0 JWT validation via Fastify using @fastify/jwt and get-jwks
• All protected endpoints: Require valid Authorization: Bearer <token>
• Service-to-Service: Platform services use service tokens
• Environment Variables:
  • PLATFORM_VEHICLES_API_URL — base URL for vehicles service
  • PLATFORM_VEHICLES_API_KEY — service token for inter-service auth

External Services

Application Services

• PostgreSQL: Application database (port 5432)
• Redis: Application caching layer (port 6379)
• MinIO: Object storage (port 9000/9001)

MVP Platform Services

• Platform PostgreSQL: Platform services database (port 5434)
• Platform Redis: Platform services caching (port 6381)
• MVP Platform Vehicles DB: PostgreSQL with normalized vehicles schema (port 5433)
• MVP Platform Vehicles Redis: Vehicles service cache (port 6380)
• MVP Platform Vehicles API: FastAPI hierarchical vehicle endpoints (port 8000)
• MVP Platform Tenants API: FastAPI multi-tenant management (port 8001)

External APIs

• Google Maps: Station location API (via stations feature)
• Auth0: Authentication and authorization

Service Health Check

# Application Services
# Frontend: https://admin.motovaultpro.com
# Backend: http://localhost:3001/health
# MinIO Console: http://localhost:9001

# MVP Platform Services
# Platform Vehicles API: http://localhost:8000/health
# Platform Vehicles Docs: http://localhost:8000/docs
# Platform Tenants API: http://localhost:8001/health
# Platform Landing: https://motovaultpro.com

Service Dependencies

Platform Services (Independent)

1. mvp-platform-vehicles (independent platform service)

Application Features (Logical Dependencies)

Note: All features deploy together in single application container

1. vehicles (consumes platform service, base application feature)
2. fuel-logs (depends on vehicles table via foreign keys)
3. maintenance (depends on vehicles table via foreign keys)
4. stations (independent feature)
5. tenant-management (cross-cutting tenant functionality)

Documentation Navigation

• Platform Services: docs/PLATFORM-SERVICES.md
• Vehicles API (Authoritative): docs/VEHICLES-API.md
• Application Features: backend/src/features/[name]/README.md
• Database: docs/DATABASE-SCHEMA.md
• Testing: docs/TESTING.md
• Security: docs/SECURITY.md

Adding New Features

./scripts/generate-feature-capsule.sh [feature-name]
# Creates complete capsule structure with all subdirectories