46 KiB
46 KiB
MotoVaultPro Greenfield AI-First Implementation Guide
Executive Summary
This guide provides a comprehensive approach to build MotoVaultPro from the ground up using AI-optimized patterns designed for maximum efficiency in AI-to-AI collaboration and maintenance.
Project Status: Greenfield - Building from scratch with AI-first architecture
Target State: Self-documenting, progressively discoverable codebase with AI-friendly navigation, context-aware documentation, and feature-based modular architecture optimized for AI development from day one.
Key Advantage: No legacy constraints - we can implement the optimal AI structure immediately.
AI-First Project Architecture
Optimal Directory Structure
motovaultpro-v2/
├── AI_README.md # 200-token complete system overview
├── PROJECT_MAP.md # Navigation and quick reference
├── CONVENTIONS.md # Project patterns and standards
├── CLAUDE.md # AI interaction guide (existing)
├── CHANGELOG_AI.md # AI-focused change tracking
├──
├── .ai/ # AI-specific metadata
│ ├── context.json # Context navigation for AI
│ ├── dependencies.yaml # Module dependency graph
│ └── shortcuts.md # Quick command reference
├──
├── backend/
│ ├── src/
│ │ ├── index.ts # Application entry point
│ │ ├── app.ts # Express app configuration
│ │ ├──
│ │ ├── core/ # Stable, critical functionality
│ │ │ ├── config/ # Environment & app configuration
│ │ │ │ ├── database.ts # PostgreSQL connection
│ │ │ │ ├── redis.ts # Redis connection
│ │ │ │ ├── auth0.ts # Auth0 middleware
│ │ │ │ └── minio.ts # MinIO client setup
│ │ │ ├── security/ # Auth and security primitives
│ │ │ │ └── auth.middleware.ts
│ │ │ └── logging/ # Centralized logging
│ │ │ └── logger.ts
│ │ ├──
│ │ ├── features/ # Business logic modules
│ │ │ ├── vehicles/ # Vehicle management feature
│ │ │ │ ├── index.ts # Public API exports
│ │ │ │ ├── vehicle.service.ts # Business logic
│ │ │ │ ├── vehicle.controller.ts # HTTP handlers
│ │ │ │ ├── vehicle.repository.ts # Data access
│ │ │ │ ├── vehicle.types.ts # Type definitions
│ │ │ │ ├── vehicle.validators.ts # Input validation
│ │ │ │ ├── vehicle.routes.ts # Route definitions
│ │ │ │ └── __tests__/ # Feature tests
│ │ │ ├── fuel-logs/ # Fuel tracking feature
│ │ │ │ └── [same structure as vehicles]
│ │ │ ├── maintenance/ # Maintenance tracking feature
│ │ │ │ └── [same structure as vehicles]
│ │ │ └── stations/ # Gas station discovery feature
│ │ │ └── [same structure as vehicles]
│ │ ├──
│ │ ├── shared/ # Reusable utilities
│ │ │ ├── types/ # Shared type definitions
│ │ │ │ ├── common.ts # Common types
│ │ │ │ └── api.ts # API response types
│ │ │ └── utils/ # Pure utility functions
│ │ │ ├── validation.ts
│ │ │ └── formatters.ts
│ │ ├──
│ │ ├── external/ # External API integrations
│ │ │ ├── vpic/ # NHTSA vPIC service
│ │ │ │ ├── vpic.service.ts
│ │ │ │ ├── vpic.types.ts
│ │ │ │ └── __tests__/
│ │ │ └── google-maps/ # Google Maps integration
│ │ │ ├── maps.service.ts
│ │ │ ├── maps.types.ts
│ │ │ └── __tests__/
│ │ └──
│ │ └── database/ # Database layer
│ │ ├── migrations/ # Schema migrations
│ │ │ ├── 001_initial_schema.sql
│ │ │ ├── 002_vin_cache.sql
│ │ │ └── 003_stored_procedures.sql
│ │ └── seeds/ # Test/dev data
│ ├──
│ ├── package.json
│ ├── tsconfig.json
│ ├── Dockerfile
│ └── jest.config.js
├──
├── frontend/
│ ├── src/
│ │ ├── main.tsx # React entry point
│ │ ├── App.tsx # Root component
│ │ ├──
│ │ ├── features/ # Feature-based organization
│ │ │ ├── vehicles/ # Vehicle management UI
│ │ │ │ ├── components/
│ │ │ │ │ ├── VehicleForm/
│ │ │ │ │ ├── VehicleList/
│ │ │ │ │ └── VINDecoder/
│ │ │ │ ├── pages/
│ │ │ │ │ ├── VehiclesPage.tsx
│ │ │ │ │ └── VehicleDetailPage.tsx
│ │ │ │ ├── hooks/
│ │ │ │ │ └── useVehicles.ts
│ │ │ │ ├── api/
│ │ │ │ │ └── vehicles.api.ts
│ │ │ │ └── types/
│ │ │ │ └── vehicle.types.ts
│ │ │ └── [fuel-logs, maintenance, stations with same structure]
│ │ ├──
│ │ ├── shared/ # Shared UI components & utilities
│ │ │ ├── components/ # Reusable UI components
│ │ │ │ ├── common/ # Basic UI elements
│ │ │ │ └── layout/ # Layout components
│ │ │ ├── hooks/ # Shared React hooks
│ │ │ │ ├── useAuth.ts
│ │ │ │ └── useApi.ts
│ │ │ ├── utils/ # Utility functions
│ │ │ └── types/ # Shared TypeScript types
│ │ ├──
│ │ └── core/ # Core application setup
│ │ ├── api/ # API client configuration
│ │ │ └── client.ts # Axios instance
│ │ ├── auth/ # Authentication setup
│ │ │ └── auth0.config.ts
│ │ └── store/ # State management
│ │ └── index.ts # Zustand/Redux store
│ ├──
│ ├── package.json
│ ├── tsconfig.json
│ ├── vite.config.ts
│ ├── Dockerfile
│ └── index.html
├──
├── templates/ # Code generation templates
│ ├── feature/ # Feature module template
│ │ ├── backend/
│ │ │ ├── [feature].service.ts
│ │ │ ├── [feature].controller.ts
│ │ │ ├── [feature].repository.ts
│ │ │ ├── [feature].types.ts
│ │ │ ├── [feature].validators.ts
│ │ │ └── [feature].routes.ts
│ │ └── frontend/
│ │ ├── [Feature]Page.tsx
│ │ ├── [Feature]Form.tsx
│ │ ├── [Feature]List.tsx
│ │ ├── use[Feature].ts
│ │ └── [feature].api.ts
│ ├── external-service/ # External API integration template
│ └── database-migration/ # Database migration template
├──
├── docs/ # Comprehensive documentation
│ ├── ARCHITECTURE.md # System design decisions
│ ├── API.md # API documentation
│ ├── DEPLOYMENT.md # Deployment guide
│ ├── TROUBLESHOOTING.md # Common issues and solutions
│ ├── external-apis/ # External API documentation
│ │ ├── nhtsa-vpic.md
│ │ └── google-maps.md
│ └── diagrams/ # Architecture diagrams
├──
├── k8s/ # Kubernetes configurations
│ └── [existing k8s structure from MOTOVAULTPRO.md]
├──
├── scripts/ # Development & deployment scripts
│ ├── setup.sh # Initial project setup
│ ├── generate-feature.sh # Generate new feature from template
│ └── migrate-db.sh # Database migration runner
├──
├── tests/ # Cross-cutting tests
│ ├── integration/ # API integration tests
│ ├── e2e/ # End-to-end tests
│ └── fixtures/ # Shared test data
├──
├── docker-compose.yml # Local development environment
├── .env.example # Environment variables template
├── Makefile # Common commands
└── README.md # Traditional project documentation
Implementation Phases
Phase 1: Project Foundation Setup (Day 1-2)
Objective: Create the complete AI-optimized project structure with foundation files.
1.1 Initialize Project Structure
Create complete directory tree (all folders from structure above)
Initialize package management:
# Backend setup
cd backend && npm init -y
npm install express typescript @types/node @types/express
npm install --save-dev jest @types/jest ts-jest nodemon
npm install pg redis ioredis minio axios joi
npm install express-jwt jwks-rsa # Auth0 integration
# Frontend setup
cd ../frontend && npm create vite@latest . -- --template react-ts
npm install @auth0/auth0-react axios zustand
npm install --save-dev @testing-library/react @testing-library/jest-dom vitest
1.2 Create Foundation Files
AI_README.md (Essential 200-token overview)
# MotoVaultPro - AI-First Vehicle Management Platform
## AI Quick Start (50 tokens)
Full-stack vehicle management platform built with React/TypeScript frontend, Node.js/Express backend, PostgreSQL database. Integrates NHTSA vPIC for VIN decoding and Google Maps for fuel station discovery. Features Auth0 authentication, Redis caching, MinIO storage. AI-optimized architecture with feature-based modules.
## Navigation Guide
- Start here: PROJECT_MAP.md
- Conventions: CONVENTIONS.md
- Architecture: docs/ARCHITECTURE.md
- AI Context: .ai/context.json
## Critical Context
- Feature-based architecture: backend/src/features/ & frontend/src/features/
- External APIs: NHTSA vPIC (VIN decode), Google Maps (stations)
- Auth0 handles authentication (JWT tokens)
- All external calls use caching (Redis TTL-based)
- Database migrations in backend/src/database/migrations/
## 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/[feature]/index.ts
- Templates: templates/feature/ for new features
PROJECT_MAP.md (AI Navigation Guide)
# MotoVaultPro AI Navigation Map
## System Overview
AI-first vehicle management platform with React frontend and Node.js backend. Features organized into self-contained modules with clear dependencies. External integrations cached via Redis. PostgreSQL for persistence, MinIO for file storage.
## Quick Navigation by Task
### Adding New Feature
1. **Use template**: `scripts/generate-feature.sh [feature-name]`
2. **Backend path**: `backend/src/features/[feature]/`
3. **Frontend path**: `frontend/src/features/[feature]/`
4. **Update dependencies**: `.ai/dependencies.yaml`
5. **Add tests**: Follow existing `__tests__/` patterns
### Debugging Issues
1. **Check logs**: `backend/src/core/logging/logger.ts` output
2. **API issues**: `backend/src/features/[feature]/[feature].controller.ts`
3. **External APIs**: `backend/src/external/[service]/`
4. **Database**: `backend/src/database/migrations/` for schema
5. **Frontend**: `frontend/src/features/[feature]/components/`
### Modifying External APIs
1. **Service layer**: `backend/src/external/[service]/[service].service.ts`
2. **Cache strategy**: Check TTL settings and invalidation logic
3. **Error handling**: Implement circuit breaker patterns
4. **Rate limiting**: Monitor API usage and implement backoff
5. **Types**: Update `[service].types.ts` for API changes
### Database Changes
1. **New migration**: `backend/src/database/migrations/`
2. **Follow naming**: `001_descriptive_name.sql`
3. **Update models**: `backend/src/features/[feature]/[feature].types.ts`
4. **Test migration**: Up AND down migrations
5. **Update seeds**: `backend/src/database/seeds/` if needed
## Feature Module Map
Each feature follows identical structure:
features/[feature]/ ├── index.ts # Public API (exports only) ├── [feature].service.ts # Business logic & external calls ├── [feature].controller.ts # HTTP request/response handling ├── [feature].repository.ts # Database operations ├── [feature].types.ts # TypeScript type definitions ├── [feature].validators.ts # Input validation schemas ├── [feature].routes.ts # Express route definitions └── tests/ # Feature-specific tests ├── unit/ # Service & utility tests ├── integration/ # API endpoint tests └── fixtures/ # Test data
## AI Context Loading Guide
### Always Load (Essential Context)
- `AI_README.md` - System understanding
- `CONVENTIONS.md` - Coding standards
- `backend/src/core/` - Core functionality
- `.ai/context.json` - Task-specific routing
### Conditional Loading (Task-Specific)
- **Vehicle operations**: `backend/src/features/vehicles/`, `backend/src/external/vpic/`
- **Fuel tracking**: `backend/src/features/fuel-logs/`
- **Authentication issues**: `backend/src/core/security/`, Auth0 config
- **Database problems**: `backend/src/database/`, core config
- **Frontend bugs**: `frontend/src/features/[relevant-feature]/`
- **External API issues**: `backend/src/external/[service]/`
## Critical Paths (High-Risk Areas)
### Security-Critical
- `backend/src/core/security/auth.middleware.ts` - JWT validation
- `backend/src/core/config/auth0.ts` - Auth0 configuration
- All `.env` handling in config files
### Performance-Critical
- `backend/src/external/` - External API integrations
- Redis caching logic in all services
- Database queries in repositories
### Business-Critical
- `backend/src/features/vehicles/vehicle.service.ts` - Core vehicle operations
- VIN decoding pipeline (NHTSA integration)
- Fuel cost calculations and tracking
1.3 Create AI Context System
.ai/context.json
{
"version": "1.0.0",
"project_type": "full-stack-app",
"language": "typescript",
"ai_optimized": true,
"context_budget": {
"always_load": [
"AI_README.md",
"CONVENTIONS.md",
"backend/src/core/",
"backend/src/shared/types/"
],
"essential_paths": [
"backend/src/index.ts",
"backend/src/app.ts",
"frontend/src/main.tsx",
"frontend/src/App.tsx"
],
"conditional": {
"if_adding_feature": [
"templates/feature/",
".ai/dependencies.yaml",
"scripts/generate-feature.sh"
],
"if_modifying_vehicles": [
"backend/src/features/vehicles/",
"backend/src/external/vpic/",
"frontend/src/features/vehicles/"
],
"if_modifying_fuel": [
"backend/src/features/fuel-logs/",
"frontend/src/features/fuel-logs/"
],
"if_debugging_auth": [
"backend/src/core/security/",
"backend/src/core/config/auth0.ts",
"frontend/src/core/auth/"
],
"if_external_api_issues": [
"backend/src/external/",
"docs/external-apis/",
"backend/src/core/logging/"
],
"if_database_issues": [
"backend/src/database/",
"backend/src/core/config/database.ts",
"backend/src/features/*/[feature].repository.ts"
],
"if_frontend_issues": [
"frontend/src/features/",
"frontend/src/shared/components/",
"frontend/src/core/"
]
}
},
"common_tasks": {
"add_feature": {
"command": "./scripts/generate-feature.sh [feature-name]",
"template": "templates/feature/",
"checklist": [
"Run feature generation script",
"Implement business logic in service",
"Add database operations to repository",
"Create API endpoints in controller",
"Add route definitions",
"Implement frontend components",
"Write comprehensive tests",
"Update .ai/dependencies.yaml",
"Add feature to main app routes"
],
"auto_created": [
"backend/src/features/[feature]/",
"frontend/src/features/[feature]/",
"Complete test structure"
]
},
"add_external_api": {
"template": "templates/external-service/",
"checklist": [
"Create service in backend/src/external/[service]/",
"Implement caching strategy",
"Add comprehensive error handling",
"Implement rate limiting/backoff",
"Create TypeScript types",
"Write integration tests",
"Document in docs/external-apis/",
"Add environment variables",
"Update .ai/dependencies.yaml"
]
},
"debug_issue": {
"start_with": [
"Check backend/src/core/logging/ output",
"Review TROUBLESHOOTING.md",
"Check recent CHANGELOG_AI.md",
"Run relevant test suite",
"Check external API status if applicable"
],
"common_paths": [
"logs → controllers → services → external APIs",
"frontend errors → API calls → backend logs",
"database issues → migrations → repositories"
]
}
},
"danger_zones": {
"backend/src/core/security/": {
"warning": "Authentication & authorization critical path",
"required_review": true,
"test_command": "npm test:security",
"checklist": [
"Test with valid/invalid JWT tokens",
"Verify Auth0 configuration",
"Check token expiration handling",
"Validate error responses",
"Test rate limiting"
]
},
"backend/src/database/migrations/": {
"warning": "Database schema changes",
"required_review": true,
"test_command": "npm run migrate:test",
"checklist": [
"Test migration UP and DOWN",
"Verify data preservation",
"Check foreign key constraints",
"Test on copy of production data",
"Update repository classes"
]
},
"backend/src/external/": {
"warning": "External API integrations",
"test_command": "npm test:integration",
"checklist": [
"Test with API mocks",
"Verify caching behavior",
"Check error handling",
"Test rate limiting",
"Monitor API usage quotas"
]
}
},
"performance_monitoring": {
"critical_paths": [
"VIN decoding pipeline",
"Fuel station discovery",
"Vehicle data queries",
"Authentication flow"
],
"caching_strategy": {
"vin_decodes": "30 days (rarely change)",
"fuel_stations": "1 hour (prices change)",
"user_vehicles": "5 minutes (frequent updates)",
"auth_tokens": "Follow JWT expiration"
}
}
}
.ai/dependencies.yaml
version: 1.0.0
last_updated: [DATE]
project_status: greenfield
# Module dependency graph for AI understanding
modules:
# Core Infrastructure
backend/src/core/config/:
depends_on: []
consumed_by: ["*"]
critical: true
modification_impact: "critical - full system restart required"
test_command: "npm test:config"
backend/src/core/logging/:
depends_on: ["backend/src/core/config/"]
consumed_by: ["*"]
critical: true
modification_impact: "medium - affects debugging capability"
test_command: "npm test:logging"
backend/src/core/security/:
depends_on: ["backend/src/core/config/", "backend/src/core/logging/"]
consumed_by: ["backend/src/features/*/[feature].controller.ts"]
critical: true
modification_impact: "critical - authentication affects all endpoints"
test_command: "npm test:security"
# Feature Modules (following identical patterns)
backend/src/features/vehicles/:
depends_on: ["backend/src/core/*", "backend/src/external/vpic/", "backend/src/shared/"]
consumed_by: ["backend/src/app.ts", "frontend/src/features/vehicles/"]
critical: true
modification_impact: "high - core business functionality"
test_command: "npm test:features:vehicles"
backend/src/features/fuel-logs/:
depends_on: ["backend/src/core/*", "backend/src/features/vehicles/", "backend/src/shared/"]
consumed_by: ["backend/src/app.ts", "frontend/src/features/fuel-logs/"]
critical: false
modification_impact: "medium - isolated feature"
test_command: "npm test:features:fuel-logs"
# External Integrations
backend/src/external/vpic/:
depends_on: ["backend/src/core/config/", "backend/src/core/logging/"]
consumed_by: ["backend/src/features/vehicles/"]
critical: false
modification_impact: "medium - affects VIN decoding only"
test_command: "npm test:external:vpic"
backend/src/external/google-maps/:
depends_on: ["backend/src/core/config/", "backend/src/core/logging/"]
consumed_by: ["backend/src/features/stations/"]
critical: false
modification_impact: "low - affects fuel station discovery only"
test_command: "npm test:external:maps"
# Frontend Features (mirror backend structure)
frontend/src/features/vehicles/:
depends_on: ["frontend/src/core/", "frontend/src/shared/"]
consumed_by: ["frontend/src/App.tsx"]
critical: true
modification_impact: "medium - user-facing functionality"
test_command: "npm test:frontend:vehicles"
# Architectural rules enforced by AI
rules:
- "Features cannot depend on other features (except vehicles as base)"
- "Core modules cannot depend on features"
- "External services must use caching"
- "All modules must depend on core/config for environment"
- "Frontend features mirror backend structure"
- "No direct database access outside repositories"
# Import cycles to prevent
forbidden_cycles:
- ["core/security", "features/*", "core/security"]
- ["features/vehicles", "features/fuel-logs", "features/vehicles"]
# High-risk modification paths requiring extra validation
high_risk_paths:
- description: "Authentication flow"
modules: ["core/security", "core/config/auth0.ts", "frontend/src/core/auth/"]
test_suite: "npm test:auth:full"
- description: "VIN decoding pipeline"
modules: ["external/vpic", "features/vehicles", "frontend/src/features/vehicles/components/VINDecoder"]
test_suite: "npm test:integration:vin"
- description: "Database operations"
modules: ["database/migrations", "features/*/[feature].repository.ts", "core/config/database.ts"]
test_suite: "npm test:database:full"
Phase 2: Feature Templates & Code Generation (Day 3-4)
Objective: Create comprehensive templates that generate consistent, AI-friendly code.
2.1 Feature Generation Script
scripts/generate-feature.sh
#!/bin/bash
set -e
FEATURE_NAME=$1
if [ -z "$FEATURE_NAME" ]; then
echo "Usage: $0 <feature-name>"
echo "Example: $0 maintenance-logs"
exit 1
fi
FEATURE_PASCAL=$(echo $FEATURE_NAME | sed -r 's/(^|-)([a-z])/\U\2/g')
FEATURE_CAMEL=$(echo $FEATURE_PASCAL | sed 's/^./\l&/')
echo "Generating feature: $FEATURE_NAME"
echo "Pascal case: $FEATURE_PASCAL"
echo "Camel case: $FEATURE_CAMEL"
# Create backend feature structure
BACKEND_DIR="backend/src/features/$FEATURE_NAME"
mkdir -p "$BACKEND_DIR/__tests__/unit"
mkdir -p "$BACKEND_DIR/__tests__/integration"
mkdir -p "$BACKEND_DIR/__tests__/fixtures"
# Generate backend files from templates
sed "s/\[FEATURE_NAME\]/$FEATURE_NAME/g; s/\[FEATURE_PASCAL\]/$FEATURE_PASCAL/g; s/\[FEATURE_CAMEL\]/$FEATURE_CAMEL/g" \
templates/feature/backend/index.template > "$BACKEND_DIR/index.ts"
sed "s/\[FEATURE_NAME\]/$FEATURE_NAME/g; s/\[FEATURE_PASCAL\]/$FEATURE_PASCAL/g; s/\[FEATURE_CAMEL\]/$FEATURE_CAMEL/g" \
templates/feature/backend/service.template > "$BACKEND_DIR/$FEATURE_CAMEL.service.ts"
sed "s/\[FEATURE_NAME\]/$FEATURE_NAME/g; s/\[FEATURE_PASCAL\]/$FEATURE_PASCAL/g; s/\[FEATURE_CAMEL\]/$FEATURE_CAMEL/g" \
templates/feature/backend/controller.template > "$BACKEND_DIR/$FEATURE_CAMEL.controller.ts"
sed "s/\[FEATURE_NAME\]/$FEATURE_NAME/g; s/\[FEATURE_PASCAL\]/$FEATURE_PASCAL/g; s/\[FEATURE_CAMEL\]/$FEATURE_CAMEL/g" \
templates/feature/backend/repository.template > "$BACKEND_DIR/$FEATURE_CAMEL.repository.ts"
sed "s/\[FEATURE_NAME\]/$FEATURE_NAME/g; s/\[FEATURE_PASCAL\]/$FEATURE_PASCAL/g; s/\[FEATURE_CAMEL\]/$FEATURE_CAMEL/g" \
templates/feature/backend/types.template > "$BACKEND_DIR/$FEATURE_CAMEL.types.ts"
sed "s/\[FEATURE_NAME\]/$FEATURE_NAME/g; s/\[FEATURE_PASCAL\]/$FEATURE_PASCAL/g; s/\[FEATURE_CAMEL\]/$FEATURE_CAMEL/g" \
templates/feature/backend/validators.template > "$BACKEND_DIR/$FEATURE_CAMEL.validators.ts"
sed "s/\[FEATURE_NAME\]/$FEATURE_NAME/g; s/\[FEATURE_PASCAL\]/$FEATURE_PASCAL/g; s/\[FEATURE_CAMEL\]/$FEATURE_CAMEL/g" \
templates/feature/backend/routes.template > "$BACKEND_DIR/$FEATURE_CAMEL.routes.ts"
# Create frontend feature structure
FRONTEND_DIR="frontend/src/features/$FEATURE_NAME"
mkdir -p "$FRONTEND_DIR/components"
mkdir -p "$FRONTEND_DIR/pages"
mkdir -p "$FRONTEND_DIR/hooks"
mkdir -p "$FRONTEND_DIR/api"
mkdir -p "$FRONTEND_DIR/types"
mkdir -p "$FRONTEND_DIR/__tests__"
# Generate frontend files from templates
sed "s/\[FEATURE_NAME\]/$FEATURE_NAME/g; s/\[FEATURE_PASCAL\]/$FEATURE_PASCAL/g; s/\[FEATURE_CAMEL\]/$FEATURE_CAMEL/g" \
templates/feature/frontend/Page.template > "$FRONTEND_DIR/pages/${FEATURE_PASCAL}Page.tsx"
sed "s/\[FEATURE_NAME\]/$FEATURE_NAME/g; s/\[FEATURE_PASCAL\]/$FEATURE_PASCAL/g; s/\[FEATURE_CAMEL\]/$FEATURE_CAMEL/g" \
templates/feature/frontend/Form.template > "$FRONTEND_DIR/components/${FEATURE_PASCAL}Form.tsx"
sed "s/\[FEATURE_NAME\]/$FEATURE_NAME/g; s/\[FEATURE_PASCAL\]/$FEATURE_PASCAL/g; s/\[FEATURE_CAMEL\]/$FEATURE_CAMEL/g" \
templates/feature/frontend/List.template > "$FRONTEND_DIR/components/${FEATURE_PASCAL}List.tsx"
sed "s/\[FEATURE_NAME\]/$FEATURE_NAME/g; s/\[FEATURE_PASCAL\]/$FEATURE_PASCAL/g; s/\[FEATURE_CAMEL\]/$FEATURE_CAMEL/g" \
templates/feature/frontend/hook.template > "$FRONTEND_DIR/hooks/use${FEATURE_PASCAL}.ts"
sed "s/\[FEATURE_NAME\]/$FEATURE_NAME/g; s/\[FEATURE_PASCAL\]/$FEATURE_PASCAL/g; s/\[FEATURE_CAMEL\]/$FEATURE_CAMEL/g" \
templates/feature/frontend/api.template > "$FRONTEND_DIR/api/$FEATURE_CAMEL.api.ts"
sed "s/\[FEATURE_NAME\]/$FEATURE_NAME/g; s/\[FEATURE_PASCAL\]/$FEATURE_PASCAL/g; s/\[FEATURE_CAMEL\]/$FEATURE_CAMEL/g" \
templates/feature/frontend/types.template > "$FRONTEND_DIR/types/$FEATURE_CAMEL.types.ts"
echo "✅ Feature $FEATURE_NAME generated successfully!"
echo ""
echo "Next steps:"
echo "1. Implement business logic in backend/src/features/$FEATURE_NAME/$FEATURE_CAMEL.service.ts"
echo "2. Add database operations in $FEATURE_CAMEL.repository.ts"
echo "3. Customize React components in frontend/src/features/$FEATURE_NAME/components/"
echo "4. Add feature routes to backend/src/app.ts and frontend/src/App.tsx"
echo "5. Write tests and update .ai/dependencies.yaml"
2.2 Comprehensive Templates
templates/feature/backend/service.template (AI-optimized service pattern)
/**
* @ai-summary Handles [FEATURE_NAME] business logic and external integrations
* @ai-examples backend/src/features/[FEATURE_NAME]/__tests__/fixtures/
* @critical-context Requires authentication, uses caching for external calls
*/
import { [FEATURE_PASCAL]Repository } from './[FEATURE_CAMEL].repository';
import {
[FEATURE_PASCAL]Input,
[FEATURE_PASCAL]Output,
[FEATURE_PASCAL]Error,
Create[FEATURE_PASCAL]Request,
Update[FEATURE_PASCAL]Request
} from './[FEATURE_CAMEL].types';
import { logger } from '../../core/logging/logger';
import { CacheService } from '../../shared/utils/cache.service';
export class [FEATURE_PASCAL]Service {
private readonly cachePrefix = '[FEATURE_NAME]';
private readonly cacheTTL = 300; // 5 minutes
constructor(
private repository: [FEATURE_PASCAL]Repository,
private cacheService: CacheService
) {}
/**
* HANDLES: Creates new [FEATURE_NAME] record with validation
* THROWS: ValidationError, DuplicateError, DatabaseError
* SIDE_EFFECTS: Database insert, cache invalidation
* AUTH_REQUIRED: true
*/
async create[FEATURE_PASCAL](
data: Create[FEATURE_PASCAL]Request,
userId: string
): Promise<[FEATURE_PASCAL]Output> {
try {
logger.info('[FEATURE_PASCAL]Service.create[FEATURE_PASCAL] started', {
userId,
dataKeys: Object.keys(data)
});
// 1. Validate business rules
await this.validateCreate[FEATURE_PASCAL](data, userId);
// 2. Transform input to domain model
const [FEATURE_CAMEL]Data = this.transformCreate[FEATURE_PASCAL](data, userId);
// 3. Persist to database
const created[FEATURE_PASCAL] = await this.repository.create(
[FEATURE_CAMEL]Data
);
// 4. Invalidate relevant cache entries
await this.invalidate[FEATURE_PASCAL]Cache(userId);
// 5. Transform to output format
const result = this.transformTo[FEATURE_PASCAL]Output(created[FEATURE_PASCAL]);
logger.info('[FEATURE_PASCAL]Service.create[FEATURE_PASCAL] completed', {
userId,
[FEATURE_CAMEL]Id: result.id
});
return result;
} catch (error) {
logger.error('[FEATURE_PASCAL]Service.create[FEATURE_PASCAL] failed', {
error: error.message,
userId,
data
});
if (error instanceof ValidationError) {
throw error;
}
throw new [FEATURE_PASCAL]Error(`Failed to create [FEATURE_NAME]: ${error.message}`);
}
}
/**
* HANDLES: Retrieves [FEATURE_NAME] records for user with caching
* THROWS: DatabaseError, NotFoundError
* SIDE_EFFECTS: Cache read/write
* AUTH_REQUIRED: true
*/
async get[FEATURE_PASCAL]sByUser(userId: string): Promise<[FEATURE_PASCAL]Output[]> {
const cacheKey = `${this.cachePrefix}:user:${userId}`;
try {
// 1. Check cache first
const cached = await this.cacheService.get<[FEATURE_PASCAL]Output[]>(cacheKey);
if (cached) {
logger.debug('[FEATURE_PASCAL]Service cache hit', { userId, cacheKey });
return cached;
}
// 2. Query database
const [FEATURE_CAMEL]s = await this.repository.findByUserId(userId);
// 3. Transform to output format
const result = [FEATURE_CAMEL]s.map(item =>
this.transformTo[FEATURE_PASCAL]Output(item)
);
// 4. Cache successful result
await this.cacheService.set(cacheKey, result, this.cacheTTL);
logger.info('[FEATURE_PASCAL]Service.get[FEATURE_PASCAL]sByUser completed', {
userId,
count: result.length
});
return result;
} catch (error) {
logger.error('[FEATURE_PASCAL]Service.get[FEATURE_PASCAL]sByUser failed', {
error: error.message,
userId
});
throw new [FEATURE_PASCAL]Error(`Failed to get [FEATURE_NAME]s: ${error.message}`);
}
}
// Private helper methods following AI-friendly patterns
private async validateCreate[FEATURE_PASCAL](
data: Create[FEATURE_PASCAL]Request,
userId: string
): Promise<void> {
// Implement validation logic
// Check business rules
// Verify user permissions
// Validate foreign key relationships
}
private transformCreate[FEATURE_PASCAL](
data: Create[FEATURE_PASCAL]Request,
userId: string
): [FEATURE_PASCAL]Input {
return {
...data,
userId,
createdAt: new Date(),
updatedAt: new Date()
} as [FEATURE_PASCAL]Input;
}
private transformTo[FEATURE_PASCAL]Output(item: [FEATURE_PASCAL]): [FEATURE_PASCAL]Output {
return {
id: item.id,
userId: item.userId,
createdAt: item.createdAt,
updatedAt: item.updatedAt,
// Add other fields as needed
} as [FEATURE_PASCAL]Output;
}
private async invalidate[FEATURE_PASCAL]Cache(userId: string): Promise<void> {
const cacheKey = `${this.cachePrefix}:user:${userId}`;
await this.cacheService.del(cacheKey);
}
}
// Custom error class
export class [FEATURE_PASCAL]Error extends Error {
constructor(message: string) {
super(message);
this.name = '[FEATURE_PASCAL]Error';
}
}
Phase 3: Core Infrastructure Implementation (Day 5-7)
Objective: Implement the core system components using AI-optimized patterns.
3.1 Backend Core Setup
backend/src/core/config/database.ts
/**
* @ai-summary PostgreSQL connection setup with connection pooling
* @ai-details docs/database/CONNECTION_MANAGEMENT.md
* @critical-context Connection pooling, automatic reconnection, query logging
*/
import { Pool, PoolConfig } from 'pg';
import { logger } from '../logging/logger';
const poolConfig: PoolConfig = {
host: process.env.DB_HOST || 'localhost',
port: parseInt(process.env.DB_PORT || '5432'),
database: process.env.DB_NAME || 'motovaultpro',
user: process.env.DB_USER || 'postgres',
password: process.env.DB_PASSWORD || '',
ssl: process.env.NODE_ENV === 'production' ? { rejectUnauthorized: false } : false,
max: parseInt(process.env.DB_POOL_MAX || '10'),
min: parseInt(process.env.DB_POOL_MIN || '2'),
idleTimeoutMillis: parseInt(process.env.DB_IDLE_TIMEOUT || '30000'),
connectionTimeoutMillis: parseInt(process.env.DB_CONNECTION_TIMEOUT || '10000'),
};
export const pool = new Pool(poolConfig);
// Connection event handlers for monitoring
pool.on('connect', (client) => {
logger.info('Database client connected', {
totalCount: pool.totalCount,
idleCount: pool.idleCount
});
});
pool.on('error', (err) => {
logger.error('Database pool error', { error: err.message });
});
pool.on('remove', () => {
logger.info('Database client removed', {
totalCount: pool.totalCount,
idleCount: pool.idleCount
});
});
// Graceful shutdown handler
process.on('SIGTERM', async () => {
logger.info('SIGTERM received, closing database pool');
await pool.end();
process.exit(0);
});
export default pool;
backend/src/core/logging/logger.ts
/**
* @ai-summary Structured logging with correlation IDs and log levels
* @ai-details docs/logging/STRUCTURED_LOGGING.md
* @critical-context All logs include correlation ID, user context, performance metrics
*/
import winston from 'winston';
const isDevelopment = process.env.NODE_ENV === 'development';
export const logger = winston.createLogger({
level: process.env.LOG_LEVEL || (isDevelopment ? 'debug' : 'info'),
format: winston.format.combine(
winston.format.timestamp(),
winston.format.errors({ stack: true }),
winston.format.json(),
winston.format.printf(({ timestamp, level, message, ...meta }) => {
const logEntry = {
timestamp,
level,
message,
service: 'motovaultpro-backend',
environment: process.env.NODE_ENV,
version: process.env.APP_VERSION,
...meta
};
return JSON.stringify(logEntry);
})
),
defaultMeta: {
service: 'motovaultpro-backend'
},
transports: [
new winston.transports.Console({
format: isDevelopment
? winston.format.combine(
winston.format.colorize(),
winston.format.simple()
)
: winston.format.json()
})
]
});
// Add file transport for production
if (process.env.NODE_ENV === 'production') {
logger.add(new winston.transports.File({
filename: 'logs/error.log',
level: 'error',
maxsize: 10485760, // 10MB
maxFiles: 5
}));
logger.add(new winston.transports.File({
filename: 'logs/combined.log',
maxsize: 10485760, // 10MB
maxFiles: 5
}));
}
export default logger;
3.2 Frontend Core Setup
frontend/src/core/api/client.ts
/**
* @ai-summary Axios client with Auth0 integration and error handling
* @ai-details docs/api/CLIENT_CONFIGURATION.md
* @critical-context Automatic token refresh, request/response logging, error transformation
*/
import axios, { AxiosInstance, AxiosRequestConfig, AxiosResponse } from 'axios';
import { useAuth0 } from '@auth0/auth0-react';
const baseURL = import.meta.env.VITE_API_BASE_URL || 'http://localhost:3001/api';
// Create axios instance
export const apiClient: AxiosInstance = axios.create({
baseURL,
timeout: 10000,
headers: {
'Content-Type': 'application/json',
},
});
// Request interceptor for adding auth token
apiClient.interceptors.request.use(
async (config: AxiosRequestConfig) => {
// Note: In actual implementation, you'd get token from Auth0 context
// This is a placeholder for the pattern
const token = localStorage.getItem('access_token');
if (token) {
config.headers = {
...config.headers,
Authorization: `Bearer ${token}`,
};
}
// Add correlation ID for request tracking
config.headers['X-Correlation-ID'] = crypto.randomUUID();
console.log(`API Request: ${config.method?.toUpperCase()} ${config.url}`, {
correlationId: config.headers['X-Correlation-ID'],
params: config.params,
});
return config;
},
(error) => {
console.error('API Request Error:', error);
return Promise.reject(error);
}
);
// Response interceptor for error handling
apiClient.interceptors.response.use(
(response: AxiosResponse) => {
console.log(`API Response: ${response.status} ${response.config.url}`, {
correlationId: response.config.headers['X-Correlation-ID'],
duration: Date.now() - (response.config as any).startTime,
});
return response;
},
async (error) => {
const { response, config } = error;
console.error('API Response Error:', {
status: response?.status,
url: config?.url,
correlationId: config?.headers['X-Correlation-ID'],
error: response?.data?.error || error.message,
});
// Handle specific error cases
if (response?.status === 401) {
// Token expired or invalid
localStorage.removeItem('access_token');
window.location.href = '/login';
}
// Transform error to consistent format
const apiError = {
status: response?.status || 500,
message: response?.data?.error || error.message || 'An unexpected error occurred',
correlationId: config?.headers['X-Correlation-ID'],
};
return Promise.reject(apiError);
}
);
export default apiClient;
Phase 4: Feature Implementation (Day 8-12)
Objective: Implement each feature using the generated templates and AI-optimized patterns.
4.1 Implementation Order & Dependencies
- Vehicles Feature (Days 8-9) - Foundation feature
- External APIs (Day 10) - NHTSA vPIC and Google Maps
- Fuel Logs Feature (Day 11) - Depends on vehicles
- Maintenance Feature (Day 12) - Depends on vehicles
- Stations Feature (Day 12) - Independent feature
4.2 Success Criteria for Each Feature
Per Feature Checklist:
- Backend service, controller, repository implemented
- Frontend components, hooks, API client implemented
- Comprehensive test coverage (unit + integration)
- External API integrations cached appropriately
- Database migrations created and tested
- Documentation updated in feature README
- Added to main application routing
- Error handling follows established patterns
Phase 5: Testing & Documentation (Day 13-14)
Objective: Comprehensive testing and AI-optimized documentation.
5.1 Testing Strategy
Test Structure (mirrors feature structure)
__tests__/
├── unit/ # Individual function/method tests
│ ├── services/
│ ├── controllers/
│ └── utils/
├── integration/ # API endpoint tests with database
│ ├── vehicles.test.ts
│ ├── fuel-logs.test.ts
│ └── auth.test.ts
├── external/ # External API integration tests (mocked)
│ ├── vpic.test.ts
│ └── google-maps.test.ts
└── e2e/ # End-to-end user flow tests
├── vehicle-management.test.ts
└── fuel-tracking.test.ts
5.2 AI-Optimized Documentation
docs/ARCHITECTURE.md
# MotoVaultPro Architecture Overview
## System Design Philosophy
AI-first architecture prioritizing:
- **Self-documenting code** through naming and structure
- **Progressive disclosure** of complexity
- **Feature isolation** with clear dependencies
- **Consistent patterns** across all modules
- **Context-efficient navigation** for AI agents
## Core Architectural Patterns
### Feature-Based Organization
Each feature is completely self-contained:
- Business logic in service layer
- Data access in repository layer
- HTTP handling in controller layer
- Type definitions co-located with feature
- Tests mirror implementation structure
### External API Integration Pattern
All external APIs follow identical structure:
- Service class with caching
- Error handling with circuit breakers
- Rate limiting and backoff
- Comprehensive logging
- Mock-friendly for testing
### Security Architecture
- Auth0 handles all authentication
- JWT tokens validated on every request
- User context available throughout request lifecycle
- No sensitive data in logs or cache
- Environment-based configuration
## Database Design
### Schema Organization
- Core entities: users, vehicles, fuel_logs, maintenance_logs
- Audit fields on all tables (created_at, updated_at, created_by)
- Foreign key constraints enforced
- Indexes on frequently queried columns
- Migration-based schema evolution
### Caching Strategy
- External API responses: Appropriate TTL based on data volatility
- User data: Short TTL (5 minutes) for consistency
- Static data: Long TTL (30 days) for performance
- Cache invalidation on data mutations
## Frontend Architecture
### Component Organization
- Feature-based component grouping
- Shared components for common UI patterns
- Custom hooks for business logic
- API clients co-located with features
- Type definitions shared between frontend and backend
### State Management
- Local state for UI-only concerns
- Global state for cross-feature data
- Server state managed by API clients
- Authentication state managed by Auth0
Implementation Timeline
Week 1: Foundation (Days 1-7)
- Days 1-2: Project structure setup, foundation files
- Days 3-4: Templates and code generation scripts
- Days 5-7: Core infrastructure implementation
Week 2: Feature Development (Days 8-14)
- Days 8-9: Vehicles feature (backend + frontend)
- Day 10: External API integrations (vPIC, Google Maps)
- Day 11: Fuel logs feature
- Day 12: Maintenance and stations features
- Days 13-14: Testing, documentation, refinement
Success Metrics
Quantitative Goals
- AI can understand system architecture in under 200 tokens
- Feature generation script creates working code in under 2 minutes
- AI requires 70% fewer file reads for common tasks vs traditional structure
- New feature implementation follows consistent patterns automatically
- Test coverage above 85% for all business logic
Qualitative Goals
- AI can navigate codebase without human guidance
- Code review focuses on business logic vs structure
- New developers understand patterns intuitively
- Feature development velocity increases over time
- Technical debt accumulates slower due to consistent patterns
Long-term Benefits
For AI Collaboration
- Context Efficiency: AI loads only relevant code for each task
- Pattern Recognition: Consistent structure enables better code generation
- Self-Documenting: Code explains itself through naming and organization
- Progressive Discovery: AI can start with overview and dive deeper as needed
For Human Developers
- Reduced Cognitive Load: Clear structure reduces context switching
- Faster Onboarding: New developers can follow established patterns
- Better Maintainability: Consistent patterns make changes predictable
- Enhanced Productivity: Templates and scripts automate repetitive tasks
For System Evolution
- Scalable Architecture: Feature isolation supports team scaling
- Technology Migration: Clear boundaries enable gradual technology updates
- Performance Optimization: Well-defined layers enable targeted optimizations
- Quality Assurance: Consistent patterns enable automated quality checks
Next Steps
- Begin Phase 1: Create project structure and foundation files
- Setup Development Environment: Docker Compose for local development
- Configure CI/CD: GitHub Actions for testing and deployment
- Team Training: Onboard development team to AI-first patterns
- Iterative Refinement: Improve templates and patterns based on usage
This greenfield approach gives us the unique opportunity to build the ideal AI-collaborative codebase from day one, setting the foundation for efficient AI-to-AI development throughout the project lifecycle.