# 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
```bash
# 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
```bash
./scripts/generate-feature-capsule.sh [feature-name]
# Creates complete capsule structure with all subdirectories
```

### Running Feature Migrations
```bash
# Single feature
npm run migrate:feature [feature-name]

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

### Testing Strategy
```bash
# 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
```bash
# 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
```bash
# 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)