Improved docs for future AI

2025-08-23 10:20:03 -05:00
parent 6683f1eeff
commit dc26c68d6f
10 changed files with 1089 additions and 128 deletions
--- a/AI_PROJECT_GUIDE.md
+++ b/AI_PROJECT_GUIDE.md
@@ -0,0 +1,155 @@
+# 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.
+
+## 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)