egullickson/motovaultpro
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial Commit

Browse Source
This commit is contained in:
Eric Gullickson
2025-09-17 16:09:15 -05:00
parent 0cdb9803de
commit a052040e3a
373 changed files with 437090 additions and 6773 deletions
Download Patch File Download Diff File Expand all files Collapse all files

223
README.md
View File

@@ -1,99 +1,190 @@
# MotoVaultPro - AI Onboarding Guide
# MotoVaultPro - Hybrid Platform: Microservices + Modular Monolith
## For AI Assistants: Instant Codebase Understanding
## 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.
To efficiently understand and maintain this codebase, follow this exact sequence:
## 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.
### 1. Load Core Context (Required - 2 minutes)
```
Read these files in order:
1. AI_PROJECT_GUIDE.md - Complete project overview and architecture
2. .ai/context.json - Loading strategies and feature metadata
3. docs/README.md - Documentation navigation hub
```
### 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
### 2. Understand the Architecture (30 seconds)
**Modified Feature Capsules**: Each feature in `backend/src/features/[name]/` is 100% self-contained with everything needed in one directory. No shared business logic.
## Quick Start
### 3. For Specific Tasks
#### Working on a Feature
Load entire feature directory: `backend/src/features/[feature-name]/`
- Start with README.md for complete API and business rules
- Everything needed is in this single directory
#### Cross-Feature Work
Load each feature's `index.ts` and `README.md`
#### Database Work
Load `docs/database-schema.md` for complete schema overview
#### Testing Work
Load `docs/testing.md` for Docker-based testing workflow
Only use docker containers for testing. Never install local tools if they do not exist already.
### 4. Development Environment (Production-Only)
### Setup Environment
```bash
# One-time setup (copies .env and builds containers)
# One-time setup (ensure .env exists, then build and start containers)
make setup
# Start/rebuild the full environment
make dev
# Start full microservices environment
make start # Starts application + platform services
```
**Production-Only Development**: This application runs in production mode only. All development happens with production builds and configurations.
### 5. Key Principles
- **Production-Only**: All development uses production builds and configuration
- **Docker-First**: All development in containers, no local installs
- **Feature Independence**: Each feature is completely isolated
- **Single Directory Context**: Load one directory for complete understanding
- **User-Scoped Data**: All data isolated by user_id
### 6. Common Tasks
### Common Development Tasks
```bash
# Run all migrations (inside containers)
make migrate
# Run all backend tests (inside containers)
# Run all tests (backend + frontend) inside containers
make test
# Run tests for a specific feature (from backend container shell)
# Run specific application feature tests (backend)
make shell-backend
npm test -- features/vehicles
# View logs
# Run frontend tests only (inside disposable node container)
make test-frontend
# View logs (all services)
make logs
# Container shell access
make shell-backend
make shell-backend # Application service
make shell-frontend
make shell-platform-vehicles # Platform service shell
# Rebuild after code/dependency changes
make rebuild
```
### 7. Feature Status
- **vehicles**: Complete (primary entity, VIN decoding)
- **fuel-logs**: Implemented (depends on vehicles); tests pending
- **maintenance**: Scaffolded (depends on vehicles)
- **stations**: Partial (Google Maps integration)
## Architecture Components
## SSL for Frontend (Production Development)
- Place `motovaultpro.com.crt` and `motovaultpro.com.key` in `./certs`.
- To generate self-signed certs for production development:
### 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"
```
- **Access frontend at**: `https://motovaultpro.com` (requires DNS or hosts file entry)
- **Hosts file setup**: Add `127.0.0.1 motovaultpro.com` to `/etc/hosts`
- HTTP requests redirect to HTTPS automatically.
## Architecture Summary
Vehicle management platform using Modified Feature Capsule design where each feature is self-contained with API, domain logic, database layer, migrations, external integrations, tests, and documentation in a single directory. Built for AI maintainability with production-only Docker development.
## 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
## Quick Navigation
- **Setup**: AI_PROJECT_GUIDE.md
- **Features**: backend/src/features/[name]/README.md
- **Database**: docs/database-schema.md
- **Testing**: docs/testing.md
- **Security**: docs/security.md
## 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
```