155 lines
4.6 KiB
Markdown
155 lines
4.6 KiB
Markdown
# MotoVaultPro - AI-First Modified Feature Capsule Architecture
|
|
|
|
## AI Quick Start (50 tokens)
|
|
Vehicle management platform using Modified Feature Capsules. Each feature in backend/src/features/[name]/ is 100% self-contained with API, domain, data, migrations, external integrations, tests, and docs. Single directory load gives complete context. No shared business logic, only pure utilities in shared-minimal/.
|
|
|
|
## Architecture Philosophy
|
|
Each feature is a complete, self-contained capsule. Load ONE directory for 100% context. Evaluate every feature if it should be in it's own Docker container. This is a microservices based archiecture where production will be run on k8s.
|
|
|
|
## Navigation & Quick Tasks
|
|
|
|
### AI Workflow
|
|
- **Feature work**: Load entire `backend/src/features/[feature]/`
|
|
- **Cross-feature**: Load each feature's `index.ts` and `README.md`
|
|
- **System tools**: `backend/src/_system/` for migrations and schema
|
|
- **AI metadata**: `.ai/` directory
|
|
- **Documentation**: See `docs/README.md` for complete documentation index
|
|
|
|
### Working on a Feature
|
|
```bash
|
|
# Load complete context
|
|
cd backend/src/features/[feature-name]/
|
|
|
|
# Everything is here:
|
|
# - API endpoints (api/)
|
|
# - Business logic (domain/)
|
|
# - Database operations (data/)
|
|
# - Schema migrations (migrations/)
|
|
# - External integrations (external/)
|
|
# - All tests (tests/)
|
|
# - Documentation (docs/)
|
|
```
|
|
|
|
### Adding New Feature
|
|
```bash
|
|
./scripts/generate-feature-capsule.sh [feature-name]
|
|
# Creates complete capsule structure with all subdirectories
|
|
```
|
|
|
|
### Running Feature Migrations
|
|
```bash
|
|
# Single feature
|
|
npm run migrate:feature [feature-name]
|
|
|
|
# All features (respects dependencies)
|
|
npm run migrate:all
|
|
```
|
|
|
|
### Testing Strategy
|
|
```bash
|
|
# Test single feature (complete isolation)
|
|
npm test -- features/[feature-name]
|
|
|
|
# Test feature integration
|
|
npm test -- features/[feature-name]/tests/integration
|
|
|
|
# Test everything
|
|
npm test
|
|
```
|
|
|
|
### Docker Development Workflow
|
|
```bash
|
|
# Start development environment
|
|
make dev
|
|
|
|
# Rebuild after code/dependency changes
|
|
make rebuild
|
|
|
|
# View logs
|
|
make logs
|
|
|
|
# Run tests in containers
|
|
make test
|
|
|
|
# Open container shells
|
|
make shell-backend
|
|
make shell-frontend
|
|
```
|
|
|
|
## Feature Capsule Structure
|
|
```
|
|
features/[name]/
|
|
├── README.md # Feature overview & API
|
|
├── index.ts # Public exports only
|
|
├── api/ # HTTP layer
|
|
├── domain/ # Business logic
|
|
├── data/ # Database layer
|
|
├── migrations/ # Feature's schema
|
|
├── external/ # Feature's external APIs
|
|
├── events/ # Event handlers
|
|
├── tests/ # All tests
|
|
└── docs/ # Documentation
|
|
```
|
|
|
|
## Feature Capsules
|
|
|
|
### Vehicles (Primary Entity)
|
|
- **Path**: `backend/src/features/vehicles/`
|
|
- **External**: NHTSA vPIC for VIN decoding
|
|
- **Dependencies**: None (base feature)
|
|
- **Cache**: VIN lookups for 30 days
|
|
- **Status**: Complete implementation
|
|
|
|
### Fuel Logs
|
|
- **Path**: `backend/src/features/fuel-logs/`
|
|
- **External**: None
|
|
- **Dependencies**: Vehicles (for vehicle_id)
|
|
- **Cache**: User's logs for 5 minutes
|
|
- **Status**: Partial implementation
|
|
|
|
### Maintenance
|
|
- **Path**: `backend/src/features/maintenance/`
|
|
- **External**: None
|
|
- **Dependencies**: Vehicles (for vehicle_id)
|
|
- **Cache**: Upcoming maintenance for 1 hour
|
|
- **Status**: Scaffolded
|
|
|
|
### Stations
|
|
- **Path**: `backend/src/features/stations/`
|
|
- **External**: Google Maps API
|
|
- **Dependencies**: None (independent)
|
|
- **Cache**: Station searches for 1 hour
|
|
- **Status**: Partial implementation
|
|
|
|
## Primary Entry Points
|
|
- **Backend**: `backend/src/index.ts` → `backend/src/app.ts`
|
|
- **Frontend**: `frontend/src/main.tsx` → `frontend/src/App.tsx`
|
|
- **Features**: `backend/src/features/[name]/index.ts`
|
|
|
|
## Development Environment
|
|
All development happens in Docker containers:
|
|
- **Development**: Dockerfile.dev with npm install during container build
|
|
- **Testing**: make test runs tests in container
|
|
- **Rebuilding**: make rebuild for code changes
|
|
- **Package changes**: Container rebuild required
|
|
|
|
## External Services
|
|
- **PostgreSQL**: Primary database (port 5432)
|
|
- **Redis**: Caching layer (port 6379)
|
|
- **MinIO**: Object storage (port 9000/9001)
|
|
- **NHTSA vPIC**: VIN decoding API
|
|
- **Google Maps**: Station location API
|
|
|
|
## Quick Health Check
|
|
```bash
|
|
# Frontend: http://localhost:3000
|
|
# Backend: http://localhost:3001/health
|
|
# MinIO Console: http://localhost:9001
|
|
```
|
|
|
|
## Migration Dependencies
|
|
Features must be migrated in dependency order:
|
|
1. **vehicles** (base feature)
|
|
2. **fuel-logs** (depends on vehicles)
|
|
3. **maintenance** (depends on vehicles)
|
|
4. **stations** (independent) |