47c5676498
Some checks failed
Deploy to Staging / Build Images (pull_request) Failing after 7m4s
Deploy to Staging / Deploy to Staging (pull_request) Has been skipped
Deploy to Staging / Verify Staging (pull_request) Has been skipped
Deploy to Staging / Notify Staging Ready (pull_request) Has been skipped
Deploy to Staging / Notify Staging Failure (pull_request) Successful in 7s
Add engine abstraction tests and update docs to reflect PaddleOCR primary architecture with optional Google Vision cloud fallback. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
317 lines
11 KiB
JSON
317 lines
11 KiB
JSON
{
|
|
"version": "6.2.0",
|
|
"architecture": "9-container",
|
|
"repository": {
|
|
"host": "gitea",
|
|
"owner": "egullickson",
|
|
"repo": "motovaultpro",
|
|
"url": "https://git.motovaultpro.com",
|
|
"default_branch": "main"
|
|
},
|
|
"ai_quick_start": {
|
|
"load_order": [
|
|
".ai/context.json (this file) - architecture and metadata",
|
|
".ai/workflow-contract.json - sprint workflow for issue tracking",
|
|
".ai/WORKFLOW-PROMPTS.md - ready-to-use prompts for common tasks",
|
|
"docs/README.md - documentation hub"
|
|
],
|
|
"work_modes": {
|
|
"feature_work": "backend/src/features/{feature}/ (start with README.md)",
|
|
"frontend_work": "frontend/README.md",
|
|
"core_backend": "backend/src/core/README.md"
|
|
},
|
|
"commands": {
|
|
"setup": "make setup | start | rebuild | migrate | logs",
|
|
"shells": "make shell-backend | make shell-frontend",
|
|
"database": "make db-shell-app"
|
|
},
|
|
"docs_hubs": {
|
|
"main": "docs/README.md",
|
|
"testing": "docs/TESTING.md",
|
|
"database": "docs/DATABASE-SCHEMA.md",
|
|
"security": "docs/SECURITY.md",
|
|
"vehicles_api": "docs/VEHICLES-API.md"
|
|
},
|
|
"urls": {
|
|
"frontend": "https://motovaultpro.com",
|
|
"backend_health": "https://motovaultpro.com/api/health",
|
|
"hosts_entry": "127.0.0.1 motovaultpro.com"
|
|
}
|
|
},
|
|
"critical_requirements": {
|
|
"mobile_desktop_development": "ALL features MUST be implemented and tested on BOTH mobile and desktop",
|
|
"context_efficiency": "95%",
|
|
"single_load_completeness": "100%",
|
|
"feature_capsule_organization": "100%",
|
|
"single_tenant": true,
|
|
"production_only_development": true,
|
|
"docker_first": true,
|
|
"multi_tenant": false
|
|
},
|
|
"ai_loading_strategy": {
|
|
"project_overview": {
|
|
"instruction": "Start with README.md for complete architecture context",
|
|
"files": ["README.md"],
|
|
"completeness": "100% - all navigation and 9-container architecture information"
|
|
},
|
|
"application_feature_work": {
|
|
"instruction": "Load entire application feature directory (features are modules within backend)",
|
|
"pattern": "backend/src/features/{feature}/",
|
|
"completeness": "100% - everything needed is in one directory"
|
|
},
|
|
"cross_feature_work": {
|
|
"instruction": "Load index.ts and README.md from each application feature",
|
|
"pattern": [
|
|
"backend/src/features/{feature}/index.ts",
|
|
"backend/src/features/{feature}/README.md"
|
|
]
|
|
},
|
|
"debugging": {
|
|
"instruction": "Start with feature README, expand to tests",
|
|
"pattern": [
|
|
"backend/src/features/{feature}/README.md",
|
|
"backend/src/features/{feature}/tests/unit/",
|
|
"backend/src/features/{feature}/tests/integration/"
|
|
]
|
|
},
|
|
"documentation": {
|
|
"instruction": "Use docs/README.md for complete documentation index",
|
|
"files": ["docs/README.md"],
|
|
"completeness": "All documentation links and navigation"
|
|
}
|
|
},
|
|
"services": {
|
|
"mvp-traefik": {
|
|
"type": "reverse_proxy",
|
|
"description": "Routes all HTTP/HTTPS traffic, TLS termination",
|
|
"ports": [80, 443, 8080]
|
|
},
|
|
"mvp-frontend": {
|
|
"type": "react_app",
|
|
"description": "Vite-based React frontend with nginx",
|
|
"port": 3000
|
|
},
|
|
"mvp-backend": {
|
|
"type": "fastify_api",
|
|
"description": "Node.js backend with feature modules (includes platform capabilities)",
|
|
"port": 3001
|
|
},
|
|
"mvp-postgres": {
|
|
"type": "database",
|
|
"description": "PostgreSQL database",
|
|
"port": 5432
|
|
},
|
|
"mvp-redis": {
|
|
"type": "cache",
|
|
"description": "Redis cache with AOF persistence",
|
|
"port": 6379
|
|
},
|
|
"mvp-ocr": {
|
|
"type": "ocr_service",
|
|
"description": "Python OCR service with pluggable engine abstraction (PaddleOCR PP-OCRv4 primary, optional Google Vision cloud fallback, Tesseract backward compat)",
|
|
"port": 8000
|
|
},
|
|
"mvp-loki": {
|
|
"type": "log_aggregation",
|
|
"description": "Grafana Loki for centralized log storage (30-day retention)",
|
|
"port": 3100
|
|
},
|
|
"mvp-alloy": {
|
|
"type": "log_collector",
|
|
"description": "Grafana Alloy for log collection and forwarding to Loki",
|
|
"port": 12345
|
|
},
|
|
"mvp-grafana": {
|
|
"type": "log_visualization",
|
|
"description": "Grafana for log querying and visualization",
|
|
"port": 3000
|
|
}
|
|
},
|
|
"application_features": {
|
|
"admin": {
|
|
"path": "backend/src/features/admin/",
|
|
"type": "core_feature",
|
|
"self_contained": true,
|
|
"database_tables": ["admin_users", "platform_change_log"],
|
|
"description": "Admin role management, platform catalog CRUD, station oversight",
|
|
"status": "implemented"
|
|
},
|
|
"auth": {
|
|
"path": "backend/src/features/auth/",
|
|
"type": "core_feature",
|
|
"self_contained": true,
|
|
"database_tables": [],
|
|
"description": "User signup, email verification workflow using Auth0",
|
|
"status": "implemented"
|
|
},
|
|
"backup": {
|
|
"path": "backend/src/features/backup/",
|
|
"type": "admin_feature",
|
|
"self_contained": true,
|
|
"database_tables": ["backup_schedules", "backup_history", "backup_settings"],
|
|
"storage": "/app/data/backups/",
|
|
"description": "Manual and scheduled database/document backups with retention policies",
|
|
"status": "implemented"
|
|
},
|
|
"documents": {
|
|
"path": "backend/src/features/documents/",
|
|
"type": "independent_feature",
|
|
"self_contained": true,
|
|
"database_tables": ["documents"],
|
|
"storage": "/app/data/documents/",
|
|
"status": "implemented"
|
|
},
|
|
"fuel-logs": {
|
|
"path": "backend/src/features/fuel-logs/",
|
|
"type": "dependent_feature",
|
|
"self_contained": true,
|
|
"depends_on": ["vehicles"],
|
|
"database_tables": ["fuel_logs"],
|
|
"cache_strategy": "User logs: 5 minutes",
|
|
"status": "implemented"
|
|
},
|
|
"maintenance": {
|
|
"path": "backend/src/features/maintenance/",
|
|
"type": "dependent_feature",
|
|
"self_contained": true,
|
|
"depends_on": ["vehicles"],
|
|
"database_tables": ["maintenance_logs", "maintenance_schedules"],
|
|
"cache_strategy": "Upcoming maintenance: 1 hour",
|
|
"status": "implemented"
|
|
},
|
|
"notifications": {
|
|
"path": "backend/src/features/notifications/",
|
|
"type": "dependent_feature",
|
|
"self_contained": true,
|
|
"depends_on": ["maintenance", "documents"],
|
|
"database_tables": ["email_templates", "notification_logs", "sent_notification_tracker", "user_notifications"],
|
|
"external_apis": ["Resend"],
|
|
"description": "Email and toast notifications for maintenance due/overdue and expiring documents",
|
|
"status": "implemented"
|
|
},
|
|
"onboarding": {
|
|
"path": "backend/src/features/onboarding/",
|
|
"type": "dependent_feature",
|
|
"self_contained": true,
|
|
"depends_on": ["user-profile", "user-preferences"],
|
|
"database_tables": [],
|
|
"description": "User onboarding flow after email verification (preferences, first vehicle)",
|
|
"status": "implemented"
|
|
},
|
|
"platform": {
|
|
"path": "backend/src/features/platform/",
|
|
"type": "platform_feature",
|
|
"self_contained": true,
|
|
"database_tables": ["vehicle_options"],
|
|
"cache_strategy": "Vehicle hierarchical data: 6 hours",
|
|
"description": "Vehicle hierarchical data lookups (years, makes, models, trims, engines). VIN decoding is planned/future.",
|
|
"status": "implemented_vin_decode_planned"
|
|
},
|
|
"stations": {
|
|
"path": "backend/src/features/stations/",
|
|
"type": "independent_feature",
|
|
"self_contained": true,
|
|
"external_apis": ["Google Maps API"],
|
|
"database_tables": ["stations", "community_stations"],
|
|
"cache_strategy": "Station searches: 1 hour",
|
|
"status": "implemented"
|
|
},
|
|
"terms-agreement": {
|
|
"path": "backend/src/features/terms-agreement/",
|
|
"type": "core_feature",
|
|
"self_contained": true,
|
|
"database_tables": ["terms_agreements"],
|
|
"description": "Legal audit trail for Terms & Conditions acceptance at signup",
|
|
"status": "implemented"
|
|
},
|
|
"user-export": {
|
|
"path": "backend/src/features/user-export/",
|
|
"type": "independent_feature",
|
|
"self_contained": true,
|
|
"depends_on": ["vehicles", "fuel-logs", "documents", "maintenance"],
|
|
"database_tables": [],
|
|
"description": "GDPR-compliant user data export (vehicles, logs, documents as TAR.GZ)",
|
|
"status": "implemented"
|
|
},
|
|
"user-preferences": {
|
|
"path": "backend/src/features/user-preferences/",
|
|
"type": "core_feature",
|
|
"self_contained": true,
|
|
"database_tables": ["user_preferences"],
|
|
"description": "User preference management (unit system, currency, timezone)",
|
|
"status": "implemented"
|
|
},
|
|
"user-profile": {
|
|
"path": "backend/src/features/user-profile/",
|
|
"type": "core_feature",
|
|
"self_contained": true,
|
|
"database_tables": ["user_profiles"],
|
|
"description": "User profile management (email, display name, notification email)",
|
|
"status": "implemented"
|
|
},
|
|
"vehicles": {
|
|
"path": "backend/src/features/vehicles/",
|
|
"type": "core_feature",
|
|
"self_contained": true,
|
|
"database_tables": ["vehicles"],
|
|
"cache_strategy": "User vehicle lists: 5 minutes",
|
|
"status": "implemented"
|
|
}
|
|
},
|
|
"feature_dependencies": {
|
|
"explanation": "Logical dependencies within single application service - all deploy together",
|
|
"sequence": ["admin", "auth", "user-profile", "user-preferences", "terms-agreement", "onboarding", "platform", "vehicles", "fuel-logs", "maintenance", "stations", "documents", "notifications", "backup", "user-export"]
|
|
},
|
|
"development_environment": {
|
|
"type": "production_only_docker",
|
|
"ssl_enabled": true,
|
|
"frontend_url": "https://motovaultpro.com",
|
|
"backend_url": "https://motovaultpro.com/api",
|
|
"cert_path": "./certs",
|
|
"hosts_file_entry": "127.0.0.1 motovaultpro.com"
|
|
},
|
|
"testing_strategy": {
|
|
"framework": "Jest (backend + frontend)",
|
|
"container_based": true,
|
|
"commands": {
|
|
"all_tests": "npm test",
|
|
"backend_shell": "make shell-backend",
|
|
"feature_specific": "npm test -- --testPathPattern=src/features/{feature}",
|
|
"single_file": "npm test -- --testPathPattern={filename}",
|
|
"watch_mode": "npm run test:watch"
|
|
},
|
|
"test_locations": {
|
|
"backend": "backend/src/features/{feature}/tests/unit/ and tests/integration/",
|
|
"frontend": "frontend/src/features/{feature}/__tests__/ or frontend/test/"
|
|
}
|
|
},
|
|
"authentication": {
|
|
"provider": "Auth0",
|
|
"backend_framework": "Fastify with @fastify/jwt"
|
|
},
|
|
"external_services": {
|
|
"containers": {
|
|
"PostgreSQL": "mvp-postgres:5432",
|
|
"Redis": "mvp-redis:6379"
|
|
},
|
|
"external_apis": [
|
|
"Google Maps API",
|
|
"Auth0",
|
|
"Resend"
|
|
]
|
|
},
|
|
"network_topology": {
|
|
"frontend_network": "10.96.1.0/24 - public, Traefik + Frontend",
|
|
"backend_network": "10.96.20.0/24 - API services (external for Auth0)",
|
|
"database_network": "10.96.64.0/24 - internal, data layer isolation"
|
|
},
|
|
"ai_optimization_metadata": {
|
|
"feature_capsule_pattern": "backend/src/features/{name}/",
|
|
"single_directory_context": true,
|
|
"single_tenant_architecture": true,
|
|
"simplified_deployment": true,
|
|
"docker_first_development": true,
|
|
"container_count": 9
|
|
}
|
|
}
|