128 lines
5.0 KiB
Markdown
128 lines
5.0 KiB
Markdown
# MotoVaultPro Documentation
|
|
|
|
Complete documentation for the MotoVaultPro vehicle management platform using Modified Feature Capsule architecture.
|
|
|
|
## 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
|
|
- **Feature Capsules** - Each feature has complete documentation in `backend/src/features/[name]/README.md`:
|
|
- **[Vehicles](../backend/src/features/vehicles/README.md)** - Primary entity with VIN decoding
|
|
- **[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
|
|
|
|
### 📦 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](../k8s/)** - 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
|
|
```bash
|
|
# 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 |