190 lines
7.4 KiB
Markdown
190 lines
7.4 KiB
Markdown
# 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
|
|
``` |