166 lines
5.0 KiB
Markdown
166 lines
5.0 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.
|
|
- This is a production only application architecture.
|
|
- Always assume this application is going into production when you are done. All security and linting should pass.
|
|
|
|
## 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 Migrations
|
|
```bash
|
|
# All features (in dependency order)
|
|
npm run migrate:all
|
|
|
|
# From project root using Docker
|
|
make migrate
|
|
```
|
|
Note: Single-feature migration is not implemented yet. Run the full migration set.
|
|
|
|
### Testing Strategy
|
|
```bash
|
|
# Run all tests (from project root)
|
|
make test
|
|
|
|
# In backend container shell
|
|
make shell-backend
|
|
npm test # all tests
|
|
npm test -- features/[feature-name]
|
|
npm test -- features/[feature-name]/tests/integration
|
|
```
|
|
|
|
### 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**: `make dev` builds and runs the stack
|
|
- **Testing**: `make test` runs backend tests in the container
|
|
- **Rebuilding**: `make rebuild` for code/dependency changes
|
|
- **Package changes**: Rebuild backend/frontend containers as needed
|
|
|
|
## Authentication (Current State)
|
|
- Backend uses a Fastify auth plugin that injects a mock user in development/test.
|
|
- JWT validation via Auth0 is planned; production configuration will enforce it.
|
|
|
|
## 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)
|