{
  "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
  }
}
