Added Documents Feature
This commit is contained in:
Eric Gullickson
206
README.md
206
README.md
@@ -1,190 +1,30 @@
|
||||
# MotoVaultPro - Hybrid Platform: Microservices + Modular Monolith
|
||||
# MotoVaultPro — Hybrid Platform
|
||||
|
||||
## 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.
|
||||
Modular monolith application with independent platform microservices.
|
||||
|
||||
## 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.
|
||||
## Requirements
|
||||
- Mobile + Desktop: Implement and test every feature on both.
|
||||
- Docker-first, production-only: All testing and validation in containers.
|
||||
- See `CLAUDE.md` for development partnership guidelines.
|
||||
|
||||
### 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
|
||||
## Quick Start (containers)
|
||||
```bash
|
||||
# One-time setup (ensure .env exists, then build and start containers)
|
||||
make setup
|
||||
|
||||
# Start full microservices environment
|
||||
make start # Starts application + platform services
|
||||
make setup # build + start + migrate
|
||||
make start # start services
|
||||
make rebuild # rebuild on changes
|
||||
make logs # tail all logs
|
||||
make migrate # run DB migrations
|
||||
make test # backend + frontend tests
|
||||
```
|
||||
|
||||
### Common Development Tasks
|
||||
```bash
|
||||
# Run all migrations (inside containers)
|
||||
make migrate
|
||||
## Documentation
|
||||
- AI quickload: `AI-INDEX.md`
|
||||
- Docs hub: `docs/README.md`
|
||||
- Features: `backend/src/features/{name}/README.md`
|
||||
- Frontend: `frontend/README.md`
|
||||
- Backend core: `backend/src/core/README.md`
|
||||
|
||||
# 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
|
||||
```
|
||||
## URLs and Hosts
|
||||
- Frontend: `https://admin.motovaultpro.com`
|
||||
- Backend health: `http://localhost:3001/health`
|
||||
- Add to `/etc/hosts`: `127.0.0.1 motovaultpro.com admin.motovaultpro.com`
|
||||
|
||||
Reference in New Issue
Block a user