Improved docs for future AI

.ai/context.json

@@ -7,6 +7,11 @@
     "feature_independence": "100%"
   },
   "loading_strategy": {
+    "project_overview": {
+      "instruction": "Start with AI_PROJECT_GUIDE.md for complete project context",
+      "example": "AI_PROJECT_GUIDE.md",
+      "completeness": "100% - all navigation and architecture information"
+    },
     "feature_work": {
       "instruction": "Load entire feature directory",
       "example": "backend/src/features/vehicles/",
@@ -26,6 +31,11 @@
         "backend/src/features/[feature]/tests/",
         "backend/src/features/[feature]/docs/TROUBLESHOOTING.md"
       ]
+    },
+    "documentation": {
+      "instruction": "Use docs/README.md for complete documentation index",
+      "example": "docs/README.md",
+      "completeness": "All documentation links and navigation"
     }
   },
   "feature_capsules": {

AI_PROJECT_GUIDE.md

@@ -0,0 +1,155 @@
+# 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.
+
+## 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)

AI_README.md

@@ -1,30 +0,0 @@
-# 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/.
-
-## Navigation
-- 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
-
-## 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
-```
-
-## 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`

CLAUDE.md

@@ -1,6 +1,8 @@
 Load .ai/context.json to understand the project's danger zones and loading strategies
 
-Load AI_README.md and @PROJECT_MAP.md to gain context on the application. 
+Load AI_PROJECT_GUIDE.md to gain complete context on the application. 
+
+Never use emojis.
 
 CRITICAL: All development practices and choices should be made taking into account the most context effecient interation with another AI. Any AI should be able to understand this applicaiton with minimal prompting. 
 

PROJECT_MAP.md

@@ -1,74 +0,0 @@
-# MotoVaultPro Navigation Map - Modified Feature Capsule Design
-
-## Architecture Philosophy
-Each feature is a complete, self-contained capsule. Load ONE directory for 100% context.
-
-## Quick Task Guide
-
-### 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
-```
-
-## 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
-
-### Fuel Logs
-- Path: `backend/src/features/fuel-logs/`
-- External: None
-- Dependencies: Vehicles (for vehicle_id)
-- Cache: User's logs for 5 minutes
-
-### Maintenance
-- Path: `backend/src/features/maintenance/`
-- External: None
-- Dependencies: Vehicles (for vehicle_id)
-- Cache: Upcoming maintenance for 1 hour
-
-### Stations
-- Path: `backend/src/features/stations/`
-- External: Google Maps API
-- Dependencies: None (independent)
-- Cache: Station searches for 1 hour

README.md

@@ -0,0 +1,74 @@
+# MotoVaultPro - AI Onboarding Guide
+
+## For AI Assistants: Instant Codebase Understanding
+
+To efficiently understand and maintain this codebase, follow this exact sequence:
+
+### 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
+```
+
+### 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.
+
+### 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
+
+### 4. Development Environment (1 command)
+```bash
+make dev  # Starts complete Docker environment
+```
+
+### 5. Key Principles
+- **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
+```bash
+# Test specific feature
+npm test -- features/vehicles
+
+# Run migrations  
+make migrate
+
+# View logs
+make logs
+
+# Container shell access
+make shell-backend
+```
+
+### 7. Feature Status
+- **vehicles**: Complete (primary entity, VIN decoding)
+- **fuel-logs**: Implemented (depends on vehicles)
+- **maintenance**: Scaffolded (depends on vehicles) 
+- **stations**: Partial (Google Maps integration)
+
+## 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 Docker-first development.
+
+## 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

backend/src/features/fuel-logs/README.md

@@ -1,35 +1,211 @@
-# UfuelUlogs Feature Capsule
+# Fuel Logs Feature Capsule
 
 ## Quick Summary (50 tokens)
-[AI: Complete feature description, main operations, dependencies, caching strategy]
+Tracks fuel purchases and calculates MPG efficiency. Depends on vehicles feature for vehicle_id. Provides analytics for fuel costs, consumption trends, and efficiency metrics. Cached user logs for 5 minutes. Supports CRUD operations with user ownership validation.
 
 ## API Endpoints
-- GET /api/fuel-logs - List all fuel-logs
+- `POST /api/fuel-logs` - Create new fuel log entry
-- GET /api/fuel-logs/:id - Get specific lUfuelUlogs
+- `GET /api/fuel-logs` - List all user's fuel logs (cached 5 min)
-- POST /api/fuel-logs - Create new lUfuelUlogs
+- `GET /api/fuel-logs/:id` - Get specific fuel log
-- PUT /api/fuel-logs/:id - Update lUfuelUlogs
+- `PUT /api/fuel-logs/:id` - Update fuel log details
-- DELETE /api/fuel-logs/:id - Delete lUfuelUlogs
+- `DELETE /api/fuel-logs/:id` - Delete fuel log
+- `GET /api/fuel-logs/vehicle/:vehicleId` - Get fuel logs for specific vehicle
+- `GET /api/fuel-logs/vehicle/:vehicleId/stats` - Get fuel efficiency statistics
 
-## Structure
+## Authentication Required
-- **api/** - HTTP endpoints, routes, validators
+All endpoints require valid JWT token with user context.
-- **domain/** - Business logic, types, rules
+
-- **data/** - Repository, database queries
+## Request/Response Examples
-- **migrations/** - Feature-specific schema
+
-- **external/** - External API integrations
+### Create Fuel Log
-- **events/** - Event handlers
+```json
-- **tests/** - All feature tests
+POST /api/fuel-logs
-- **docs/** - Detailed documentation
+{
+  "vehicleId": "uuid-vehicle-id",
+  "date": "2024-01-15",
+  "odometer": 52000,
+  "gallons": 12.5,
+  "pricePerGallon": 3.299,
+  "totalCost": 41.24,
+  "station": "Shell Station",
+  "location": "123 Main St, City, ST",
+  "notes": "Full tank, premium gas"
+}
+
+Response (201):
+{
+  "id": "uuid-here",
+  "userId": "user-id",
+  "vehicleId": "uuid-vehicle-id", 
+  "date": "2024-01-15",
+  "odometer": 52000,
+  "gallons": 12.5,
+  "pricePerGallon": 3.299,
+  "totalCost": 41.24,
+  "station": "Shell Station",
+  "location": "123 Main St, City, ST",
+  "notes": "Full tank, premium gas",
+  "mpg": 28.4, // Auto-calculated from previous log
+  "createdAt": "2024-01-15T10:30:00Z",
+  "updatedAt": "2024-01-15T10:30:00Z"
+}
+```
+
+### Get Vehicle Statistics
+```json
+GET /api/fuel-logs/vehicle/:vehicleId/stats
+
+Response (200):
+{
+  "totalLogs": 15,
+  "totalGallons": 187.5,
+  "totalCost": 618.45,
+  "averageMpg": 29.2,
+  "averagePricePerGallon": 3.299,
+  "lastFillUp": "2024-01-15",
+  "milesTracked": 5475
+}
+```
+
+## Feature Architecture
+
+### Complete Self-Contained Structure
+```
+fuel-logs/
+├── README.md              # This file
+├── index.ts               # Public API exports
+├── api/                   # HTTP layer
+│   ├── fuel-logs.controller.ts
+│   ├── fuel-logs.routes.ts
+│   └── fuel-logs.validators.ts
+├── domain/                # Business logic
+│   ├── fuel-logs.service.ts
+│   └── fuel-logs.types.ts
+├── data/                  # Database layer
+│   └── fuel-logs.repository.ts
+├── migrations/            # Feature schema
+│   └── 001_create_fuel_logs_table.sql
+├── tests/                 # All tests
+│   ├── unit/
+│   │   └── fuel-logs.service.test.ts
+│   └── integration/
+│       └── fuel-logs.integration.test.ts
+└── docs/                  # Additional docs
+```
+
+## Key Features
+
+### MPG Calculation
+- **Auto-calculation**: Computes MPG based on odometer difference from previous log
+- **First Entry**: No MPG for first fuel log (no baseline)
+- **Accuracy**: Requires consistent odometer readings
+- **Validation**: Ensures odometer readings increase over time
+
+### Database Schema
+- **Primary Table**: `fuel_logs` with foreign key to vehicles
+- **Indexes**: Optimized for user queries, vehicle lookups, date ranges
+- **Constraints**: Valid vehicle_id, positive gallons/cost, future dates allowed
+
+### Performance Optimizations
+- **Redis Caching**: User fuel logs cached for 5 minutes
+- **Indexes**: Strategic database indexes for fast queries
+- **Efficient Queries**: Single query for MPG calculations
+
+## Business Rules
+
+### Data Validation
+- **Vehicle Ownership**: User must own the vehicle
+- **Positive Values**: Gallons, price, cost must be > 0
+- **Odometer Logic**: Reading must be >= previous reading for same vehicle
+- **Date Validation**: No fuel logs in future (beyond today)
+
+### MPG Calculation Logic
+- **Formula**: (Current Odometer - Previous Odometer) / Gallons
+- **Baseline**: Requires at least 2 fuel logs for calculation
+- **Edge Cases**: Handles first log, odometer resets, missing data
 
 ## Dependencies
-- Internal: core/auth, core/cache
-- External: [List any external APIs]
-- Database: fuel-logs table
 
-## Quick Commands
+### Internal Core Services
+- `core/auth` - JWT authentication middleware
+- `core/config` - Database pool, Redis cache
+- `core/logging` - Structured logging with Winston
+- `shared-minimal/utils` - Pure validation utilities
+
+### Feature Dependencies
+- **vehicles** - REQUIRED: vehicle_id foreign key relationship
+- Must have valid vehicle before creating fuel logs
+
+### Database Tables
+- `fuel_logs` - Primary fuel tracking data
+- `vehicles` - Referenced via vehicle_id foreign key
+
+## Caching Strategy
+
+### User Fuel Logs (5 minutes)
+- **Key**: `fuel-logs:user:{userId}`
+- **TTL**: 300 seconds (5 minutes)
+- **Invalidation**: On create, update, delete
+
+### Vehicle Statistics (15 minutes)
+- **Key**: `fuel-stats:vehicle:{vehicleId}`
+- **TTL**: 900 seconds (15 minutes)
+- **Rationale**: Stats change less frequently than individual logs
+
+## Testing
+
+### Unit Tests
+- `fuel-logs.service.test.ts` - Business logic with mocked dependencies
+- Tests MPG calculation logic
+- Tests vehicle ownership validation
+- Tests error handling paths
+
+### Integration Tests
+- `fuel-logs.integration.test.ts` - Complete API workflow with test database
+
+### Run Tests
 ```bash
-# Run feature tests
+# All fuel log tests
 npm test -- features/fuel-logs
 
-# Run feature migrations
+# Unit tests only
-npm run migrate:feature fuel-logs
+npm test -- features/fuel-logs/tests/unit
+
+# Integration tests only  
+npm test -- features/fuel-logs/tests/integration
+
+# With coverage
+npm test -- features/fuel-logs --coverage
+```
+
+## Error Handling
+
+### Client Errors (4xx)
+- `400` - Invalid data, negative values, validation errors
+- `401` - Missing or invalid JWT token
+- `403` - User not authorized for vehicle/fuel log
+- `404` - Vehicle or fuel log not found
+- `409` - Odometer reading conflicts
+
+### Server Errors (5xx)
+- `500` - Database connection failures
+- Graceful error responses with meaningful messages
+
+## Development Commands
+
+```bash
+# Run migrations
+make migrate
+
+# Start development environment
+make dev
+
+# View feature logs
+make logs-backend | grep fuel-logs
+
+# Open container shell
+make shell-backend
+
+# Inside container - run feature tests
+npm test -- features/fuel-logs
 ```

docs/README.md

@@ -0,0 +1,128 @@
+# MotoVaultPro Documentation
+
+Complete documentation for the MotoVaultPro vehicle management platform using Modified Feature Capsule architecture.
+
+## Quick Navigation
+
+### 🚀 Getting Started
+- **[AI Project Guide](../AI_PROJECT_GUIDE.md)** - Complete AI-friendly project overview and navigation
+- **[Security Architecture](security.md)** - Authentication, authorization, and security considerations
+
+### 🏗️ Architecture
+- **[Architecture Directory](architecture/)** - Detailed architectural documentation
+- **Feature Capsules** - Each feature has complete documentation in `backend/src/features/[name]/README.md`:
+  - **[Vehicles](../backend/src/features/vehicles/README.md)** - Primary entity with VIN decoding
+  - **[Fuel Logs](../backend/src/features/fuel-logs/README.md)** - Fuel tracking and analytics
+  - **[Maintenance](../backend/src/features/maintenance/README.md)** - Vehicle maintenance scheduling
+  - **[Stations](../backend/src/features/stations/README.md)** - Gas station location services
+
+### 🔧 Development
+- **[Docker Setup](../docker-compose.yml)** - Complete containerized development environment
+- **[Makefile Commands](../Makefile)** - All available development commands
+- **[Backend Package](../backend/package.json)** - Scripts and dependencies
+- **[Frontend Package](../frontend/package.json)** - React app configuration
+
+### 🧪 Testing
+Each feature contains complete test suites:
+- **Unit Tests**: `backend/src/features/[name]/tests/unit/`
+- **Integration Tests**: `backend/src/features/[name]/tests/integration/`
+- **Test Commands**: `npm test -- features/[feature-name]`
+
+### 🗄️ Database
+- **[Migration System](../backend/src/_system/migrations/)** - Database schema management
+- **Feature Migrations**: Each feature manages its own schema in `migrations/` directory
+- **Migration Order**: vehicles → fuel-logs → maintenance → stations
+
+### 🔐 Security
+- **[Security Overview](security.md)** - Complete security architecture
+- **Authentication**: Auth0 JWT for all protected endpoints
+- **Authorization**: User-scoped data access
+- **External APIs**: Rate limiting and caching strategies
+
+### 📦 External Integrations
+- **NHTSA vPIC API**: Vehicle VIN decoding (30-day cache)
+- **Google Maps API**: Station location services (1-hour cache)
+- **Auth0**: Authentication and authorization
+- **PostgreSQL**: Primary data storage
+- **Redis**: Caching layer
+- **MinIO**: Object storage for files
+
+### 🚀 Deployment
+- **[Kubernetes](../k8s/)** - Production deployment manifests
+- **Environment**: Use `.env.example` as template
+- **Services**: All services containerized with health checks
+
+## Documentation Standards
+
+### Feature Documentation
+Each feature capsule maintains comprehensive documentation:
+- **README.md**: Complete API reference, business rules, caching strategy
+- **docs/**: Additional feature-specific documentation
+- **API Examples**: Request/response samples with authentication
+- **Error Handling**: Complete error code documentation
+
+### Code Documentation  
+- **Self-documenting code**: Meaningful names and clear structure
+- **Minimal comments**: Code should be self-explanatory
+- **Type definitions**: Complete TypeScript types in `domain/types.ts`
+
+## Getting Help
+
+### Quick Commands
+```bash
+# Start everything
+make dev
+
+# View all logs
+make logs
+
+# Run all tests
+make test
+
+# Rebuild after changes
+make rebuild
+
+# Access container shells
+make shell-backend
+make shell-frontend
+```
+
+### Health Checks
+- **Frontend**: http://localhost:3000
+- **Backend API**: http://localhost:3001/health
+- **MinIO Console**: http://localhost:9001
+
+### Troubleshooting
+1. **Container Issues**: `make clean && make dev`
+2. **Database Issues**: Check `make logs-backend` for migration errors
+3. **Permission Issues**: Verify USER_ID/GROUP_ID in `.env`
+4. **Port Conflicts**: Ensure ports 3000, 3001, 5432, 6379, 9000, 9001 are available
+
+## Contributing
+
+### Adding New Features
+1. **Generate**: `./scripts/generate-feature-capsule.sh [feature-name]`
+2. **Implement**: Fill out all capsule directories (api, domain, data, etc.)
+3. **Document**: Complete README.md following existing patterns
+4. **Test**: Add comprehensive unit and integration tests
+5. **Migrate**: Create and test database migrations
+
+### Code Standards
+- **Feature Independence**: No shared business logic between features
+- **Docker-First**: All development in containers
+- **Test Coverage**: Unit and integration tests required
+- **Documentation**: AI-friendly documentation for all features
+
+## Architecture Benefits
+
+### For AI Maintenance
+- **Single Directory Context**: Load one feature directory for complete understanding
+- **Self-Contained Features**: No need to trace dependencies across codebase
+- **Consistent Structure**: Every feature follows identical patterns
+- **Complete Documentation**: All information needed is co-located with code
+
+### For Developers
+- **Feature Isolation**: Work on features independently
+- **Predictable Structure**: Same organization across all features
+- **Easy Testing**: Feature-level test isolation
+- **Clear Dependencies**: Explicit feature dependency graph

docs/database-schema.md

@@ -0,0 +1,229 @@
+# Database Schema Overview
+
+Complete database schema for MotoVaultPro Modified Feature Capsule architecture.
+
+## Migration System
+
+### Migration Order (Dependencies)
+1. **vehicles** - Primary entity, no dependencies
+2. **fuel-logs** - Depends on vehicles (vehicle_id FK)
+3. **maintenance** - Depends on vehicles (vehicle_id FK)  
+4. **stations** - Independent feature
+
+### Migration Tracking
+- **Table**: `_migrations`
+- **Purpose**: Tracks executed migrations per feature
+- **Location**: Created by `backend/src/_system/migrations/run-all.ts`
+
+## Core Tables
+
+### vehicles
+Primary entity for all vehicle data.
+
+```sql
+vehicles (
+  id UUID PRIMARY KEY,
+  user_id VARCHAR(255) NOT NULL,
+  vin VARCHAR(17) NOT NULL,
+  make VARCHAR(100),
+  model VARCHAR(100), 
+  year INTEGER,
+  nickname VARCHAR(100),
+  color VARCHAR(50),
+  license_plate VARCHAR(20),
+  odometer_reading INTEGER DEFAULT 0,
+  is_active BOOLEAN DEFAULT true,
+  deleted_at TIMESTAMP WITH TIME ZONE, -- Soft delete
+  created_at TIMESTAMP WITH TIME ZONE,
+  updated_at TIMESTAMP WITH TIME ZONE,
+  
+  CONSTRAINT unique_user_vin UNIQUE(user_id, vin)
+)
+```
+
+**Indexes**: user_id, vin, is_active, created_at
+**Triggers**: auto-update updated_at column
+
+### vin_cache
+Caches NHTSA vPIC API responses for 30 days.
+
+```sql
+vin_cache (
+  vin VARCHAR(17) PRIMARY KEY,
+  make VARCHAR(100),
+  model VARCHAR(100),
+  year INTEGER,
+  engine_type VARCHAR(100),
+  body_type VARCHAR(100),
+  raw_data JSONB,
+  cached_at TIMESTAMP WITH TIME ZONE
+)
+```
+
+**Indexes**: cached_at (for cleanup)
+**TTL**: 30 days (application-managed)
+
+### fuel_logs
+Tracks fuel purchases and efficiency.
+
+```sql
+fuel_logs (
+  id UUID PRIMARY KEY,
+  user_id VARCHAR(255) NOT NULL,
+  vehicle_id UUID NOT NULL REFERENCES vehicles(id),
+  date DATE NOT NULL,
+  odometer_reading INTEGER NOT NULL,
+  gallons DECIMAL(8,3) NOT NULL,
+  price_per_gallon DECIMAL(6,3),
+  total_cost DECIMAL(8,2),
+  station_name VARCHAR(200),
+  notes TEXT,
+  created_at TIMESTAMP WITH TIME ZONE,
+  updated_at TIMESTAMP WITH TIME ZONE
+)
+```
+
+**Foreign Keys**: vehicle_id → vehicles.id
+**Indexes**: user_id, vehicle_id, date
+
+### stations
+Gas station locations and details.
+
+```sql
+stations (
+  id UUID PRIMARY KEY,
+  google_place_id VARCHAR(255) UNIQUE,
+  name VARCHAR(200) NOT NULL,
+  address TEXT,
+  latitude DECIMAL(10,8),
+  longitude DECIMAL(11,8),
+  phone VARCHAR(20),
+  website VARCHAR(255),
+  created_at TIMESTAMP WITH TIME ZONE,
+  updated_at TIMESTAMP WITH TIME ZONE
+)
+```
+
+**External Source**: Google Maps Places API
+**Cache Strategy**: 1 hour TTL via Redis
+
+### maintenance
+Vehicle maintenance records and scheduling.
+
+```sql
+maintenance (
+  id UUID PRIMARY KEY,
+  user_id VARCHAR(255) NOT NULL,
+  vehicle_id UUID NOT NULL REFERENCES vehicles(id),
+  type VARCHAR(100) NOT NULL, -- oil_change, tire_rotation, etc
+  description TEXT,
+  due_date DATE,
+  due_mileage INTEGER,
+  completed_date DATE,
+  completed_mileage INTEGER,
+  cost DECIMAL(8,2),
+  service_location VARCHAR(200),
+  notes TEXT,
+  is_completed BOOLEAN DEFAULT false,
+  created_at TIMESTAMP WITH TIME ZONE,
+  updated_at TIMESTAMP WITH TIME ZONE
+)
+```
+
+**Foreign Keys**: vehicle_id → vehicles.id
+**Indexes**: user_id, vehicle_id, due_date, is_completed
+
+## Relationships
+
+```
+vehicles (1) ──── (many) fuel_logs
+    │
+    └──── (many) maintenance
+
+stations (independent - no FK relationships)
+```
+
+## Data Constraints
+
+### User Data Isolation
+- All user data tables include `user_id` column
+- Application enforces user-scoped queries
+- No cross-user data access possible
+
+### Referential Integrity
+- fuel_logs.vehicle_id → vehicles.id (CASCADE on update, RESTRICT on delete)
+- maintenance.vehicle_id → vehicles.id (CASCADE on update, RESTRICT on delete)
+- Soft deletes on vehicles (deleted_at) preserve referential data
+
+### VIN Validation
+- Exactly 17 characters
+- Cannot contain letters I, O, or Q
+- Application-level checksum validation
+- Unique per user (same VIN can exist for different users)
+
+## Caching Strategy
+
+### Application-Level Caching (Redis)
+- **VIN decodes**: 30 days (key: `vpic:vin:{vin}`)
+- **User vehicle lists**: 5 minutes (key: `vehicles:user:{userId}`)
+- **Station searches**: 1 hour (key: `stations:search:{query}`)
+- **Maintenance upcoming**: 1 hour (key: `maintenance:upcoming:{userId}`)
+
+### Database-Level Caching
+- **vin_cache table**: Persistent 30-day cache for vPIC API results
+- **Cleanup**: Application-managed, removes entries older than 30 days
+
+## Migration Commands
+
+### Run All Migrations
+```bash
+# In container
+npm run migrate:all
+
+# Via Docker
+make migrate
+```
+
+### Run Single Feature
+```bash
+# In container
+npm run migrate:feature vehicles
+
+# Individual features
+npm run migrate:feature fuel-logs
+npm run migrate:feature maintenance  
+npm run migrate:feature stations
+```
+
+### Migration Files
+- **Location**: `backend/src/features/[feature]/migrations/`
+- **Format**: `001_descriptive_name.sql`
+- **Order**: Lexicographic sorting (001, 002, etc.)
+
+## Database Connection
+
+### Development (Docker)
+- **Host**: postgres (container name)
+- **Port**: 5432
+- **Database**: motovaultpro
+- **User**: postgres
+- **Password**: localdev123
+
+### Connection Pool
+- **Implementation**: pg (node-postgres)
+- **Pool Size**: Default (10 connections)
+- **Idle Timeout**: 30 seconds
+- **Location**: `backend/src/core/config/database.ts`
+
+## Backup Strategy
+
+### Development
+- **Docker Volume**: `postgres_data`
+- **Persistence**: Survives container restarts
+- **Reset**: `make clean` removes all data
+
+### Production Considerations
+- Regular pg_dump backups
+- Point-in-time recovery
+- Read replicas for analytics
+- Connection pooling (PgBouncer)

docs/testing.md

@@ -0,0 +1,291 @@
+# Testing Guide
+
+Comprehensive testing strategy for MotoVaultPro Modified Feature Capsule architecture.
+
+## Testing Philosophy
+
+Each feature capsule contains complete, isolated test suites with no cross-feature dependencies.
+
+## Test Structure
+
+### Per Feature Organization
+```
+backend/src/features/[name]/tests/
+├── fixtures/           # Test data
+├── unit/              # Isolated unit tests
+│   ├── [name].service.test.ts
+│   └── [external].client.test.ts
+└── integration/       # Full API tests
+    └── [name].integration.test.ts
+```
+
+## Docker Testing Workflow
+
+### Primary Test Command
+```bash
+# Run all tests in containers
+make test
+```
+
+This executes: `docker-compose exec backend npm test`
+
+### Feature-Specific Testing
+```bash
+# Test single feature (complete isolation)
+make shell-backend
+npm test -- features/vehicles
+
+# Test specific test type
+npm test -- features/vehicles/tests/unit
+npm test -- features/vehicles/tests/integration
+
+# Test with coverage
+npm test -- features/vehicles --coverage
+```
+
+### Test Environment Setup
+1. **Container-Based**: All tests run inside Docker containers
+2. **Test Database**: Isolated test database per feature
+3. **Mock External APIs**: No real API calls during testing
+4. **Cleanup**: Automatic test data cleanup after each test
+
+## Test Types
+
+### Unit Tests
+**Location**: `features/[name]/tests/unit/`
+**Purpose**: Test business logic in isolation
+**Mocking**: All external dependencies mocked
+
+Example: `vehicles.service.test.ts`
+- Tests VIN validation logic
+- Tests vehicle creation with mocked vPIC responses
+- Tests caching behavior with mocked Redis
+- Tests error handling paths
+
+### Integration Tests  
+**Location**: `features/[name]/tests/integration/`
+**Purpose**: Test complete API workflows
+**Database**: Real test database with transactions
+
+Example: `vehicles.integration.test.ts`
+- Tests complete POST /api/vehicles workflow
+- Tests authentication middleware
+- Tests database persistence
+- Tests error responses
+
+### Test Fixtures
+**Location**: `features/[name]/tests/fixtures/`
+**Purpose**: Reusable test data
+**Format**: JSON files with valid test objects
+
+Example: `vehicles.fixtures.json`
+```json
+{
+  "validVehicle": {
+    "vin": "1HGBH41JXMN109186",
+    "nickname": "Test Honda",
+    "color": "Blue"
+  },
+  "vpicResponse": {
+    "Make": "Honda",
+    "Model": "Civic", 
+    "ModelYear": "2021"
+  }
+}
+```
+
+## Testing Commands Reference
+
+### Development Testing
+```bash
+# Enter backend container
+make shell-backend
+
+# Run all tests
+npm test
+
+# Run specific feature
+npm test -- features/vehicles
+npm test -- features/fuel-logs
+npm test -- features/maintenance
+npm test -- features/stations
+
+# Run with file watching
+npm run test:watch
+
+# Run single test file
+npm test -- vehicles.service.test.ts
+
+# Run tests matching pattern
+npm test -- --testNamePattern="VIN validation"
+```
+
+### Coverage Reports
+```bash
+# Generate coverage for specific feature
+npm test -- features/vehicles --coverage
+
+# View coverage report
+open coverage/lcov-report/index.html
+```
+
+### Container Management
+```bash
+# Restart containers with fresh database
+make rebuild
+
+# View test logs
+make logs-backend
+
+# Clean all test data
+make clean && make dev
+```
+
+## Test Configuration
+
+### Jest Configuration
+**File**: `backend/jest.config.js`
+**Setup**: TypeScript support, test environment
+**Coverage**: Exclude node_modules, include src only
+
+### Database Testing
+- **Test DB**: Same as development (motovaultpro)
+- **Transactions**: Each test runs in transaction, rolled back after
+- **Isolation**: Tests cannot interfere with each other
+- **Seeding**: Minimal seed data, test-specific fixtures
+
+### Mock Strategy
+- **External APIs**: Completely mocked (vPIC, Google Maps)
+- **Database**: Real database with transactions
+- **Redis**: Mocked for unit tests, real for integration
+- **Auth**: Mocked JWT tokens for protected endpoints
+
+## Test Data Management
+
+### Fixtures Strategy
+```javascript
+// In test files
+import fixtures from '../fixtures/vehicles.fixtures.json';
+
+describe('Vehicle Service', () => {
+  it('should create vehicle', async () => {
+    const result = await vehicleService.create(
+      fixtures.validVehicle, 
+      'user123'
+    );
+    expect(result.make).toBe('Honda');
+  });
+});
+```
+
+### Database Seeding
+```javascript
+beforeEach(async () => {
+  // Clean slate for each test
+  await db.query('TRUNCATE TABLE vehicles CASCADE');
+  
+  // Insert test-specific data
+  await db.query('INSERT INTO vehicles ...', testData);
+});
+```
+
+## Debugging Tests
+
+### Debug Single Test
+```bash
+# Run specific test with debugging
+npm test -- --testNamePattern="should create vehicle" --verbose
+
+# Debug integration test
+npm test -- features/vehicles/tests/integration --detectOpenHandles
+```
+
+### Common Issues
+
+#### Container Connection Issues
+```bash
+# Check container health
+make logs-backend
+
+# Restart with fresh state
+make rebuild
+```
+
+#### Database Connection Issues
+```bash
+# Check postgres container
+docker-compose logs postgres
+
+# Reset database
+make clean && make dev
+```
+
+#### Test Timeout Issues
+```bash
+# Increase timeout in jest config
+# Or debug hanging connections
+npm test -- --detectOpenHandles
+```
+
+## Continuous Integration
+
+### Pre-commit Testing
+All tests must pass before commits:
+```bash
+# Run linting and tests
+npm run lint
+npm test
+
+# In Docker environment
+make test
+```
+
+### Feature Development Workflow
+1. **Write tests first**: TDD approach preferred
+2. **Run tests continuously**: Use `npm run test:watch`
+3. **Test in containers**: Always verify with `make test`
+4. **Check coverage**: Ensure new code is covered
+5. **Integration last**: Run full test suite before PR
+
+## Test Performance
+
+### Parallel Execution
+- Jest runs tests in parallel by default
+- Feature isolation allows true parallel testing
+- No shared state between feature tests
+
+### Test Speed Optimization
+- **Unit tests**: Fast (< 1 second per test)
+- **Integration tests**: Medium (< 5 seconds per test)
+- **Full suite**: Target < 30 seconds total
+
+### Database Optimization
+- Use transactions for rollback (faster than truncate)
+- Minimal fixture data
+- Avoid complex joins in test setup
+
+## Error Testing Strategy
+
+### Expected Error Cases
+```javascript
+describe('Error Handling', () => {
+  it('should handle invalid VIN', async () => {
+    await expect(
+      vehicleService.create({ vin: 'INVALID' }, 'user123')
+    ).rejects.toThrow('Invalid VIN format');
+  });
+  
+  it('should handle vPIC API failure', async () => {
+    mockVpicClient.decode.mockRejectedValue(new Error('API down'));
+    
+    const result = await vehicleService.create(validVehicle, 'user123');
+    expect(result.make).toBeNull(); // Graceful degradation
+  });
+});
+```
+
+### External Service Failures
+- Mock API failures to test error handling
+- Test timeout scenarios
+- Test network connectivity issues
+- Verify graceful degradation paths