motovaultpro/docs

MotoVaultPro Documentation

Complete documentation for the MotoVaultPro distributed microservices platform with Modified Feature Capsule application layer and MVP Platform Services.

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
• Platform Services Guide - MVP Platform Services architecture and development
• Vehicles API (Authoritative) - Vehicles platform service + app integration
• Application Feature Capsules - Each feature has complete documentation in backend/src/features/[name]/README.md:
  • Vehicles - Platform service consumer for vehicle management
  • 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

📦 Services & Integrations

MVP Platform Services

• See Vehicles API (Authoritative): VEHICLES-API.md
• Future Platform Services: Analytics, notifications, payments, document management

Application Services

• PostgreSQL: Application data storage
• Redis: Application caching layer
• MinIO: Object storage for files

External APIs

• Google Maps API: Station location services (1-hour cache)
• Auth0: Authentication and authorization

🚀 Deployment

• Kubernetes - Production deployment manifests
• Environment: Ensure a valid .env exists at project root
• 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 full microservices environment
make start

# View all logs
make logs

# View platform service logs
make logs-platform-vehicles

# Run all tests
make test

# Rebuild after changes
make rebuild

# Access container shells
make shell-backend           # Application service
make shell-frontend
make shell-platform-vehicles # Platform service

Health Checks

Application Services

• Frontend: http://localhost:3000
• Backend API: http://localhost:3001/health
• MinIO Console: http://localhost:9001

Platform Services

• Platform Vehicles API: http://localhost:8000/health
• Platform Vehicles Docs: http://localhost:8000/docs

Troubleshooting

1. Container Issues: make clean && make start
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

• Service Independence: Platform services are completely independent
• Feature Independence: No shared business logic between application features
• Docker-First: All development in containers
• Test Coverage: Unit and integration tests required
• Documentation: AI-friendly documentation for all services and features

Architecture Benefits

For AI Maintenance

• Service-Level Context: Load platform service docs OR feature directory for complete understanding
• Self-Contained Components: No need to trace dependencies across service boundaries
• Consistent Patterns: Platform services and application features follow consistent structures
• Complete Documentation: All information needed is co-located with service/feature code
• Clear Boundaries: Explicit separation between platform and application concerns

For Developers

• Service Independence: Work on platform services and application features independently
• Microservices Benefits: Independent deployment, scaling, and technology choices
• Predictable Structure: Same organization patterns across services and features
• Easy Testing: Service-level and feature-level test isolation
• Clear Dependencies: Explicit service communication patterns