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 (Production-Only)

# One-time setup (copies .env and builds containers)
make setup

# Start/rebuild the full environment
make dev

Production-Only Development: This application runs in production mode only. All development happens with production builds and configurations.

5. Key Principles

• Production-Only: All development uses production builds and configuration
• 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

# 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 (Production Development)

• Place motovaultpro.com.crt and motovaultpro.com.key in ./certs.
• To generate self-signed certs for production development:

  openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
    -keyout certs/motovaultpro.com.key \
    -out certs/motovaultpro.com.crt \
    -subj "/CN=motovaultpro.com"
  

• Access frontend at: https://motovaultpro.com (requires DNS or hosts file entry)
• Hosts file setup: Add 127.0.0.1 motovaultpro.com to /etc/hosts
• HTTP requests redirect to HTTPS automatically.

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 production-only Docker 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