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.
• This is a production only application architecture.
• Always assume this application is going into production when you are done. All security and linting should pass.

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 Migrations

# All features (in dependency order)
npm run migrate:all

# From project root using Docker
make migrate

Note: Single-feature migration is not implemented yet. Run the full migration set.

Testing Strategy

# Run all tests (from project root)
make test

# In backend container shell
make shell-backend
npm test                 # all tests
npm test -- features/[feature-name]
npm test -- features/[feature-name]/tests/integration

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: make dev builds and runs the stack
• Testing: make test runs backend tests in the container
• Rebuilding: make rebuild for code/dependency changes
• Package changes: Rebuild backend/frontend containers as needed

Authentication (Current State)

• Backend uses a Fastify auth plugin that injects a mock user in development/test.
• JWT validation via Auth0 is planned; production configuration will enforce it.

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)