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

### 📦 Services & Integrations

#### MVP Platform Services
- See **Vehicles API (Authoritative)**: [VEHICLES-API.md](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](../k8s/)** - 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
```bash
# 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