# 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
Only use docker containers for testing. Never install local tools if they do not exist already. 

### 4. Development Environment (Docker-first)
```bash
# One-time setup (copies .env and builds containers)
make setup

# Start/rebuild the full environment
make dev
```

Note: The frontend runs behind nginx with HTTPS in dev. You must provide local certificates in `./certs` (see SSL section below) or the frontend container will fail to start.

### 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
# Run all migrations (inside containers)
make migrate

# Run all backend tests (inside containers)
make test

# Run tests for a specific feature (from backend container shell)
make shell-backend
npm test -- features/vehicles

# 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); tests pending
- **maintenance**: Scaffolded (depends on vehicles) 
- **stations**: Partial (Google Maps integration)

## SSL for Frontend (Local Dev)
- Place `motovaultpro.com.crt` and `motovaultpro.com.key` in `./certs`.
- To generate self-signed dev certs:
  ```bash
  openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
    -keyout certs/motovaultpro.com.key \
    -out certs/motovaultpro.com.crt \
    -subj "/CN=localhost"
  ```
- Access frontend at `https://localhost:3443` (HTTP on `:3000` redirects to HTTPS).

## 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