motovaultpro/docs

MotoVaultPro Documentation

Complete documentation for the MotoVaultPro vehicle management platform using Modified Feature Capsule architecture.

Quick Navigation

🚀 Getting Started

• AI Project Guide - Complete AI-friendly project overview and navigation
• Security Architecture - Authentication, authorization, and security considerations

🏗️ Architecture

• Architecture Directory - Detailed architectural documentation
• Feature Capsules - Each feature has complete documentation in backend/src/features/[name]/README.md:
  • Vehicles - Primary entity with VIN decoding
  • Fuel Logs - Fuel tracking and analytics
  • Maintenance - Vehicle maintenance scheduling
  • Stations - Gas station location services

🔧 Development

• Docker Setup - Complete containerized development environment
• Makefile Commands - All available development commands
• Backend Package - Scripts and dependencies
• Frontend Package - 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 - Database schema management
• Feature Migrations: Each feature manages its own schema in migrations/ directory
• Migration Order: vehicles → fuel-logs → maintenance → stations

🔐 Security

• Security Overview - 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 - 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

# 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