# 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
```bash
# 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
```bash
# 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:
  ```bash
  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
```bash
# 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
```bash
./scripts/generate-feature-capsule.sh [feature-name]
# Creates complete capsule structure with all subdirectories
```