motovaultpro/AI_PROJECT_GUIDE.md

MotoVaultPro - AI-First Modified Feature Capsule Architecture

AI Quick Start (50 tokens)

Vehicle management platform using Modified Feature Capsules. Each feature in backend/src/features/[name]/ is 100% self-contained with API, domain, data, migrations, external integrations, tests, and docs. Single directory load gives complete context. No shared business logic, only pure utilities in shared-minimal/.

Architecture Philosophy

Each feature is a complete, self-contained capsule. Load ONE directory for 100% context. Evaluate every feature if it should be in it's own Docker container. This is a microservices based archiecture where production will be run on k8s.

Navigation & Quick Tasks

AI Workflow

• Feature work: Load entire backend/src/features/[feature]/
• Cross-feature: Load each feature's index.ts and README.md
• System tools: backend/src/_system/ for migrations and schema
• AI metadata: .ai/ directory
• Documentation: See docs/README.md for complete documentation index

Working on a Feature

# Load complete context
cd backend/src/features/[feature-name]/

# Everything is here:
# - API endpoints (api/)
# - Business logic (domain/)
# - Database operations (data/)
# - Schema migrations (migrations/)
# - External integrations (external/)
# - All tests (tests/)
# - Documentation (docs/)

Adding New Feature

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

Running Feature Migrations

# Single feature
npm run migrate:feature [feature-name]

# All features (respects dependencies)
npm run migrate:all

Testing Strategy

# Test single feature (complete isolation)
npm test -- features/[feature-name]

# Test feature integration
npm test -- features/[feature-name]/tests/integration

# Test everything
npm test

Docker Development Workflow

# Start development environment
make dev

# Rebuild after code/dependency changes
make rebuild

# View logs
make logs

# Run tests in containers
make test

# Open container shells
make shell-backend
make shell-frontend

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

Feature Capsules

Vehicles (Primary Entity)

• Path: backend/src/features/vehicles/
• External: NHTSA vPIC for VIN decoding
• Dependencies: None (base feature)
• Cache: VIN lookups for 30 days
• Status: Complete implementation

Fuel Logs

• Path: backend/src/features/fuel-logs/
• External: None
• Dependencies: Vehicles (for vehicle_id)
• Cache: User's logs for 5 minutes
• Status: Partial implementation

Maintenance

• Path: backend/src/features/maintenance/
• External: None
• Dependencies: Vehicles (for vehicle_id)
• Cache: Upcoming maintenance for 1 hour
• Status: Scaffolded

Stations

• Path: backend/src/features/stations/
• External: Google Maps API
• Dependencies: None (independent)
• Cache: Station searches for 1 hour
• Status: Partial implementation

Primary Entry Points

• Backend: backend/src/index.ts → backend/src/app.ts
• Frontend: frontend/src/main.tsx → frontend/src/App.tsx
• Features: backend/src/features/[name]/index.ts

Development Environment

All development happens in Docker containers:

• Development: Dockerfile.dev with npm install during container build
• Testing: make test runs tests in container
• Rebuilding: make rebuild for code changes
• Package changes: Container rebuild required

External Services

• PostgreSQL: Primary database (port 5432)
• Redis: Caching layer (port 6379)
• MinIO: Object storage (port 9000/9001)
• NHTSA vPIC: VIN decoding API
• Google Maps: Station location API

Quick Health Check

# Frontend: http://localhost:3000
# Backend: http://localhost:3001/health
# MinIO Console: http://localhost:9001

Migration Dependencies

Features must be migrated in dependency order:

1. vehicles (base feature)
2. fuel-logs (depends on vehicles)
3. maintenance (depends on vehicles)
4. stations (independent)