fix: increase VIN decode timeout to 60s for Gemini cold start (refs #229 )

Default 10s API client timeout caused frontend "Failed to decode" errors when Gemini engine cold-starts (34s+ on first call). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
chore: change google region
2026-02-19 21:30:31 -06:00 · 2026-02-19 20:59:40 -06:00 · 2026-02-19 20:36:34 -06:00 · 2026-02-19 20:35:06 -06:00 · 2026-02-19 20:14:54 -06:00 · 2026-02-18 21:51:45 -06:00
487 changed files with 51245 additions and 3907 deletions
--- a/.ai/context.json
+++ b/.ai/context.json
@@ -1,11 +1,12 @@
 {
  "version": "6.2.0",
-  "architecture": "simplified-5-container",
+  "architecture": "9-container",
  "repository": {
    "host": "gitea",
    "owner": "egullickson",
    "repo": "motovaultpro",
-    "url": "https://git.motovaultpro.com"
+    "url": "https://git.motovaultpro.com",
+    "default_branch": "main"
  },
  "ai_quick_start": {
    "load_order": [
@@ -51,7 +52,7 @@
    "project_overview": {
      "instruction": "Start with README.md for complete architecture context",
      "files": ["README.md"],
-      "completeness": "100% - all navigation and 5-container architecture information"
+      "completeness": "100% - all navigation and 9-container architecture information"
    },
    "application_feature_work": {
      "instruction": "Load entire application feature directory (features are modules within backend)",
@@ -104,6 +105,26 @@
      "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": {
@@ -290,6 +311,6 @@
    "single_tenant_architecture": true,
    "simplified_deployment": true,
    "docker_first_development": true,
-    "container_count": 5
+    "container_count": 9
  }
 }
--- a/.ai/workflow-contract.json
+++ b/.ai/workflow-contract.json
@@ -40,46 +40,79 @@
      "When moving status, remove the previous status/* label first."
    ]
  },
+  "sub_issues": {
+    "when": "Multi-file features (3+ files) or features that benefit from smaller AI context windows.",
+    "parent_issue": "The original feature issue. Tracks overall status. Only the parent gets status label transitions.",
+    "sub_issue_title_format": "{type}: {summary} (#{parent_index})",
+    "sub_issue_body": "First line must be 'Relates to #{parent_index}'. Each sub-issue is a self-contained unit of work.",
+    "sub_issue_labels": "status/in-progress + same type/* as parent. Sub-issues move to in-progress as they are worked on.",
+    "sub_issue_milestone": "Same sprint milestone as parent.",
+    "rules": [
+      "ONE branch for the parent issue. Never create branches per sub-issue.",
+      "ONE PR for the parent issue. The PR closes the parent and all sub-issues.",
+      "Commits reference the specific sub-issue index they implement.",
+      "Sub-issues should be small enough to fit in a single AI context window.",
+      "Plan milestones map 1:1 to sub-issues."
+    ],
+    "examples": {
+      "parent": "#105 'feat: Add Grafana dashboards and alerting'",
+      "sub_issues": [
+        "#106 'feat: Grafana dashboard provisioning infrastructure (#105)'",
+        "#107 'feat: Application Overview Grafana dashboard (#105)'"
+      ]
+    }
+  },
  "branching": {
-    "branch_format": "issue-{index}-{slug}",
+    "branch_format": "issue-{parent_index}-{slug}",
    "target_branch": "main",
-    "example": "issue-42-add-fuel-efficiency-report"
+    "note": "Always use the parent issue index. When sub-issues exist, the branch is for the parent.",
+    "examples": [
+      "issue-42-add-fuel-efficiency-report (standalone issue)",
+      "issue-105-add-grafana-dashboards (parent issue with sub-issues #106-#111)"
+    ]
  },
  "commit_conventions": {
    "message_format": "{type}: {short summary} (refs #{index})",
    "allowed_types": ["feat", "fix", "chore", "docs", "refactor", "test"],
+    "note": "When working on a sub-issue, {index} is the sub-issue number. For standalone issues, {index} is the issue number.",
    "examples": [
      "feat: add fuel efficiency calculation (refs #42)",
-      "fix: correct VIN validation for pre-1981 vehicles (refs #1)"
+      "fix: correct VIN validation for pre-1981 vehicles (refs #1)",
+      "feat: add dashboard provisioning infrastructure (refs #106)",
+      "feat: add API performance dashboard (refs #108)"
    ]
  },
  "pull_requests": {
-    "title_format": "{type}: {summary} (#{index})",
+    "title_format": "{type}: {summary} (#{parent_index})",
+    "note": "PR title always uses the parent issue index.",
    "body_requirements": [
-      "Link issue(s) using 'Fixes #123' or 'Relates to #123'.",
+      "Link parent issue using 'Fixes #{parent_index}'.",
+      "Link all sub-issues using 'Fixes #{sub_index}' on separate lines.",
      "Include test plan and results.",
      "Confirm acceptance criteria completion."
    ],
+    "body_example": "Fixes #105\nFixes #106\nFixes #107\nFixes #108\nFixes #109\nFixes #110\nFixes #111",
    "merge_policy": "squash_or_rebase_ok",
    "template_location": ".gitea/PULL_REQUEST_TEMPLATE.md"
  },
  "execution_loop": [
    "List repo issues in current sprint milestone with status/ready; if none, pull from status/backlog and promote the best candidate to status/ready.",
    "Select one issue (prefer smallest size and highest priority).",
-    "Move issue to status/in-progress.",
+    "Move parent issue to status/in-progress.",
    "[SKILL] Codebase Analysis if unfamiliar area.",
    "[SKILL] Problem Analysis if complex problem.",
    "[SKILL] Decision Critic if uncertain approach.",
-    "[SKILL] Planner writes plan as issue comment.",
+    "If multi-file feature (3+ files): decompose into sub-issues per sub_issues rules. Each sub-issue = one plan milestone.",
+    "[SKILL] Planner writes plan as parent issue comment. Plan milestones map 1:1 to sub-issues.",
    "[SKILL] Plan review cycle: QR plan-completeness -> TW plan-scrub -> QR plan-code -> QR plan-docs.",
-    "Create branch issue-{index}-{slug}.",
-    "[SKILL] Planner executes plan, delegates to Developer per milestone.",
-    "[SKILL] QR post-implementation per milestone (results in issue comment).",
-    "Open PR targeting main and linking issue(s).",
-    "Move issue to status/review.",
-    "[SKILL] Quality Agent validates with RULE 0/1/2 (result in issue comment).",
+    "Create ONE branch issue-{parent_index}-{slug} from main.",
+    "[SKILL] Planner executes plan, delegates to Developer per milestone/sub-issue.",
+    "[SKILL] QR post-implementation per milestone (results in parent issue comment).",
+    "Open ONE PR targeting main. Title uses parent index. Body lists 'Fixes #N' for parent and all sub-issues.",
+    "Move parent issue to status/review.",
+    "[SKILL] Quality Agent validates with RULE 0/1/2 (result in parent issue comment).",
    "If CI/tests fail, iterate until pass.",
-    "When PR is merged, move issue to status/done and close issue if not auto-closed.",
+    "When PR is merged, parent and all sub-issues move to status/done. Close any not auto-closed.",
    "[SKILL] Doc-Sync on affected directories."
  ],
  "skill_integration": {
--- a/.claude/skills/planner/POST
+++ b/.claude/skills/planner/POST
--- a/.claude/skills/planner/StripeClient.createSubscription
+++ b/.claude/skills/planner/StripeClient.createSubscription
--- a/.claude/skills/planner/SubscriptionPage
+++ b/.claude/skills/planner/SubscriptionPage
--- a/.claude/skills/planner/sync
+++ b/.claude/skills/planner/sync
--- a/.claude/tdd-guard/data/test.json
+++ b/.claude/tdd-guard/data/test.json
@@ -0,0 +1,23 @@
+{
+  "testModules": [
+    {
+      "moduleId": "/Users/egullickson/Documents/Technology/coding/motovaultpro/frontend/src/features/dashboard/components/__tests__/ActionBar.test.tsx",
+      "tests": [
+        {
+          "name": "Module failed to load (Error)",
+          "fullName": "Module failed to load (Error)",
+          "state": "failed",
+          "errors": [
+            {
+              "message": "File not found: tsconfig.json (resolved as: /Users/egullickson/Documents/Technology/coding/motovaultpro/tsconfig.json)",
+              "name": "Error",
+              "stack": "Error: File not found: tsconfig.json (resolved as: /Users/egullickson/Documents/Technology/coding/motovaultpro/tsconfig.json)\n    at ConfigSet.resolvePath (/Users/egullickson/Documents/Technology/coding/motovaultpro/frontend/node_modules/ts-jest/dist/legacy/config/config-set.js:616:19)\n    at ConfigSet._setupConfigSet (/Users/egullickson/Documents/Technology/coding/motovaultpro/frontend/node_modules/ts-jest/dist/legacy/config/config-set.js:322:71)\n    at new ConfigSet (/Users/egullickson/Documents/Technology/coding/motovaultpro/frontend/node_modules/ts-jest/dist/legacy/config/config-set.js:206:14)\n    at TsJestTransformer._createConfigSet (/Users/egullickson/Documents/Technology/coding/motovaultpro/frontend/node_modules/ts-jest/dist/legacy/ts-jest-transformer.js:119:16)\n    at TsJestTransformer._configsFor (/Users/egullickson/Documents/Technology/coding/motovaultpro/frontend/node_modules/ts-jest/dist/legacy/ts-jest-transformer.js:98:34)\n    at TsJestTransformer.getCacheKey (/Users/egullickson/Documents/Technology/coding/motovaultpro/frontend/node_modules/ts-jest/dist/legacy/ts-jest-transformer.js:249:30)\n    at ScriptTransformer._getCacheKey (/Users/egullickson/Documents/Technology/coding/motovaultpro/node_modules/@jest/transform/build/index.js:195:41)\n    at ScriptTransformer._getFileCachePath (/Users/egullickson/Documents/Technology/coding/motovaultpro/node_modules/@jest/transform/build/index.js:231:27)\n    at ScriptTransformer.transformSource (/Users/egullickson/Documents/Technology/coding/motovaultpro/node_modules/@jest/transform/build/index.js:402:32)\n    at ScriptTransformer._transformAndBuildScript (/Users/egullickson/Documents/Technology/coding/motovaultpro/node_modules/@jest/transform/build/index.js:519:40)\n    at ScriptTransformer.transform (/Users/egullickson/Documents/Technology/coding/motovaultpro/node_modules/@jest/transform/build/index.js:558:19)\n    at Runtime.transformFile (/Users/egullickson/Documents/Technology/coding/motovaultpro/node_modules/jest-runtime/build/index.js:1290:53)\n    at Runtime._execModule (/Users/egullickson/Documents/Technology/coding/motovaultpro/node_modules/jest-runtime/build/index.js:1243:34)\n    at Runtime._loadModule (/Users/egullickson/Documents/Technology/coding/motovaultpro/node_modules/jest-runtime/build/index.js:944:12)\n    at Runtime.requireModule (/Users/egullickson/Documents/Technology/coding/motovaultpro/node_modules/jest-runtime/build/index.js:832:12)\n    at jestAdapter (/Users/egullickson/Documents/Technology/coding/motovaultpro/node_modules/jest-circus/build/runner.js:84:33)\n    at processTicksAndRejections (node:internal/process/task_queues:104:5)\n    at runTestInternal (/Users/egullickson/Documents/Technology/coding/motovaultpro/node_modules/jest-runner/build/index.js:275:16)\n    at runTest (/Users/egullickson/Documents/Technology/coding/motovaultpro/node_modules/jest-runner/build/index.js:343:7)"
+            }
+          ]
+        }
+      ]
+    }
+  ],
+  "unhandledErrors": [],
+  "reason": "failed"
+}
--- a/.env.example
+++ b/.env.example
@@ -0,0 +1,36 @@
+# MotoVaultPro Environment Configuration
+# Copy to .env and fill in environment-specific values
+# Generated .env files should NOT be committed to version control
+#
+# Local dev: No .env needed -- base docker-compose.yml defaults are sandbox values
+# Staging/Production: CI/CD generates .env from Gitea variables + generate-log-config.sh
+
+# ===========================================
+# Stripe Price IDs (environment-specific)
+# ===========================================
+# Sandbox defaults used for local development
+STRIPE_PRO_MONTHLY_PRICE_ID=price_1T1ZHMJXoKkh5RcKwKSSGIlR
+STRIPE_PRO_YEARLY_PRICE_ID=price_1T1ZHnJXoKkh5RcKWlG2MPpX
+STRIPE_ENTERPRISE_MONTHLY_PRICE_ID=price_1T1ZIBJXoKkh5RcKu2jyhqBN
+STRIPE_ENTERPRISE_YEARLY_PRICE_ID=price_1T1ZIQJXoKkh5RcK34YXiJQm
+
+# ===========================================
+# Stripe Publishable Key (baked into frontend at build time)
+# ===========================================
+# VITE_STRIPE_PUBLISHABLE_KEY=pk_test_...
+
+# ===========================================
+# Log Levels (generated by scripts/ci/generate-log-config.sh)
+# ===========================================
+# Run: ./scripts/ci/generate-log-config.sh DEBUG >> .env
+#
+# BACKEND_LOG_LEVEL=debug
+# TRAEFIK_LOG_LEVEL=DEBUG
+# POSTGRES_LOG_STATEMENT=all
+# POSTGRES_LOG_MIN_DURATION=0
+# REDIS_LOGLEVEL=debug
+
+# ===========================================
+# Grafana
+# ===========================================
+# GRAFANA_ADMIN_PASSWORD=admin
--- a/.gitea/CLAUDE.md
+++ b/.gitea/CLAUDE.md
@@ -0,0 +1,14 @@
+# .gitea/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `PULL_REQUEST_TEMPLATE.md` | PR template | Creating pull requests |
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `workflows/` | CI/CD workflow definitions | Pipeline configuration |
+| `ISSUE_TEMPLATE/` | Issue templates (bug, feature, chore) | Creating issues |
--- a/.gitea/SPRINTS.md
+++ b/.gitea/SPRINTS.md
@@ -1,36 +0,0 @@
-# SPRINTS.md — MotoVaultPro Sprint Calendar (2026)
-
-**Cadence:** 2 weeks (14 days)  
-**Sprint weeks:** Monday → Sunday  
-**Naming convention:** `Sprint YYYY-MM-DD` (the Monday start date)
-
-> Note: Sprint 26 ends on **2027-01-03** (it crosses into the next year).
-
-| # | Sprint | Start (Mon) | End (Sun) |
-|---:|---|---|---|
-| 1 | Sprint 2026-01-05 | 2026-01-05 | 2026-01-18 |
-| 2 | Sprint 2026-01-19 | 2026-01-19 | 2026-02-01 |
-| 3 | Sprint 2026-02-02 | 2026-02-02 | 2026-02-15 |
-| 4 | Sprint 2026-02-16 | 2026-02-16 | 2026-03-01 |
-| 5 | Sprint 2026-03-02 | 2026-03-02 | 2026-03-15 |
-| 6 | Sprint 2026-03-16 | 2026-03-16 | 2026-03-29 |
-| 7 | Sprint 2026-03-30 | 2026-03-30 | 2026-04-12 |
-| 8 | Sprint 2026-04-13 | 2026-04-13 | 2026-04-26 |
-| 9 | Sprint 2026-04-27 | 2026-04-27 | 2026-05-10 |
-| 10 | Sprint 2026-05-11 | 2026-05-11 | 2026-05-24 |
-| 11 | Sprint 2026-05-25 | 2026-05-25 | 2026-06-07 |
-| 12 | Sprint 2026-06-08 | 2026-06-08 | 2026-06-21 |
-| 13 | Sprint 2026-06-22 | 2026-06-22 | 2026-07-05 |
-| 14 | Sprint 2026-07-06 | 2026-07-06 | 2026-07-19 |
-| 15 | Sprint 2026-07-20 | 2026-07-20 | 2026-08-02 |
-| 16 | Sprint 2026-08-03 | 2026-08-03 | 2026-08-16 |
-| 17 | Sprint 2026-08-17 | 2026-08-17 | 2026-08-30 |
-| 18 | Sprint 2026-08-31 | 2026-08-31 | 2026-09-13 |
-| 19 | Sprint 2026-09-14 | 2026-09-14 | 2026-09-27 |
-| 20 | Sprint 2026-09-28 | 2026-09-28 | 2026-10-11 |
-| 21 | Sprint 2026-10-12 | 2026-10-12 | 2026-10-25 |
-| 22 | Sprint 2026-10-26 | 2026-10-26 | 2026-11-08 |
-| 23 | Sprint 2026-11-09 | 2026-11-09 | 2026-11-22 |
-| 24 | Sprint 2026-11-23 | 2026-11-23 | 2026-12-06 |
-| 25 | Sprint 2026-12-07 | 2026-12-07 | 2026-12-20 |
-| 26 | Sprint 2026-12-21 | 2026-12-21 | 2027-01-03 |
--- a/.gitea/workflows/production.yaml
+++ b/.gitea/workflows/production.yaml
@@ -19,9 +19,11 @@ on:
 env:
  REGISTRY: git.motovaultpro.com
  DEPLOY_PATH: /opt/motovaultpro
-  COMPOSE_FILE: docker-compose.yml
+  BASE_COMPOSE_FILE: docker-compose.yml
  COMPOSE_BLUE_GREEN: docker-compose.blue-green.yml
-  HEALTH_CHECK_TIMEOUT: "60"
+  COMPOSE_PROD: docker-compose.prod.yml
+  HEALTH_CHECK_TIMEOUT: "240"
+  LOG_LEVEL: INFO

 jobs:
  # ============================================
@@ -34,6 +36,7 @@ jobs:
      target_stack: ${{ steps.determine-stack.outputs.target_stack }}
      backend_image: ${{ steps.set-images.outputs.backend_image }}
      frontend_image: ${{ steps.set-images.outputs.frontend_image }}
+      ocr_image: ${{ steps.set-images.outputs.ocr_image }}
    steps:
      - name: Check Docker availability
        run: |
@@ -53,6 +56,7 @@ jobs:
          TAG="${{ inputs.image_tag }}"
          echo "backend_image=$REGISTRY/egullickson/backend:$TAG" >> $GITHUB_OUTPUT
          echo "frontend_image=$REGISTRY/egullickson/frontend:$TAG" >> $GITHUB_OUTPUT
+          echo "ocr_image=$REGISTRY/egullickson/ocr:$TAG" >> $GITHUB_OUTPUT

      - name: Determine target stack
        id: determine-stack
@@ -83,6 +87,7 @@ jobs:
      TARGET_STACK: ${{ needs.validate.outputs.target_stack }}
      BACKEND_IMAGE: ${{ needs.validate.outputs.backend_image }}
      FRONTEND_IMAGE: ${{ needs.validate.outputs.frontend_image }}
+      OCR_IMAGE: ${{ needs.validate.outputs.ocr_image }}
    steps:
      - name: Checkout scripts, config, and compose files
        uses: actions/checkout@v4
@@ -90,8 +95,11 @@ jobs:
          sparse-checkout: |
            scripts/
            config/
+            secrets/app/google-wif-config.json
            docker-compose.yml
            docker-compose.blue-green.yml
+            docker-compose.prod.yml
+            .env.example
          sparse-checkout-cone-mode: false
          fetch-depth: 1

@@ -101,6 +109,27 @@ jobs:
          rsync -av --delete "$GITHUB_WORKSPACE/scripts/" "$DEPLOY_PATH/scripts/"
          cp "$GITHUB_WORKSPACE/docker-compose.yml" "$DEPLOY_PATH/"
          cp "$GITHUB_WORKSPACE/docker-compose.blue-green.yml" "$DEPLOY_PATH/"
+          cp "$GITHUB_WORKSPACE/docker-compose.prod.yml" "$DEPLOY_PATH/"
+          # WIF credential config (not a secret -- references Auth0 token script path)
+          # Remove any Docker-created directory artifact from failed bind mounts
+          rm -rf "$DEPLOY_PATH/secrets/app/google-wif-config.json"
+          mkdir -p "$DEPLOY_PATH/secrets/app"
+          cp "$GITHUB_WORKSPACE/secrets/app/google-wif-config.json" "$DEPLOY_PATH/secrets/app/"
+
+      - name: Generate environment configuration
+        run: |
+          cd "$DEPLOY_PATH"
+          {
+            echo "# Generated by CI/CD - DO NOT EDIT"
+            echo "STRIPE_PRO_MONTHLY_PRICE_ID=${{ vars.STRIPE_PRO_MONTHLY_PRICE_ID }}"
+            echo "STRIPE_PRO_YEARLY_PRICE_ID=${{ vars.STRIPE_PRO_YEARLY_PRICE_ID }}"
+            echo "STRIPE_ENTERPRISE_MONTHLY_PRICE_ID=${{ vars.STRIPE_ENTERPRISE_MONTHLY_PRICE_ID }}"
+            echo "STRIPE_ENTERPRISE_YEARLY_PRICE_ID=${{ vars.STRIPE_ENTERPRISE_YEARLY_PRICE_ID }}"
+            echo "VITE_STRIPE_PUBLISHABLE_KEY=${{ vars.VITE_STRIPE_PUBLISHABLE_KEY }}"
+            echo "GRAFANA_ADMIN_PASSWORD=${{ secrets.GRAFANA_ADMIN_PASSWORD }}"
+          } > .env
+          chmod +x scripts/ci/generate-log-config.sh
+          ./scripts/ci/generate-log-config.sh "$LOG_LEVEL" >> .env

      - name: Login to registry
        run: |
@@ -108,17 +137,22 @@ jobs:

      - name: Inject secrets
        run: |
-          chmod +x "$GITHUB_WORKSPACE/scripts/inject-secrets.sh"
-          "$GITHUB_WORKSPACE/scripts/inject-secrets.sh"
+          cd "$DEPLOY_PATH"
+          chmod +x scripts/inject-secrets.sh
+          SECRETS_DIR="$DEPLOY_PATH/secrets/app" ./scripts/inject-secrets.sh
        env:
          POSTGRES_PASSWORD: ${{ secrets.POSTGRES_PASSWORD }}
          AUTH0_CLIENT_SECRET: ${{ secrets.AUTH0_CLIENT_SECRET }}
          AUTH0_MANAGEMENT_CLIENT_ID: ${{ secrets.AUTH0_MANAGEMENT_CLIENT_ID }}
          AUTH0_MANAGEMENT_CLIENT_SECRET: ${{ secrets.AUTH0_MANAGEMENT_CLIENT_SECRET }}
+          AUTH0_OCR_CLIENT_ID: ${{ secrets.AUTH0_OCR_CLIENT_ID }}
+          AUTH0_OCR_CLIENT_SECRET: ${{ secrets.AUTH0_OCR_CLIENT_SECRET }}
          GOOGLE_MAPS_API_KEY: ${{ secrets.GOOGLE_MAPS_API_KEY }}
          GOOGLE_MAPS_MAP_ID: ${{ secrets.GOOGLE_MAPS_MAP_ID }}
          CF_DNS_API_TOKEN: ${{ secrets.CF_DNS_API_TOKEN }}
          RESEND_API_KEY: ${{ secrets.RESEND_API_KEY }}
+          STRIPE_SECRET_KEY: ${{ secrets.STRIPE_SECRET_KEY }}
+          STRIPE_WEBHOOK_SECRET: ${{ secrets.STRIPE_WEBHOOK_SECRET }}

      - name: Initialize data directories
        run: |
@@ -136,6 +170,7 @@ jobs:
        run: |
          docker pull $BACKEND_IMAGE
          docker pull $FRONTEND_IMAGE
+          docker pull $OCR_IMAGE

      - name: Record expected image IDs
        id: expected-images
@@ -148,18 +183,50 @@ jobs:
          echo "frontend_id=$FRONTEND_ID" >> $GITHUB_OUTPUT
          echo "backend_id=$BACKEND_ID" >> $GITHUB_OUTPUT

+      - name: Start shared services
+        run: |
+          cd "$DEPLOY_PATH"
+          # Start shared infrastructure services (database, cache, logging)
+          # --no-recreate prevents restarting postgres/redis when config files change
+          # These must persist across blue-green deployments to avoid data service disruption
+          docker compose -f $BASE_COMPOSE_FILE -f $COMPOSE_BLUE_GREEN -f $COMPOSE_PROD up -d --no-recreate \
+            mvp-postgres mvp-redis mvp-loki mvp-alloy mvp-grafana
+
+      - name: Wait for shared services health
+        run: |
+          echo "Waiting for PostgreSQL and Redis to be healthy..."
+          for service in mvp-postgres mvp-redis; do
+            for i in $(seq 1 24); do
+              health=$(docker inspect --format='{{.State.Health.Status}}' $service 2>/dev/null || echo "unknown")
+              if [ "$health" = "healthy" ]; then
+                echo "OK: $service is healthy"
+                break
+              fi
+              if [ $i -eq 24 ]; then
+                echo "ERROR: $service health check timed out (status: $health)"
+                docker logs $service --tail 50 2>/dev/null || true
+                exit 1
+              fi
+              echo "Waiting for $service... (attempt $i/24, status: $health)"
+              sleep 5
+            done
+          done
+          echo "All shared services healthy"
+
      - name: Start target stack
        run: |
          cd "$DEPLOY_PATH"
          export BACKEND_IMAGE=$BACKEND_IMAGE
          export FRONTEND_IMAGE=$FRONTEND_IMAGE
+          export OCR_IMAGE=$OCR_IMAGE
          # --force-recreate ensures containers are recreated even if image tag is same
          # This prevents stale container content when image digest changes
-          docker compose -f $COMPOSE_FILE -f $COMPOSE_BLUE_GREEN up -d --force-recreate \
-            mvp-frontend-$TARGET_STACK mvp-backend-$TARGET_STACK
+          # Start shared OCR service and target stack
+          docker compose -f $BASE_COMPOSE_FILE -f $COMPOSE_BLUE_GREEN -f $COMPOSE_PROD up -d --force-recreate \
+            mvp-ocr mvp-frontend-$TARGET_STACK mvp-backend-$TARGET_STACK

      - name: Wait for stack initialization
-        run: sleep 10
+        run: sleep 5

      - name: Verify container images
        run: |
@@ -194,7 +261,7 @@ jobs:
      - name: Start Traefik
        run: |
          cd "$DEPLOY_PATH"
-          docker compose -f $COMPOSE_FILE -f $COMPOSE_BLUE_GREEN up -d mvp-traefik
+          docker compose -f $BASE_COMPOSE_FILE -f $COMPOSE_BLUE_GREEN -f $COMPOSE_PROD up -d mvp-traefik

      - name: Wait for Traefik
        run: |
@@ -238,22 +305,79 @@ jobs:
      - name: Wait for routing propagation
        run: sleep 5

+      - name: Check container status and health
+        run: |
+          for service in mvp-frontend-$TARGET_STACK mvp-backend-$TARGET_STACK mvp-ocr; do
+            status=$(docker inspect --format='{{.State.Status}}' $service 2>/dev/null || echo "not found")
+            if [ "$status" != "running" ]; then
+              echo "ERROR: $service is not running (status: $status)"
+              docker logs $service --tail 50 2>/dev/null || true
+              exit 1
+            fi
+            echo "OK: $service is running"
+          done
+
+          # Wait for Docker healthchecks to complete (services with healthcheck defined)
+          echo ""
+          echo "Waiting for Docker healthchecks..."
+          for service in mvp-frontend-$TARGET_STACK mvp-backend-$TARGET_STACK mvp-ocr; do
+            # Check if service has a healthcheck defined
+            has_healthcheck=$(docker inspect --format='{{if .Config.Healthcheck}}true{{else}}false{{end}}' $service 2>/dev/null || echo "false")
+            if [ "$has_healthcheck" = "true" ]; then
+              # 48 attempts x 5 seconds = 4 minutes max wait (backend with fresh migrations can take ~3 min)
+              for i in $(seq 1 48); do
+                health=$(docker inspect --format='{{.State.Health.Status}}' $service 2>/dev/null || echo "unknown")
+                if [ "$health" = "healthy" ]; then
+                  echo "OK: $service is healthy"
+                  break
+                fi
+                # Don't fail immediately on unhealthy - container may still be starting up
+                # and can recover. Let the timeout handle truly broken containers.
+                if [ $i -eq 48 ]; then
+                  echo "ERROR: $service health check timed out (status: $health)"
+                  docker logs $service --tail 100 2>/dev/null || true
+                  exit 1
+                fi
+                echo "Waiting for $service healthcheck... (attempt $i/48, status: $health)"
+                sleep 5
+              done
+            else
+              echo "SKIP: $service has no healthcheck defined"
+            fi
+          done
+
+      - name: Wait for backend health
+        run: |
+          for i in $(seq 1 12); do
+            if docker exec mvp-backend-$TARGET_STACK curl -sf http://localhost:3001/health > /dev/null 2>&1; then
+              echo "OK: Backend health check passed"
+              exit 0
+            fi
+            if [ $i -eq 12 ]; then
+              echo "ERROR: Backend health check failed after 12 attempts"
+              docker logs mvp-backend-$TARGET_STACK --tail 100
+              exit 1
+            fi
+            echo "Attempt $i/12: Backend not ready, waiting 5s..."
+            sleep 5
+          done
+
      - name: External health check
        run: |
          REQUIRED_FEATURES='["admin","auth","onboarding","vehicles","documents","fuel-logs","stations","maintenance","platform","notifications","user-profile","user-preferences","user-export"]'

-          for i in 1 2 3 4 5 6; do
+          for i in $(seq 1 12); do
            RESPONSE=$(curl -sf https://motovaultpro.com/api/health 2>/dev/null) || {
-              echo "Attempt $i/6: Connection failed, waiting 10s..."
-              sleep 10
+              echo "Attempt $i/12: Connection failed, waiting 5s..."
+              sleep 5
              continue
            }

            # Check status is "healthy"
            STATUS=$(echo "$RESPONSE" | jq -r '.status')
            if [ "$STATUS" != "healthy" ]; then
-              echo "Attempt $i/6: Status is '$STATUS', not 'healthy'. Waiting 10s..."
-              sleep 10
+              echo "Attempt $i/12: Status is '$STATUS', not 'healthy'. Waiting 5s..."
+              sleep 5
              continue
            fi

@@ -263,8 +387,8 @@ jobs:
            ')

            if [ -n "$MISSING" ]; then
-              echo "Attempt $i/6: Missing features: $MISSING. Waiting 10s..."
-              sleep 10
+              echo "Attempt $i/12: Missing features: $MISSING. Waiting 5s..."
+              sleep 5
              continue
            fi

@@ -273,7 +397,7 @@ jobs:
            exit 0
          done

-          echo "ERROR: Production health check failed after 6 attempts"
+          echo "ERROR: Production health check failed after 12 attempts"
          echo "Last response: $RESPONSE"
          exit 1

--- a/.gitea/workflows/staging.yaml
+++ b/.gitea/workflows/staging.yaml
@@ -15,9 +15,10 @@ on:
 env:
  REGISTRY: git.motovaultpro.com
  DEPLOY_PATH: /opt/motovaultpro
-  COMPOSE_FILE: docker-compose.yml
-  COMPOSE_STAGING: docker-compose.staging.yml
+  BASE_COMPOSE_FILE: docker-compose.yml
+  STAGING_COMPOSE_FILE: docker-compose.staging.yml
  HEALTH_CHECK_TIMEOUT: "60"
+  LOG_LEVEL: DEBUG

 jobs:
  # ============================================
@@ -29,6 +30,7 @@ jobs:
    outputs:
      backend_image: ${{ steps.tags.outputs.backend_image }}
      frontend_image: ${{ steps.tags.outputs.frontend_image }}
+      ocr_image: ${{ steps.tags.outputs.ocr_image }}
      short_sha: ${{ steps.tags.outputs.short_sha }}
    steps:
      - name: Checkout code
@@ -45,6 +47,7 @@ jobs:
          SHORT_SHA="${SHORT_SHA:0:7}"
          echo "backend_image=$REGISTRY/egullickson/backend:$SHORT_SHA" >> $GITHUB_OUTPUT
          echo "frontend_image=$REGISTRY/egullickson/frontend:$SHORT_SHA" >> $GITHUB_OUTPUT
+          echo "ocr_image=$REGISTRY/egullickson/ocr:$SHORT_SHA" >> $GITHUB_OUTPUT
          echo "short_sha=$SHORT_SHA" >> $GITHUB_OUTPUT

      - name: Build backend image
@@ -67,18 +70,32 @@ jobs:
            --build-arg VITE_AUTH0_CLIENT_ID=${{ vars.VITE_AUTH0_CLIENT_ID }} \
            --build-arg VITE_AUTH0_AUDIENCE=${{ vars.VITE_AUTH0_AUDIENCE }} \
            --build-arg VITE_API_BASE_URL=/api \
+            --build-arg VITE_STRIPE_PUBLISHABLE_KEY=${{ vars.VITE_STRIPE_PUBLISHABLE_KEY }} \
            --cache-from $REGISTRY/egullickson/frontend:latest \
            -t ${{ steps.tags.outputs.frontend_image }} \
            -t $REGISTRY/egullickson/frontend:latest \
            -f frontend/Dockerfile \
            frontend

+      - name: Build OCR image
+        run: |
+          docker build \
+            --build-arg BUILDKIT_INLINE_CACHE=1 \
+            --build-arg REGISTRY_MIRRORS=$REGISTRY/egullickson/mirrors \
+            --cache-from $REGISTRY/egullickson/ocr:latest \
+            -t ${{ steps.tags.outputs.ocr_image }} \
+            -t $REGISTRY/egullickson/ocr:latest \
+            -f ocr/Dockerfile \
+            ocr
+
      - name: Push images
        run: |
          docker push ${{ steps.tags.outputs.backend_image }}
          docker push ${{ steps.tags.outputs.frontend_image }}
+          docker push ${{ steps.tags.outputs.ocr_image }}
          docker push $REGISTRY/egullickson/backend:latest
          docker push $REGISTRY/egullickson/frontend:latest
+          docker push $REGISTRY/egullickson/ocr:latest

  # ============================================
  # DEPLOY STAGING - Deploy to staging server
@@ -90,10 +107,38 @@ jobs:
    env:
      BACKEND_IMAGE: ${{ needs.build.outputs.backend_image }}
      FRONTEND_IMAGE: ${{ needs.build.outputs.frontend_image }}
+      OCR_IMAGE: ${{ needs.build.outputs.ocr_image }}
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

+      - name: Sync config, scripts, and compose files to deploy path
+        run: |
+          rsync -av --delete "$GITHUB_WORKSPACE/config/" "$DEPLOY_PATH/config/"
+          rsync -av --delete "$GITHUB_WORKSPACE/scripts/" "$DEPLOY_PATH/scripts/"
+          cp "$GITHUB_WORKSPACE/docker-compose.yml" "$DEPLOY_PATH/"
+          cp "$GITHUB_WORKSPACE/docker-compose.staging.yml" "$DEPLOY_PATH/"
+          # WIF credential config (not a secret -- references Auth0 token script path)
+          # Remove any Docker-created directory artifact from failed bind mounts
+          rm -rf "$DEPLOY_PATH/secrets/app/google-wif-config.json"
+          mkdir -p "$DEPLOY_PATH/secrets/app"
+          cp "$GITHUB_WORKSPACE/secrets/app/google-wif-config.json" "$DEPLOY_PATH/secrets/app/"
+
+      - name: Generate environment configuration
+        run: |
+          cd "$DEPLOY_PATH"
+          {
+            echo "# Generated by CI/CD - DO NOT EDIT"
+            echo "STRIPE_PRO_MONTHLY_PRICE_ID=${{ vars.STRIPE_PRO_MONTHLY_PRICE_ID }}"
+            echo "STRIPE_PRO_YEARLY_PRICE_ID=${{ vars.STRIPE_PRO_YEARLY_PRICE_ID }}"
+            echo "STRIPE_ENTERPRISE_MONTHLY_PRICE_ID=${{ vars.STRIPE_ENTERPRISE_MONTHLY_PRICE_ID }}"
+            echo "STRIPE_ENTERPRISE_YEARLY_PRICE_ID=${{ vars.STRIPE_ENTERPRISE_YEARLY_PRICE_ID }}"
+            echo "VITE_STRIPE_PUBLISHABLE_KEY=${{ vars.VITE_STRIPE_PUBLISHABLE_KEY }}"
+            echo "GRAFANA_ADMIN_PASSWORD=${{ secrets.GRAFANA_ADMIN_PASSWORD }}"
+          } > .env
+          chmod +x scripts/ci/generate-log-config.sh
+          ./scripts/ci/generate-log-config.sh "$LOG_LEVEL" >> .env
+
      - name: Login to registry
        run: |
          echo "${{ secrets.REGISTRY_PASSWORD }}" | docker login -u "${{ secrets.REGISTRY_USER }}" --password-stdin "$REGISTRY"
@@ -108,10 +153,14 @@ jobs:
          AUTH0_CLIENT_SECRET: ${{ secrets.AUTH0_CLIENT_SECRET }}
          AUTH0_MANAGEMENT_CLIENT_ID: ${{ secrets.AUTH0_MANAGEMENT_CLIENT_ID }}
          AUTH0_MANAGEMENT_CLIENT_SECRET: ${{ secrets.AUTH0_MANAGEMENT_CLIENT_SECRET }}
+          AUTH0_OCR_CLIENT_ID: ${{ secrets.AUTH0_OCR_CLIENT_ID }}
+          AUTH0_OCR_CLIENT_SECRET: ${{ secrets.AUTH0_OCR_CLIENT_SECRET }}
          GOOGLE_MAPS_API_KEY: ${{ secrets.GOOGLE_MAPS_API_KEY }}
          GOOGLE_MAPS_MAP_ID: ${{ secrets.GOOGLE_MAPS_MAP_ID }}
          CF_DNS_API_TOKEN: ${{ secrets.CF_DNS_API_TOKEN }}
          RESEND_API_KEY: ${{ secrets.RESEND_API_KEY }}
+          STRIPE_SECRET_KEY: ${{ secrets.STRIPE_SECRET_KEY }}
+          STRIPE_WEBHOOK_SECRET: ${{ secrets.STRIPE_WEBHOOK_SECRET }}

      - name: Initialize data directories
        run: |
@@ -129,17 +178,19 @@ jobs:
        run: |
          docker pull $BACKEND_IMAGE
          docker pull $FRONTEND_IMAGE
+          docker pull $OCR_IMAGE

      - name: Deploy staging stack
        run: |
          cd "$DEPLOY_PATH"
          export BACKEND_IMAGE=$BACKEND_IMAGE
          export FRONTEND_IMAGE=$FRONTEND_IMAGE
-          docker compose -f $COMPOSE_FILE -f $COMPOSE_STAGING down --timeout 30 || true
-          docker compose -f $COMPOSE_FILE -f $COMPOSE_STAGING up -d
+          export OCR_IMAGE=$OCR_IMAGE
+          docker compose -f $BASE_COMPOSE_FILE -f $STAGING_COMPOSE_FILE down --timeout 30 || true
+          docker compose -f $BASE_COMPOSE_FILE -f $STAGING_COMPOSE_FILE up -d

      - name: Wait for services
-        run: sleep 15
+        run: sleep 5

  # ============================================
  # VERIFY STAGING - Health checks
@@ -154,7 +205,7 @@ jobs:

      - name: Check container status and health
        run: |
-          for service in mvp-frontend-staging mvp-backend-staging mvp-postgres-staging mvp-redis-staging; do
+          for service in mvp-frontend-staging mvp-backend-staging mvp-ocr-staging mvp-postgres-staging mvp-redis-staging; do
            status=$(docker inspect --format='{{.State.Status}}' $service 2>/dev/null || echo "not found")
            if [ "$status" != "running" ]; then
              echo "ERROR: $service is not running (status: $status)"
@@ -167,26 +218,25 @@ jobs:
          # Wait for Docker healthchecks to complete (services with healthcheck defined)
          echo ""
          echo "Waiting for Docker healthchecks..."
-          for service in mvp-frontend-staging mvp-backend-staging mvp-postgres-staging mvp-redis-staging; do
+          for service in mvp-frontend-staging mvp-backend-staging mvp-ocr-staging mvp-postgres-staging mvp-redis-staging; do
            # Check if service has a healthcheck defined
            has_healthcheck=$(docker inspect --format='{{if .Config.Healthcheck}}true{{else}}false{{end}}' $service 2>/dev/null || echo "false")
            if [ "$has_healthcheck" = "true" ]; then
-              for i in 1 2 3 4 5 6 7 8 9 10; do
+              # 48 attempts x 5 seconds = 4 minutes max wait (backend with fresh migrations can take ~3 min)
+              for i in $(seq 1 48); do
                health=$(docker inspect --format='{{.State.Health.Status}}' $service 2>/dev/null || echo "unknown")
                if [ "$health" = "healthy" ]; then
                  echo "OK: $service is healthy"
                  break
-                elif [ "$health" = "unhealthy" ]; then
-                  echo "ERROR: $service is unhealthy"
-                  docker logs $service --tail 50 2>/dev/null || true
-                  exit 1
                fi
-                if [ $i -eq 10 ]; then
+                # Don't fail immediately on unhealthy - container may still be starting up
+                # and can recover. Let the timeout handle truly broken containers.
+                if [ $i -eq 48 ]; then
                  echo "ERROR: $service health check timed out (status: $health)"
-                  docker logs $service --tail 50 2>/dev/null || true
+                  docker logs $service --tail 100 2>/dev/null || true
                  exit 1
                fi
-                echo "Waiting for $service healthcheck... (attempt $i/10, status: $health)"
+                echo "Waiting for $service healthcheck... (attempt $i/48, status: $health)"
                sleep 5
              done
            else
@@ -196,36 +246,36 @@ jobs:

      - name: Wait for backend health
        run: |
-          for i in 1 2 3 4 5 6; do
+          for i in $(seq 1 12); do
            if docker exec mvp-backend-staging curl -sf http://localhost:3001/health > /dev/null 2>&1; then
              echo "OK: Backend health check passed"
              exit 0
            fi
-            if [ $i -eq 6 ]; then
-              echo "ERROR: Backend health check failed after 6 attempts"
+            if [ $i -eq 12 ]; then
+              echo "ERROR: Backend health check failed after 12 attempts"
              docker logs mvp-backend-staging --tail 100
              exit 1
            fi
-            echo "Attempt $i/6: Backend not ready, waiting 10s..."
-            sleep 10
+            echo "Attempt $i/12: Backend not ready, waiting 5s..."
+            sleep 5
          done

      - name: Check external endpoint
        run: |
          REQUIRED_FEATURES='["admin","auth","onboarding","vehicles","documents","fuel-logs","stations","maintenance","platform","notifications","user-profile","user-preferences","user-export"]'

-          for i in 1 2 3 4 5 6; do
+          for i in $(seq 1 12); do
            RESPONSE=$(curl -sf https://staging.motovaultpro.com/api/health 2>/dev/null) || {
-              echo "Attempt $i/6: Connection failed, waiting 10s..."
-              sleep 10
+              echo "Attempt $i/12: Connection failed, waiting 5s..."
+              sleep 5
              continue
            }

            # Check status is "healthy"
            STATUS=$(echo "$RESPONSE" | jq -r '.status')
            if [ "$STATUS" != "healthy" ]; then
-              echo "Attempt $i/6: Status is '$STATUS', not 'healthy'. Waiting 10s..."
-              sleep 10
+              echo "Attempt $i/12: Status is '$STATUS', not 'healthy'. Waiting 5s..."
+              sleep 5
              continue
            fi

@@ -235,8 +285,8 @@ jobs:
            ')

            if [ -n "$MISSING" ]; then
-              echo "Attempt $i/6: Missing features: $MISSING. Waiting 10s..."
-              sleep 10
+              echo "Attempt $i/12: Missing features: $MISSING. Waiting 5s..."
+              sleep 5
              continue
            fi

@@ -245,7 +295,7 @@ jobs:
            exit 0
          done

-          echo "ERROR: Staging health check failed after 6 attempts"
+          echo "ERROR: Staging health check failed after 12 attempts"
          echo "Last response: $RESPONSE"
          exit 1

--- a/.gitignore
+++ b/.gitignore
@@ -2,6 +2,7 @@ node_modules/
 .env
 .env.local
 .env.backup
+.env.logging
 dist/
 *.log
 .DS_Store
@@ -12,12 +13,16 @@ coverage/
 *.swo
 .venv
 .playwright-mcp
+__pycache__/
+*.py[cod]
+*$py.class

 # K8s-aligned secret mounts (real files ignored; examples committed)
 secrets/**
 !secrets/
 !secrets/**/
 !secrets/**/*.example
+!secrets/app/google-wif-config.json

 # Traefik ACME certificates (contains private keys)
 data/traefik/acme.json
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,6 +1,6 @@
 # MotoVaultPro

-Single-tenant vehicle management application with 5-container architecture (Traefik, Frontend, Backend, PostgreSQL, Redis).
+Single-tenant vehicle management application with 9-container architecture (6 application: Traefik, Frontend, Backend, OCR, PostgreSQL, Redis + 3 logging: Loki, Alloy, Grafana).

 ## Files

@@ -8,6 +8,9 @@ Single-tenant vehicle management application with 5-container architecture (Trae
 | ---- | ---- | ------------ |
 | `Makefile` | Build, test, deploy commands | Running any make command |
 | `docker-compose.yml` | Development container orchestration | Local development setup |
+| `docker-compose.staging.yml` | Staging container orchestration | Staging deployment |
+| `docker-compose.prod.yml` | Production container orchestration | Production deployment |
+| `docker-compose.blue-green.yml` | Blue-green deployment orchestration | Zero-downtime deploys |
 | `package.json` | Root workspace dependencies | Dependency management |
 | `README.md` | Project overview | First-time setup |

@@ -17,13 +20,17 @@ Single-tenant vehicle management application with 5-container architecture (Trae
 | --------- | ---- | ------------ |
 | `backend/` | Fastify API server with feature capsules | Backend development |
 | `frontend/` | React/Vite SPA with MUI | Frontend development |
+| `ocr/` | Python OCR microservice (Tesseract) | OCR pipeline, receipt/VIN extraction |
 | `docs/` | Project documentation hub | Architecture, APIs, testing |
-| `config/` | Configuration files (Traefik, monitoring) | Infrastructure setup |
-| `scripts/` | Utility scripts (backup, deploy) | Automation tasks |
+| `config/` | Configuration files (Traefik, logging stack) | Infrastructure setup |
+| `scripts/` | Utility scripts (backup, deploy, CI) | Automation tasks |
 | `.ai/` | AI context and workflow contracts | AI-assisted development |
 | `.claude/` | Claude Code agents and skills | Delegating to agents, using skills |
 | `.gitea/` | Gitea workflows and templates | CI/CD, issue templates |
 | `ansible/` | Ansible deployment playbooks | Server provisioning |
+| `certs/` | TLS certificates | SSL/TLS configuration |
+| `secrets/` | Docker secrets (Stripe keys, Traefik) | Secret management |
+| `data/` | Persistent data volumes (backups, documents) | Storage paths, volume mounts |

 ## Build for staging and production. NOT FOR DEVELOPMENT

@@ -167,13 +174,23 @@ Issues are the source of truth. See `.ai/workflow-contract.json` for complete wo
 - Every PR must link to at least one issue
 - Use Gitea MCP tools for issue/label/branch/PR operations
 - Labels: `status/backlog` -> `status/ready` -> `status/in-progress` -> `status/review` -> `status/done`
- Branches: `issue-{index}-{slug}` (e.g., `issue-42-add-fuel-report`)
+- Branches: `issue-{parent_index}-{slug}` (e.g., `issue-42-add-fuel-report`)
 - Commits: `{type}: {summary} (refs #{index})` (e.g., `feat: add fuel report (refs #42)`)

+### Sub-Issue Decomposition
+Multi-file features (3+ files) must be broken into sub-issues for smaller AI context windows:
+- **Sub-issue title**: `{type}: {summary} (#{parent_index})` -- parent index in title
+- **Sub-issue body**: First line `Relates to #{parent_index}`
+- **ONE branch** per parent issue only. Never branch per sub-issue.
+- **ONE PR** per parent issue. Body lists `Fixes #N` for parent and every sub-issue.
+- **Commits** reference the specific sub-issue: `feat: add dashboard (refs #107)`
+- **Status labels** tracked on parent only. Sub-issues stay `status/backlog`.
+- **Plan milestones** map 1:1 to sub-issues.
+
 ## Architecture Context for AI

-### Simplified 5-Container Architecture
-**MotoVaultPro uses a simplified architecture:** A single-tenant application with 5 containers - Traefik, Frontend, Backend, PostgreSQL, and Redis. Application features in `backend/src/features/[name]/` are self-contained modules within the backend service, including the platform feature for vehicle data and VIN decoding.
+### 9-Container Architecture
+**MotoVaultPro uses a unified architecture:** A single-tenant application with 9 containers - 6 application (Traefik, Frontend, Backend, OCR, PostgreSQL, Redis) + 3 logging (Loki, Alloy, Grafana). Application features in `backend/src/features/[name]/` are self-contained modules within the backend service, including the platform feature for vehicle data and VIN decoding. See `docs/LOGGING.md` for unified logging system documentation.

 ### Key Principles for AI Understanding
 - **Feature Capsule Organization**: Application features are self-contained modules within the backend
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # MotoVaultPro — Simplified Architecture

-Simplified 5-container architecture with integrated platform feature.
+9-container architecture (6 application + 3 logging) with integrated platform feature.

 ## Requirements
 - Mobile + Desktop: Implement and test every feature on both.
@@ -240,10 +240,19 @@ make migrate  # run DB migrations
    Skills: codebase-analysis, problem-analysis, decision-critic, planner, doc-sync
    Role-Agents: Developer, Technical Writer (TW), Quality Reviewer (QR), Debugger
    Domain Agents: Feature Agent, Frontend Agent, Platform Agent, Quality Agent
-    
+
    Labels: status/backlog -> status/ready -> status/in-progress -> status/review -> status/done
    Commits: {type}: {summary} (refs #{N})  |  Types: feat, fix, chore, docs, refactor, test
    Branches: issue-{N}-{slug}  |  Example: issue-42-add-fuel-report
+
+    SUB-ISSUE PATTERN (multi-file features)
+    ----------------------------------------
+    Parent: #105 "feat: Add Grafana dashboards"
+    Sub:    #106 "feat: Dashboard provisioning (#105)"  <-- parent index in title
+    Branch: issue-105-add-grafana-dashboards            <-- ONE branch, parent index
+    Commit: feat: add provisioning (refs #106)          <-- refs specific sub-issue
+    PR:     feat: Add Grafana dashboards (#105)         <-- ONE PR, parent index
+            Body: Fixes #105, Fixes #106, Fixes #107... <-- closes all
    
    QUALITY RULES
    -------------
--- a/ansible/CLAUDE.md
+++ b/ansible/CLAUDE.md
@@ -0,0 +1,11 @@
+# ansible/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `deploy-production-runner.yml` | Production runner deployment | Production deployments |
+| `deploy-staging-runner.yml` | Staging runner deployment | Staging deployments |
+| `inventory.yml` | Server inventory | Server host configuration |
+| `inventory.yml.example` | Example inventory template | Setting up new environments |
+| `config.yaml.j2` | Jinja2 config template | Runner configuration |
--- a/ansible/deploy-production-runner.yml
+++ b/ansible/deploy-production-runner.yml
@@ -269,24 +269,17 @@
      when: gitea_registry_token is defined

    # ============================================
-    # Maintenance Scripts
+    # Remove Legacy Docker Cleanup (was destroying volumes)
    # ============================================
-    - name: Create Docker cleanup script
-      copy:
-        dest: /usr/local/bin/docker-cleanup.sh
-        content: |
-          #!/bin/bash
-          # Remove unused Docker resources older than 7 days
-          docker system prune -af --filter "until=168h"
-          docker volume prune -f
-        mode: '0755'
-
-    - name: Schedule Docker cleanup cron job
+    - name: Remove legacy Docker cleanup cron job
      cron:
        name: "Docker cleanup"
-        minute: "0"
-        hour: "3"
-        job: "/usr/local/bin/docker-cleanup.sh >> /var/log/docker-cleanup.log 2>&1"
+        state: absent
+
+    - name: Remove legacy Docker cleanup script
+      file:
+        path: /usr/local/bin/docker-cleanup.sh
+        state: absent

    # ============================================
    # Production-Specific Security Hardening
--- a/ansible/deploy-staging-runner.yml
+++ b/ansible/deploy-staging-runner.yml
@@ -300,24 +300,17 @@
      when: gitea_registry_token is defined

    # ============================================
-    # Maintenance Scripts
+    # Remove Legacy Docker Cleanup (was destroying volumes)
    # ============================================
-    - name: Create Docker cleanup script
-      copy:
-        dest: /usr/local/bin/docker-cleanup.sh
-        content: |
-          #!/bin/bash
-          # Remove unused Docker resources older than 7 days
-          docker system prune -af --filter "until=168h"
-          docker volume prune -f
-        mode: '0755'
-
-    - name: Schedule Docker cleanup cron job
+    - name: Remove legacy Docker cleanup cron job
      cron:
        name: "Docker cleanup"
-        minute: "0"
-        hour: "3"
-        job: "/usr/local/bin/docker-cleanup.sh >> /var/log/docker-cleanup.log 2>&1"
+        state: absent
+
+    - name: Remove legacy Docker cleanup script
+      file:
+        path: /usr/local/bin/docker-cleanup.sh
+        state: absent

  handlers:
    - name: Restart act_runner
--- a/backend/CLAUDE.md
+++ b/backend/CLAUDE.md
@@ -7,7 +7,8 @@
 | `README.md` | Backend quickstart and commands | Getting started with backend development |
 | `package.json` | Dependencies and npm scripts | Adding dependencies, understanding build |
 | `tsconfig.json` | TypeScript configuration | Compiler settings, path aliases |
-| `jest.config.ts` | Jest test configuration | Test setup, coverage settings |
+| `eslint.config.js` | ESLint configuration | Linting rules, code style |
+| `jest.config.js` | Jest test configuration | Test setup, coverage settings |
 | `Dockerfile` | Container build definition | Docker builds, deployment |

 ## Subdirectories
@@ -15,4 +16,4 @@
 | Directory | What | When to read |
 | --------- | ---- | ------------ |
 | `src/` | Application source code | Any backend development |
-| `scripts/` | Utility scripts | Database scripts, automation |
+| `scripts/` | Utility scripts (docker-entrypoint) | Container startup, automation |
--- a/backend/package-lock.json
+++ b/backend/package-lock.json
@@ -20,21 +20,26 @@
        "fastify": "^5.2.0",
        "fastify-plugin": "^5.0.1",
        "file-type": "^16.5.4",
+        "form-data": "^4.0.0",
        "get-jwks": "^11.0.3",
        "ioredis": "^5.4.2",
        "js-yaml": "^4.1.0",
+        "mailparser": "^3.9.3",
        "node-cron": "^3.0.3",
        "opossum": "^8.0.0",
        "pg": "^8.13.1",
+        "pino": "^9.6.0",
        "resend": "^3.0.0",
+        "stripe": "^20.2.0",
+        "svix": "^1.85.0",
        "tar": "^7.4.3",
-        "winston": "^3.17.0",
        "zod": "^3.24.1"
      },
      "devDependencies": {
        "@eslint/js": "^9.17.0",
        "@types/jest": "^29.5.10",
        "@types/js-yaml": "^4.0.9",
+        "@types/mailparser": "^3.4.6",
        "@types/node": "^22.0.0",
        "@types/node-cron": "^3.0.11",
        "@types/opossum": "^8.0.0",
@@ -81,7 +86,6 @@
      "integrity": "sha512-e7jT4DxYvIDLk1ZHmU/m/mB19rex9sv0c2ftBtjSBv+kVM/902eh0fINUzD7UwLLNR+jU585GxUJ8/EBfAM5fw==",
      "dev": true,
      "license": "MIT",
-      "peer": true,
      "dependencies": {
        "@babel/code-frame": "^7.27.1",
        "@babel/generator": "^7.28.5",
@@ -577,15 +581,6 @@
      "dev": true,
      "license": "MIT"
    },
-    "node_modules/@colors/colors": {
-      "version": "1.6.0",
-      "resolved": "https://registry.npmjs.org/@colors/colors/-/colors-1.6.0.tgz",
-      "integrity": "sha512-Ir+AOibqzrIsL6ajt3Rz3LskB7OiMVHqltZmspbW/TJuTVuyOMirVqAkjfY6JISiLHgyNqicAC8AyHHGzNd/dA==",
-      "license": "MIT",
-      "engines": {
-        "node": ">=0.1.90"
-      }
-    },
    "node_modules/@cspotcode/source-map-support": {
      "version": "0.8.1",
      "resolved": "https://registry.npmjs.org/@cspotcode/source-map-support/-/source-map-support-0.8.1.tgz",
@@ -610,17 +605,6 @@
        "@jridgewell/sourcemap-codec": "^1.4.10"
      }
    },
-    "node_modules/@dabh/diagnostics": {
-      "version": "2.0.8",
-      "resolved": "https://registry.npmjs.org/@dabh/diagnostics/-/diagnostics-2.0.8.tgz",
-      "integrity": "sha512-R4MSXTVnuMzGD7bzHdW2ZhhdPC/igELENcq5IjEverBvq5hn1SXCWcsi6eSsdWP0/Ur+SItRRjAktmdoX/8R/Q==",
-      "license": "MIT",
-      "dependencies": {
-        "@so-ric/colorspace": "^1.1.6",
-        "enabled": "2.0.x",
-        "kuler": "^2.0.0"
-      }
-    },
    "node_modules/@eslint-community/eslint-utils": {
      "version": "4.9.0",
      "resolved": "https://registry.npmjs.org/@eslint-community/eslint-utils/-/eslint-utils-4.9.0.tgz",
@@ -1784,15 +1768,11 @@
        "@sinonjs/commons": "^3.0.0"
      }
    },
-    "node_modules/@so-ric/colorspace": {
-      "version": "1.1.6",
-      "resolved": "https://registry.npmjs.org/@so-ric/colorspace/-/colorspace-1.1.6.tgz",
-      "integrity": "sha512-/KiKkpHNOBgkFJwu9sh48LkHSMYGyuTcSFK/qMBdnOAlrRJzRSXAOFB5qwzaVQuDl8wAvHVMkaASQDReTahxuw==",
-      "license": "MIT",
-      "dependencies": {
-        "color": "^5.0.2",
-        "text-hex": "1.0.x"
-      }
+    "node_modules/@stablelib/base64": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/@stablelib/base64/-/base64-1.0.1.tgz",
+      "integrity": "sha512-1bnPQqSxSuc3Ii6MhBysoWCg58j97aUjuCSZrGSmDxNqtytIi0k8utUenAwTZN4V5mXXYGsVUI9zeBqy+jBOSQ==",
+      "license": "MIT"
    },
    "node_modules/@tokenizer/token": {
      "version": "0.3.0",
@@ -1949,6 +1929,30 @@
      "dev": true,
      "license": "MIT"
    },
+    "node_modules/@types/mailparser": {
+      "version": "3.4.6",
+      "resolved": "https://registry.npmjs.org/@types/mailparser/-/mailparser-3.4.6.tgz",
+      "integrity": "sha512-wVV3cnIKzxTffaPH8iRnddX1zahbYB1ZEoAxyhoBo3TBCBuK6nZ8M8JYO/RhsCuuBVOw/DEN/t/ENbruwlxn6Q==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "*",
+        "iconv-lite": "^0.6.3"
+      }
+    },
+    "node_modules/@types/mailparser/node_modules/iconv-lite": {
+      "version": "0.6.3",
+      "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.6.3.tgz",
+      "integrity": "sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "safer-buffer": ">= 2.1.2 < 3.0.0"
+      },
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
    "node_modules/@types/methods": {
      "version": "1.1.4",
      "resolved": "https://registry.npmjs.org/@types/methods/-/methods-1.1.4.tgz",
@@ -1960,9 +1964,8 @@
      "version": "22.19.3",
      "resolved": "https://registry.npmjs.org/@types/node/-/node-22.19.3.tgz",
      "integrity": "sha512-1N9SBnWYOJTrNZCdh/yJE+t910Y128BoyY+zBLWhL3r0TYzlTmFdXrPwHL9DyFZmlEXNQQolTZh3KHV31QDhyA==",
-      "dev": true,
+      "devOptional": true,
      "license": "MIT",
-      "peer": true,
      "dependencies": {
        "undici-types": "~6.21.0"
      }
@@ -2027,12 +2030,6 @@
        "@types/superagent": "^8.1.0"
      }
    },
-    "node_modules/@types/triple-beam": {
-      "version": "1.3.5",
-      "resolved": "https://registry.npmjs.org/@types/triple-beam/-/triple-beam-1.3.5.tgz",
-      "integrity": "sha512-6WaYesThRMCl19iryMYP7/x2OVgCtbIVflDGFpWnb9irXI3UjYE4AzmYuiUKY1AJstGijoY+MgUszMgRxIYTYw==",
-      "license": "MIT"
-    },
    "node_modules/@types/yargs": {
      "version": "17.0.35",
      "resolved": "https://registry.npmjs.org/@types/yargs/-/yargs-17.0.35.tgz",
@@ -2095,7 +2092,6 @@
      "integrity": "sha512-6/cmF2piao+f6wSxUsJLZjck7OQsYyRtcOZS02k7XINSNlz93v6emM8WutDQSXnroG2xwYlEVHJI+cPA7CPM3Q==",
      "dev": true,
      "license": "MIT",
-      "peer": true,
      "dependencies": {
        "@typescript-eslint/scope-manager": "8.50.0",
        "@typescript-eslint/types": "8.50.0",
@@ -2307,6 +2303,17 @@
        "url": "https://opencollective.com/typescript-eslint"
      }
    },
+    "node_modules/@zone-eu/mailsplit": {
+      "version": "5.4.8",
+      "resolved": "https://registry.npmjs.org/@zone-eu/mailsplit/-/mailsplit-5.4.8.tgz",
+      "integrity": "sha512-eEyACj4JZ7sjzRvy26QhLgKEMWwQbsw1+QZnlLX+/gihcNH07lVPOcnwf5U6UAL7gkc//J3jVd76o/WS+taUiA==",
+      "license": "(MIT OR EUPL-1.1+)",
+      "dependencies": {
+        "libbase64": "1.3.0",
+        "libmime": "5.3.7",
+        "libqp": "2.1.1"
+      }
+    },
    "node_modules/abbrev": {
      "version": "2.0.0",
      "resolved": "https://registry.npmjs.org/abbrev/-/abbrev-2.0.0.tgz",
@@ -2340,7 +2347,6 @@
      "integrity": "sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg==",
      "dev": true,
      "license": "MIT",
-      "peer": true,
      "bin": {
        "acorn": "bin/acorn"
      },
@@ -2513,12 +2519,6 @@
        "safer-buffer": "^2.1.0"
      }
    },
-    "node_modules/async": {
-      "version": "3.2.6",
-      "resolved": "https://registry.npmjs.org/async/-/async-3.2.6.tgz",
-      "integrity": "sha512-htCUDlxyyCLMgaM3xXg0C0LW2xqfuQ6p05pCEIsXuyQ+a1koYKTuBMzRNwmybfLgvJDMd0r1LTn4+E0Ti6C2AA==",
-      "license": "MIT"
-    },
    "node_modules/asynckit": {
      "version": "0.4.0",
      "resolved": "https://registry.npmjs.org/asynckit/-/asynckit-0.4.0.tgz",
@@ -2813,7 +2813,6 @@
        }
      ],
      "license": "MIT",
-      "peer": true,
      "dependencies": {
        "baseline-browser-mapping": "^2.9.0",
        "caniuse-lite": "^1.0.30001759",
@@ -2899,7 +2898,6 @@
      "version": "1.0.4",
      "resolved": "https://registry.npmjs.org/call-bound/-/call-bound-1.0.4.tgz",
      "integrity": "sha512-+ys997U96po4Kx/ABpBCqhA9EuxJaQWDQg7295H4hBphv3IZg0boBKuwYpt4YXp6MZ5AmZQnU/tyMTlRpaSejg==",
-      "dev": true,
      "license": "MIT",
      "dependencies": {
        "call-bind-apply-helpers": "^1.0.2",
@@ -3092,19 +3090,6 @@
      "dev": true,
      "license": "MIT"
    },
-    "node_modules/color": {
-      "version": "5.0.3",
-      "resolved": "https://registry.npmjs.org/color/-/color-5.0.3.tgz",
-      "integrity": "sha512-ezmVcLR3xAVp8kYOm4GS45ZLLgIE6SPAFoduLr6hTDajwb3KZ2F46gulK3XpcwRFb5KKGCSezCBAY4Dw4HsyXA==",
-      "license": "MIT",
-      "dependencies": {
-        "color-convert": "^3.1.3",
-        "color-string": "^2.1.3"
-      },
-      "engines": {
-        "node": ">=18"
-      }
-    },
    "node_modules/color-convert": {
      "version": "2.0.1",
      "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz",
@@ -3123,48 +3108,6 @@
      "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==",
      "license": "MIT"
    },
-    "node_modules/color-string": {
-      "version": "2.1.4",
-      "resolved": "https://registry.npmjs.org/color-string/-/color-string-2.1.4.tgz",
-      "integrity": "sha512-Bb6Cq8oq0IjDOe8wJmi4JeNn763Xs9cfrBcaylK1tPypWzyoy2G3l90v9k64kjphl/ZJjPIShFztenRomi8WTg==",
-      "license": "MIT",
-      "dependencies": {
-        "color-name": "^2.0.0"
-      },
-      "engines": {
-        "node": ">=18"
-      }
-    },
-    "node_modules/color-string/node_modules/color-name": {
-      "version": "2.1.0",
-      "resolved": "https://registry.npmjs.org/color-name/-/color-name-2.1.0.tgz",
-      "integrity": "sha512-1bPaDNFm0axzE4MEAzKPuqKWeRaT43U/hyxKPBdqTfmPF+d6n7FSoTFxLVULUJOmiLp01KjhIPPH+HrXZJN4Rg==",
-      "license": "MIT",
-      "engines": {
-        "node": ">=12.20"
-      }
-    },
-    "node_modules/color/node_modules/color-convert": {
-      "version": "3.1.3",
-      "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-3.1.3.tgz",
-      "integrity": "sha512-fasDH2ont2GqF5HpyO4w0+BcewlhHEZOFn9c1ckZdHpJ56Qb7MHhH/IcJZbBGgvdtwdwNbLvxiBEdg336iA9Sg==",
-      "license": "MIT",
-      "dependencies": {
-        "color-name": "^2.0.0"
-      },
-      "engines": {
-        "node": ">=14.6"
-      }
-    },
-    "node_modules/color/node_modules/color-name": {
-      "version": "2.1.0",
-      "resolved": "https://registry.npmjs.org/color-name/-/color-name-2.1.0.tgz",
-      "integrity": "sha512-1bPaDNFm0axzE4MEAzKPuqKWeRaT43U/hyxKPBdqTfmPF+d6n7FSoTFxLVULUJOmiLp01KjhIPPH+HrXZJN4Rg==",
-      "license": "MIT",
-      "engines": {
-        "node": ">=12.20"
-      }
-    },
    "node_modules/combined-stream": {
      "version": "1.0.8",
      "resolved": "https://registry.npmjs.org/combined-stream/-/combined-stream-1.0.8.tgz",
@@ -3566,11 +3509,14 @@
      "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==",
      "license": "MIT"
    },
-    "node_modules/enabled": {
-      "version": "2.0.0",
-      "resolved": "https://registry.npmjs.org/enabled/-/enabled-2.0.0.tgz",
-      "integrity": "sha512-AKrN98kuwOzMIdAizXGI86UFBoo26CL21UM763y1h/GMSJ4/OHU9k2YlsmBpyScFo/wbLzWQJBMCW4+IO3/+OQ==",
-      "license": "MIT"
+    "node_modules/encoding-japanese": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/encoding-japanese/-/encoding-japanese-2.2.0.tgz",
+      "integrity": "sha512-EuJWwlHPZ1LbADuKTClvHtwbaFn4rOD+dRAbWysqEOXRc2Uui0hJInNJrsdH0c+OhJA4nrCBdSkW4DD5YxAo6A==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=8.10.0"
+      }
    },
    "node_modules/entities": {
      "version": "4.5.0",
@@ -3668,7 +3614,6 @@
      "integrity": "sha512-LEyamqS7W5HB3ujJyvi0HQK/dtVINZvd5mAAp9eT5S/ujByGjiZLCzPcHVzuXbpJDJF/cxwHlfceVUDZ2lnSTw==",
      "dev": true,
      "license": "MIT",
-      "peer": true,
      "dependencies": {
        "@eslint-community/eslint-utils": "^4.8.0",
        "@eslint-community/regexpp": "^4.12.1",
@@ -4002,6 +3947,12 @@
      "dev": true,
      "license": "MIT"
    },
+    "node_modules/fast-sha256": {
+      "version": "1.3.0",
+      "resolved": "https://registry.npmjs.org/fast-sha256/-/fast-sha256-1.3.0.tgz",
+      "integrity": "sha512-n11RGP/lrWEFI/bWdygLxhI+pVeo1ZYIVwvvPkW7azl/rOy+F3HYRZ2K5zeE9mmkhQppyv9sQFx0JM9UabnpPQ==",
+      "license": "Unlicense"
+    },
    "node_modules/fast-uri": {
      "version": "3.1.0",
      "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.0.tgz",
@@ -4079,6 +4030,49 @@
      ],
      "license": "MIT"
    },
+    "node_modules/fastify/node_modules/pino": {
+      "version": "10.3.0",
+      "resolved": "https://registry.npmjs.org/pino/-/pino-10.3.0.tgz",
+      "integrity": "sha512-0GNPNzHXBKw6U/InGe79A3Crzyk9bcSyObF9/Gfo9DLEf5qj5RF50RSjsu0W1rZ6ZqRGdzDFCRBQvi9/rSGPtA==",
+      "license": "MIT",
+      "dependencies": {
+        "@pinojs/redact": "^0.4.0",
+        "atomic-sleep": "^1.0.0",
+        "on-exit-leak-free": "^2.1.0",
+        "pino-abstract-transport": "^3.0.0",
+        "pino-std-serializers": "^7.0.0",
+        "process-warning": "^5.0.0",
+        "quick-format-unescaped": "^4.0.3",
+        "real-require": "^0.2.0",
+        "safe-stable-stringify": "^2.3.1",
+        "sonic-boom": "^4.0.1",
+        "thread-stream": "^4.0.0"
+      },
+      "bin": {
+        "pino": "bin.js"
+      }
+    },
+    "node_modules/fastify/node_modules/pino-abstract-transport": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/pino-abstract-transport/-/pino-abstract-transport-3.0.0.tgz",
+      "integrity": "sha512-wlfUczU+n7Hy/Ha5j9a/gZNy7We5+cXp8YL+X+PG8S0KXxw7n/JXA3c46Y0zQznIJ83URJiwy7Lh56WLokNuxg==",
+      "license": "MIT",
+      "dependencies": {
+        "split2": "^4.0.0"
+      }
+    },
+    "node_modules/fastify/node_modules/thread-stream": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/thread-stream/-/thread-stream-4.0.0.tgz",
+      "integrity": "sha512-4iMVL6HAINXWf1ZKZjIPcz5wYaOdPhtO8ATvZ+Xqp3BTdaqtAwQkNmKORqcIo5YkQqGXq5cwfswDwMqqQNrpJA==",
+      "license": "MIT",
+      "dependencies": {
+        "real-require": "^0.2.0"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
    "node_modules/fastparallel": {
      "version": "2.4.1",
      "resolved": "https://registry.npmjs.org/fastparallel/-/fastparallel-2.4.1.tgz",
@@ -4118,12 +4112,6 @@
        "bser": "2.1.1"
      }
    },
-    "node_modules/fecha": {
-      "version": "4.2.3",
-      "resolved": "https://registry.npmjs.org/fecha/-/fecha-4.2.3.tgz",
-      "integrity": "sha512-OP2IUU6HeYKJi3i0z4A19kHMQoLVs4Hc+DPqqxI2h/DPZHTm/vjsfC6P0b4jCMy14XizLBqvndQ+UilD7707Jw==",
-      "license": "MIT"
-    },
    "node_modules/file-entry-cache": {
      "version": "8.0.0",
      "resolved": "https://registry.npmjs.org/file-entry-cache/-/file-entry-cache-8.0.0.tgz",
@@ -4219,12 +4207,6 @@
      "dev": true,
      "license": "ISC"
    },
-    "node_modules/fn.name": {
-      "version": "1.1.0",
-      "resolved": "https://registry.npmjs.org/fn.name/-/fn.name-1.1.0.tgz",
-      "integrity": "sha512-GRnmB5gPyJpAhTQdSZTSp9uaPSvl09KoYcMQtsB9rQoOmzs9dH6ffeccH+Z+cv6P68Hu5bC6JjRh4Ah/mHSNRw==",
-      "license": "MIT"
-    },
    "node_modules/follow-redirects": {
      "version": "1.15.11",
      "resolved": "https://registry.npmjs.org/follow-redirects/-/follow-redirects-1.15.11.tgz",
@@ -4579,6 +4561,15 @@
        "node": ">= 0.4"
      }
    },
+    "node_modules/he": {
+      "version": "1.2.0",
+      "resolved": "https://registry.npmjs.org/he/-/he-1.2.0.tgz",
+      "integrity": "sha512-F/1DnUGPopORZi0ni+CvrCgHQ5FyEAHRLSApuYWMmrbSwoN2Mn/7k+Gl38gJnR7yyDZk6WLXwiGod1JOWNDKGw==",
+      "license": "MIT",
+      "bin": {
+        "he": "bin/he"
+      }
+    },
    "node_modules/helmet": {
      "version": "8.1.0",
      "resolved": "https://registry.npmjs.org/helmet/-/helmet-8.1.0.tgz",
@@ -4651,6 +4642,22 @@
        "node": ">=10.17.0"
      }
    },
+    "node_modules/iconv-lite": {
+      "version": "0.7.2",
+      "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.7.2.tgz",
+      "integrity": "sha512-im9DjEDQ55s9fL4EYzOAv0yMqmMBSZp6G0VvFyTMPKWxiSBHUj9NW/qqLmXUwXrrM7AvqSlTCfvqRb0cM8yYqw==",
+      "license": "MIT",
+      "dependencies": {
+        "safer-buffer": ">= 2.1.2 < 3.0.0"
+      },
+      "engines": {
+        "node": ">=0.10.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/express"
+      }
+    },
    "node_modules/ieee754": {
      "version": "1.2.1",
      "resolved": "https://registry.npmjs.org/ieee754/-/ieee754-1.2.1.tgz",
@@ -4884,6 +4891,7 @@
      "version": "2.0.1",
      "resolved": "https://registry.npmjs.org/is-stream/-/is-stream-2.0.1.tgz",
      "integrity": "sha512-hFoiJiTl63nn+kstHGBtewWSKnQLpyb155KHheA1l39uvtO9nWIop1p3udqPcUd/xbF1VLMO4n7OI6p7RbngDg==",
+      "dev": true,
      "license": "MIT",
      "engines": {
        "node": ">=8"
@@ -4990,7 +4998,6 @@
      "integrity": "sha512-NIy3oAFp9shda19hy4HK0HRTWKtPJmGdnvywu01nOqNC2vZg+Z+fvJDxpMQA88eb2I9EcafcdjYgsDthnYTvGw==",
      "dev": true,
      "license": "MIT",
-      "peer": true,
      "dependencies": {
        "@jest/core": "^29.7.0",
        "@jest/types": "^29.6.3",
@@ -5773,12 +5780,6 @@
        "node": ">=6"
      }
    },
-    "node_modules/kuler": {
-      "version": "2.0.0",
-      "resolved": "https://registry.npmjs.org/kuler/-/kuler-2.0.0.tgz",
-      "integrity": "sha512-Xq9nH7KlWZmXAtodXDDRE7vs6DU1gTU8zYDHDiWLSip45Egwq3plLHzPn27NgvzL2r1LMPC1vdqh98sQxtqj4A==",
-      "license": "MIT"
-    },
    "node_modules/leac": {
      "version": "0.6.0",
      "resolved": "https://registry.npmjs.org/leac/-/leac-0.6.0.tgz",
@@ -5812,6 +5813,42 @@
        "node": ">= 0.8.0"
      }
    },
+    "node_modules/libbase64": {
+      "version": "1.3.0",
+      "resolved": "https://registry.npmjs.org/libbase64/-/libbase64-1.3.0.tgz",
+      "integrity": "sha512-GgOXd0Eo6phYgh0DJtjQ2tO8dc0IVINtZJeARPeiIJqge+HdsWSuaDTe8ztQ7j/cONByDZ3zeB325AHiv5O0dg==",
+      "license": "MIT"
+    },
+    "node_modules/libmime": {
+      "version": "5.3.7",
+      "resolved": "https://registry.npmjs.org/libmime/-/libmime-5.3.7.tgz",
+      "integrity": "sha512-FlDb3Wtha8P01kTL3P9M+ZDNDWPKPmKHWaU/cG/lg5pfuAwdflVpZE+wm9m7pKmC5ww6s+zTxBKS1p6yl3KpSw==",
+      "license": "MIT",
+      "dependencies": {
+        "encoding-japanese": "2.2.0",
+        "iconv-lite": "0.6.3",
+        "libbase64": "1.3.0",
+        "libqp": "2.1.1"
+      }
+    },
+    "node_modules/libmime/node_modules/iconv-lite": {
+      "version": "0.6.3",
+      "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.6.3.tgz",
+      "integrity": "sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw==",
+      "license": "MIT",
+      "dependencies": {
+        "safer-buffer": ">= 2.1.2 < 3.0.0"
+      },
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/libqp": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/libqp/-/libqp-2.1.1.tgz",
+      "integrity": "sha512-0Wd+GPz1O134cP62YU2GTOPNA7Qgl09XwCqM5zpBv87ERCXdfDtyKXvV7c9U22yWJh44QZqBocFnXN11K96qow==",
+      "license": "MIT"
+    },
    "node_modules/light-my-request": {
      "version": "6.6.0",
      "resolved": "https://registry.npmjs.org/light-my-request/-/light-my-request-6.6.0.tgz",
@@ -5856,6 +5893,15 @@
      "dev": true,
      "license": "MIT"
    },
+    "node_modules/linkify-it": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/linkify-it/-/linkify-it-5.0.0.tgz",
+      "integrity": "sha512-5aHCbzQRADcdP+ATqnDuhhJ/MRIqDkZX5pyjFHRRysS8vZ5AbqGEoFIb6pYHPZ+L/OC2Lc+xT8uHVVR5CAK/wQ==",
+      "license": "MIT",
+      "dependencies": {
+        "uc.micro": "^2.0.0"
+      }
+    },
    "node_modules/locate-path": {
      "version": "6.0.0",
      "resolved": "https://registry.npmjs.org/locate-path/-/locate-path-6.0.0.tgz",
@@ -5898,28 +5944,12 @@
      "dev": true,
      "license": "MIT"
    },
-    "node_modules/logform": {
-      "version": "2.7.0",
-      "resolved": "https://registry.npmjs.org/logform/-/logform-2.7.0.tgz",
-      "integrity": "sha512-TFYA4jnP7PVbmlBIfhlSe+WKxs9dklXMTEGcBCIvLhE/Tn3H6Gk1norupVW7m5Cnd4bLcr08AytbyV/xj7f/kQ==",
-      "license": "MIT",
-      "dependencies": {
-        "@colors/colors": "1.6.0",
-        "@types/triple-beam": "^1.3.2",
-        "fecha": "^4.2.0",
-        "ms": "^2.1.1",
-        "safe-stable-stringify": "^2.3.1",
-        "triple-beam": "^1.3.0"
-      },
-      "engines": {
-        "node": ">= 12.0.0"
-      }
-    },
    "node_modules/loose-envify": {
      "version": "1.4.0",
      "resolved": "https://registry.npmjs.org/loose-envify/-/loose-envify-1.4.0.tgz",
      "integrity": "sha512-lyuxPGr/Wfhrlem2CL/UcnUc1zcqKAImBDzukY7Y5F/yQiNdko6+fRLevlw1HgMySw7f611UIY408EtxRSoK3Q==",
      "license": "MIT",
+      "peer": true,
      "dependencies": {
        "js-tokens": "^3.0.0 || ^4.0.0"
      },
@@ -5936,6 +5966,24 @@
        "node": "20 || >=22"
      }
    },
+    "node_modules/mailparser": {
+      "version": "3.9.3",
+      "resolved": "https://registry.npmjs.org/mailparser/-/mailparser-3.9.3.tgz",
+      "integrity": "sha512-AnB0a3zROum6fLaa52L+/K2SoRJVyFDk78Ea6q1D0ofcZLxWEWDtsS1+OrVqKbV7r5dulKL/AwYQccFGAPpuYQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@zone-eu/mailsplit": "5.4.8",
+        "encoding-japanese": "2.2.0",
+        "he": "1.2.0",
+        "html-to-text": "9.0.5",
+        "iconv-lite": "0.7.2",
+        "libmime": "5.3.7",
+        "linkify-it": "5.0.0",
+        "nodemailer": "7.0.13",
+        "punycode.js": "2.3.1",
+        "tlds": "1.261.0"
+      }
+    },
    "node_modules/make-dir": {
      "version": "4.0.0",
      "resolved": "https://registry.npmjs.org/make-dir/-/make-dir-4.0.0.tgz",
@@ -6164,6 +6212,15 @@
      "dev": true,
      "license": "MIT"
    },
+    "node_modules/nodemailer": {
+      "version": "7.0.13",
+      "resolved": "https://registry.npmjs.org/nodemailer/-/nodemailer-7.0.13.tgz",
+      "integrity": "sha512-PNDFSJdP+KFgdsG3ZzMXCgquO7I6McjY2vlqILjtJd0hy8wEvtugS9xKRF2NWlPNGxvLCXlTNIae4serI7dinw==",
+      "license": "MIT-0",
+      "engines": {
+        "node": ">=6.0.0"
+      }
+    },
    "node_modules/nodemon": {
      "version": "3.1.11",
      "resolved": "https://registry.npmjs.org/nodemon/-/nodemon-3.1.11.tgz",
@@ -6258,7 +6315,6 @@
      "version": "1.13.4",
      "resolved": "https://registry.npmjs.org/object-inspect/-/object-inspect-1.13.4.tgz",
      "integrity": "sha512-W67iLl4J2EXEGTbfeHCffrjDfitvLANg0UlX3wFUUSTx92KXRFegMHUVgSqE+wvhAbi4WqjGg9czysTV2Epbew==",
-      "dev": true,
      "license": "MIT",
      "engines": {
        "node": ">= 0.4"
@@ -6292,15 +6348,6 @@
        "wrappy": "1"
      }
    },
-    "node_modules/one-time": {
-      "version": "1.0.0",
-      "resolved": "https://registry.npmjs.org/one-time/-/one-time-1.0.0.tgz",
-      "integrity": "sha512-5DXOiRKwuSEcQ/l0kGCF6Q3jcADFv5tSmRaJck/OqkVFcOzutB134KRSfF0xDrL39MNnqxbHBbUUcjZIhTgb2g==",
-      "license": "MIT",
-      "dependencies": {
-        "fn.name": "1.x.x"
-      }
-    },
    "node_modules/onetime": {
      "version": "5.1.2",
      "resolved": "https://registry.npmjs.org/onetime/-/onetime-5.1.2.tgz",
@@ -6522,7 +6569,6 @@
      "resolved": "https://registry.npmjs.org/pg/-/pg-8.16.3.tgz",
      "integrity": "sha512-enxc1h0jA/aq5oSDMvqyW3q89ra6XIIDZgCX9vkMrnz5DFTw/Ny3Li2lFQ+pt3L6MCgm/5o2o8HW9hiJji+xvw==",
      "license": "MIT",
-      "peer": true,
      "dependencies": {
        "pg-connection-string": "^2.9.1",
        "pg-pool": "^3.10.1",
@@ -6628,9 +6674,9 @@
      }
    },
    "node_modules/pino": {
-      "version": "10.1.0",
-      "resolved": "https://registry.npmjs.org/pino/-/pino-10.1.0.tgz",
-      "integrity": "sha512-0zZC2ygfdqvqK8zJIr1e+wT1T/L+LF6qvqvbzEQ6tiMAoTqEVK9a1K3YRu8HEUvGEvNqZyPJTtb2sNIoTkB83w==",
+      "version": "9.14.0",
+      "resolved": "https://registry.npmjs.org/pino/-/pino-9.14.0.tgz",
+      "integrity": "sha512-8OEwKp5juEvb/MjpIc4hjqfgCNysrS94RIOMXYvpYCdm/jglrKEiAYmiumbmGhCvs+IcInsphYDFwqrjr7398w==",
      "license": "MIT",
      "dependencies": {
        "@pinojs/redact": "^0.4.0",
@@ -6888,6 +6934,15 @@
        "node": ">=6"
      }
    },
+    "node_modules/punycode.js": {
+      "version": "2.3.1",
+      "resolved": "https://registry.npmjs.org/punycode.js/-/punycode.js-2.3.1.tgz",
+      "integrity": "sha512-uxFIHU0YlHYhDQtV4R9J6a52SLx28BCjT+4ieh7IGbgwVJWO+km431c4yRlREUAsAmt/uMjQUyQHNEPf0M39CA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
    "node_modules/pure-rand": {
      "version": "6.1.0",
      "resolved": "https://registry.npmjs.org/pure-rand/-/pure-rand-6.1.0.tgz",
@@ -6906,10 +6961,9 @@
      "license": "MIT"
    },
    "node_modules/qs": {
-      "version": "6.14.0",
-      "resolved": "https://registry.npmjs.org/qs/-/qs-6.14.0.tgz",
-      "integrity": "sha512-YWWTjgABSKcvs/nWBi9PycY/JiPJqOD4JA6o9Sej2AtvSGarXxKC3OQSk4pAarbdQlKAh5D4FCQkJNkW+GAn3w==",
-      "dev": true,
+      "version": "6.14.1",
+      "resolved": "https://registry.npmjs.org/qs/-/qs-6.14.1.tgz",
+      "integrity": "sha512-4EK3+xJl8Ts67nLYNwqw/dsFVnCf+qR7RgXSK9jEEm9unao3njwMDdmsdvoKBKHzxd7tCYz5e5M+SnMjdtXGQQ==",
      "license": "BSD-3-Clause",
      "dependencies": {
        "side-channel": "^1.1.0"
@@ -6976,20 +7030,6 @@
      "integrity": "sha512-bCK/2Z4zLidyB4ReuIsvALH6w31YfAQDmXMqMx6FyfHqvBxtjC0eRumeSu4Bs3XtXwpyIywtSTrVT99BxY1f9w==",
      "license": "MIT"
    },
-    "node_modules/readable-stream": {
-      "version": "3.6.2",
-      "resolved": "https://registry.npmjs.org/readable-stream/-/readable-stream-3.6.2.tgz",
-      "integrity": "sha512-9u/sniCrY3D5WdsERHzHE4G2YCXqoG5FTHUiCC4SIbr6XcLZBY05ya9EKjYek9O5xOAwjGq+1JdGBAS7Q9ScoA==",
-      "license": "MIT",
-      "dependencies": {
-        "inherits": "^2.0.3",
-        "string_decoder": "^1.1.1",
-        "util-deprecate": "^1.0.1"
-      },
-      "engines": {
-        "node": ">= 6"
-      }
-    },
    "node_modules/readable-web-to-node-stream": {
      "version": "3.0.4",
      "resolved": "https://registry.npmjs.org/readable-web-to-node-stream/-/readable-web-to-node-stream-3.0.4.tgz",
@@ -7244,6 +7284,7 @@
      "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.23.2.tgz",
      "integrity": "sha512-UOShsPwz7NrMUqhR6t0hWjFduvOzbtv7toDH1/hIrfRNIDBnnBWd0CwJTGvTpngVlmwGCdP9/Zl/tVrDqcuYzQ==",
      "license": "MIT",
+      "peer": true,
      "dependencies": {
        "loose-envify": "^1.1.0"
      }
@@ -7319,7 +7360,6 @@
      "version": "1.1.0",
      "resolved": "https://registry.npmjs.org/side-channel/-/side-channel-1.1.0.tgz",
      "integrity": "sha512-ZX99e6tRweoUXqR+VBrslhda51Nh5MTQwou5tnUDgbtyM0dBgmhEDtWGP/xbKn6hqfPRHujUNwz5fy/wbbhnpw==",
-      "dev": true,
      "license": "MIT",
      "dependencies": {
        "es-errors": "^1.3.0",
@@ -7339,7 +7379,6 @@
      "version": "1.0.0",
      "resolved": "https://registry.npmjs.org/side-channel-list/-/side-channel-list-1.0.0.tgz",
      "integrity": "sha512-FCLHtRD/gnpCiCHEiJLOwdmFP+wzCmDEkc9y7NsYxeF4u7Btsn1ZuwgwJGxImImHicJArLP4R0yX4c2KCrMrTA==",
-      "dev": true,
      "license": "MIT",
      "dependencies": {
        "es-errors": "^1.3.0",
@@ -7356,7 +7395,6 @@
      "version": "1.0.1",
      "resolved": "https://registry.npmjs.org/side-channel-map/-/side-channel-map-1.0.1.tgz",
      "integrity": "sha512-VCjCNfgMsby3tTdo02nbjtM/ewra6jPHmpThenkTYh8pG9ucZ/1P8So4u4FGBek/BjpOVsDCMoLA/iuBKIFXRA==",
-      "dev": true,
      "license": "MIT",
      "dependencies": {
        "call-bound": "^1.0.2",
@@ -7375,7 +7413,6 @@
      "version": "1.0.2",
      "resolved": "https://registry.npmjs.org/side-channel-weakmap/-/side-channel-weakmap-1.0.2.tgz",
      "integrity": "sha512-WPS/HvHQTYnHisLo9McqBHOJk2FkHO/tlpvldyrnem4aeQp4hai3gythswg6p01oSoTl58rcpiFAjF2br2Ak2A==",
-      "dev": true,
      "license": "MIT",
      "dependencies": {
        "call-bound": "^1.0.2",
@@ -7474,15 +7511,6 @@
      "dev": true,
      "license": "BSD-3-Clause"
    },
-    "node_modules/stack-trace": {
-      "version": "0.0.10",
-      "resolved": "https://registry.npmjs.org/stack-trace/-/stack-trace-0.0.10.tgz",
-      "integrity": "sha512-KGzahc7puUKkzyMt+IqAep+TVNbKP+k2Lmwhub39m1AsTSkaDutx56aDCo+HLDzf/D26BIHTJWNiTG1KAJiQCg==",
-      "license": "MIT",
-      "engines": {
-        "node": "*"
-      }
-    },
    "node_modules/stack-utils": {
      "version": "2.0.6",
      "resolved": "https://registry.npmjs.org/stack-utils/-/stack-utils-2.0.6.tgz",
@@ -7512,6 +7540,16 @@
      "integrity": "sha512-qoRRSyROncaz1z0mvYqIE4lCd9p2R90i6GxW3uZv5ucSu8tU7B5HXUP1gG8pVZsYNVaXjk8ClXHPttLyxAL48A==",
      "license": "MIT"
    },
+    "node_modules/standardwebhooks": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/standardwebhooks/-/standardwebhooks-1.0.0.tgz",
+      "integrity": "sha512-BbHGOQK9olHPMvQNHWul6MYlrRTAOKn03rOe4A8O3CLWhNf4YHBqq2HJKKC+sfqpxiBY52pNeesD6jIiLDz8jg==",
+      "license": "MIT",
+      "dependencies": {
+        "@stablelib/base64": "^1.0.0",
+        "fast-sha256": "^1.3.0"
+      }
+    },
    "node_modules/steed": {
      "version": "1.1.3",
      "resolved": "https://registry.npmjs.org/steed/-/steed-1.1.3.tgz",
@@ -7635,6 +7673,26 @@
        "url": "https://github.com/sponsors/sindresorhus"
      }
    },
+    "node_modules/stripe": {
+      "version": "20.2.0",
+      "resolved": "https://registry.npmjs.org/stripe/-/stripe-20.2.0.tgz",
+      "integrity": "sha512-m8niTfdm3nPP/yQswRWMwQxqEUcTtB3RTJQ9oo6NINDzgi7aPOadsH/fPXIIfL1Sc5+lqQFKSk7WiO6CXmvaeA==",
+      "license": "MIT",
+      "dependencies": {
+        "qs": "^6.14.1"
+      },
+      "engines": {
+        "node": ">=16"
+      },
+      "peerDependencies": {
+        "@types/node": ">=16"
+      },
+      "peerDependenciesMeta": {
+        "@types/node": {
+          "optional": true
+        }
+      }
+    },
    "node_modules/strtok3": {
      "version": "6.3.0",
      "resolved": "https://registry.npmjs.org/strtok3/-/strtok3-6.3.0.tgz",
@@ -7713,6 +7771,29 @@
        "url": "https://github.com/sponsors/ljharb"
      }
    },
+    "node_modules/svix": {
+      "version": "1.85.0",
+      "resolved": "https://registry.npmjs.org/svix/-/svix-1.85.0.tgz",
+      "integrity": "sha512-4OxNw++bnNay8SoBwESgzfjMnYmurS1qBX+luhzvljr6EAPn/hqqmkdCR1pbgIe1K1+BzKZEHjAKz9OYrKJYwQ==",
+      "license": "MIT",
+      "dependencies": {
+        "standardwebhooks": "1.0.0",
+        "uuid": "^10.0.0"
+      }
+    },
+    "node_modules/svix/node_modules/uuid": {
+      "version": "10.0.0",
+      "resolved": "https://registry.npmjs.org/uuid/-/uuid-10.0.0.tgz",
+      "integrity": "sha512-8XkAphELsDnEGrDxUOHB3RGvXz6TeuYSGEZBOjtTtPm2lwhGBjLgOzLHB63IUWfBpNucQjND6d3AOudO+H3RWQ==",
+      "funding": [
+        "https://github.com/sponsors/broofa",
+        "https://github.com/sponsors/ctavan"
+      ],
+      "license": "MIT",
+      "bin": {
+        "uuid": "dist/bin/uuid"
+      }
+    },
    "node_modules/tar": {
      "version": "7.5.2",
      "resolved": "https://registry.npmjs.org/tar/-/tar-7.5.2.tgz",
@@ -7753,12 +7834,6 @@
        "node": ">=8"
      }
    },
-    "node_modules/text-hex": {
-      "version": "1.0.0",
-      "resolved": "https://registry.npmjs.org/text-hex/-/text-hex-1.0.0.tgz",
-      "integrity": "sha512-uuVGNWzgJ4yhRaNSiubPY7OjISw4sw4E5Uv0wbjp+OzcbmVU/rsT8ujgcXJhn9ypzsgr5vlzpPqP+MBBKcGvbg==",
-      "license": "MIT"
-    },
    "node_modules/thread-stream": {
      "version": "3.1.0",
      "resolved": "https://registry.npmjs.org/thread-stream/-/thread-stream-3.1.0.tgz",
@@ -7809,7 +7884,6 @@
      "integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==",
      "dev": true,
      "license": "MIT",
-      "peer": true,
      "engines": {
        "node": ">=12"
      },
@@ -7817,6 +7891,15 @@
        "url": "https://github.com/sponsors/jonschlinkert"
      }
    },
+    "node_modules/tlds": {
+      "version": "1.261.0",
+      "resolved": "https://registry.npmjs.org/tlds/-/tlds-1.261.0.tgz",
+      "integrity": "sha512-QXqwfEl9ddlGBaRFXIvNKK6OhipSiLXuRuLJX5DErz0o0Q0rYxulWLdFryTkV5PkdZct5iMInwYEGe/eR++1AA==",
+      "license": "MIT",
+      "bin": {
+        "tlds": "bin.js"
+      }
+    },
    "node_modules/tmpl": {
      "version": "1.0.5",
      "resolved": "https://registry.npmjs.org/tmpl/-/tmpl-1.0.5.tgz",
@@ -7873,15 +7956,6 @@
        "nodetouch": "bin/nodetouch.js"
      }
    },
-    "node_modules/triple-beam": {
-      "version": "1.4.1",
-      "resolved": "https://registry.npmjs.org/triple-beam/-/triple-beam-1.4.1.tgz",
-      "integrity": "sha512-aZbgViZrg1QNcG+LULa7nhZpJTZSLm/mXnHXnbAbjmN5aSa0y7V+wvv6+4WaBtpISJzThKy+PIPxc1Nq1EJ9mg==",
-      "license": "MIT",
-      "engines": {
-        "node": ">= 14.0.0"
-      }
-    },
    "node_modules/ts-api-utils": {
      "version": "2.1.0",
      "resolved": "https://registry.npmjs.org/ts-api-utils/-/ts-api-utils-2.1.0.tgz",
@@ -7967,7 +8041,6 @@
      "integrity": "sha512-f0FFpIdcHgn8zcPSbf1dRevwt047YMnaiJM3u2w2RewrB+fob/zePZcrOyQoLMMO7aBIddLcQIEK5dYjkLnGrQ==",
      "dev": true,
      "license": "MIT",
-      "peer": true,
      "dependencies": {
        "@cspotcode/source-map-support": "^0.8.0",
        "@tsconfig/node10": "^1.0.7",
@@ -8055,7 +8128,6 @@
      "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
      "dev": true,
      "license": "Apache-2.0",
-      "peer": true,
      "bin": {
        "tsc": "bin/tsc",
        "tsserver": "bin/tsserver"
@@ -8088,6 +8160,12 @@
        "typescript": ">=4.8.4 <6.0.0"
      }
    },
+    "node_modules/uc.micro": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/uc.micro/-/uc.micro-2.1.0.tgz",
+      "integrity": "sha512-ARDJmphmdvUk6Glw7y9DQ2bFkKBHwQHLi2lsaH6PPmz/Ka9sFOBsBluozhDltWmnv9u/cF6Rt87znRTPV+yp/A==",
+      "license": "MIT"
+    },
    "node_modules/uglify-js": {
      "version": "3.19.3",
      "resolved": "https://registry.npmjs.org/uglify-js/-/uglify-js-3.19.3.tgz",
@@ -8156,12 +8234,6 @@
        "punycode": "^2.1.0"
      }
    },
-    "node_modules/util-deprecate": {
-      "version": "1.0.2",
-      "resolved": "https://registry.npmjs.org/util-deprecate/-/util-deprecate-1.0.2.tgz",
-      "integrity": "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==",
-      "license": "MIT"
-    },
    "node_modules/uuid": {
      "version": "8.3.2",
      "resolved": "https://registry.npmjs.org/uuid/-/uuid-8.3.2.tgz",
@@ -8218,42 +8290,6 @@
        "node": ">= 8"
      }
    },
-    "node_modules/winston": {
-      "version": "3.19.0",
-      "resolved": "https://registry.npmjs.org/winston/-/winston-3.19.0.tgz",
-      "integrity": "sha512-LZNJgPzfKR+/J3cHkxcpHKpKKvGfDZVPS4hfJCc4cCG0CgYzvlD6yE/S3CIL/Yt91ak327YCpiF/0MyeZHEHKA==",
-      "license": "MIT",
-      "dependencies": {
-        "@colors/colors": "^1.6.0",
-        "@dabh/diagnostics": "^2.0.8",
-        "async": "^3.2.3",
-        "is-stream": "^2.0.0",
-        "logform": "^2.7.0",
-        "one-time": "^1.0.0",
-        "readable-stream": "^3.4.0",
-        "safe-stable-stringify": "^2.3.1",
-        "stack-trace": "0.0.x",
-        "triple-beam": "^1.3.0",
-        "winston-transport": "^4.9.0"
-      },
-      "engines": {
-        "node": ">= 12.0.0"
-      }
-    },
-    "node_modules/winston-transport": {
-      "version": "4.9.0",
-      "resolved": "https://registry.npmjs.org/winston-transport/-/winston-transport-4.9.0.tgz",
-      "integrity": "sha512-8drMJ4rkgaPo1Me4zD/3WLfI/zPdA9o2IipKODunnGDcuqbHwjsbB79ylv04LCGGzU0xQ6vTznOMpQGaLhhm6A==",
-      "license": "MIT",
-      "dependencies": {
-        "logform": "^2.7.0",
-        "readable-stream": "^3.6.2",
-        "triple-beam": "^1.3.0"
-      },
-      "engines": {
-        "node": ">= 12.0.0"
-      }
-    },
    "node_modules/word-wrap": {
      "version": "1.2.5",
      "resolved": "https://registry.npmjs.org/word-wrap/-/word-wrap-1.2.5.tgz",
--- a/backend/package.json
+++ b/backend/package.json
@@ -18,45 +18,50 @@
    "type-check": "tsc --noEmit"
  },
  "dependencies": {
-    "pg": "^8.13.1",
-    "ioredis": "^5.4.2",
-    "@fastify/multipart": "^9.0.1",
-    "axios": "^1.7.9",
-    "opossum": "^8.0.0",
-    "winston": "^3.17.0",
-    "zod": "^3.24.1",
-    "js-yaml": "^4.1.0",
-    "fastify": "^5.2.0",
+    "@fastify/autoload": "^6.0.1",
    "@fastify/cors": "^11.2.0",
    "@fastify/helmet": "^13.0.2",
    "@fastify/jwt": "^10.0.0",
+    "@fastify/multipart": "^9.0.1",
    "@fastify/type-provider-typebox": "^6.1.0",
    "@sinclair/typebox": "^0.34.0",
-    "fastify-plugin": "^5.0.1",
-    "@fastify/autoload": "^6.0.1",
-    "get-jwks": "^11.0.3",
-    "file-type": "^16.5.4",
-    "resend": "^3.0.0",
-    "node-cron": "^3.0.3",
    "auth0": "^4.12.0",
-    "tar": "^7.4.3"
+    "axios": "^1.7.9",
+    "fastify": "^5.2.0",
+    "fastify-plugin": "^5.0.1",
+    "file-type": "^16.5.4",
+    "form-data": "^4.0.0",
+    "get-jwks": "^11.0.3",
+    "ioredis": "^5.4.2",
+    "js-yaml": "^4.1.0",
+    "mailparser": "^3.9.3",
+    "node-cron": "^3.0.3",
+    "opossum": "^8.0.0",
+    "pg": "^8.13.1",
+    "pino": "^9.6.0",
+    "resend": "^3.0.0",
+    "stripe": "^20.2.0",
+    "svix": "^1.85.0",
+    "tar": "^7.4.3",
+    "zod": "^3.24.1"
  },
  "devDependencies": {
-    "@types/node": "^22.0.0",
-    "@types/pg": "^8.10.9",
-    "@types/js-yaml": "^4.0.9",
-    "@types/node-cron": "^3.0.11",
-    "typescript": "^5.7.2",
-    "ts-node": "^10.9.1",
-    "nodemon": "^3.1.9",
-    "jest": "^29.7.0",
-    "@types/jest": "^29.5.10",
-    "ts-jest": "^29.1.1",
-    "supertest": "^7.1.4",
-    "@types/supertest": "^6.0.3",
-    "@types/opossum": "^8.0.0",
-    "eslint": "^9.17.0",
    "@eslint/js": "^9.17.0",
+    "@types/jest": "^29.5.10",
+    "@types/js-yaml": "^4.0.9",
+    "@types/mailparser": "^3.4.6",
+    "@types/node": "^22.0.0",
+    "@types/node-cron": "^3.0.11",
+    "@types/opossum": "^8.0.0",
+    "@types/pg": "^8.10.9",
+    "@types/supertest": "^6.0.3",
+    "eslint": "^9.17.0",
+    "jest": "^29.7.0",
+    "nodemon": "^3.1.9",
+    "supertest": "^7.1.4",
+    "ts-jest": "^29.1.1",
+    "ts-node": "^10.9.1",
+    "typescript": "^5.7.2",
    "typescript-eslint": "^8.18.1"
  }
 }
--- a/backend/src/_system/CLAUDE.md
+++ b/backend/src/_system/CLAUDE.md
@@ -0,0 +1,10 @@
+# _system/
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `cli/` | CLI commands and tools | Running backend CLI commands |
+| `migrations/` | Database migration runner | Running or writing migrations |
+| `schema/` | Database schema generation | Schema export, documentation |
+| `scripts/` | System utility scripts | Database maintenance, automation |
--- a/backend/src/_system/migrations/run-all.ts
+++ b/backend/src/_system/migrations/run-all.ts
@@ -17,7 +17,8 @@ const pool = new Pool({
 const MIGRATION_ORDER = [
  'features/vehicles',          // Primary entity, defines update_updated_at_column()
  'features/platform',          // Normalized make/model/trim schema for dropdowns
-  'features/documents',         // Depends on vehicles; provides documents table
+  'features/user-profile',      // User profile management; needed by documents migration
+  'features/documents',         // Depends on vehicles, user-profile; provides documents table
  'core/user-preferences',      // Depends on update_updated_at_column()
  'features/fuel-logs',         // Depends on vehicles
  'features/maintenance',       // Depends on vehicles
@@ -25,9 +26,12 @@ const MIGRATION_ORDER = [
  'features/admin',             // Admin role management and oversight; depends on update_updated_at_column()
  'features/backup',            // Admin backup feature; depends on update_updated_at_column()
  'features/notifications',     // Depends on maintenance and documents
-  'features/user-profile',      // User profile management; independent
+  'features/email-ingestion',   // Depends on documents, notifications (extends email_templates)
  'features/terms-agreement',   // Terms & Conditions acceptance audit trail
  'features/audit-log',         // Centralized audit logging; independent
+  'features/ownership-costs',   // Depends on vehicles and documents; TCO recurring costs
+  'features/subscriptions',     // Stripe subscriptions; depends on user-profile, vehicles
+  'core/identity-migration',    // Cross-cutting UUID migration; must run after all feature tables exist
 ];

 // Base directory where migrations are copied inside the image (set by Dockerfile)
--- a/backend/src/app.ts
+++ b/backend/src/app.ts
@@ -32,6 +32,10 @@ import { onboardingRoutes } from './features/onboarding';
 import { userPreferencesRoutes } from './features/user-preferences';
 import { userExportRoutes } from './features/user-export';
 import { userImportRoutes } from './features/user-import';
+import { ownershipCostsRoutes } from './features/ownership-costs';
+import { subscriptionsRoutes, donationsRoutes, webhooksRoutes } from './features/subscriptions';
+import { ocrRoutes } from './features/ocr';
+import { emailIngestionWebhookRoutes, emailIngestionRoutes } from './features/email-ingestion';
 import { pool } from './core/config/database';
 import { configRoutes } from './core/config/config.routes';

@@ -93,7 +97,7 @@ async function buildApp(): Promise<FastifyInstance> {
      status: 'healthy',
      timestamp: new Date().toISOString(),
      environment: process.env['NODE_ENV'],
-      features: ['admin', 'auth', 'config', 'onboarding', 'vehicles', 'documents', 'fuel-logs', 'stations', 'maintenance', 'platform', 'notifications', 'user-profile', 'user-preferences', 'user-export', 'user-import']
+      features: ['admin', 'auth', 'config', 'onboarding', 'vehicles', 'documents', 'fuel-logs', 'stations', 'maintenance', 'platform', 'notifications', 'user-profile', 'user-preferences', 'user-export', 'user-import', 'ownership-costs', 'subscriptions', 'donations', 'ocr', 'email-ingestion']
    });
  });

@@ -103,7 +107,7 @@ async function buildApp(): Promise<FastifyInstance> {
      status: 'healthy',
      scope: 'api',
      timestamp: new Date().toISOString(),
-      features: ['admin', 'auth', 'config', 'onboarding', 'vehicles', 'documents', 'fuel-logs', 'stations', 'maintenance', 'platform', 'notifications', 'user-profile', 'user-preferences', 'user-export', 'user-import']
+      features: ['admin', 'auth', 'config', 'onboarding', 'vehicles', 'documents', 'fuel-logs', 'stations', 'maintenance', 'platform', 'notifications', 'user-profile', 'user-preferences', 'user-export', 'user-import', 'ownership-costs', 'subscriptions', 'donations', 'ocr', 'email-ingestion']
    });
  });

@@ -145,6 +149,13 @@ async function buildApp(): Promise<FastifyInstance> {
  await app.register(userPreferencesRoutes, { prefix: '/api' });
  await app.register(userExportRoutes, { prefix: '/api' });
  await app.register(userImportRoutes, { prefix: '/api' });
+  await app.register(ownershipCostsRoutes, { prefix: '/api' });
+  await app.register(subscriptionsRoutes, { prefix: '/api' });
+  await app.register(donationsRoutes, { prefix: '/api' });
+  await app.register(webhooksRoutes, { prefix: '/api' });
+  await app.register(emailIngestionWebhookRoutes, { prefix: '/api' });
+  await app.register(emailIngestionRoutes, { prefix: '/api' });
+  await app.register(ocrRoutes, { prefix: '/api' });
  await app.register(configRoutes, { prefix: '/api' });

  // 404 handler
--- a/backend/src/core/CLAUDE.md
+++ b/backend/src/core/CLAUDE.md
@@ -11,10 +11,10 @@
 | Directory | What | When to read |
 | --------- | ---- | ------------ |
 | `auth/` | Authentication utilities | JWT handling, user context |
-| `config/` | Configuration loading (env, database, redis) | Environment setup, connection pools |
+| `config/` | Configuration loading (env, database, redis) and feature tier gating (fuelLog.receiptScan, document.scanMaintenanceSchedule, vehicle.vinDecode) | Environment setup, connection pools, tier requirements |
 | `logging/` | Winston structured logging | Log configuration, debugging |
 | `middleware/` | Fastify middleware | Request processing, user extraction |
-| `plugins/` | Fastify plugins (auth, error, logging) | Plugin registration, hooks |
+| `plugins/` | Fastify plugins (auth, error, logging, tier guard) | Plugin registration, hooks, tier gating |
 | `scheduler/` | Job scheduling infrastructure | Scheduled tasks, cron jobs |
 | `storage/` | Storage abstraction and adapters | File storage, S3/filesystem |
 | `user-preferences/` | User preferences data and migrations | User settings storage |
--- a/backend/src/core/config/config-loader.ts
+++ b/backend/src/core/config/config-loader.ts
@@ -41,14 +41,6 @@ const configSchema = z.object({
    audience: z.string(),
  }),

-  // External APIs configuration (optional)
-  external: z.object({
-    vpic: z.object({
-      url: z.string(),
-      timeout: z.string(),
-    }).optional(),
-  }).optional(),
-
  // Service configuration
  service: z.object({
    name: z.string(),
@@ -126,6 +118,10 @@ const secretsSchema = z.object({
  auth0_management_client_secret: z.string(),
  google_maps_api_key: z.string(),
  resend_api_key: z.string(),
+  resend_webhook_secret: z.string().optional(),
+  // Stripe secrets (API keys only - price IDs are config, not secrets)
+  stripe_secret_key: z.string(),
+  stripe_webhook_secret: z.string(),
 });

 type Config = z.infer<typeof configSchema>;
@@ -140,6 +136,14 @@ export interface AppConfiguration {
  getRedisUrl(): string;
  getAuth0Config(): { domain: string; audience: string; clientSecret: string };
  getAuth0ManagementConfig(): { domain: string; clientId: string; clientSecret: string };
+  getResendConfig(): {
+    apiKey: string;
+    webhookSecret: string | undefined;
+  };
+  getStripeConfig(): {
+    secretKey: string;
+    webhookSecret: string;
+  };
 }

 class ConfigurationLoader {
@@ -178,6 +182,9 @@ class ConfigurationLoader {
      'auth0-management-client-secret',
      'google-maps-api-key',
      'resend-api-key',
+      'resend-webhook-secret',
+      'stripe-secret-key',
+      'stripe-webhook-secret',
    ];

    for (const secretFile of secretFiles) {
@@ -240,10 +247,27 @@ class ConfigurationLoader {
          clientSecret: secrets.auth0_management_client_secret,
        };
      },
+
+      getResendConfig() {
+        return {
+          apiKey: secrets.resend_api_key,
+          webhookSecret: secrets.resend_webhook_secret,
+        };
+      },
+
+      getStripeConfig() {
+        return {
+          secretKey: secrets.stripe_secret_key,
+          webhookSecret: secrets.stripe_webhook_secret,
+        };
+      },
    };

-    // Set RESEND_API_KEY in environment for EmailService
+    // Set Resend environment variables for EmailService and webhook verification
    process.env['RESEND_API_KEY'] = secrets.resend_api_key;
+    if (secrets.resend_webhook_secret) {
+      process.env['RESEND_WEBHOOK_SECRET'] = secrets.resend_webhook_secret;
+    }

    logger.info('Configuration loaded successfully', {
      configSource: 'yaml',
--- a/backend/src/core/config/feature-tiers.ts
+++ b/backend/src/core/config/feature-tiers.ts
@@ -29,7 +29,17 @@ export const FEATURE_TIERS: Record<string, FeatureConfig> = {
  'vehicle.vinDecode': {
    minTier: 'pro',
    name: 'VIN Decode',
-    upgradePrompt: 'Upgrade to Pro to automatically decode VIN and populate vehicle details from the NHTSA database.',
+    upgradePrompt: 'Upgrade to Pro to automatically decode VIN and populate vehicle details from the vehicle database.',
+  },
+  'fuelLog.receiptScan': {
+    minTier: 'pro',
+    name: 'Receipt Scan',
+    upgradePrompt: 'Upgrade to Pro to scan fuel receipts and auto-fill your fuel log entries.',
+  },
+  'maintenance.receiptScan': {
+    minTier: 'pro',
+    name: 'Maintenance Receipt Scan',
+    upgradePrompt: 'Upgrade to Pro to scan maintenance receipts and extract service details automatically.',
  },
 } as const;

--- a/backend/src/core/config/tests/feature-tiers.test.ts
+++ b/backend/src/core/config/tests/feature-tiers.test.ts
@@ -34,6 +34,30 @@ describe('feature-tiers', () => {
      expect(feature.name).toBe('Scan for Maintenance Schedule');
      expect(feature.upgradePrompt).toBeTruthy();
    });
+
+    it('includes fuelLog.receiptScan feature', () => {
+      const feature = FEATURE_TIERS['fuelLog.receiptScan'];
+      expect(feature).toBeDefined();
+      expect(feature.minTier).toBe('pro');
+      expect(feature.name).toBe('Receipt Scan');
+      expect(feature.upgradePrompt).toBeTruthy();
+    });
+  });
+
+  describe('canAccessFeature - fuelLog.receiptScan', () => {
+    const featureKey = 'fuelLog.receiptScan';
+
+    it('denies access for free tier user', () => {
+      expect(canAccessFeature('free', featureKey)).toBe(false);
+    });
+
+    it('allows access for pro tier user', () => {
+      expect(canAccessFeature('pro', featureKey)).toBe(true);
+    });
+
+    it('allows access for enterprise tier user (inherits pro)', () => {
+      expect(canAccessFeature('enterprise', featureKey)).toBe(true);
+    });
  });

  describe('getTierLevel', () => {
--- a/backend/src/core/identity-migration/migrations/001_migrate_user_id_to_uuid.sql
+++ b/backend/src/core/identity-migration/migrations/001_migrate_user_id_to_uuid.sql
@@ -0,0 +1,404 @@
+-- Migration: 001_migrate_user_id_to_uuid.sql
+-- Feature: identity-migration (cross-cutting)
+-- Description: Migrate all user identity columns from VARCHAR(255) storing auth0_sub
+--              to UUID referencing user_profiles.id. Admin tables restructured with UUID PKs.
+-- Requires: All feature tables must exist (runs last in MIGRATION_ORDER)
+
+BEGIN;
+
+-- ============================================================================
+-- PHASE 1: Add new UUID columns alongside existing VARCHAR columns
+-- ============================================================================
+
+-- 1a. Feature tables (17 tables with user_id VARCHAR)
+ALTER TABLE vehicles ADD COLUMN IF NOT EXISTS user_profile_id UUID;
+ALTER TABLE fuel_logs ADD COLUMN IF NOT EXISTS user_profile_id UUID;
+ALTER TABLE maintenance_records ADD COLUMN IF NOT EXISTS user_profile_id UUID;
+ALTER TABLE maintenance_schedules ADD COLUMN IF NOT EXISTS user_profile_id UUID;
+ALTER TABLE documents ADD COLUMN IF NOT EXISTS user_profile_id UUID;
+ALTER TABLE notification_logs ADD COLUMN IF NOT EXISTS user_profile_id UUID;
+ALTER TABLE user_notifications ADD COLUMN IF NOT EXISTS user_profile_id UUID;
+ALTER TABLE user_preferences ADD COLUMN IF NOT EXISTS user_profile_id UUID;
+ALTER TABLE saved_stations ADD COLUMN IF NOT EXISTS user_profile_id UUID;
+ALTER TABLE audit_logs ADD COLUMN IF NOT EXISTS user_profile_id UUID;
+ALTER TABLE ownership_costs ADD COLUMN IF NOT EXISTS user_profile_id UUID;
+ALTER TABLE email_ingestion_queue ADD COLUMN IF NOT EXISTS user_profile_id UUID;
+ALTER TABLE pending_vehicle_associations ADD COLUMN IF NOT EXISTS user_profile_id UUID;
+ALTER TABLE subscriptions ADD COLUMN IF NOT EXISTS user_profile_id UUID;
+ALTER TABLE donations ADD COLUMN IF NOT EXISTS user_profile_id UUID;
+ALTER TABLE tier_vehicle_selections ADD COLUMN IF NOT EXISTS user_profile_id UUID;
+ALTER TABLE terms_agreements ADD COLUMN IF NOT EXISTS user_profile_id UUID;
+
+-- 1b. Special user-reference columns (submitted_by/reported_by store auth0_sub)
+ALTER TABLE community_stations ADD COLUMN IF NOT EXISTS submitted_by_uuid UUID;
+ALTER TABLE station_removal_reports ADD COLUMN IF NOT EXISTS reported_by_uuid UUID;
+
+-- 1c. Admin table: add id UUID and user_profile_id UUID
+ALTER TABLE admin_users ADD COLUMN IF NOT EXISTS id UUID;
+ALTER TABLE admin_users ADD COLUMN IF NOT EXISTS user_profile_id UUID;
+
+-- 1d. Admin-referencing columns: add UUID equivalents
+ALTER TABLE admin_audit_logs ADD COLUMN IF NOT EXISTS actor_admin_uuid UUID;
+ALTER TABLE admin_audit_logs ADD COLUMN IF NOT EXISTS target_admin_uuid UUID;
+ALTER TABLE admin_users ADD COLUMN IF NOT EXISTS created_by_uuid UUID;
+ALTER TABLE community_stations ADD COLUMN IF NOT EXISTS reviewed_by_uuid UUID;
+ALTER TABLE backup_history ADD COLUMN IF NOT EXISTS created_by_uuid UUID;
+ALTER TABLE platform_change_log ADD COLUMN IF NOT EXISTS changed_by_uuid UUID;
+ALTER TABLE user_profiles ADD COLUMN IF NOT EXISTS deactivated_by_uuid UUID;
+
+
+-- ============================================================================
+-- PHASE 2: Backfill UUID values from user_profiles join
+-- ============================================================================
+
+-- 2a. Feature tables: map user_id (auth0_sub) -> user_profiles.id (UUID)
+UPDATE vehicles SET user_profile_id = up.id
+  FROM user_profiles up WHERE vehicles.user_id = up.auth0_sub AND vehicles.user_profile_id IS NULL;
+
+UPDATE fuel_logs SET user_profile_id = up.id
+  FROM user_profiles up WHERE fuel_logs.user_id = up.auth0_sub AND fuel_logs.user_profile_id IS NULL;
+
+UPDATE maintenance_records SET user_profile_id = up.id
+  FROM user_profiles up WHERE maintenance_records.user_id = up.auth0_sub AND maintenance_records.user_profile_id IS NULL;
+
+UPDATE maintenance_schedules SET user_profile_id = up.id
+  FROM user_profiles up WHERE maintenance_schedules.user_id = up.auth0_sub AND maintenance_schedules.user_profile_id IS NULL;
+
+UPDATE documents SET user_profile_id = up.id
+  FROM user_profiles up WHERE documents.user_id = up.auth0_sub AND documents.user_profile_id IS NULL;
+
+UPDATE notification_logs SET user_profile_id = up.id
+  FROM user_profiles up WHERE notification_logs.user_id = up.auth0_sub AND notification_logs.user_profile_id IS NULL;
+
+UPDATE user_notifications SET user_profile_id = up.id
+  FROM user_profiles up WHERE user_notifications.user_id = up.auth0_sub AND user_notifications.user_profile_id IS NULL;
+
+UPDATE user_preferences SET user_profile_id = up.id
+  FROM user_profiles up WHERE user_preferences.user_id = up.auth0_sub AND user_preferences.user_profile_id IS NULL;
+
+-- 2a-fix. user_preferences has rows where user_id already contains user_profiles.id (UUID)
+-- instead of auth0_sub. Match these directly by casting to UUID.
+UPDATE user_preferences SET user_profile_id = up.id
+  FROM user_profiles up
+  WHERE user_preferences.user_id ~ '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
+    AND user_preferences.user_id::uuid = up.id
+    AND user_preferences.user_profile_id IS NULL;
+
+-- Delete truly orphaned user_preferences (UUID user_id with no matching user_profile)
+DELETE FROM user_preferences
+  WHERE user_profile_id IS NULL
+    AND user_id ~ '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$'
+    AND NOT EXISTS (SELECT 1 FROM user_profiles WHERE id = user_preferences.user_id::uuid);
+
+-- Deduplicate user_preferences: same user may have both an auth0_sub row and
+-- a UUID row, both now mapping to the same user_profile_id. Keep the newest.
+DELETE FROM user_preferences a
+  USING user_preferences b
+  WHERE a.user_profile_id = b.user_profile_id
+    AND a.user_profile_id IS NOT NULL
+    AND (a.updated_at < b.updated_at OR (a.updated_at = b.updated_at AND a.id < b.id));
+
+UPDATE saved_stations SET user_profile_id = up.id
+  FROM user_profiles up WHERE saved_stations.user_id = up.auth0_sub AND saved_stations.user_profile_id IS NULL;
+
+UPDATE audit_logs SET user_profile_id = up.id
+  FROM user_profiles up WHERE audit_logs.user_id = up.auth0_sub AND audit_logs.user_profile_id IS NULL;
+
+UPDATE ownership_costs SET user_profile_id = up.id
+  FROM user_profiles up WHERE ownership_costs.user_id = up.auth0_sub AND ownership_costs.user_profile_id IS NULL;
+
+UPDATE email_ingestion_queue SET user_profile_id = up.id
+  FROM user_profiles up WHERE email_ingestion_queue.user_id = up.auth0_sub AND email_ingestion_queue.user_profile_id IS NULL;
+
+UPDATE pending_vehicle_associations SET user_profile_id = up.id
+  FROM user_profiles up WHERE pending_vehicle_associations.user_id = up.auth0_sub AND pending_vehicle_associations.user_profile_id IS NULL;
+
+UPDATE subscriptions SET user_profile_id = up.id
+  FROM user_profiles up WHERE subscriptions.user_id = up.auth0_sub AND subscriptions.user_profile_id IS NULL;
+
+UPDATE donations SET user_profile_id = up.id
+  FROM user_profiles up WHERE donations.user_id = up.auth0_sub AND donations.user_profile_id IS NULL;
+
+UPDATE tier_vehicle_selections SET user_profile_id = up.id
+  FROM user_profiles up WHERE tier_vehicle_selections.user_id = up.auth0_sub AND tier_vehicle_selections.user_profile_id IS NULL;
+
+UPDATE terms_agreements SET user_profile_id = up.id
+  FROM user_profiles up WHERE terms_agreements.user_id = up.auth0_sub AND terms_agreements.user_profile_id IS NULL;
+
+-- 2b. Special user columns
+UPDATE community_stations SET submitted_by_uuid = up.id
+  FROM user_profiles up WHERE community_stations.submitted_by = up.auth0_sub AND community_stations.submitted_by_uuid IS NULL;
+
+UPDATE station_removal_reports SET reported_by_uuid = up.id
+  FROM user_profiles up WHERE station_removal_reports.reported_by = up.auth0_sub AND station_removal_reports.reported_by_uuid IS NULL;
+
+
+-- ============================================================================
+-- PHASE 3: Admin-specific transformations
+-- ============================================================================
+
+-- 3a. Create user_profiles entries for any admin_users that lack one
+INSERT INTO user_profiles (auth0_sub, email)
+SELECT au.auth0_sub, au.email
+FROM admin_users au
+WHERE NOT EXISTS (
+  SELECT 1 FROM user_profiles up WHERE up.auth0_sub = au.auth0_sub
+)
+ON CONFLICT (auth0_sub) DO NOTHING;
+
+-- 3b. Populate admin_users.id (DEFAULT doesn't auto-fill on ALTER ADD COLUMN for existing rows)
+UPDATE admin_users SET id = uuid_generate_v4() WHERE id IS NULL;
+
+-- 3c. Backfill admin_users.user_profile_id from user_profiles join
+UPDATE admin_users SET user_profile_id = up.id
+  FROM user_profiles up WHERE admin_users.auth0_sub = up.auth0_sub AND admin_users.user_profile_id IS NULL;
+
+-- 3d. Backfill admin-referencing columns: map auth0_sub -> admin_users.id UUID
+UPDATE admin_audit_logs SET actor_admin_uuid = au.id
+  FROM admin_users au WHERE admin_audit_logs.actor_admin_id = au.auth0_sub AND admin_audit_logs.actor_admin_uuid IS NULL;
+
+UPDATE admin_audit_logs SET target_admin_uuid = au.id
+  FROM admin_users au WHERE admin_audit_logs.target_admin_id = au.auth0_sub AND admin_audit_logs.target_admin_uuid IS NULL;
+
+UPDATE admin_users au SET created_by_uuid = creator.id
+  FROM admin_users creator WHERE au.created_by = creator.auth0_sub AND au.created_by_uuid IS NULL;
+
+UPDATE community_stations SET reviewed_by_uuid = au.id
+  FROM admin_users au WHERE community_stations.reviewed_by = au.auth0_sub AND community_stations.reviewed_by_uuid IS NULL;
+
+UPDATE backup_history SET created_by_uuid = au.id
+  FROM admin_users au WHERE backup_history.created_by = au.auth0_sub AND backup_history.created_by_uuid IS NULL;
+
+UPDATE platform_change_log SET changed_by_uuid = au.id
+  FROM admin_users au WHERE platform_change_log.changed_by = au.auth0_sub AND platform_change_log.changed_by_uuid IS NULL;
+
+UPDATE user_profiles SET deactivated_by_uuid = au.id
+  FROM admin_users au WHERE user_profiles.deactivated_by = au.auth0_sub AND user_profiles.deactivated_by_uuid IS NULL;
+
+
+-- ============================================================================
+-- PHASE 4: Add constraints
+-- ============================================================================
+
+-- 4a. Set NOT NULL on feature table UUID columns (audit_logs stays nullable)
+ALTER TABLE vehicles ALTER COLUMN user_profile_id SET NOT NULL;
+ALTER TABLE fuel_logs ALTER COLUMN user_profile_id SET NOT NULL;
+ALTER TABLE maintenance_records ALTER COLUMN user_profile_id SET NOT NULL;
+ALTER TABLE maintenance_schedules ALTER COLUMN user_profile_id SET NOT NULL;
+ALTER TABLE documents ALTER COLUMN user_profile_id SET NOT NULL;
+ALTER TABLE notification_logs ALTER COLUMN user_profile_id SET NOT NULL;
+ALTER TABLE user_notifications ALTER COLUMN user_profile_id SET NOT NULL;
+ALTER TABLE user_preferences ALTER COLUMN user_profile_id SET NOT NULL;
+ALTER TABLE saved_stations ALTER COLUMN user_profile_id SET NOT NULL;
+-- audit_logs.user_profile_id stays NULLABLE (system actions have no user)
+ALTER TABLE ownership_costs ALTER COLUMN user_profile_id SET NOT NULL;
+ALTER TABLE email_ingestion_queue ALTER COLUMN user_profile_id SET NOT NULL;
+ALTER TABLE pending_vehicle_associations ALTER COLUMN user_profile_id SET NOT NULL;
+ALTER TABLE subscriptions ALTER COLUMN user_profile_id SET NOT NULL;
+ALTER TABLE donations ALTER COLUMN user_profile_id SET NOT NULL;
+ALTER TABLE tier_vehicle_selections ALTER COLUMN user_profile_id SET NOT NULL;
+ALTER TABLE terms_agreements ALTER COLUMN user_profile_id SET NOT NULL;
+ALTER TABLE community_stations ALTER COLUMN submitted_by_uuid SET NOT NULL;
+ALTER TABLE station_removal_reports ALTER COLUMN reported_by_uuid SET NOT NULL;
+
+-- 4b. Admin table NOT NULL constraints
+ALTER TABLE admin_users ALTER COLUMN id SET NOT NULL;
+ALTER TABLE admin_users ALTER COLUMN user_profile_id SET NOT NULL;
+ALTER TABLE admin_audit_logs ALTER COLUMN actor_admin_uuid SET NOT NULL;
+-- target_admin_uuid stays nullable (some actions have no target)
+-- created_by_uuid stays nullable (bootstrap admin may not have a creator)
+ALTER TABLE platform_change_log ALTER COLUMN changed_by_uuid SET NOT NULL;
+
+-- 4c. Admin table PK transformation
+ALTER TABLE admin_users DROP CONSTRAINT admin_users_pkey;
+ALTER TABLE admin_users ADD PRIMARY KEY (id);
+
+-- 4d. Add FK constraints to user_profiles(id) with ON DELETE CASCADE
+ALTER TABLE vehicles ADD CONSTRAINT fk_vehicles_user_profile_id
+  FOREIGN KEY (user_profile_id) REFERENCES user_profiles(id) ON DELETE CASCADE;
+ALTER TABLE fuel_logs ADD CONSTRAINT fk_fuel_logs_user_profile_id
+  FOREIGN KEY (user_profile_id) REFERENCES user_profiles(id) ON DELETE CASCADE;
+ALTER TABLE maintenance_records ADD CONSTRAINT fk_maintenance_records_user_profile_id
+  FOREIGN KEY (user_profile_id) REFERENCES user_profiles(id) ON DELETE CASCADE;
+ALTER TABLE maintenance_schedules ADD CONSTRAINT fk_maintenance_schedules_user_profile_id
+  FOREIGN KEY (user_profile_id) REFERENCES user_profiles(id) ON DELETE CASCADE;
+ALTER TABLE documents ADD CONSTRAINT fk_documents_user_profile_id
+  FOREIGN KEY (user_profile_id) REFERENCES user_profiles(id) ON DELETE CASCADE;
+ALTER TABLE notification_logs ADD CONSTRAINT fk_notification_logs_user_profile_id
+  FOREIGN KEY (user_profile_id) REFERENCES user_profiles(id) ON DELETE CASCADE;
+ALTER TABLE user_notifications ADD CONSTRAINT fk_user_notifications_user_profile_id
+  FOREIGN KEY (user_profile_id) REFERENCES user_profiles(id) ON DELETE CASCADE;
+ALTER TABLE user_preferences ADD CONSTRAINT fk_user_preferences_user_profile_id
+  FOREIGN KEY (user_profile_id) REFERENCES user_profiles(id) ON DELETE CASCADE;
+ALTER TABLE saved_stations ADD CONSTRAINT fk_saved_stations_user_profile_id
+  FOREIGN KEY (user_profile_id) REFERENCES user_profiles(id) ON DELETE CASCADE;
+ALTER TABLE audit_logs ADD CONSTRAINT fk_audit_logs_user_profile_id
+  FOREIGN KEY (user_profile_id) REFERENCES user_profiles(id) ON DELETE CASCADE;
+ALTER TABLE ownership_costs ADD CONSTRAINT fk_ownership_costs_user_profile_id
+  FOREIGN KEY (user_profile_id) REFERENCES user_profiles(id) ON DELETE CASCADE;
+ALTER TABLE email_ingestion_queue ADD CONSTRAINT fk_email_ingestion_queue_user_profile_id
+  FOREIGN KEY (user_profile_id) REFERENCES user_profiles(id) ON DELETE CASCADE;
+ALTER TABLE pending_vehicle_associations ADD CONSTRAINT fk_pending_vehicle_assoc_user_profile_id
+  FOREIGN KEY (user_profile_id) REFERENCES user_profiles(id) ON DELETE CASCADE;
+ALTER TABLE subscriptions ADD CONSTRAINT fk_subscriptions_user_profile_id
+  FOREIGN KEY (user_profile_id) REFERENCES user_profiles(id) ON DELETE CASCADE;
+ALTER TABLE donations ADD CONSTRAINT fk_donations_user_profile_id
+  FOREIGN KEY (user_profile_id) REFERENCES user_profiles(id) ON DELETE CASCADE;
+ALTER TABLE tier_vehicle_selections ADD CONSTRAINT fk_tier_vehicle_selections_user_profile_id
+  FOREIGN KEY (user_profile_id) REFERENCES user_profiles(id) ON DELETE CASCADE;
+ALTER TABLE terms_agreements ADD CONSTRAINT fk_terms_agreements_user_profile_id
+  FOREIGN KEY (user_profile_id) REFERENCES user_profiles(id) ON DELETE CASCADE;
+ALTER TABLE community_stations ADD CONSTRAINT fk_community_stations_submitted_by
+  FOREIGN KEY (submitted_by_uuid) REFERENCES user_profiles(id) ON DELETE CASCADE;
+ALTER TABLE station_removal_reports ADD CONSTRAINT fk_station_removal_reports_reported_by
+  FOREIGN KEY (reported_by_uuid) REFERENCES user_profiles(id) ON DELETE CASCADE;
+
+-- 4e. Admin FK constraints
+ALTER TABLE admin_users ADD CONSTRAINT fk_admin_users_user_profile_id
+  FOREIGN KEY (user_profile_id) REFERENCES user_profiles(id);
+ALTER TABLE admin_users ADD CONSTRAINT uq_admin_users_user_profile_id
+  UNIQUE (user_profile_id);
+
+
+-- ============================================================================
+-- PHASE 5: Drop old columns, rename new ones, recreate indexes
+-- ============================================================================
+
+-- 5a. Drop old FK constraints on VARCHAR user_id columns
+ALTER TABLE subscriptions DROP CONSTRAINT IF EXISTS fk_subscriptions_user_id;
+ALTER TABLE donations DROP CONSTRAINT IF EXISTS fk_donations_user_id;
+ALTER TABLE tier_vehicle_selections DROP CONSTRAINT IF EXISTS fk_tier_vehicle_selections_user_id;
+
+-- 5b. Drop old UNIQUE constraints involving VARCHAR columns
+ALTER TABLE vehicles DROP CONSTRAINT IF EXISTS unique_user_vin;
+ALTER TABLE saved_stations DROP CONSTRAINT IF EXISTS unique_user_station;
+ALTER TABLE user_preferences DROP CONSTRAINT IF EXISTS user_preferences_user_id_key;
+ALTER TABLE station_removal_reports DROP CONSTRAINT IF EXISTS unique_user_station_report;
+
+-- 5c. Drop old indexes on VARCHAR columns
+DROP INDEX IF EXISTS idx_vehicles_user_id;
+DROP INDEX IF EXISTS idx_fuel_logs_user_id;
+DROP INDEX IF EXISTS idx_maintenance_records_user_id;
+DROP INDEX IF EXISTS idx_maintenance_schedules_user_id;
+DROP INDEX IF EXISTS idx_documents_user_id;
+DROP INDEX IF EXISTS idx_documents_user_vehicle;
+DROP INDEX IF EXISTS idx_notification_logs_user_id;
+DROP INDEX IF EXISTS idx_user_notifications_user_id;
+DROP INDEX IF EXISTS idx_user_notifications_unread;
+DROP INDEX IF EXISTS idx_user_preferences_user_id;
+DROP INDEX IF EXISTS idx_saved_stations_user_id;
+DROP INDEX IF EXISTS idx_audit_logs_user_created;
+DROP INDEX IF EXISTS idx_ownership_costs_user_id;
+DROP INDEX IF EXISTS idx_email_ingestion_queue_user_id;
+DROP INDEX IF EXISTS idx_pending_vehicle_assoc_user_id;
+DROP INDEX IF EXISTS idx_subscriptions_user_id;
+DROP INDEX IF EXISTS idx_donations_user_id;
+DROP INDEX IF EXISTS idx_tier_vehicle_selections_user_id;
+DROP INDEX IF EXISTS idx_terms_agreements_user_id;
+DROP INDEX IF EXISTS idx_community_stations_submitted_by;
+DROP INDEX IF EXISTS idx_removal_reports_reported_by;
+DROP INDEX IF EXISTS idx_admin_audit_logs_actor_id;
+DROP INDEX IF EXISTS idx_admin_audit_logs_target_id;
+DROP INDEX IF EXISTS idx_platform_change_log_changed_by;
+
+-- 5d. Drop old VARCHAR user_id columns from feature tables
+ALTER TABLE vehicles DROP COLUMN user_id;
+ALTER TABLE fuel_logs DROP COLUMN user_id;
+ALTER TABLE maintenance_records DROP COLUMN user_id;
+ALTER TABLE maintenance_schedules DROP COLUMN user_id;
+ALTER TABLE documents DROP COLUMN user_id;
+ALTER TABLE notification_logs DROP COLUMN user_id;
+ALTER TABLE user_notifications DROP COLUMN user_id;
+ALTER TABLE user_preferences DROP COLUMN user_id;
+ALTER TABLE saved_stations DROP COLUMN user_id;
+ALTER TABLE audit_logs DROP COLUMN user_id;
+ALTER TABLE ownership_costs DROP COLUMN user_id;
+ALTER TABLE email_ingestion_queue DROP COLUMN user_id;
+ALTER TABLE pending_vehicle_associations DROP COLUMN user_id;
+ALTER TABLE subscriptions DROP COLUMN user_id;
+ALTER TABLE donations DROP COLUMN user_id;
+ALTER TABLE tier_vehicle_selections DROP COLUMN user_id;
+ALTER TABLE terms_agreements DROP COLUMN user_id;
+
+-- 5e. Rename user_profile_id -> user_id in feature tables
+ALTER TABLE vehicles RENAME COLUMN user_profile_id TO user_id;
+ALTER TABLE fuel_logs RENAME COLUMN user_profile_id TO user_id;
+ALTER TABLE maintenance_records RENAME COLUMN user_profile_id TO user_id;
+ALTER TABLE maintenance_schedules RENAME COLUMN user_profile_id TO user_id;
+ALTER TABLE documents RENAME COLUMN user_profile_id TO user_id;
+ALTER TABLE notification_logs RENAME COLUMN user_profile_id TO user_id;
+ALTER TABLE user_notifications RENAME COLUMN user_profile_id TO user_id;
+ALTER TABLE user_preferences RENAME COLUMN user_profile_id TO user_id;
+ALTER TABLE saved_stations RENAME COLUMN user_profile_id TO user_id;
+ALTER TABLE audit_logs RENAME COLUMN user_profile_id TO user_id;
+ALTER TABLE ownership_costs RENAME COLUMN user_profile_id TO user_id;
+ALTER TABLE email_ingestion_queue RENAME COLUMN user_profile_id TO user_id;
+ALTER TABLE pending_vehicle_associations RENAME COLUMN user_profile_id TO user_id;
+ALTER TABLE subscriptions RENAME COLUMN user_profile_id TO user_id;
+ALTER TABLE donations RENAME COLUMN user_profile_id TO user_id;
+ALTER TABLE tier_vehicle_selections RENAME COLUMN user_profile_id TO user_id;
+ALTER TABLE terms_agreements RENAME COLUMN user_profile_id TO user_id;
+
+-- 5f. Drop and rename special user columns
+ALTER TABLE community_stations DROP COLUMN submitted_by;
+ALTER TABLE community_stations RENAME COLUMN submitted_by_uuid TO submitted_by;
+ALTER TABLE station_removal_reports DROP COLUMN reported_by;
+ALTER TABLE station_removal_reports RENAME COLUMN reported_by_uuid TO reported_by;
+
+-- 5g. Drop and rename admin-referencing columns
+ALTER TABLE admin_users DROP COLUMN auth0_sub;
+ALTER TABLE admin_users DROP COLUMN created_by;
+ALTER TABLE admin_users RENAME COLUMN created_by_uuid TO created_by;
+
+ALTER TABLE admin_audit_logs DROP COLUMN actor_admin_id;
+ALTER TABLE admin_audit_logs DROP COLUMN target_admin_id;
+ALTER TABLE admin_audit_logs RENAME COLUMN actor_admin_uuid TO actor_admin_id;
+ALTER TABLE admin_audit_logs RENAME COLUMN target_admin_uuid TO target_admin_id;
+
+ALTER TABLE community_stations DROP COLUMN reviewed_by;
+ALTER TABLE community_stations RENAME COLUMN reviewed_by_uuid TO reviewed_by;
+
+ALTER TABLE backup_history DROP COLUMN created_by;
+ALTER TABLE backup_history RENAME COLUMN created_by_uuid TO created_by;
+
+ALTER TABLE platform_change_log DROP COLUMN changed_by;
+ALTER TABLE platform_change_log RENAME COLUMN changed_by_uuid TO changed_by;
+
+ALTER TABLE user_profiles DROP COLUMN deactivated_by;
+ALTER TABLE user_profiles RENAME COLUMN deactivated_by_uuid TO deactivated_by;
+
+-- 5h. Recreate indexes on new UUID columns (feature tables)
+CREATE INDEX idx_vehicles_user_id ON vehicles(user_id);
+CREATE INDEX idx_fuel_logs_user_id ON fuel_logs(user_id);
+CREATE INDEX idx_maintenance_records_user_id ON maintenance_records(user_id);
+CREATE INDEX idx_maintenance_schedules_user_id ON maintenance_schedules(user_id);
+CREATE INDEX idx_documents_user_id ON documents(user_id);
+CREATE INDEX idx_documents_user_vehicle ON documents(user_id, vehicle_id);
+CREATE INDEX idx_notification_logs_user_id ON notification_logs(user_id);
+CREATE INDEX idx_user_notifications_user_id ON user_notifications(user_id);
+CREATE INDEX idx_user_notifications_unread ON user_notifications(user_id, created_at DESC) WHERE is_read = false;
+CREATE INDEX idx_user_preferences_user_id ON user_preferences(user_id);
+CREATE INDEX idx_saved_stations_user_id ON saved_stations(user_id);
+CREATE INDEX idx_audit_logs_user_created ON audit_logs(user_id, created_at DESC);
+CREATE INDEX idx_ownership_costs_user_id ON ownership_costs(user_id);
+CREATE INDEX idx_email_ingestion_queue_user_id ON email_ingestion_queue(user_id);
+CREATE INDEX idx_pending_vehicle_assoc_user_id ON pending_vehicle_associations(user_id);
+CREATE INDEX idx_subscriptions_user_id ON subscriptions(user_id);
+CREATE INDEX idx_donations_user_id ON donations(user_id);
+CREATE INDEX idx_tier_vehicle_selections_user_id ON tier_vehicle_selections(user_id);
+CREATE INDEX idx_terms_agreements_user_id ON terms_agreements(user_id);
+
+-- 5i. Recreate indexes on special columns
+CREATE INDEX idx_community_stations_submitted_by ON community_stations(submitted_by);
+CREATE INDEX idx_removal_reports_reported_by ON station_removal_reports(reported_by);
+CREATE INDEX idx_admin_audit_logs_actor_id ON admin_audit_logs(actor_admin_id);
+CREATE INDEX idx_admin_audit_logs_target_id ON admin_audit_logs(target_admin_id);
+CREATE INDEX idx_platform_change_log_changed_by ON platform_change_log(changed_by);
+
+-- 5j. Recreate UNIQUE constraints on new UUID columns
+ALTER TABLE vehicles ADD CONSTRAINT unique_user_vin UNIQUE(user_id, vin);
+ALTER TABLE saved_stations ADD CONSTRAINT unique_user_station UNIQUE(user_id, place_id);
+ALTER TABLE user_preferences ADD CONSTRAINT user_preferences_user_id_key UNIQUE(user_id);
+ALTER TABLE station_removal_reports ADD CONSTRAINT unique_user_station_report UNIQUE(station_id, reported_by);
+
+COMMIT;
--- a/backend/src/core/logging/logger.ts
+++ b/backend/src/core/logging/logger.ts
@@ -1,24 +1,42 @@
 /**
- * @ai-summary Structured logging with Winston
- * @ai-context All features use this for consistent logging
+ * @ai-summary Structured logging with Pino (Winston-compatible wrapper)
+ * @ai-context All features use this for consistent logging. API maintains Winston compatibility.
 */
-import * as winston from 'winston';
+import pino from 'pino';

-export const logger = winston.createLogger({
-  level: 'info',
-  format: winston.format.combine(
-    winston.format.timestamp(),
-    winston.format.errors({ stack: true }),
-    winston.format.json()
-  ),
-  defaultMeta: {
-    service: 'motovaultpro-backend',
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+const validLevels: LogLevel[] = ['debug', 'info', 'warn', 'error'];
+
+const rawLevel = (process.env.LOG_LEVEL?.toLowerCase() || 'info') as LogLevel;
+const level = validLevels.includes(rawLevel) ? rawLevel : 'info';
+
+if (process.env.LOG_LEVEL && rawLevel !== level) {
+  console.warn(`Invalid LOG_LEVEL "${process.env.LOG_LEVEL}", falling back to "info"`);
+}
+
+const pinoLogger = pino({
+  level,
+  formatters: {
+    level: (label) => ({ level: label }),
  },
-  transports: [
-    new winston.transports.Console({
-      format: winston.format.json(),
-    }),
-  ],
+  timestamp: pino.stdTimeFunctions.isoTime,
 });

-export default logger;
+// Wrapper maintains logger.info(msg, meta) API for backward compatibility
+export const logger = {
+  info: (msg: string, meta?: object) => pinoLogger.info(meta || {}, msg),
+  warn: (msg: string, meta?: object) => pinoLogger.warn(meta || {}, msg),
+  error: (msg: string, meta?: object) => pinoLogger.error(meta || {}, msg),
+  debug: (msg: string, meta?: object) => pinoLogger.debug(meta || {}, msg),
+  child: (bindings: object) => {
+    const childPino = pinoLogger.child(bindings);
+    return {
+      info: (msg: string, meta?: object) => childPino.info(meta || {}, msg),
+      warn: (msg: string, meta?: object) => childPino.warn(meta || {}, msg),
+      error: (msg: string, meta?: object) => childPino.error(meta || {}, msg),
+      debug: (msg: string, meta?: object) => childPino.debug(meta || {}, msg),
+    };
+  },
+};
+
+export default logger;
--- a/backend/src/core/middleware/require-tier.test.ts
+++ b/backend/src/core/middleware/require-tier.test.ts
@@ -0,0 +1,191 @@
+import { FastifyRequest, FastifyReply } from 'fastify';
+import { requireTier } from './require-tier';
+
+// Mock logger to suppress output during tests
+jest.mock('../logging/logger', () => ({
+  logger: {
+    error: jest.fn(),
+    warn: jest.fn(),
+    debug: jest.fn(),
+    info: jest.fn(),
+  },
+}));
+
+const createRequest = (subscriptionTier?: string): Partial<FastifyRequest> => {
+  if (subscriptionTier === undefined) {
+    return { userContext: undefined };
+  }
+  return {
+    userContext: {
+      userId: '550e8400-e29b-41d4-a716-446655440000',
+      email: 'user@example.com',
+      emailVerified: true,
+      onboardingCompleted: true,
+      isAdmin: false,
+      subscriptionTier: subscriptionTier as any,
+    },
+  };
+};
+
+const createReply = (): Partial<FastifyReply> & { statusCode?: number; payload?: unknown } => {
+  const reply: any = {
+    sent: false,
+    code: jest.fn(function (this: any, status: number) {
+      this.statusCode = status;
+      return this;
+    }),
+    send: jest.fn(function (this: any, payload: unknown) {
+      this.payload = payload;
+      this.sent = true;
+      return this;
+    }),
+  };
+  return reply;
+};
+
+describe('requireTier middleware', () => {
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe('pro user passes fuelLog.receiptScan check', () => {
+    it('allows pro user through without sending a response', async () => {
+      const handler = requireTier('fuelLog.receiptScan');
+      const request = createRequest('pro');
+      const reply = createReply();
+
+      await handler(request as FastifyRequest, reply as FastifyReply);
+
+      expect(reply.code).not.toHaveBeenCalled();
+      expect(reply.send).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('enterprise user passes all checks (tier inheritance)', () => {
+    it('allows enterprise user access to pro-gated features', async () => {
+      const handler = requireTier('fuelLog.receiptScan');
+      const request = createRequest('enterprise');
+      const reply = createReply();
+
+      await handler(request as FastifyRequest, reply as FastifyReply);
+
+      expect(reply.code).not.toHaveBeenCalled();
+      expect(reply.send).not.toHaveBeenCalled();
+    });
+
+    it('allows enterprise user access to document.scanMaintenanceSchedule', async () => {
+      const handler = requireTier('document.scanMaintenanceSchedule');
+      const request = createRequest('enterprise');
+      const reply = createReply();
+
+      await handler(request as FastifyRequest, reply as FastifyReply);
+
+      expect(reply.code).not.toHaveBeenCalled();
+      expect(reply.send).not.toHaveBeenCalled();
+    });
+
+    it('allows enterprise user access to vehicle.vinDecode', async () => {
+      const handler = requireTier('vehicle.vinDecode');
+      const request = createRequest('enterprise');
+      const reply = createReply();
+
+      await handler(request as FastifyRequest, reply as FastifyReply);
+
+      expect(reply.code).not.toHaveBeenCalled();
+      expect(reply.send).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('free user blocked with 403 and correct response body', () => {
+    it('blocks free user from fuelLog.receiptScan', async () => {
+      const handler = requireTier('fuelLog.receiptScan');
+      const request = createRequest('free');
+      const reply = createReply();
+
+      await handler(request as FastifyRequest, reply as FastifyReply);
+
+      expect(reply.code).toHaveBeenCalledWith(403);
+      expect(reply.send).toHaveBeenCalledWith(
+        expect.objectContaining({
+          error: 'TIER_REQUIRED',
+          requiredTier: 'pro',
+          currentTier: 'free',
+          featureName: 'Receipt Scan',
+          upgradePrompt: expect.any(String),
+        }),
+      );
+    });
+
+    it('blocks free user from document.scanMaintenanceSchedule', async () => {
+      const handler = requireTier('document.scanMaintenanceSchedule');
+      const request = createRequest('free');
+      const reply = createReply();
+
+      await handler(request as FastifyRequest, reply as FastifyReply);
+
+      expect(reply.code).toHaveBeenCalledWith(403);
+      expect(reply.send).toHaveBeenCalledWith(
+        expect.objectContaining({
+          error: 'TIER_REQUIRED',
+          requiredTier: 'pro',
+          currentTier: 'free',
+          featureName: 'Scan for Maintenance Schedule',
+          upgradePrompt: expect.any(String),
+        }),
+      );
+    });
+
+    it('response body includes all required fields', async () => {
+      const handler = requireTier('fuelLog.receiptScan');
+      const request = createRequest('free');
+      const reply = createReply();
+
+      await handler(request as FastifyRequest, reply as FastifyReply);
+
+      const body = (reply.send as jest.Mock).mock.calls[0][0];
+      expect(body).toHaveProperty('requiredTier', 'pro');
+      expect(body).toHaveProperty('currentTier', 'free');
+      expect(body).toHaveProperty('featureName', 'Receipt Scan');
+      expect(body).toHaveProperty('upgradePrompt');
+      expect(typeof body.upgradePrompt).toBe('string');
+      expect(body.upgradePrompt.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe('unknown feature key returns 500', () => {
+    it('returns 500 INTERNAL_ERROR for unregistered feature', async () => {
+      const handler = requireTier('unknown.nonexistent.feature');
+      const request = createRequest('pro');
+      const reply = createReply();
+
+      await handler(request as FastifyRequest, reply as FastifyReply);
+
+      expect(reply.code).toHaveBeenCalledWith(500);
+      expect(reply.send).toHaveBeenCalledWith(
+        expect.objectContaining({
+          error: 'INTERNAL_ERROR',
+          message: 'Unknown feature configuration',
+        }),
+      );
+    });
+  });
+
+  describe('missing user.tier on request returns 403', () => {
+    it('defaults to free tier when userContext is undefined', async () => {
+      const handler = requireTier('fuelLog.receiptScan');
+      const request = createRequest(); // no tier = undefined userContext
+      const reply = createReply();
+
+      await handler(request as FastifyRequest, reply as FastifyReply);
+
+      expect(reply.code).toHaveBeenCalledWith(403);
+      expect(reply.send).toHaveBeenCalledWith(
+        expect.objectContaining({
+          error: 'TIER_REQUIRED',
+          currentTier: 'free',
+          requiredTier: 'pro',
+        }),
+      );
+    });
+  });
+});
--- a/backend/src/core/middleware/require-tier.ts
+++ b/backend/src/core/middleware/require-tier.ts
@@ -0,0 +1,64 @@
+/**
+ * @ai-summary Standalone tier guard middleware for route-level feature gating
+ * @ai-context Returns a Fastify preHandler that checks user subscription tier against feature requirements.
+ *   Must be composed AFTER requireAuth in preHandler arrays.
+ */
+
+import { FastifyRequest, FastifyReply } from 'fastify';
+import { canAccessFeature, getFeatureConfig } from '../config/feature-tiers';
+import { logger } from '../logging/logger';
+
+/**
+ * Creates a preHandler middleware that enforces subscription tier requirements.
+ *
+ * Reads the user's tier from request.userContext.subscriptionTier (set by auth middleware).
+ * Must be placed AFTER requireAuth in the preHandler chain.
+ *
+ * Usage:
+ *   fastify.post('/premium-route', {
+ *     preHandler: [requireAuth, requireTier('fuelLog.receiptScan')],
+ *     handler: controller.method
+ *   });
+ *
+ * @param featureKey - Key from FEATURE_TIERS registry (e.g. 'fuelLog.receiptScan')
+ * @returns Fastify preHandler function
+ */
+export function requireTier(featureKey: string) {
+  return async (request: FastifyRequest, reply: FastifyReply): Promise<void> => {
+    // Validate feature key exists in registry
+    const featureConfig = getFeatureConfig(featureKey);
+    if (!featureConfig) {
+      logger.error('requireTier: unknown feature key', { featureKey });
+      return reply.code(500).send({
+        error: 'INTERNAL_ERROR',
+        message: 'Unknown feature configuration',
+      });
+    }
+
+    // Get user tier from userContext (populated by auth middleware)
+    const currentTier = request.userContext?.subscriptionTier || 'free';
+
+    if (!canAccessFeature(currentTier, featureKey)) {
+      logger.warn('requireTier: access denied', {
+        userId: request.userContext?.userId?.substring(0, 8) + '...',
+        currentTier,
+        requiredTier: featureConfig.minTier,
+        featureKey,
+      });
+
+      return reply.code(403).send({
+        error: 'TIER_REQUIRED',
+        requiredTier: featureConfig.minTier,
+        currentTier,
+        featureName: featureConfig.name,
+        upgradePrompt: featureConfig.upgradePrompt,
+      });
+    }
+
+    logger.debug('requireTier: access granted', {
+      userId: request.userContext?.userId?.substring(0, 8) + '...',
+      currentTier,
+      featureKey,
+    });
+  };
+}
--- a/backend/src/core/plugins/admin-guard.plugin.ts
+++ b/backend/src/core/plugins/admin-guard.plugin.ts
@@ -58,9 +58,9 @@ const adminGuardPlugin: FastifyPluginAsync = async (fastify) => {

      // Check if user is in admin_users table and not revoked
      const query = `
-        SELECT auth0_sub, email, role, revoked_at
+        SELECT id, user_profile_id, email, role, revoked_at
        FROM admin_users
-        WHERE auth0_sub = $1 AND revoked_at IS NULL
+        WHERE user_profile_id = $1 AND revoked_at IS NULL
        LIMIT 1
      `;

--- a/backend/src/core/plugins/auth.plugin.ts
+++ b/backend/src/core/plugins/auth.plugin.ts
@@ -121,11 +121,14 @@ const authPlugin: FastifyPluginAsync = async (fastify) => {
    try {
      await request.jwtVerify();

-      const userId = request.user?.sub;
-      if (!userId) {
+      // Two identifiers: auth0Sub (external, for Auth0 API) and userId (internal UUID, for all DB operations)
+      const auth0Sub = request.user?.sub;
+      if (!auth0Sub) {
        throw new Error('Missing user ID in JWT');
      }

+      let userId: string = auth0Sub; // Default to auth0Sub; overwritten with UUID after profile load
+
      // Get or create user profile from database
      let email = request.user?.email;
      let displayName: string | undefined;
@@ -137,28 +140,29 @@ const authPlugin: FastifyPluginAsync = async (fastify) => {
        // If JWT doesn't have email, fetch from Auth0 Management API
        if (!email || email.includes('@unknown.local')) {
          try {
-            const auth0User = await auth0ManagementClient.getUser(userId);
+            const auth0User = await auth0ManagementClient.getUser(auth0Sub);
            if (auth0User.email) {
              email = auth0User.email;
              emailVerified = auth0User.emailVerified;
              logger.info('Fetched email from Auth0 Management API', {
-                userId: userId.substring(0, 8) + '...',
+                userId: auth0Sub.substring(0, 8) + '...',
                hasEmail: true,
              });
            }
          } catch (auth0Error) {
            logger.warn('Failed to fetch user from Auth0 Management API', {
-              userId: userId.substring(0, 8) + '...',
+              userId: auth0Sub.substring(0, 8) + '...',
              error: auth0Error instanceof Error ? auth0Error.message : 'Unknown error',
            });
          }
        }

        // Get or create profile with correct email
-        const profile = await profileRepo.getOrCreate(userId, {
-          email: email || `${userId}@unknown.local`,
+        const profile = await profileRepo.getOrCreate(auth0Sub, {
+          email: email || `${auth0Sub}@unknown.local`,
          displayName: request.user?.name || request.user?.nickname,
        });
+        userId = profile.id;

        // If profile has placeholder email but we now have real email, update it
        if (profile.email.includes('@unknown.local') && email && !email.includes('@unknown.local')) {
@@ -178,7 +182,7 @@ const authPlugin: FastifyPluginAsync = async (fastify) => {
        // Sync email verification status from Auth0 if needed
        if (!emailVerified) {
          try {
-            const isVerifiedInAuth0 = await auth0ManagementClient.checkEmailVerified(userId);
+            const isVerifiedInAuth0 = await auth0ManagementClient.checkEmailVerified(auth0Sub);
            if (isVerifiedInAuth0 && !profile.emailVerified) {
              await profileRepo.updateEmailVerified(userId, true);
              emailVerified = true;
@@ -197,7 +201,7 @@ const authPlugin: FastifyPluginAsync = async (fastify) => {
      } catch (profileError) {
        // Log but don't fail auth if profile fetch fails
        logger.warn('Failed to fetch user profile', {
-          userId: userId.substring(0, 8) + '...',
+          userId: auth0Sub.substring(0, 8) + '...',
          error: profileError instanceof Error ? profileError.message : 'Unknown error',
        });
        // Fall back to JWT email if available
--- a/backend/src/core/plugins/logging.plugin.ts
+++ b/backend/src/core/plugins/logging.plugin.ts
@@ -1,20 +1,24 @@
 /**
- * @ai-summary Fastify request logging plugin
- * @ai-context Logs request/response details with timing
+ * @ai-summary Fastify request logging plugin with correlation IDs
+ * @ai-context Logs request/response details with timing and requestId
 */
 import { FastifyPluginAsync } from 'fastify';
 import fp from 'fastify-plugin';
+import { randomUUID } from 'crypto';
 import { logger } from '../logging/logger';

 const loggingPlugin: FastifyPluginAsync = async (fastify) => {
  fastify.addHook('onRequest', async (request) => {
    request.startTime = Date.now();
+    // Extract X-Request-Id from Traefik or generate new UUID
+    request.requestId = (request.headers['x-request-id'] as string) || randomUUID();
  });

  fastify.addHook('onResponse', async (request, reply) => {
    const duration = Date.now() - (request.startTime || Date.now());
-    
+
    logger.info('Request processed', {
+      requestId: request.requestId,
      method: request.method,
      path: request.url,
      status: reply.statusCode,
@@ -24,13 +28,13 @@ const loggingPlugin: FastifyPluginAsync = async (fastify) => {
  });
 };

-// Augment FastifyRequest to include startTime
 declare module 'fastify' {
  interface FastifyRequest {
    startTime?: number;
+    requestId?: string;
  }
 }

 export default fp(loggingPlugin, {
  name: 'logging-plugin'
-});
+});
--- a/backend/src/core/plugins/tests/tier-guard.plugin.test.ts
+++ b/backend/src/core/plugins/tests/tier-guard.plugin.test.ts
@@ -26,7 +26,7 @@ describe('tier guard plugin', () => {
    // Mock authenticate to set userContext
    authenticateMock = jest.fn(async (request: FastifyRequest) => {
      request.userContext = {
-        userId: 'auth0|user123',
+        userId: '550e8400-e29b-41d4-a716-446655440000',
        email: 'user@example.com',
        emailVerified: true,
        onboardingCompleted: true,
@@ -48,7 +48,7 @@ describe('tier guard plugin', () => {
    it('allows access when user tier meets minimum', async () => {
      authenticateMock.mockImplementation(async (request: FastifyRequest) => {
        request.userContext = {
-          userId: 'auth0|user123',
+          userId: '550e8400-e29b-41d4-a716-446655440000',
          email: 'user@example.com',
          emailVerified: true,
          onboardingCompleted: true,
@@ -71,7 +71,7 @@ describe('tier guard plugin', () => {
    it('allows access when user tier exceeds minimum', async () => {
      authenticateMock.mockImplementation(async (request: FastifyRequest) => {
        request.userContext = {
-          userId: 'auth0|user123',
+          userId: '550e8400-e29b-41d4-a716-446655440000',
          email: 'user@example.com',
          emailVerified: true,
          onboardingCompleted: true,
@@ -130,7 +130,7 @@ describe('tier guard plugin', () => {
    it('allows pro tier access to pro feature', async () => {
      authenticateMock.mockImplementation(async (request: FastifyRequest) => {
        request.userContext = {
-          userId: 'auth0|user123',
+          userId: '550e8400-e29b-41d4-a716-446655440000',
          email: 'user@example.com',
          emailVerified: true,
          onboardingCompleted: true,
--- a/backend/src/core/scheduler/index.ts
+++ b/backend/src/core/scheduler/index.ts
@@ -19,6 +19,10 @@ import {
  processAuditLogCleanup,
  setAuditLogCleanupJobPool,
 } from '../../features/audit-log/jobs/cleanup.job';
+import {
+  processGracePeriodExpirations,
+  setGracePeriodJobPool,
+} from '../../features/subscriptions/jobs/grace-period.job';
 import { pool } from '../config/database';

 let schedulerInitialized = false;
@@ -38,6 +42,9 @@ export function initializeScheduler(): void {
  // Initialize audit log cleanup job pool
  setAuditLogCleanupJobPool(pool);

+  // Initialize grace period job pool
+  setGracePeriodJobPool(pool);
+
  // Daily notification processing at 8 AM
  cron.schedule('0 8 * * *', async () => {
    logger.info('Running scheduled notification job');
@@ -67,6 +74,23 @@ export function initializeScheduler(): void {
    }
  });

+  // Grace period expiration check at 2:30 AM daily
+  cron.schedule('30 2 * * *', async () => {
+    logger.info('Running grace period expiration job');
+    try {
+      const result = await processGracePeriodExpirations();
+      logger.info('Grace period job completed', {
+        processed: result.processed,
+        downgraded: result.downgraded,
+        errors: result.errors.length,
+      });
+    } catch (error) {
+      logger.error('Grace period job failed', {
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  });
+
  // Check for scheduled backups every minute
  cron.schedule('* * * * *', async () => {
    logger.debug('Checking for scheduled backups');
@@ -120,7 +144,7 @@ export function initializeScheduler(): void {
  });

  schedulerInitialized = true;
-  logger.info('Cron scheduler initialized - notification (8 AM), account purge (2 AM), audit log cleanup (3 AM), backup check (every min), retention cleanup (4 AM)');
+  logger.info('Cron scheduler initialized - notification (8 AM), account purge (2 AM), grace period (2:30 AM), audit log cleanup (3 AM), backup check (every min), retention cleanup (4 AM)');
 }

 export function isSchedulerInitialized(): boolean {
--- a/backend/src/features/CLAUDE.md
+++ b/backend/src/features/CLAUDE.md
@@ -1,7 +1,5 @@
 # backend/src/features/

-Feature capsule directory. Each feature is 100% self-contained with api/, domain/, data/, migrations/, tests/.
-
 ## Subdirectories

 | Directory | What | When to read |
@@ -14,9 +12,12 @@ Feature capsule directory. Each feature is 100% self-contained with api/, domain
 | `fuel-logs/` | Fuel consumption tracking | Fuel log CRUD, statistics |
 | `maintenance/` | Maintenance record management | Service records, reminders |
 | `notifications/` | Email and push notifications | Alert system, email templates |
+| `ocr/` | OCR proxy to mvp-ocr service (VIN, receipt, manual extraction) | Image text extraction, receipt scanning, manual PDF extraction, async jobs |
 | `onboarding/` | User onboarding flow | First-time user setup |
+| `ownership-costs/` | Ownership cost tracking and reports | Cost aggregation, expense analysis |
 | `platform/` | Vehicle data and VIN decoding | Make/model lookup, VIN validation |
 | `stations/` | Gas station search and favorites | Google Maps integration, station data |
+| `subscriptions/` | Stripe payment and billing | Subscription tiers, donations, webhooks |
 | `terms-agreement/` | Terms & Conditions acceptance audit | Signup T&C, legal compliance |
 | `user-export/` | User data export | GDPR compliance, data portability |
 | `user-import/` | User data import | Restore from backup, data migration |
--- a/backend/src/features/admin/CLAUDE.md
+++ b/backend/src/features/admin/CLAUDE.md
@@ -0,0 +1,18 @@
+# admin/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `README.md` | Feature documentation | Understanding admin functionality |
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `api/` | HTTP endpoints and routes | API changes |
+| `domain/` | Business logic, services, types | Core admin logic |
+| `data/` | Repository, database queries | Database operations |
+| `migrations/` | Database schema | Schema changes |
+| `scripts/` | Admin utility scripts | Admin automation |
+| `tests/` | Unit and integration tests | Adding or modifying tests |
--- a/backend/src/features/admin/api/admin.controller.ts
+++ b/backend/src/features/admin/api/admin.controller.ts
@@ -6,11 +6,12 @@
 import { FastifyRequest, FastifyReply } from 'fastify';
 import { AdminService } from '../domain/admin.service';
 import { AdminRepository } from '../data/admin.repository';
+import { UserProfileRepository } from '../../user-profile/data/user-profile.repository';
 import { pool } from '../../../core/config/database';
 import { logger } from '../../../core/logging/logger';
 import {
  CreateAdminInput,
-  AdminAuth0SubInput,
+  AdminIdInput,
  AuditLogsQueryInput,
  BulkCreateAdminInput,
  BulkRevokeAdminInput,
@@ -18,7 +19,7 @@ import {
 } from './admin.validation';
 import {
  createAdminSchema,
-  adminAuth0SubSchema,
+  adminIdSchema,
  auditLogsQuerySchema,
  bulkCreateAdminSchema,
  bulkRevokeAdminSchema,
@@ -33,10 +34,12 @@ import {

 export class AdminController {
  private adminService: AdminService;
+  private userProfileRepository: UserProfileRepository;

  constructor() {
    const repository = new AdminRepository(pool);
    this.adminService = new AdminService(repository);
+    this.userProfileRepository = new UserProfileRepository(pool);
  }

  /**
@@ -47,49 +50,18 @@ export class AdminController {
      const userId = request.userContext?.userId;
      const userEmail = this.resolveUserEmail(request);

-      console.log('[DEBUG] Admin verify - userId:', userId);
-      console.log('[DEBUG] Admin verify - userEmail:', userEmail);
-
      if (userEmail && request.userContext) {
        request.userContext.email = userEmail.toLowerCase();
      }

-      if (!userId && !userEmail) {
-        console.log('[DEBUG] Admin verify - No userId or userEmail, returning 401');
+      if (!userId) {
        return reply.code(401).send({
          error: 'Unauthorized',
          message: 'User context missing'
        });
      }

-      let adminRecord = userId
-        ? await this.adminService.getAdminByAuth0Sub(userId)
-        : null;
-
-      console.log('[DEBUG] Admin verify - adminRecord by auth0Sub:', adminRecord ? 'FOUND' : 'NOT FOUND');
-
-      // Fallback: attempt to resolve admin by email for legacy records
-      if (!adminRecord && userEmail) {
-        const emailMatch = await this.adminService.getAdminByEmail(userEmail.toLowerCase());
-
-        console.log('[DEBUG] Admin verify - emailMatch:', emailMatch ? 'FOUND' : 'NOT FOUND');
-        if (emailMatch) {
-          console.log('[DEBUG] Admin verify - emailMatch.auth0Sub:', emailMatch.auth0Sub);
-          console.log('[DEBUG] Admin verify - emailMatch.revokedAt:', emailMatch.revokedAt);
-        }
-
-        if (emailMatch && !emailMatch.revokedAt) {
-          // If the stored auth0Sub differs, link it to the authenticated user
-          if (userId && emailMatch.auth0Sub !== userId) {
-            console.log('[DEBUG] Admin verify - Calling linkAdminAuth0Sub to update auth0Sub');
-            adminRecord = await this.adminService.linkAdminAuth0Sub(userEmail, userId);
-            console.log('[DEBUG] Admin verify - adminRecord after link:', adminRecord ? 'SUCCESS' : 'FAILED');
-          } else {
-            console.log('[DEBUG] Admin verify - Using emailMatch as adminRecord');
-            adminRecord = emailMatch;
-          }
-        }
-      }
+      const adminRecord = await this.adminService.getAdminByUserProfileId(userId);

      if (adminRecord && !adminRecord.revokedAt) {
        if (request.userContext) {
@@ -97,12 +69,11 @@ export class AdminController {
          request.userContext.adminRecord = adminRecord;
        }

-        console.log('[DEBUG] Admin verify - Returning isAdmin: true');
-        // User is an active admin
        return reply.code(200).send({
          isAdmin: true,
          adminRecord: {
-            auth0Sub: adminRecord.auth0Sub,
+            id: adminRecord.id,
+            userProfileId: adminRecord.userProfileId,
            email: adminRecord.email,
            role: adminRecord.role
          }
@@ -114,14 +85,11 @@ export class AdminController {
        request.userContext.adminRecord = undefined;
      }

-      console.log('[DEBUG] Admin verify - Returning isAdmin: false');
-      // User is not an admin
      return reply.code(200).send({
        isAdmin: false,
        adminRecord: null
      });
    } catch (error) {
-      console.log('[DEBUG] Admin verify - Error caught:', error instanceof Error ? error.message : 'Unknown error');
      logger.error('Error verifying admin access', {
        error: error instanceof Error ? error.message : 'Unknown error',
        userId: request.userContext?.userId?.substring(0, 8) + '...'
@@ -139,9 +107,9 @@ export class AdminController {
   */
  async listAdmins(request: FastifyRequest, reply: FastifyReply) {
    try {
-      const actorId = request.userContext?.userId;
+      const actorUserProfileId = request.userContext?.userId;

-      if (!actorId) {
+      if (!actorUserProfileId) {
        return reply.code(401).send({
          error: 'Unauthorized',
          message: 'User context missing'
@@ -150,11 +118,6 @@ export class AdminController {

      const admins = await this.adminService.getAllAdmins();

-      // Log VIEW action
-      await this.adminService.getAdminByAuth0Sub(actorId);
-      // Note: Not logging VIEW as it would create excessive audit entries
-      // VIEW logging can be enabled if needed for compliance
-
      return reply.code(200).send({
        total: admins.length,
        admins
@@ -162,7 +125,7 @@ export class AdminController {
    } catch (error: any) {
      logger.error('Error listing admins', {
        error: error.message,
-        actorId: request.userContext?.userId
+        actorUserProfileId: request.userContext?.userId
      });
      return reply.code(500).send({
        error: 'Internal server error',
@@ -179,15 +142,24 @@ export class AdminController {
    reply: FastifyReply
  ) {
    try {
-      const actorId = request.userContext?.userId;
+      const actorUserProfileId = request.userContext?.userId;

-      if (!actorId) {
+      if (!actorUserProfileId) {
        return reply.code(401).send({
          error: 'Unauthorized',
          message: 'User context missing'
        });
      }

+      // Get actor's admin record to get admin ID
+      const actorAdmin = await this.adminService.getAdminByUserProfileId(actorUserProfileId);
+      if (!actorAdmin) {
+        return reply.code(403).send({
+          error: 'Forbidden',
+          message: 'Actor is not an admin'
+        });
+      }
+
      // Validate request body
      const validation = createAdminSchema.safeParse(request.body);
      if (!validation.success) {
@@ -200,23 +172,27 @@ export class AdminController {

      const { email, role } = validation.data;

-      // Generate auth0Sub for the new admin
-      // In production, this should be the actual Auth0 user ID
-      // For now, we'll use email-based identifier
-      const auth0Sub = `auth0|${email.replace('@', '_at_')}`;
+      // Look up user profile by email to get UUID
+      const userProfile = await this.userProfileRepository.getByEmail(email);
+      if (!userProfile) {
+        return reply.code(404).send({
+          error: 'Not Found',
+          message: `No user profile found with email ${email}. User must sign up first.`
+        });
+      }

      const admin = await this.adminService.createAdmin(
        email,
        role,
-        auth0Sub,
-        actorId
+        userProfile.id,
+        actorAdmin.id
      );

      return reply.code(201).send(admin);
    } catch (error: any) {
      logger.error('Error creating admin', {
        error: error.message,
-        actorId: request.userContext?.userId
+        actorUserProfileId: request.userContext?.userId
      });

      if (error.message.includes('already exists')) {
@@ -234,36 +210,45 @@ export class AdminController {
  }

  /**
-   * PATCH /api/admin/admins/:auth0Sub/revoke - Revoke admin access
+   * PATCH /api/admin/admins/:id/revoke - Revoke admin access
   */
  async revokeAdmin(
-    request: FastifyRequest<{ Params: AdminAuth0SubInput }>,
+    request: FastifyRequest<{ Params: AdminIdInput }>,
    reply: FastifyReply
  ) {
    try {
-      const actorId = request.userContext?.userId;
+      const actorUserProfileId = request.userContext?.userId;

-      if (!actorId) {
+      if (!actorUserProfileId) {
        return reply.code(401).send({
          error: 'Unauthorized',
          message: 'User context missing'
        });
      }

+      // Get actor's admin record
+      const actorAdmin = await this.adminService.getAdminByUserProfileId(actorUserProfileId);
+      if (!actorAdmin) {
+        return reply.code(403).send({
+          error: 'Forbidden',
+          message: 'Actor is not an admin'
+        });
+      }
+
      // Validate params
-      const validation = adminAuth0SubSchema.safeParse(request.params);
+      const validation = adminIdSchema.safeParse(request.params);
      if (!validation.success) {
        return reply.code(400).send({
          error: 'Bad Request',
-          message: 'Invalid auth0Sub parameter',
+          message: 'Invalid admin ID parameter',
          details: validation.error.errors
        });
      }

-      const { auth0Sub } = validation.data;
+      const { id } = validation.data;

      // Check if admin exists
-      const targetAdmin = await this.adminService.getAdminByAuth0Sub(auth0Sub);
+      const targetAdmin = await this.adminService.getAdminById(id);
      if (!targetAdmin) {
        return reply.code(404).send({
          error: 'Not Found',
@@ -272,14 +257,14 @@ export class AdminController {
      }

      // Revoke the admin (service handles last admin check)
-      const admin = await this.adminService.revokeAdmin(auth0Sub, actorId);
+      const admin = await this.adminService.revokeAdmin(id, actorAdmin.id);

      return reply.code(200).send(admin);
    } catch (error: any) {
      logger.error('Error revoking admin', {
        error: error.message,
-        actorId: request.userContext?.userId,
-        targetAuth0Sub: request.params.auth0Sub
+        actorUserProfileId: request.userContext?.userId,
+        targetAdminId: (request.params as any).id
      });

      if (error.message.includes('Cannot revoke the last active admin')) {
@@ -304,36 +289,45 @@ export class AdminController {
  }

  /**
-   * PATCH /api/admin/admins/:auth0Sub/reinstate - Restore revoked admin
+   * PATCH /api/admin/admins/:id/reinstate - Restore revoked admin
   */
  async reinstateAdmin(
-    request: FastifyRequest<{ Params: AdminAuth0SubInput }>,
+    request: FastifyRequest<{ Params: AdminIdInput }>,
    reply: FastifyReply
  ) {
    try {
-      const actorId = request.userContext?.userId;
+      const actorUserProfileId = request.userContext?.userId;

-      if (!actorId) {
+      if (!actorUserProfileId) {
        return reply.code(401).send({
          error: 'Unauthorized',
          message: 'User context missing'
        });
      }

+      // Get actor's admin record
+      const actorAdmin = await this.adminService.getAdminByUserProfileId(actorUserProfileId);
+      if (!actorAdmin) {
+        return reply.code(403).send({
+          error: 'Forbidden',
+          message: 'Actor is not an admin'
+        });
+      }
+
      // Validate params
-      const validation = adminAuth0SubSchema.safeParse(request.params);
+      const validation = adminIdSchema.safeParse(request.params);
      if (!validation.success) {
        return reply.code(400).send({
          error: 'Bad Request',
-          message: 'Invalid auth0Sub parameter',
+          message: 'Invalid admin ID parameter',
          details: validation.error.errors
        });
      }

-      const { auth0Sub } = validation.data;
+      const { id } = validation.data;

      // Check if admin exists
-      const targetAdmin = await this.adminService.getAdminByAuth0Sub(auth0Sub);
+      const targetAdmin = await this.adminService.getAdminById(id);
      if (!targetAdmin) {
        return reply.code(404).send({
          error: 'Not Found',
@@ -342,14 +336,14 @@ export class AdminController {
      }

      // Reinstate the admin
-      const admin = await this.adminService.reinstateAdmin(auth0Sub, actorId);
+      const admin = await this.adminService.reinstateAdmin(id, actorAdmin.id);

      return reply.code(200).send(admin);
    } catch (error: any) {
      logger.error('Error reinstating admin', {
        error: error.message,
-        actorId: request.userContext?.userId,
-        targetAuth0Sub: request.params.auth0Sub
+        actorUserProfileId: request.userContext?.userId,
+        targetAdminId: (request.params as any).id
      });

      if (error.message.includes('not found')) {
@@ -418,15 +412,24 @@ export class AdminController {
    reply: FastifyReply
  ) {
    try {
-      const actorId = request.userContext?.userId;
+      const actorUserProfileId = request.userContext?.userId;

-      if (!actorId) {
+      if (!actorUserProfileId) {
        return reply.code(401).send({
          error: 'Unauthorized',
          message: 'User context missing'
        });
      }

+      // Get actor's admin record
+      const actorAdmin = await this.adminService.getAdminByUserProfileId(actorUserProfileId);
+      if (!actorAdmin) {
+        return reply.code(403).send({
+          error: 'Forbidden',
+          message: 'Actor is not an admin'
+        });
+      }
+
      // Validate request body
      const validation = bulkCreateAdminSchema.safeParse(request.body);
      if (!validation.success) {
@@ -447,15 +450,21 @@ export class AdminController {
        try {
          const { email, role = 'admin' } = adminInput;

-          // Generate auth0Sub for the new admin
-          // In production, this should be the actual Auth0 user ID
-          const auth0Sub = `auth0|${email.replace('@', '_at_')}`;
+          // Look up user profile by email to get UUID
+          const userProfile = await this.userProfileRepository.getByEmail(email);
+          if (!userProfile) {
+            failed.push({
+              email,
+              error: `No user profile found with email ${email}. User must sign up first.`
+            });
+            continue;
+          }

          const admin = await this.adminService.createAdmin(
            email,
            role,
-            auth0Sub,
-            actorId
+            userProfile.id,
+            actorAdmin.id
          );

          created.push(admin);
@@ -463,7 +472,7 @@ export class AdminController {
          logger.error('Error creating admin in bulk operation', {
            error: error.message,
            email: adminInput.email,
-            actorId
+            actorAdminId: actorAdmin.id
          });

          failed.push({
@@ -485,7 +494,7 @@ export class AdminController {
    } catch (error: any) {
      logger.error('Error in bulk create admins', {
        error: error.message,
-        actorId: request.userContext?.userId
+        actorUserProfileId: request.userContext?.userId
      });

      return reply.code(500).send({
@@ -503,15 +512,24 @@ export class AdminController {
    reply: FastifyReply
  ) {
    try {
-      const actorId = request.userContext?.userId;
+      const actorUserProfileId = request.userContext?.userId;

-      if (!actorId) {
+      if (!actorUserProfileId) {
        return reply.code(401).send({
          error: 'Unauthorized',
          message: 'User context missing'
        });
      }

+      // Get actor's admin record
+      const actorAdmin = await this.adminService.getAdminByUserProfileId(actorUserProfileId);
+      if (!actorAdmin) {
+        return reply.code(403).send({
+          error: 'Forbidden',
+          message: 'Actor is not an admin'
+        });
+      }
+
      // Validate request body
      const validation = bulkRevokeAdminSchema.safeParse(request.body);
      if (!validation.success) {
@@ -522,37 +540,36 @@ export class AdminController {
        });
      }

-      const { auth0Subs } = validation.data;
+      const { ids } = validation.data;

      const revoked: AdminUser[] = [];
-      const failed: Array<{ auth0Sub: string; error: string }> = [];
+      const failed: Array<{ id: string; error: string }> = [];

      // Process each revocation sequentially to maintain data consistency
-      for (const auth0Sub of auth0Subs) {
+      for (const id of ids) {
        try {
          // Check if admin exists
-          const targetAdmin = await this.adminService.getAdminByAuth0Sub(auth0Sub);
+          const targetAdmin = await this.adminService.getAdminById(id);
          if (!targetAdmin) {
            failed.push({
-              auth0Sub,
+              id,
              error: 'Admin user not found'
            });
            continue;
          }

          // Attempt to revoke the admin
-          const admin = await this.adminService.revokeAdmin(auth0Sub, actorId);
+          const admin = await this.adminService.revokeAdmin(id, actorAdmin.id);
          revoked.push(admin);
        } catch (error: any) {
          logger.error('Error revoking admin in bulk operation', {
            error: error.message,
-            auth0Sub,
-            actorId
+            adminId: id,
+            actorAdminId: actorAdmin.id
          });

-          // Special handling for "last admin" constraint
          failed.push({
-            auth0Sub,
+            id,
            error: error.message || 'Failed to revoke admin'
          });
        }
@@ -570,7 +587,7 @@ export class AdminController {
    } catch (error: any) {
      logger.error('Error in bulk revoke admins', {
        error: error.message,
-        actorId: request.userContext?.userId
+        actorUserProfileId: request.userContext?.userId
      });

      return reply.code(500).send({
@@ -588,15 +605,24 @@ export class AdminController {
    reply: FastifyReply
  ) {
    try {
-      const actorId = request.userContext?.userId;
+      const actorUserProfileId = request.userContext?.userId;

-      if (!actorId) {
+      if (!actorUserProfileId) {
        return reply.code(401).send({
          error: 'Unauthorized',
          message: 'User context missing'
        });
      }

+      // Get actor's admin record
+      const actorAdmin = await this.adminService.getAdminByUserProfileId(actorUserProfileId);
+      if (!actorAdmin) {
+        return reply.code(403).send({
+          error: 'Forbidden',
+          message: 'Actor is not an admin'
+        });
+      }
+
      // Validate request body
      const validation = bulkReinstateAdminSchema.safeParse(request.body);
      if (!validation.success) {
@@ -607,36 +633,36 @@ export class AdminController {
        });
      }

-      const { auth0Subs } = validation.data;
+      const { ids } = validation.data;

      const reinstated: AdminUser[] = [];
-      const failed: Array<{ auth0Sub: string; error: string }> = [];
+      const failed: Array<{ id: string; error: string }> = [];

      // Process each reinstatement sequentially to maintain data consistency
-      for (const auth0Sub of auth0Subs) {
+      for (const id of ids) {
        try {
          // Check if admin exists
-          const targetAdmin = await this.adminService.getAdminByAuth0Sub(auth0Sub);
+          const targetAdmin = await this.adminService.getAdminById(id);
          if (!targetAdmin) {
            failed.push({
-              auth0Sub,
+              id,
              error: 'Admin user not found'
            });
            continue;
          }

          // Attempt to reinstate the admin
-          const admin = await this.adminService.reinstateAdmin(auth0Sub, actorId);
+          const admin = await this.adminService.reinstateAdmin(id, actorAdmin.id);
          reinstated.push(admin);
        } catch (error: any) {
          logger.error('Error reinstating admin in bulk operation', {
            error: error.message,
-            auth0Sub,
-            actorId
+            adminId: id,
+            actorAdminId: actorAdmin.id
          });

          failed.push({
-            auth0Sub,
+            id,
            error: error.message || 'Failed to reinstate admin'
          });
        }
@@ -654,7 +680,7 @@ export class AdminController {
    } catch (error: any) {
      logger.error('Error in bulk reinstate admins', {
        error: error.message,
-        actorId: request.userContext?.userId
+        actorUserProfileId: request.userContext?.userId
      });

      return reply.code(500).send({
@@ -665,9 +691,6 @@ export class AdminController {
  }

  private resolveUserEmail(request: FastifyRequest): string | undefined {
-    console.log('[DEBUG] resolveUserEmail - request.userContext:', JSON.stringify(request.userContext, null, 2));
-    console.log('[DEBUG] resolveUserEmail - request.user:', JSON.stringify((request as any).user, null, 2));
-
    const candidates: Array<string | undefined> = [
      request.userContext?.email,
      (request as any).user?.email,
@@ -676,15 +699,11 @@ export class AdminController {
      (request as any).user?.preferred_username,
    ];

-    console.log('[DEBUG] resolveUserEmail - candidates:', candidates);
-
    for (const value of candidates) {
      if (typeof value === 'string' && value.includes('@')) {
-        console.log('[DEBUG] resolveUserEmail - found email:', value);
        return value.trim();
      }
    }
-    console.log('[DEBUG] resolveUserEmail - no email found');
    return undefined;
  }
 }
--- a/backend/src/features/admin/api/admin.routes.ts
+++ b/backend/src/features/admin/api/admin.routes.ts
@@ -8,7 +8,7 @@ import { AdminController } from './admin.controller';
 import { UsersController } from './users.controller';
 import {
  CreateAdminInput,
-  AdminAuth0SubInput,
+  AdminIdInput,
  BulkCreateAdminInput,
  BulkRevokeAdminInput,
  BulkReinstateAdminInput,
@@ -17,7 +17,7 @@ import {
 } from './admin.validation';
 import {
  ListUsersQueryInput,
-  UserAuth0SubInput,
+  UserIdInput,
  UpdateTierInput,
  DeactivateUserInput,
  UpdateProfileInput,
@@ -65,14 +65,14 @@ export const adminRoutes: FastifyPluginAsync = async (fastify) => {
    handler: adminController.createAdmin.bind(adminController)
  });

-  // PATCH /api/admin/admins/:auth0Sub/revoke - Revoke admin access
-  fastify.patch<{ Params: AdminAuth0SubInput }>('/admin/admins/:auth0Sub/revoke', {
+  // PATCH /api/admin/admins/:id/revoke - Revoke admin access
+  fastify.patch<{ Params: AdminIdInput }>('/admin/admins/:id/revoke', {
    preHandler: [fastify.requireAdmin],
    handler: adminController.revokeAdmin.bind(adminController)
  });

-  // PATCH /api/admin/admins/:auth0Sub/reinstate - Restore revoked admin
-  fastify.patch<{ Params: AdminAuth0SubInput }>('/admin/admins/:auth0Sub/reinstate', {
+  // PATCH /api/admin/admins/:id/reinstate - Restore revoked admin
+  fastify.patch<{ Params: AdminIdInput }>('/admin/admins/:id/reinstate', {
    preHandler: [fastify.requireAdmin],
    handler: adminController.reinstateAdmin.bind(adminController)
  });
@@ -117,50 +117,50 @@ export const adminRoutes: FastifyPluginAsync = async (fastify) => {
    handler: usersController.listUsers.bind(usersController)
  });

-  // GET /api/admin/users/:auth0Sub - Get single user details
-  fastify.get<{ Params: UserAuth0SubInput }>('/admin/users/:auth0Sub', {
+  // GET /api/admin/users/:userId - Get single user details
+  fastify.get<{ Params: UserIdInput }>('/admin/users/:userId', {
    preHandler: [fastify.requireAdmin],
    handler: usersController.getUser.bind(usersController)
  });

-  // GET /api/admin/users/:auth0Sub/vehicles - Get user's vehicles (admin view)
-  fastify.get<{ Params: UserAuth0SubInput }>('/admin/users/:auth0Sub/vehicles', {
+  // GET /api/admin/users/:userId/vehicles - Get user's vehicles (admin view)
+  fastify.get<{ Params: UserIdInput }>('/admin/users/:userId/vehicles', {
    preHandler: [fastify.requireAdmin],
    handler: usersController.getUserVehicles.bind(usersController)
  });

-  // PATCH /api/admin/users/:auth0Sub/tier - Update subscription tier
-  fastify.patch<{ Params: UserAuth0SubInput; Body: UpdateTierInput }>('/admin/users/:auth0Sub/tier', {
+  // PATCH /api/admin/users/:userId/tier - Update subscription tier
+  fastify.patch<{ Params: UserIdInput; Body: UpdateTierInput }>('/admin/users/:userId/tier', {
    preHandler: [fastify.requireAdmin],
    handler: usersController.updateTier.bind(usersController)
  });

-  // PATCH /api/admin/users/:auth0Sub/deactivate - Soft delete user
-  fastify.patch<{ Params: UserAuth0SubInput; Body: DeactivateUserInput }>('/admin/users/:auth0Sub/deactivate', {
+  // PATCH /api/admin/users/:userId/deactivate - Soft delete user
+  fastify.patch<{ Params: UserIdInput; Body: DeactivateUserInput }>('/admin/users/:userId/deactivate', {
    preHandler: [fastify.requireAdmin],
    handler: usersController.deactivateUser.bind(usersController)
  });

-  // PATCH /api/admin/users/:auth0Sub/reactivate - Restore deactivated user
-  fastify.patch<{ Params: UserAuth0SubInput }>('/admin/users/:auth0Sub/reactivate', {
+  // PATCH /api/admin/users/:userId/reactivate - Restore deactivated user
+  fastify.patch<{ Params: UserIdInput }>('/admin/users/:userId/reactivate', {
    preHandler: [fastify.requireAdmin],
    handler: usersController.reactivateUser.bind(usersController)
  });

-  // PATCH /api/admin/users/:auth0Sub/profile - Update user email/displayName
-  fastify.patch<{ Params: UserAuth0SubInput; Body: UpdateProfileInput }>('/admin/users/:auth0Sub/profile', {
+  // PATCH /api/admin/users/:userId/profile - Update user email/displayName
+  fastify.patch<{ Params: UserIdInput; Body: UpdateProfileInput }>('/admin/users/:userId/profile', {
    preHandler: [fastify.requireAdmin],
    handler: usersController.updateProfile.bind(usersController)
  });

-  // PATCH /api/admin/users/:auth0Sub/promote - Promote user to admin
-  fastify.patch<{ Params: UserAuth0SubInput; Body: PromoteToAdminInput }>('/admin/users/:auth0Sub/promote', {
+  // PATCH /api/admin/users/:userId/promote - Promote user to admin
+  fastify.patch<{ Params: UserIdInput; Body: PromoteToAdminInput }>('/admin/users/:userId/promote', {
    preHandler: [fastify.requireAdmin],
    handler: usersController.promoteToAdmin.bind(usersController)
  });

-  // DELETE /api/admin/users/:auth0Sub - Hard delete user (permanent)
-  fastify.delete<{ Params: UserAuth0SubInput }>('/admin/users/:auth0Sub', {
+  // DELETE /api/admin/users/:userId - Hard delete user (permanent)
+  fastify.delete<{ Params: UserIdInput }>('/admin/users/:userId', {
    preHandler: [fastify.requireAdmin],
    handler: usersController.hardDeleteUser.bind(usersController)
  });
--- a/backend/src/features/admin/api/admin.validation.ts
+++ b/backend/src/features/admin/api/admin.validation.ts
@@ -10,8 +10,8 @@ export const createAdminSchema = z.object({
  role: z.enum(['admin', 'super_admin']).default('admin'),
 });

-export const adminAuth0SubSchema = z.object({
-  auth0Sub: z.string().min(1, 'auth0Sub is required'),
+export const adminIdSchema = z.object({
+  id: z.string().uuid('Invalid admin ID format'),
 });

 export const auditLogsQuerySchema = z.object({
@@ -29,14 +29,14 @@ export const bulkCreateAdminSchema = z.object({
 });

 export const bulkRevokeAdminSchema = z.object({
-  auth0Subs: z.array(z.string().min(1, 'auth0Sub cannot be empty'))
-    .min(1, 'At least one auth0Sub must be provided')
+  ids: z.array(z.string().uuid('Invalid admin ID format'))
+    .min(1, 'At least one admin ID must be provided')
    .max(100, 'Maximum 100 admins per batch'),
 });

 export const bulkReinstateAdminSchema = z.object({
-  auth0Subs: z.array(z.string().min(1, 'auth0Sub cannot be empty'))
-    .min(1, 'At least one auth0Sub must be provided')
+  ids: z.array(z.string().uuid('Invalid admin ID format'))
+    .min(1, 'At least one admin ID must be provided')
    .max(100, 'Maximum 100 admins per batch'),
 });

@@ -49,7 +49,7 @@ export const bulkDeleteCatalogSchema = z.object({
 });

 export type CreateAdminInput = z.infer<typeof createAdminSchema>;
-export type AdminAuth0SubInput = z.infer<typeof adminAuth0SubSchema>;
+export type AdminIdInput = z.infer<typeof adminIdSchema>;
 export type AuditLogsQueryInput = z.infer<typeof auditLogsQuerySchema>;
 export type BulkCreateAdminInput = z.infer<typeof bulkCreateAdminSchema>;
 export type BulkRevokeAdminInput = z.infer<typeof bulkRevokeAdminSchema>;
--- a/backend/src/features/admin/api/users.controller.ts
+++ b/backend/src/features/admin/api/users.controller.ts
@@ -7,17 +7,20 @@ import { FastifyRequest, FastifyReply } from 'fastify';
 import { UserProfileService } from '../../user-profile/domain/user-profile.service';
 import { UserProfileRepository } from '../../user-profile/data/user-profile.repository';
 import { AdminRepository } from '../data/admin.repository';
+import { SubscriptionsService } from '../../subscriptions/domain/subscriptions.service';
+import { SubscriptionsRepository } from '../../subscriptions/data/subscriptions.repository';
+import { StripeClient } from '../../subscriptions/external/stripe/stripe.client';
 import { pool } from '../../../core/config/database';
 import { logger } from '../../../core/logging/logger';
 import {
  listUsersQuerySchema,
-  userAuth0SubSchema,
+  userIdSchema,
  updateTierSchema,
  deactivateUserSchema,
  updateProfileSchema,
  promoteToAdminSchema,
  ListUsersQueryInput,
-  UserAuth0SubInput,
+  UserIdInput,
  UpdateTierInput,
  DeactivateUserInput,
  UpdateProfileInput,
@@ -28,15 +31,22 @@ import { AdminService } from '../domain/admin.service';
 export class UsersController {
  private userProfileService: UserProfileService;
  private adminService: AdminService;
+  private subscriptionsService: SubscriptionsService;
  private userProfileRepository: UserProfileRepository;
+  private adminRepository: AdminRepository;

  constructor() {
    this.userProfileRepository = new UserProfileRepository(pool);
-    const adminRepository = new AdminRepository(pool);
+    this.adminRepository = new AdminRepository(pool);
+    const subscriptionsRepository = new SubscriptionsRepository(pool);
+    const stripeClient = new StripeClient();

    this.userProfileService = new UserProfileService(this.userProfileRepository);
-    this.userProfileService.setAdminRepository(adminRepository);
-    this.adminService = new AdminService(adminRepository);
+    this.userProfileService.setAdminRepository(this.adminRepository);
+    this.adminService = new AdminService(this.adminRepository);
+    // Admin feature depends on Subscriptions for tier management
+    // This is intentional - admin has oversight capabilities
+    this.subscriptionsService = new SubscriptionsService(subscriptionsRepository, stripeClient, pool);
  }

  /**
@@ -85,10 +95,10 @@ export class UsersController {
  }

  /**
-   * GET /api/admin/users/:auth0Sub/vehicles - Get user's vehicles (admin view)
+   * GET /api/admin/users/:userId/vehicles - Get user's vehicles (admin view)
   */
  async getUserVehicles(
-    request: FastifyRequest<{ Params: UserAuth0SubInput }>,
+    request: FastifyRequest<{ Params: UserIdInput }>,
    reply: FastifyReply
  ) {
    try {
@@ -109,7 +119,7 @@ export class UsersController {
      }

      // Validate path param
-      const parseResult = userAuth0SubSchema.safeParse(request.params);
+      const parseResult = userIdSchema.safeParse(request.params);
      if (!parseResult.success) {
        return reply.code(400).send({
          error: 'Validation error',
@@ -117,14 +127,14 @@ export class UsersController {
        });
      }

-      const { auth0Sub } = parseResult.data;
-      const vehicles = await this.userProfileRepository.getUserVehiclesForAdmin(auth0Sub);
+      const { userId } = parseResult.data;
+      const vehicles = await this.userProfileRepository.getUserVehiclesForAdmin(userId);

      return reply.code(200).send({ vehicles });
    } catch (error) {
      logger.error('Error getting user vehicles', {
        error: error instanceof Error ? error.message : 'Unknown error',
-        auth0Sub: request.params?.auth0Sub,
+        userId: (request.params as any)?.userId,
      });

      return reply.code(500).send({
@@ -176,10 +186,10 @@ export class UsersController {
  }

  /**
-   * GET /api/admin/users/:auth0Sub - Get single user details
+   * GET /api/admin/users/:userId - Get single user details
   */
  async getUser(
-    request: FastifyRequest<{ Params: UserAuth0SubInput }>,
+    request: FastifyRequest<{ Params: UserIdInput }>,
    reply: FastifyReply
  ) {
    try {
@@ -192,7 +202,7 @@ export class UsersController {
      }

      // Validate path param
-      const parseResult = userAuth0SubSchema.safeParse(request.params);
+      const parseResult = userIdSchema.safeParse(request.params);
      if (!parseResult.success) {
        return reply.code(400).send({
          error: 'Validation error',
@@ -200,8 +210,8 @@ export class UsersController {
        });
      }

-      const { auth0Sub } = parseResult.data;
-      const user = await this.userProfileService.getUserDetails(auth0Sub);
+      const { userId } = parseResult.data;
+      const user = await this.userProfileService.getUserDetails(userId);

      if (!user) {
        return reply.code(404).send({
@@ -214,7 +224,7 @@ export class UsersController {
    } catch (error) {
      logger.error('Error getting user details', {
        error: error instanceof Error ? error.message : 'Unknown error',
-        auth0Sub: request.params?.auth0Sub,
+        userId: (request.params as any)?.userId,
      });

      return reply.code(500).send({
@@ -225,10 +235,12 @@ export class UsersController {
  }

  /**
-   * PATCH /api/admin/users/:auth0Sub/tier - Update subscription tier
+   * PATCH /api/admin/users/:userId/tier - Update subscription tier
+   * Uses subscriptionsService.adminOverrideTier() to sync both subscriptions.tier
+   * and user_profiles.subscription_tier atomically
   */
  async updateTier(
-    request: FastifyRequest<{ Params: UserAuth0SubInput; Body: UpdateTierInput }>,
+    request: FastifyRequest<{ Params: UserIdInput; Body: UpdateTierInput }>,
    reply: FastifyReply
  ) {
    try {
@@ -241,7 +253,7 @@ export class UsersController {
      }

      // Validate path param
-      const paramsResult = userAuth0SubSchema.safeParse(request.params);
+      const paramsResult = userIdSchema.safeParse(request.params);
      if (!paramsResult.success) {
        return reply.code(400).send({
          error: 'Validation error',
@@ -258,22 +270,49 @@ export class UsersController {
        });
      }

-      const { auth0Sub } = paramsResult.data;
+      const { userId } = paramsResult.data;
      const { subscriptionTier } = bodyResult.data;

-      const updatedUser = await this.userProfileService.updateSubscriptionTier(
-        auth0Sub,
-        subscriptionTier,
-        actorId
+      // Verify user exists before attempting tier change
+      const currentUser = await this.userProfileService.getUserDetails(userId);
+      if (!currentUser) {
+        return reply.code(404).send({
+          error: 'Not found',
+          message: 'User not found',
+        });
+      }
+
+      const previousTier = currentUser.subscriptionTier;
+
+      // Use subscriptionsService to update both tables atomically
+      await this.subscriptionsService.adminOverrideTier(userId, subscriptionTier);
+
+      // Log audit action
+      await this.adminRepository.logAuditAction(
+        actorId,
+        'UPDATE_TIER',
+        userId,
+        'user_profile',
+        currentUser.id,
+        { previousTier, newTier: subscriptionTier }
      );

+      logger.info('User subscription tier updated via admin', {
+        userId,
+        previousTier,
+        newTier: subscriptionTier,
+        actorId,
+      });
+
+      // Return updated user profile
+      const updatedUser = await this.userProfileService.getUserDetails(userId);
      return reply.code(200).send(updatedUser);
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : 'Unknown error';

      logger.error('Error updating user tier', {
        error: errorMessage,
-        auth0Sub: request.params?.auth0Sub,
+        userId: (request.params as any)?.userId,
      });

      if (errorMessage === 'User not found') {
@@ -291,10 +330,10 @@ export class UsersController {
  }

  /**
-   * PATCH /api/admin/users/:auth0Sub/deactivate - Soft delete user
+   * PATCH /api/admin/users/:userId/deactivate - Soft delete user
   */
  async deactivateUser(
-    request: FastifyRequest<{ Params: UserAuth0SubInput; Body: DeactivateUserInput }>,
+    request: FastifyRequest<{ Params: UserIdInput; Body: DeactivateUserInput }>,
    reply: FastifyReply
  ) {
    try {
@@ -307,7 +346,7 @@ export class UsersController {
      }

      // Validate path param
-      const paramsResult = userAuth0SubSchema.safeParse(request.params);
+      const paramsResult = userIdSchema.safeParse(request.params);
      if (!paramsResult.success) {
        return reply.code(400).send({
          error: 'Validation error',
@@ -324,11 +363,11 @@ export class UsersController {
        });
      }

-      const { auth0Sub } = paramsResult.data;
+      const { userId } = paramsResult.data;
      const { reason } = bodyResult.data;

      const deactivatedUser = await this.userProfileService.deactivateUser(
-        auth0Sub,
+        userId,
        actorId,
        reason
      );
@@ -339,7 +378,7 @@ export class UsersController {

      logger.error('Error deactivating user', {
        error: errorMessage,
-        auth0Sub: request.params?.auth0Sub,
+        userId: (request.params as any)?.userId,
      });

      if (errorMessage === 'User not found') {
@@ -371,10 +410,10 @@ export class UsersController {
  }

  /**
-   * PATCH /api/admin/users/:auth0Sub/reactivate - Restore deactivated user
+   * PATCH /api/admin/users/:userId/reactivate - Restore deactivated user
   */
  async reactivateUser(
-    request: FastifyRequest<{ Params: UserAuth0SubInput }>,
+    request: FastifyRequest<{ Params: UserIdInput }>,
    reply: FastifyReply
  ) {
    try {
@@ -387,7 +426,7 @@ export class UsersController {
      }

      // Validate path param
-      const paramsResult = userAuth0SubSchema.safeParse(request.params);
+      const paramsResult = userIdSchema.safeParse(request.params);
      if (!paramsResult.success) {
        return reply.code(400).send({
          error: 'Validation error',
@@ -395,10 +434,10 @@ export class UsersController {
        });
      }

-      const { auth0Sub } = paramsResult.data;
+      const { userId } = paramsResult.data;

      const reactivatedUser = await this.userProfileService.reactivateUser(
-        auth0Sub,
+        userId,
        actorId
      );

@@ -408,7 +447,7 @@ export class UsersController {

      logger.error('Error reactivating user', {
        error: errorMessage,
-        auth0Sub: request.params?.auth0Sub,
+        userId: (request.params as any)?.userId,
      });

      if (errorMessage === 'User not found') {
@@ -433,10 +472,10 @@ export class UsersController {
  }

  /**
-   * PATCH /api/admin/users/:auth0Sub/profile - Update user email/displayName
+   * PATCH /api/admin/users/:userId/profile - Update user email/displayName
   */
  async updateProfile(
-    request: FastifyRequest<{ Params: UserAuth0SubInput; Body: UpdateProfileInput }>,
+    request: FastifyRequest<{ Params: UserIdInput; Body: UpdateProfileInput }>,
    reply: FastifyReply
  ) {
    try {
@@ -449,7 +488,7 @@ export class UsersController {
      }

      // Validate path param
-      const paramsResult = userAuth0SubSchema.safeParse(request.params);
+      const paramsResult = userIdSchema.safeParse(request.params);
      if (!paramsResult.success) {
        return reply.code(400).send({
          error: 'Validation error',
@@ -466,11 +505,11 @@ export class UsersController {
        });
      }

-      const { auth0Sub } = paramsResult.data;
+      const { userId } = paramsResult.data;
      const updates = bodyResult.data;

      const updatedUser = await this.userProfileService.adminUpdateProfile(
-        auth0Sub,
+        userId,
        updates,
        actorId
      );
@@ -481,7 +520,7 @@ export class UsersController {

      logger.error('Error updating user profile', {
        error: errorMessage,
-        auth0Sub: request.params?.auth0Sub,
+        userId: (request.params as any)?.userId,
      });

      if (errorMessage === 'User not found') {
@@ -499,10 +538,10 @@ export class UsersController {
  }

  /**
-   * PATCH /api/admin/users/:auth0Sub/promote - Promote user to admin
+   * PATCH /api/admin/users/:userId/promote - Promote user to admin
   */
  async promoteToAdmin(
-    request: FastifyRequest<{ Params: UserAuth0SubInput; Body: PromoteToAdminInput }>,
+    request: FastifyRequest<{ Params: UserIdInput; Body: PromoteToAdminInput }>,
    reply: FastifyReply
  ) {
    try {
@@ -515,7 +554,7 @@ export class UsersController {
      }

      // Validate path param
-      const paramsResult = userAuth0SubSchema.safeParse(request.params);
+      const paramsResult = userIdSchema.safeParse(request.params);
      if (!paramsResult.success) {
        return reply.code(400).send({
          error: 'Validation error',
@@ -532,11 +571,11 @@ export class UsersController {
        });
      }

-      const { auth0Sub } = paramsResult.data;
+      const { userId } = paramsResult.data;
      const { role } = bodyResult.data;

-      // Get the user profile first to verify they exist and get their email
-      const user = await this.userProfileService.getUserDetails(auth0Sub);
+      // Get the user profile to verify they exist and get their email
+      const user = await this.userProfileService.getUserDetails(userId);
      if (!user) {
        return reply.code(404).send({
          error: 'Not found',
@@ -552,12 +591,15 @@ export class UsersController {
        });
      }

-      // Create the admin record using the user's real auth0Sub
+      // Get actor's admin record for audit trail
+      const actorAdmin = await this.adminService.getAdminByUserProfileId(actorId);
+
+      // Create the admin record using the user's UUID
      const adminUser = await this.adminService.createAdmin(
        user.email,
        role,
-        auth0Sub, // Use the real auth0Sub from the user profile
-        actorId
+        userId,
+        actorAdmin?.id || actorId
      );

      return reply.code(201).send(adminUser);
@@ -566,7 +608,7 @@ export class UsersController {

      logger.error('Error promoting user to admin', {
        error: errorMessage,
-        auth0Sub: request.params?.auth0Sub,
+        userId: (request.params as any)?.userId,
      });

      if (errorMessage.includes('already exists')) {
@@ -584,10 +626,10 @@ export class UsersController {
  }

  /**
-   * DELETE /api/admin/users/:auth0Sub - Hard delete user (permanent)
+   * DELETE /api/admin/users/:userId - Hard delete user (permanent)
   */
  async hardDeleteUser(
-    request: FastifyRequest<{ Params: UserAuth0SubInput }>,
+    request: FastifyRequest<{ Params: UserIdInput }>,
    reply: FastifyReply
  ) {
    try {
@@ -600,7 +642,7 @@ export class UsersController {
      }

      // Validate path param
-      const paramsResult = userAuth0SubSchema.safeParse(request.params);
+      const paramsResult = userIdSchema.safeParse(request.params);
      if (!paramsResult.success) {
        return reply.code(400).send({
          error: 'Validation error',
@@ -608,14 +650,14 @@ export class UsersController {
        });
      }

-      const { auth0Sub } = paramsResult.data;
+      const { userId } = paramsResult.data;

      // Optional reason from query params
      const reason = (request.query as any)?.reason;

      // Hard delete user
      await this.userProfileService.adminHardDeleteUser(
-        auth0Sub,
+        userId,
        actorId,
        reason
      );
@@ -628,7 +670,7 @@ export class UsersController {

      logger.error('Error hard deleting user', {
        error: errorMessage,
-        auth0Sub: request.params?.auth0Sub,
+        userId: (request.params as any)?.userId,
      });

      if (errorMessage === 'Cannot delete your own account') {
--- a/backend/src/features/admin/api/users.validation.ts
+++ b/backend/src/features/admin/api/users.validation.ts
@@ -19,9 +19,9 @@ export const listUsersQuerySchema = z.object({
  sortOrder: z.enum(['asc', 'desc']).default('desc'),
 });

-// Path param for user auth0Sub
-export const userAuth0SubSchema = z.object({
-  auth0Sub: z.string().min(1, 'auth0Sub is required'),
+// Path param for user UUID
+export const userIdSchema = z.object({
+  userId: z.string().uuid('Invalid user ID format'),
 });

 // Body for updating subscription tier
@@ -50,7 +50,7 @@ export const promoteToAdminSchema = z.object({

 // Type exports
 export type ListUsersQueryInput = z.infer<typeof listUsersQuerySchema>;
-export type UserAuth0SubInput = z.infer<typeof userAuth0SubSchema>;
+export type UserIdInput = z.infer<typeof userIdSchema>;
 export type UpdateTierInput = z.infer<typeof updateTierSchema>;
 export type DeactivateUserInput = z.infer<typeof deactivateUserSchema>;
 export type UpdateProfileInput = z.infer<typeof updateProfileSchema>;
--- a/backend/src/features/admin/data/admin.repository.ts
+++ b/backend/src/features/admin/data/admin.repository.ts
@@ -10,29 +10,49 @@ import { logger } from '../../../core/logging/logger';
 export class AdminRepository {
  constructor(private pool: Pool) {}

-  async getAdminByAuth0Sub(auth0Sub: string): Promise<AdminUser | null> {
+  async getAdminById(id: string): Promise<AdminUser | null> {
    const query = `
-      SELECT auth0_sub, email, role, created_at, created_by, revoked_at, updated_at
+      SELECT id, user_profile_id, email, role, created_at, created_by, revoked_at, updated_at
      FROM admin_users
-      WHERE auth0_sub = $1
+      WHERE id = $1
      LIMIT 1
    `;

    try {
-      const result = await this.pool.query(query, [auth0Sub]);
+      const result = await this.pool.query(query, [id]);
      if (result.rows.length === 0) {
        return null;
      }
      return this.mapRowToAdminUser(result.rows[0]);
    } catch (error) {
-      logger.error('Error fetching admin by auth0_sub', { error, auth0Sub });
+      logger.error('Error fetching admin by id', { error, id });
+      throw error;
+    }
+  }
+
+  async getAdminByUserProfileId(userProfileId: string): Promise<AdminUser | null> {
+    const query = `
+      SELECT id, user_profile_id, email, role, created_at, created_by, revoked_at, updated_at
+      FROM admin_users
+      WHERE user_profile_id = $1
+      LIMIT 1
+    `;
+
+    try {
+      const result = await this.pool.query(query, [userProfileId]);
+      if (result.rows.length === 0) {
+        return null;
+      }
+      return this.mapRowToAdminUser(result.rows[0]);
+    } catch (error) {
+      logger.error('Error fetching admin by user_profile_id', { error, userProfileId });
      throw error;
    }
  }

  async getAdminByEmail(email: string): Promise<AdminUser | null> {
    const query = `
-      SELECT auth0_sub, email, role, created_at, created_by, revoked_at, updated_at
+      SELECT id, user_profile_id, email, role, created_at, created_by, revoked_at, updated_at
      FROM admin_users
      WHERE LOWER(email) = LOWER($1)
      LIMIT 1
@@ -52,7 +72,7 @@ export class AdminRepository {

  async getAllAdmins(): Promise<AdminUser[]> {
    const query = `
-      SELECT auth0_sub, email, role, created_at, created_by, revoked_at, updated_at
+      SELECT id, user_profile_id, email, role, created_at, created_by, revoked_at, updated_at
      FROM admin_users
      ORDER BY created_at DESC
    `;
@@ -68,7 +88,7 @@ export class AdminRepository {

  async getActiveAdmins(): Promise<AdminUser[]> {
    const query = `
-      SELECT auth0_sub, email, role, created_at, created_by, revoked_at, updated_at
+      SELECT id, user_profile_id, email, role, created_at, created_by, revoked_at, updated_at
      FROM admin_users
      WHERE revoked_at IS NULL
      ORDER BY created_at DESC
@@ -83,61 +103,61 @@ export class AdminRepository {
    }
  }

-  async createAdmin(auth0Sub: string, email: string, role: string, createdBy: string): Promise<AdminUser> {
+  async createAdmin(userProfileId: string, email: string, role: string, createdBy: string): Promise<AdminUser> {
    const query = `
-      INSERT INTO admin_users (auth0_sub, email, role, created_by)
+      INSERT INTO admin_users (user_profile_id, email, role, created_by)
      VALUES ($1, $2, $3, $4)
-      RETURNING auth0_sub, email, role, created_at, created_by, revoked_at, updated_at
+      RETURNING id, user_profile_id, email, role, created_at, created_by, revoked_at, updated_at
    `;

    try {
-      const result = await this.pool.query(query, [auth0Sub, email, role, createdBy]);
+      const result = await this.pool.query(query, [userProfileId, email, role, createdBy]);
      if (result.rows.length === 0) {
        throw new Error('Failed to create admin user');
      }
      return this.mapRowToAdminUser(result.rows[0]);
    } catch (error) {
-      logger.error('Error creating admin', { error, auth0Sub, email });
+      logger.error('Error creating admin', { error, userProfileId, email });
      throw error;
    }
  }

-  async revokeAdmin(auth0Sub: string): Promise<AdminUser> {
+  async revokeAdmin(id: string): Promise<AdminUser> {
    const query = `
      UPDATE admin_users
      SET revoked_at = CURRENT_TIMESTAMP
-      WHERE auth0_sub = $1
-      RETURNING auth0_sub, email, role, created_at, created_by, revoked_at, updated_at
+      WHERE id = $1
+      RETURNING id, user_profile_id, email, role, created_at, created_by, revoked_at, updated_at
    `;

    try {
-      const result = await this.pool.query(query, [auth0Sub]);
+      const result = await this.pool.query(query, [id]);
      if (result.rows.length === 0) {
        throw new Error('Admin user not found');
      }
      return this.mapRowToAdminUser(result.rows[0]);
    } catch (error) {
-      logger.error('Error revoking admin', { error, auth0Sub });
+      logger.error('Error revoking admin', { error, id });
      throw error;
    }
  }

-  async reinstateAdmin(auth0Sub: string): Promise<AdminUser> {
+  async reinstateAdmin(id: string): Promise<AdminUser> {
    const query = `
      UPDATE admin_users
      SET revoked_at = NULL
-      WHERE auth0_sub = $1
-      RETURNING auth0_sub, email, role, created_at, created_by, revoked_at, updated_at
+      WHERE id = $1
+      RETURNING id, user_profile_id, email, role, created_at, created_by, revoked_at, updated_at
    `;

    try {
-      const result = await this.pool.query(query, [auth0Sub]);
+      const result = await this.pool.query(query, [id]);
      if (result.rows.length === 0) {
        throw new Error('Admin user not found');
      }
      return this.mapRowToAdminUser(result.rows[0]);
    } catch (error) {
-      logger.error('Error reinstating admin', { error, auth0Sub });
+      logger.error('Error reinstating admin', { error, id });
      throw error;
    }
  }
@@ -202,30 +222,11 @@ export class AdminRepository {
    }
  }

-  async updateAuth0SubByEmail(email: string, auth0Sub: string): Promise<AdminUser> {
-    const query = `
-      UPDATE admin_users
-      SET auth0_sub = $1,
-          updated_at = CURRENT_TIMESTAMP
-      WHERE LOWER(email) = LOWER($2)
-      RETURNING auth0_sub, email, role, created_at, created_by, revoked_at, updated_at
-    `;
-
-    try {
-      const result = await this.pool.query(query, [auth0Sub, email]);
-      if (result.rows.length === 0) {
-        throw new Error(`Admin user with email ${email} not found`);
-      }
-      return this.mapRowToAdminUser(result.rows[0]);
-    } catch (error) {
-      logger.error('Error updating admin auth0_sub by email', { error, email, auth0Sub });
-      throw error;
-    }
-  }

  private mapRowToAdminUser(row: any): AdminUser {
    return {
-      auth0Sub: row.auth0_sub,
+      id: row.id,
+      userProfileId: row.user_profile_id,
      email: row.email,
      role: row.role,
      createdAt: new Date(row.created_at),
--- a/backend/src/features/admin/domain/admin.service.ts
+++ b/backend/src/features/admin/domain/admin.service.ts
@@ -11,11 +11,20 @@ import { auditLogService } from '../../audit-log';
 export class AdminService {
  constructor(private repository: AdminRepository) {}

-  async getAdminByAuth0Sub(auth0Sub: string): Promise<AdminUser | null> {
+  async getAdminById(id: string): Promise<AdminUser | null> {
    try {
-      return await this.repository.getAdminByAuth0Sub(auth0Sub);
+      return await this.repository.getAdminById(id);
    } catch (error) {
-      logger.error('Error getting admin by auth0_sub', { error });
+      logger.error('Error getting admin by id', { error });
+      throw error;
+    }
+  }
+
+  async getAdminByUserProfileId(userProfileId: string): Promise<AdminUser | null> {
+    try {
+      return await this.repository.getAdminByUserProfileId(userProfileId);
+    } catch (error) {
+      logger.error('Error getting admin by user_profile_id', { error });
      throw error;
    }
  }
@@ -47,7 +56,7 @@ export class AdminService {
    }
  }

-  async createAdmin(email: string, role: string, auth0Sub: string, createdBy: string): Promise<AdminUser> {
+  async createAdmin(email: string, role: string, userProfileId: string, createdByAdminId: string): Promise<AdminUser> {
    try {
      // Check if admin already exists
      const normalizedEmail = email.trim().toLowerCase();
@@ -57,10 +66,10 @@ export class AdminService {
      }

      // Create new admin
-      const admin = await this.repository.createAdmin(auth0Sub, normalizedEmail, role, createdBy);
+      const admin = await this.repository.createAdmin(userProfileId, normalizedEmail, role, createdByAdminId);

      // Log audit action (legacy)
-      await this.repository.logAuditAction(createdBy, 'CREATE', admin.auth0Sub, 'admin_user', admin.email, {
+      await this.repository.logAuditAction(createdByAdminId, 'CREATE', admin.id, 'admin_user', admin.email, {
        email,
        role
      });
@@ -68,10 +77,10 @@ export class AdminService {
      // Log to unified audit log
      await auditLogService.info(
        'admin',
-        createdBy,
+        userProfileId,
        `Admin user created: ${admin.email}`,
        'admin_user',
-        admin.auth0Sub,
+        admin.id,
        { email: admin.email, role }
      ).catch(err => logger.error('Failed to log admin create audit event', { error: err }));

@@ -83,7 +92,7 @@ export class AdminService {
    }
  }

-  async revokeAdmin(auth0Sub: string, revokedBy: string): Promise<AdminUser> {
+  async revokeAdmin(id: string, revokedByAdminId: string): Promise<AdminUser> {
    try {
      // Check that at least one active admin will remain
      const activeAdmins = await this.repository.getActiveAdmins();
@@ -92,51 +101,51 @@ export class AdminService {
      }

      // Revoke the admin
-      const admin = await this.repository.revokeAdmin(auth0Sub);
+      const admin = await this.repository.revokeAdmin(id);

      // Log audit action (legacy)
-      await this.repository.logAuditAction(revokedBy, 'REVOKE', auth0Sub, 'admin_user', admin.email);
+      await this.repository.logAuditAction(revokedByAdminId, 'REVOKE', id, 'admin_user', admin.email);

      // Log to unified audit log
      await auditLogService.info(
        'admin',
-        revokedBy,
+        admin.userProfileId,
        `Admin user revoked: ${admin.email}`,
        'admin_user',
-        auth0Sub,
+        id,
        { email: admin.email }
      ).catch(err => logger.error('Failed to log admin revoke audit event', { error: err }));

-      logger.info('Admin user revoked', { auth0Sub, email: admin.email });
+      logger.info('Admin user revoked', { id, email: admin.email });
      return admin;
    } catch (error) {
-      logger.error('Error revoking admin', { error, auth0Sub });
+      logger.error('Error revoking admin', { error, id });
      throw error;
    }
  }

-  async reinstateAdmin(auth0Sub: string, reinstatedBy: string): Promise<AdminUser> {
+  async reinstateAdmin(id: string, reinstatedByAdminId: string): Promise<AdminUser> {
    try {
      // Reinstate the admin
-      const admin = await this.repository.reinstateAdmin(auth0Sub);
+      const admin = await this.repository.reinstateAdmin(id);

      // Log audit action (legacy)
-      await this.repository.logAuditAction(reinstatedBy, 'REINSTATE', auth0Sub, 'admin_user', admin.email);
+      await this.repository.logAuditAction(reinstatedByAdminId, 'REINSTATE', id, 'admin_user', admin.email);

      // Log to unified audit log
      await auditLogService.info(
        'admin',
-        reinstatedBy,
+        admin.userProfileId,
        `Admin user reinstated: ${admin.email}`,
        'admin_user',
-        auth0Sub,
+        id,
        { email: admin.email }
      ).catch(err => logger.error('Failed to log admin reinstate audit event', { error: err }));

-      logger.info('Admin user reinstated', { auth0Sub, email: admin.email });
+      logger.info('Admin user reinstated', { id, email: admin.email });
      return admin;
    } catch (error) {
-      logger.error('Error reinstating admin', { error, auth0Sub });
+      logger.error('Error reinstating admin', { error, id });
      throw error;
    }
  }
@@ -150,12 +159,4 @@ export class AdminService {
    }
  }

-  async linkAdminAuth0Sub(email: string, auth0Sub: string): Promise<AdminUser> {
-    try {
-      return await this.repository.updateAuth0SubByEmail(email.trim().toLowerCase(), auth0Sub);
-    } catch (error) {
-      logger.error('Error linking admin auth0_sub to email', { error, email, auth0Sub });
-      throw error;
-    }
-  }
 }
--- a/backend/src/features/admin/domain/admin.types.ts
+++ b/backend/src/features/admin/domain/admin.types.ts
@@ -4,7 +4,8 @@
 */

 export interface AdminUser {
-  auth0Sub: string;
+  id: string;
+  userProfileId: string;
  email: string;
  role: 'admin' | 'super_admin';
  createdAt: Date;
@@ -19,11 +20,11 @@ export interface CreateAdminRequest {
 }

 export interface RevokeAdminRequest {
-  auth0Sub: string;
+  id: string;
 }

 export interface ReinstateAdminRequest {
-  auth0Sub: string;
+  id: string;
 }

 export interface AdminAuditLog {
@@ -71,25 +72,25 @@ export interface BulkCreateAdminResponse {
 }

 export interface BulkRevokeAdminRequest {
-  auth0Subs: string[];
+  ids: string[];
 }

 export interface BulkRevokeAdminResponse {
  revoked: AdminUser[];
  failed: Array<{
-    auth0Sub: string;
+    id: string;
    error: string;
  }>;
 }

 export interface BulkReinstateAdminRequest {
-  auth0Subs: string[];
+  ids: string[];
 }

 export interface BulkReinstateAdminResponse {
  reinstated: AdminUser[];
  failed: Array<{
-    auth0Sub: string;
+    id: string;
    error: string;
  }>;
 }
--- a/backend/src/features/admin/tests/integration/admin.integration.test.ts
+++ b/backend/src/features/admin/tests/integration/admin.integration.test.ts
@@ -4,18 +4,19 @@
 */

 import request from 'supertest';
-import { app } from '../../../../app';
+import { buildApp } from '../../../../app';
 import pool from '../../../../core/config/database';
+import { FastifyInstance } from 'fastify';
 import { readFileSync } from 'fs';
 import { join } from 'path';
 import fastifyPlugin from 'fastify-plugin';
 import { setAdminGuardPool } from '../../../../core/plugins/admin-guard.plugin';

-const DEFAULT_ADMIN_SUB = 'test-admin-123';
+const DEFAULT_ADMIN_ID = '7c9e6679-7425-40de-944b-e07fc1f90ae7';
 const DEFAULT_ADMIN_EMAIL = 'test-admin@motovaultpro.com';

 let currentUser = {
-  sub: DEFAULT_ADMIN_SUB,
+  sub: 'auth0|test-admin-123',
  email: DEFAULT_ADMIN_EMAIL,
 };

@@ -25,11 +26,15 @@ jest.mock('../../../../core/plugins/auth.plugin', () => {
    default: fastifyPlugin(async function(fastify) {
      fastify.decorate('authenticate', async function(request, _reply) {
        // Inject dynamic test user context
+        // JWT sub is still auth0|xxx format
        request.user = { sub: currentUser.sub };
        request.userContext = {
-          userId: currentUser.sub,
+          userId: DEFAULT_ADMIN_ID,
          email: currentUser.email,
+          emailVerified: true,
+          onboardingCompleted: true,
          isAdmin: false, // Will be set by admin guard
+          subscriptionTier: 'free',
        };
      });
    }, { name: 'auth-plugin' })
@@ -37,10 +42,14 @@ jest.mock('../../../../core/plugins/auth.plugin', () => {
 });

 describe('Admin Management Integration Tests', () => {
-  let testAdminAuth0Sub: string;
-  let testNonAdminAuth0Sub: string;
+  let app: FastifyInstance;
+  let testAdminId: string;

  beforeAll(async () => {
+    // Build the app
+    app = await buildApp();
+    await app.ready();
+
    // Run the admin migration directly using the migration file
    const migrationFile = join(__dirname, '../../migrations/001_create_admin_users.sql');
    const migrationSQL = readFileSync(migrationFile, 'utf-8');
@@ -50,33 +59,31 @@ describe('Admin Management Integration Tests', () => {
    setAdminGuardPool(pool);

    // Create test admin user
-    testAdminAuth0Sub = DEFAULT_ADMIN_SUB;
+    testAdminId = DEFAULT_ADMIN_ID;
    await pool.query(`
-      INSERT INTO admin_users (auth0_sub, email, role, created_by)
-      VALUES ($1, $2, $3, $4)
-      ON CONFLICT (auth0_sub) DO NOTHING
-    `, [testAdminAuth0Sub, DEFAULT_ADMIN_EMAIL, 'admin', 'system']);
-
-    // Create test non-admin auth0Sub for permission tests
-    testNonAdminAuth0Sub = 'test-non-admin-456';
+      INSERT INTO admin_users (id, user_profile_id, email, role, created_by)
+      VALUES ($1, $2, $3, $4, $5)
+      ON CONFLICT (user_profile_id) DO NOTHING
+    `, [testAdminId, testAdminId, DEFAULT_ADMIN_EMAIL, 'admin', 'system']);
  });

  afterAll(async () => {
    // Clean up test database
    await pool.query('DROP TABLE IF EXISTS admin_audit_logs CASCADE');
    await pool.query('DROP TABLE IF EXISTS admin_users CASCADE');
+    await app.close();
    await pool.end();
  });

  beforeEach(async () => {
    // Clean up test data before each test (except the test admin)
    await pool.query(
-      'DELETE FROM admin_users WHERE auth0_sub != $1 AND auth0_sub != $2',
-      [testAdminAuth0Sub, 'system|bootstrap']
+      'DELETE FROM admin_users WHERE user_profile_id != $1',
+      [testAdminId]
    );
    await pool.query('DELETE FROM admin_audit_logs');
    currentUser = {
-      sub: DEFAULT_ADMIN_SUB,
+      sub: 'auth0|test-admin-123',
      email: DEFAULT_ADMIN_EMAIL,
    };
  });
@@ -85,11 +92,11 @@ describe('Admin Management Integration Tests', () => {
    it('should reject non-admin user trying to list admins', async () => {
      // Create mock for non-admin user
      currentUser = {
-        sub: testNonAdminAuth0Sub,
+        sub: 'auth0|test-non-admin-456',
        email: 'test-user@example.com',
      };

-      const response = await request(app)
+      const response = await request(app.server)
        .get('/api/admin/admins')
        .expect(403);

@@ -101,51 +108,51 @@ describe('Admin Management Integration Tests', () => {
  describe('GET /api/admin/verify', () => {
    it('should confirm admin access for existing admin', async () => {
      currentUser = {
-        sub: testAdminAuth0Sub,
+        sub: 'auth0|test-admin-123',
        email: DEFAULT_ADMIN_EMAIL,
      };

-      const response = await request(app)
+      const response = await request(app.server)
        .get('/api/admin/verify')
        .expect(200);

      expect(response.body.isAdmin).toBe(true);
      expect(response.body.adminRecord).toMatchObject({
-        auth0Sub: testAdminAuth0Sub,
+        id: testAdminId,
        email: DEFAULT_ADMIN_EMAIL,
      });
    });

-    it('should link admin record by email when auth0_sub differs', async () => {
-      const placeholderSub = 'auth0|placeholder-sub';
-      const realSub = 'auth0|real-admin-sub';
+    it('should link admin record by email when user_profile_id differs', async () => {
+      const placeholderId = '9b9a1234-1234-1234-1234-123456789abc';
+      const realId = 'a1b2c3d4-5678-90ab-cdef-123456789def';
      const email = 'link-admin@example.com';

      await pool.query(`
-        INSERT INTO admin_users (auth0_sub, email, role, created_by)
-        VALUES ($1, $2, $3, $4)
-      `, [placeholderSub, email, 'admin', testAdminAuth0Sub]);
+        INSERT INTO admin_users (id, user_profile_id, email, role, created_by)
+        VALUES ($1, $2, $3, $4, $5)
+      `, [placeholderId, placeholderId, email, 'admin', testAdminId]);

      currentUser = {
-        sub: realSub,
+        sub: 'auth0|real-admin-sub',
        email,
      };

-      const response = await request(app)
+      const response = await request(app.server)
        .get('/api/admin/verify')
        .expect(200);

      expect(response.body.isAdmin).toBe(true);
      expect(response.body.adminRecord).toMatchObject({
-        auth0Sub: realSub,
+        userProfileId: realId,
        email,
      });

      const record = await pool.query(
-        'SELECT auth0_sub FROM admin_users WHERE email = $1',
+        'SELECT user_profile_id FROM admin_users WHERE email = $1',
        [email]
      );
-      expect(record.rows[0].auth0_sub).toBe(realSub);
+      expect(record.rows[0].user_profile_id).toBe(realId);
    });

    it('should return non-admin response for unknown user', async () => {
@@ -154,7 +161,7 @@ describe('Admin Management Integration Tests', () => {
        email: 'non-admin@example.com',
      };

-      const response = await request(app)
+      const response = await request(app.server)
        .get('/api/admin/verify')
        .expect(200);

@@ -166,17 +173,19 @@ describe('Admin Management Integration Tests', () => {
  describe('GET /api/admin/admins', () => {
    it('should list all admin users', async () => {
      // Create additional test admins
+      const admin1Id = '6ba7b810-9dad-11d1-80b4-00c04fd430c8';
+      const admin2Id = '8f14e45f-ceea-367f-a27f-c9a6d0c67e0e';
      await pool.query(`
-        INSERT INTO admin_users (auth0_sub, email, role, created_by)
+        INSERT INTO admin_users (id, user_profile_id, email, role, created_by)
        VALUES
-        ($1, $2, $3, $4),
-        ($5, $6, $7, $8)
+        ($1, $2, $3, $4, $5),
+        ($6, $7, $8, $9, $10)
      `, [
-        'auth0|admin1', 'admin1@example.com', 'admin', testAdminAuth0Sub,
-        'auth0|admin2', 'admin2@example.com', 'super_admin', testAdminAuth0Sub
+        admin1Id, admin1Id, 'admin1@example.com', 'admin', testAdminId,
+        admin2Id, admin2Id, 'admin2@example.com', 'super_admin', testAdminId
      ]);

-      const response = await request(app)
+      const response = await request(app.server)
        .get('/api/admin/admins')
        .expect(200);

@@ -184,7 +193,7 @@ describe('Admin Management Integration Tests', () => {
      expect(response.body).toHaveProperty('admins');
      expect(response.body.admins.length).toBeGreaterThanOrEqual(3); // At least test admin + 2 created
      expect(response.body.admins[0]).toMatchObject({
-        auth0Sub: expect.any(String),
+        id: expect.any(String),
        email: expect.any(String),
        role: expect.stringMatching(/^(admin|super_admin)$/),
        createdAt: expect.any(String),
@@ -194,12 +203,13 @@ describe('Admin Management Integration Tests', () => {

    it('should include revoked admins in the list', async () => {
      // Create and revoke an admin
+      const revokedId = 'f1e2d3c4-b5a6-9788-6543-210fedcba987';
      await pool.query(`
-        INSERT INTO admin_users (auth0_sub, email, role, created_by, revoked_at)
-        VALUES ($1, $2, $3, $4, CURRENT_TIMESTAMP)
-      `, ['auth0|revoked', 'revoked@example.com', 'admin', testAdminAuth0Sub]);
+        INSERT INTO admin_users (id, user_profile_id, email, role, created_by, revoked_at)
+        VALUES ($1, $2, $3, $4, $5, CURRENT_TIMESTAMP)
+      `, [revokedId, revokedId, 'revoked@example.com', 'admin', testAdminId]);

-      const response = await request(app)
+      const response = await request(app.server)
        .get('/api/admin/admins')
        .expect(200);

@@ -218,17 +228,17 @@ describe('Admin Management Integration Tests', () => {
        role: 'admin'
      };

-      const response = await request(app)
+      const response = await request(app.server)
        .post('/api/admin/admins')
        .send(newAdminData)
        .expect(201);

      expect(response.body).toMatchObject({
-        auth0Sub: expect.any(String),
+        id: expect.any(String),
        email: 'newadmin@example.com',
        role: 'admin',
        createdAt: expect.any(String),
-        createdBy: testAdminAuth0Sub,
+        createdBy: testAdminId,
        revokedAt: null
      });

@@ -238,7 +248,7 @@ describe('Admin Management Integration Tests', () => {
        ['CREATE', 'newadmin@example.com']
      );
      expect(auditResult.rows.length).toBe(1);
-      expect(auditResult.rows[0].actor_admin_id).toBe(testAdminAuth0Sub);
+      expect(auditResult.rows[0].actor_admin_id).toBe(testAdminId);
    });

    it('should reject invalid email', async () => {
@@ -247,7 +257,7 @@ describe('Admin Management Integration Tests', () => {
        role: 'admin'
      };

-      const response = await request(app)
+      const response = await request(app.server)
        .post('/api/admin/admins')
        .send(invalidData)
        .expect(400);
@@ -263,13 +273,13 @@ describe('Admin Management Integration Tests', () => {
      };

      // Create first admin
-      await request(app)
+      await request(app.server)
        .post('/api/admin/admins')
        .send(adminData)
        .expect(201);

      // Try to create duplicate
-      const response = await request(app)
+      const response = await request(app.server)
        .post('/api/admin/admins')
        .send(adminData)
        .expect(400);
@@ -284,7 +294,7 @@ describe('Admin Management Integration Tests', () => {
        role: 'super_admin'
      };

-      const response = await request(app)
+      const response = await request(app.server)
        .post('/api/admin/admins')
        .send(superAdminData)
        .expect(201);
@@ -297,7 +307,7 @@ describe('Admin Management Integration Tests', () => {
        email: 'defaultrole@example.com'
      };

-      const response = await request(app)
+      const response = await request(app.server)
        .post('/api/admin/admins')
        .send(adminData)
        .expect(201);
@@ -306,23 +316,24 @@ describe('Admin Management Integration Tests', () => {
    });
  });

-  describe('PATCH /api/admin/admins/:auth0Sub/revoke', () => {
+  describe('PATCH /api/admin/admins/:id/revoke', () => {
    it('should revoke admin access', async () => {
      // Create admin to revoke
+      const toRevokeId = 'b1c2d3e4-f5a6-7890-1234-567890abcdef';
      const createResult = await pool.query(`
-        INSERT INTO admin_users (auth0_sub, email, role, created_by)
-        VALUES ($1, $2, $3, $4)
-        RETURNING auth0_sub
-      `, ['auth0|to-revoke', 'torevoke@example.com', 'admin', testAdminAuth0Sub]);
+        INSERT INTO admin_users (id, user_profile_id, email, role, created_by)
+        VALUES ($1, $2, $3, $4, $5)
+        RETURNING id
+      `, [toRevokeId, toRevokeId, 'torevoke@example.com', 'admin', testAdminId]);

-      const auth0Sub = createResult.rows[0].auth0_sub;
+      const adminId = createResult.rows[0].id;

-      const response = await request(app)
-        .patch(`/api/admin/admins/${auth0Sub}/revoke`)
+      const response = await request(app.server)
+        .patch(`/api/admin/admins/${adminId}/revoke`)
        .expect(200);

      expect(response.body).toMatchObject({
-        auth0Sub,
+        id: adminId,
        email: 'torevoke@example.com',
        revokedAt: expect.any(String)
      });
@@ -330,7 +341,7 @@ describe('Admin Management Integration Tests', () => {
      // Verify audit log
      const auditResult = await pool.query(
        'SELECT * FROM admin_audit_logs WHERE action = $1 AND target_admin_id = $2',
-        ['REVOKE', auth0Sub]
+        ['REVOKE', adminId]
      );
      expect(auditResult.rows.length).toBe(1);
    });
@@ -338,12 +349,12 @@ describe('Admin Management Integration Tests', () => {
    it('should prevent revoking last active admin', async () => {
      // First, ensure only one active admin exists
      await pool.query(
-        'UPDATE admin_users SET revoked_at = CURRENT_TIMESTAMP WHERE auth0_sub != $1',
-        [testAdminAuth0Sub]
+        'UPDATE admin_users SET revoked_at = CURRENT_TIMESTAMP WHERE user_profile_id != $1',
+        [testAdminId]
      );

-      const response = await request(app)
-        .patch(`/api/admin/admins/${testAdminAuth0Sub}/revoke`)
+      const response = await request(app.server)
+        .patch(`/api/admin/admins/${testAdminId}/revoke`)
        .expect(400);

      expect(response.body.error).toBe('Bad Request');
@@ -351,8 +362,8 @@ describe('Admin Management Integration Tests', () => {
    });

    it('should return 404 for non-existent admin', async () => {
-      const response = await request(app)
-        .patch('/api/admin/admins/auth0|nonexistent/revoke')
+      const response = await request(app.server)
+        .patch('/api/admin/admins/00000000-0000-0000-0000-000000000000/revoke')
        .expect(404);

      expect(response.body.error).toBe('Not Found');
@@ -360,23 +371,24 @@ describe('Admin Management Integration Tests', () => {
    });
  });

-  describe('PATCH /api/admin/admins/:auth0Sub/reinstate', () => {
+  describe('PATCH /api/admin/admins/:id/reinstate', () => {
    it('should reinstate revoked admin', async () => {
      // Create revoked admin
+      const reinstateId = 'c2d3e4f5-a6b7-8901-2345-678901bcdef0';
      const createResult = await pool.query(`
-        INSERT INTO admin_users (auth0_sub, email, role, created_by, revoked_at)
-        VALUES ($1, $2, $3, $4, CURRENT_TIMESTAMP)
-        RETURNING auth0_sub
-      `, ['auth0|to-reinstate', 'toreinstate@example.com', 'admin', testAdminAuth0Sub]);
+        INSERT INTO admin_users (id, user_profile_id, email, role, created_by, revoked_at)
+        VALUES ($1, $2, $3, $4, $5, CURRENT_TIMESTAMP)
+        RETURNING id
+      `, [reinstateId, reinstateId, 'toreinstate@example.com', 'admin', testAdminId]);

-      const auth0Sub = createResult.rows[0].auth0_sub;
+      const adminId = createResult.rows[0].id;

-      const response = await request(app)
-        .patch(`/api/admin/admins/${auth0Sub}/reinstate`)
+      const response = await request(app.server)
+        .patch(`/api/admin/admins/${adminId}/reinstate`)
        .expect(200);

      expect(response.body).toMatchObject({
-        auth0Sub,
+        id: adminId,
        email: 'toreinstate@example.com',
        revokedAt: null
      });
@@ -384,14 +396,14 @@ describe('Admin Management Integration Tests', () => {
      // Verify audit log
      const auditResult = await pool.query(
        'SELECT * FROM admin_audit_logs WHERE action = $1 AND target_admin_id = $2',
-        ['REINSTATE', auth0Sub]
+        ['REINSTATE', adminId]
      );
      expect(auditResult.rows.length).toBe(1);
    });

    it('should return 404 for non-existent admin', async () => {
-      const response = await request(app)
-        .patch('/api/admin/admins/auth0|nonexistent/reinstate')
+      const response = await request(app.server)
+        .patch('/api/admin/admins/00000000-0000-0000-0000-000000000000/reinstate')
        .expect(404);

      expect(response.body.error).toBe('Not Found');
@@ -400,16 +412,17 @@ describe('Admin Management Integration Tests', () => {

    it('should handle reinstating already active admin', async () => {
      // Create active admin
+      const activeId = 'd3e4f5a6-b7c8-9012-3456-789012cdef01';
      const createResult = await pool.query(`
-        INSERT INTO admin_users (auth0_sub, email, role, created_by)
-        VALUES ($1, $2, $3, $4)
-        RETURNING auth0_sub
-      `, ['auth0|already-active', 'active@example.com', 'admin', testAdminAuth0Sub]);
+        INSERT INTO admin_users (id, user_profile_id, email, role, created_by)
+        VALUES ($1, $2, $3, $4, $5)
+        RETURNING id
+      `, [activeId, activeId, 'active@example.com', 'admin', testAdminId]);

-      const auth0Sub = createResult.rows[0].auth0_sub;
+      const adminId = createResult.rows[0].id;

-      const response = await request(app)
-        .patch(`/api/admin/admins/${auth0Sub}/reinstate`)
+      const response = await request(app.server)
+        .patch(`/api/admin/admins/${adminId}/reinstate`)
        .expect(200);

      expect(response.body.revokedAt).toBeNull();
@@ -426,12 +439,12 @@ describe('Admin Management Integration Tests', () => {
        ($5, $6, $7, $8),
        ($9, $10, $11, $12)
      `, [
-        testAdminAuth0Sub, 'CREATE', 'admin_user', 'test1@example.com',
-        testAdminAuth0Sub, 'REVOKE', 'admin_user', 'test2@example.com',
-        testAdminAuth0Sub, 'REINSTATE', 'admin_user', 'test3@example.com'
+        testAdminId, 'CREATE', 'admin_user', 'test1@example.com',
+        testAdminId, 'REVOKE', 'admin_user', 'test2@example.com',
+        testAdminId, 'REINSTATE', 'admin_user', 'test3@example.com'
      ]);

-      const response = await request(app)
+      const response = await request(app.server)
        .get('/api/admin/audit-logs')
        .expect(200);

@@ -440,7 +453,7 @@ describe('Admin Management Integration Tests', () => {
      expect(response.body.logs.length).toBeGreaterThanOrEqual(3);
      expect(response.body.logs[0]).toMatchObject({
        id: expect.any(String),
-        actorAdminId: testAdminAuth0Sub,
+        actorAdminId: testAdminId,
        action: expect.any(String),
        resourceType: expect.any(String),
        createdAt: expect.any(String)
@@ -453,10 +466,10 @@ describe('Admin Management Integration Tests', () => {
        await pool.query(`
          INSERT INTO admin_audit_logs (actor_admin_id, action, resource_type, resource_id)
          VALUES ($1, $2, $3, $4)
-        `, [testAdminAuth0Sub, 'CREATE', 'admin_user', `test${i}@example.com`]);
+        `, [testAdminId, 'CREATE', 'admin_user', `test${i}@example.com`]);
      }

-      const response = await request(app)
+      const response = await request(app.server)
        .get('/api/admin/audit-logs?limit=5&offset=0')
        .expect(200);

@@ -473,12 +486,12 @@ describe('Admin Management Integration Tests', () => {
        ($3, $4, CURRENT_TIMESTAMP - INTERVAL '1 minute'),
        ($5, $6, CURRENT_TIMESTAMP)
      `, [
-        testAdminAuth0Sub, 'FIRST',
-        testAdminAuth0Sub, 'SECOND',
-        testAdminAuth0Sub, 'THIRD'
+        testAdminId, 'FIRST',
+        testAdminId, 'SECOND',
+        testAdminId, 'THIRD'
      ]);

-      const response = await request(app)
+      const response = await request(app.server)
        .get('/api/admin/audit-logs?limit=3')
        .expect(200);

@@ -491,45 +504,45 @@ describe('Admin Management Integration Tests', () => {
  describe('End-to-end workflow', () => {
    it('should create, revoke, and reinstate admin with full audit trail', async () => {
      // 1. Create new admin
-      const createResponse = await request(app)
+      const createResponse = await request(app.server)
        .post('/api/admin/admins')
        .send({ email: 'workflow@example.com', role: 'admin' })
        .expect(201);

-      const auth0Sub = createResponse.body.auth0Sub;
+      const adminId = createResponse.body.id;

      // 2. Verify admin appears in list
-      const listResponse = await request(app)
+      const listResponse = await request(app.server)
        .get('/api/admin/admins')
        .expect(200);

      const createdAdmin = listResponse.body.admins.find(
-        (admin: any) => admin.auth0Sub === auth0Sub
+        (admin: any) => admin.id === adminId
      );
      expect(createdAdmin).toBeDefined();
      expect(createdAdmin.revokedAt).toBeNull();

      // 3. Revoke admin
-      const revokeResponse = await request(app)
-        .patch(`/api/admin/admins/${auth0Sub}/revoke`)
+      const revokeResponse = await request(app.server)
+        .patch(`/api/admin/admins/${adminId}/revoke`)
        .expect(200);

      expect(revokeResponse.body.revokedAt).toBeTruthy();

      // 4. Reinstate admin
-      const reinstateResponse = await request(app)
-        .patch(`/api/admin/admins/${auth0Sub}/reinstate`)
+      const reinstateResponse = await request(app.server)
+        .patch(`/api/admin/admins/${adminId}/reinstate`)
        .expect(200);

      expect(reinstateResponse.body.revokedAt).toBeNull();

      // 5. Verify complete audit trail
-      const auditResponse = await request(app)
+      const auditResponse = await request(app.server)
        .get('/api/admin/audit-logs')
        .expect(200);

      const workflowLogs = auditResponse.body.logs.filter(
-        (log: any) => log.targetAdminId === auth0Sub || log.resourceId === 'workflow@example.com'
+        (log: any) => log.targetAdminId === adminId || log.resourceId === 'workflow@example.com'
      );

      expect(workflowLogs.length).toBeGreaterThanOrEqual(3);
--- a/backend/src/features/admin/tests/unit/admin.guard.test.ts
+++ b/backend/src/features/admin/tests/unit/admin.guard.test.ts
@@ -26,7 +26,7 @@ describe('admin guard plugin', () => {
    fastify = Fastify();
    authenticateMock = jest.fn(async (request: FastifyRequest) => {
      request.userContext = {
-        userId: 'auth0|admin',
+        userId: '7c9e6679-7425-40de-944b-e07fc1f90ae7',
        email: 'admin@motovaultpro.com',
        emailVerified: true,
        onboardingCompleted: true,
@@ -41,7 +41,7 @@ describe('admin guard plugin', () => {
    mockPool = {
      query: jest.fn().mockResolvedValue({
        rows: [{
-          auth0_sub: 'auth0|admin',
+          user_profile_id: '7c9e6679-7425-40de-944b-e07fc1f90ae7',
          email: 'admin@motovaultpro.com',
          role: 'admin',
          revoked_at: null,
--- a/backend/src/features/admin/tests/unit/admin.service.test.ts
+++ b/backend/src/features/admin/tests/unit/admin.service.test.ts
@@ -6,13 +6,23 @@
 import { AdminService } from '../../domain/admin.service';
 import { AdminRepository } from '../../data/admin.repository';

+// Mock the audit log service
+jest.mock('../../../audit-log', () => ({
+  auditLogService: {
+    info: jest.fn().mockResolvedValue(undefined),
+    warn: jest.fn().mockResolvedValue(undefined),
+    error: jest.fn().mockResolvedValue(undefined),
+  },
+}));
+
 describe('AdminService', () => {
  let adminService: AdminService;
  let mockRepository: jest.Mocked<AdminRepository>;

  beforeEach(() => {
    mockRepository = {
-      getAdminByAuth0Sub: jest.fn(),
+      getAdminById: jest.fn(),
+      getAdminByUserProfileId: jest.fn(),
      getAdminByEmail: jest.fn(),
      getAllAdmins: jest.fn(),
      getActiveAdmins: jest.fn(),
@@ -26,30 +36,31 @@ describe('AdminService', () => {
    adminService = new AdminService(mockRepository);
  });

-  describe('getAdminByAuth0Sub', () => {
+  describe('getAdminById', () => {
    it('should return admin when found', async () => {
      const mockAdmin = {
-        auth0Sub: 'auth0|123456',
+        id: '7c9e6679-7425-40de-944b-e07fc1f90ae7',
+        userProfileId: '7c9e6679-7425-40de-944b-e07fc1f90ae7',
        email: 'admin@motovaultpro.com',
-        role: 'admin',
+        role: 'admin' as const,
        createdAt: new Date(),
-        createdBy: 'system',
+        createdBy: '550e8400-e29b-41d4-a716-446655440000',
        revokedAt: null,
        updatedAt: new Date(),
      };

-      mockRepository.getAdminByAuth0Sub.mockResolvedValue(mockAdmin);
+      mockRepository.getAdminById.mockResolvedValue(mockAdmin);

-      const result = await adminService.getAdminByAuth0Sub('auth0|123456');
+      const result = await adminService.getAdminById('7c9e6679-7425-40de-944b-e07fc1f90ae7');

      expect(result).toEqual(mockAdmin);
-      expect(mockRepository.getAdminByAuth0Sub).toHaveBeenCalledWith('auth0|123456');
+      expect(mockRepository.getAdminById).toHaveBeenCalledWith('7c9e6679-7425-40de-944b-e07fc1f90ae7');
    });

    it('should return null when admin not found', async () => {
-      mockRepository.getAdminByAuth0Sub.mockResolvedValue(null);
+      mockRepository.getAdminById.mockResolvedValue(null);

-      const result = await adminService.getAdminByAuth0Sub('auth0|unknown');
+      const result = await adminService.getAdminById('00000000-0000-0000-0000-000000000000');

      expect(result).toBeNull();
    });
@@ -57,12 +68,15 @@ describe('AdminService', () => {

  describe('createAdmin', () => {
    it('should create new admin and log audit', async () => {
+      const newAdminId = '8f14e45f-ceea-367f-a27f-c9a6d0c67e0e';
+      const creatorId = '7c9e6679-7425-40de-944b-e07fc1f90ae7';
      const mockAdmin = {
-        auth0Sub: 'auth0|newadmin',
+        id: newAdminId,
+        userProfileId: newAdminId,
        email: 'newadmin@motovaultpro.com',
-        role: 'admin',
+        role: 'admin' as const,
        createdAt: new Date(),
-        createdBy: 'auth0|existing',
+        createdBy: creatorId,
        revokedAt: null,
        updatedAt: new Date(),
      };
@@ -74,16 +88,16 @@ describe('AdminService', () => {
      const result = await adminService.createAdmin(
        'newadmin@motovaultpro.com',
        'admin',
-        'auth0|newadmin',
-        'auth0|existing'
+        newAdminId,
+        creatorId
      );

      expect(result).toEqual(mockAdmin);
      expect(mockRepository.createAdmin).toHaveBeenCalled();
      expect(mockRepository.logAuditAction).toHaveBeenCalledWith(
-        'auth0|existing',
+        creatorId,
        'CREATE',
-        mockAdmin.auth0Sub,
+        mockAdmin.id,
        'admin_user',
        mockAdmin.email,
        expect.any(Object)
@@ -91,12 +105,14 @@ describe('AdminService', () => {
    });

    it('should reject if admin already exists', async () => {
+      const existingId = '7c9e6679-7425-40de-944b-e07fc1f90ae7';
      const existingAdmin = {
-        auth0Sub: 'auth0|existing',
+        id: existingId,
+        userProfileId: existingId,
        email: 'admin@motovaultpro.com',
-        role: 'admin',
+        role: 'admin' as const,
        createdAt: new Date(),
-        createdBy: 'system',
+        createdBy: '550e8400-e29b-41d4-a716-446655440000',
        revokedAt: null,
        updatedAt: new Date(),
      };
@@ -104,39 +120,46 @@ describe('AdminService', () => {
      mockRepository.getAdminByEmail.mockResolvedValue(existingAdmin);

      await expect(
-        adminService.createAdmin('admin@motovaultpro.com', 'admin', 'auth0|new', 'auth0|existing')
+        adminService.createAdmin('admin@motovaultpro.com', 'admin', '8f14e45f-ceea-367f-a27f-c9a6d0c67e0e', existingId)
      ).rejects.toThrow('already exists');
    });
  });

  describe('revokeAdmin', () => {
    it('should revoke admin when multiple active admins exist', async () => {
+      const toRevokeId = 'a1b2c3d4-e5f6-7890-1234-567890abcdef';
+      const admin1Id = '6ba7b810-9dad-11d1-80b4-00c04fd430c8';
+      const admin2Id = '8f14e45f-ceea-367f-a27f-c9a6d0c67e0e';
+
      const revokedAdmin = {
-        auth0Sub: 'auth0|toadmin',
+        id: toRevokeId,
+        userProfileId: toRevokeId,
        email: 'toadmin@motovaultpro.com',
-        role: 'admin',
+        role: 'admin' as const,
        createdAt: new Date(),
-        createdBy: 'system',
+        createdBy: '550e8400-e29b-41d4-a716-446655440000',
        revokedAt: new Date(),
        updatedAt: new Date(),
      };

      const activeAdmins = [
        {
-          auth0Sub: 'auth0|admin1',
+          id: admin1Id,
+          userProfileId: admin1Id,
          email: 'admin1@motovaultpro.com',
-          role: 'admin',
+          role: 'admin' as const,
          createdAt: new Date(),
-          createdBy: 'system',
+          createdBy: '550e8400-e29b-41d4-a716-446655440000',
          revokedAt: null,
          updatedAt: new Date(),
        },
        {
-          auth0Sub: 'auth0|admin2',
+          id: admin2Id,
+          userProfileId: admin2Id,
          email: 'admin2@motovaultpro.com',
-          role: 'admin',
+          role: 'admin' as const,
          createdAt: new Date(),
-          createdBy: 'system',
+          createdBy: '550e8400-e29b-41d4-a716-446655440000',
          revokedAt: null,
          updatedAt: new Date(),
        },
@@ -146,20 +169,22 @@ describe('AdminService', () => {
      mockRepository.revokeAdmin.mockResolvedValue(revokedAdmin);
      mockRepository.logAuditAction.mockResolvedValue({} as any);

-      const result = await adminService.revokeAdmin('auth0|toadmin', 'auth0|admin1');
+      const result = await adminService.revokeAdmin(toRevokeId, admin1Id);

      expect(result).toEqual(revokedAdmin);
-      expect(mockRepository.revokeAdmin).toHaveBeenCalledWith('auth0|toadmin');
+      expect(mockRepository.revokeAdmin).toHaveBeenCalledWith(toRevokeId);
      expect(mockRepository.logAuditAction).toHaveBeenCalled();
    });

    it('should prevent revoking last active admin', async () => {
+      const lastAdminId = '7c9e6679-7425-40de-944b-e07fc1f90ae7';
      const lastAdmin = {
-        auth0Sub: 'auth0|lastadmin',
+        id: lastAdminId,
+        userProfileId: lastAdminId,
        email: 'last@motovaultpro.com',
-        role: 'admin',
+        role: 'admin' as const,
        createdAt: new Date(),
-        createdBy: 'system',
+        createdBy: '550e8400-e29b-41d4-a716-446655440000',
        revokedAt: null,
        updatedAt: new Date(),
      };
@@ -167,19 +192,22 @@ describe('AdminService', () => {
      mockRepository.getActiveAdmins.mockResolvedValue([lastAdmin]);

      await expect(
-        adminService.revokeAdmin('auth0|lastadmin', 'auth0|lastadmin')
+        adminService.revokeAdmin(lastAdminId, lastAdminId)
      ).rejects.toThrow('Cannot revoke the last active admin');
    });
  });

  describe('reinstateAdmin', () => {
    it('should reinstate revoked admin and log audit', async () => {
+      const reinstateId = 'b2c3d4e5-f6a7-8901-2345-678901bcdef0';
+      const adminActorId = '7c9e6679-7425-40de-944b-e07fc1f90ae7';
      const reinstatedAdmin = {
-        auth0Sub: 'auth0|reinstate',
+        id: reinstateId,
+        userProfileId: reinstateId,
        email: 'reinstate@motovaultpro.com',
-        role: 'admin',
+        role: 'admin' as const,
        createdAt: new Date(),
-        createdBy: 'system',
+        createdBy: '550e8400-e29b-41d4-a716-446655440000',
        revokedAt: null,
        updatedAt: new Date(),
      };
@@ -187,14 +215,14 @@ describe('AdminService', () => {
      mockRepository.reinstateAdmin.mockResolvedValue(reinstatedAdmin);
      mockRepository.logAuditAction.mockResolvedValue({} as any);

-      const result = await adminService.reinstateAdmin('auth0|reinstate', 'auth0|admin');
+      const result = await adminService.reinstateAdmin(reinstateId, adminActorId);

      expect(result).toEqual(reinstatedAdmin);
-      expect(mockRepository.reinstateAdmin).toHaveBeenCalledWith('auth0|reinstate');
+      expect(mockRepository.reinstateAdmin).toHaveBeenCalledWith(reinstateId);
      expect(mockRepository.logAuditAction).toHaveBeenCalledWith(
-        'auth0|admin',
+        adminActorId,
        'REINSTATE',
-        'auth0|reinstate',
+        reinstateId,
        'admin_user',
        reinstatedAdmin.email
      );
--- a/backend/src/features/audit-log/CLAUDE.md
+++ b/backend/src/features/audit-log/CLAUDE.md
@@ -1,12 +1,11 @@
 # audit-log/

-Centralized audit logging system for tracking all user and system actions.
-
 ## Files

 | File | What | When to read |
 | ---- | ---- | ------------ |
-| `README.md` | Architecture and API documentation | Understanding audit log system |
+| `README.md` | Architecture, usage patterns, categories | Understanding audit log system |
+| `audit-log.instance.ts` | Singleton service instance | Cross-feature logging integration |

 ## Subdirectories

@@ -18,38 +17,3 @@ Centralized audit logging system for tracking all user and system actions.
 | `jobs/` | Scheduled cleanup job | Retention policy |
 | `migrations/` | Database schema | Schema changes |
 | `__tests__/` | Integration tests | Adding or modifying tests |
-
-## Key Files
-
-| File | What | When to read |
-| ---- | ---- | ------------ |
-| `audit-log.instance.ts` | Singleton service instance | Cross-feature logging |
-| `domain/audit-log.types.ts` | Types, categories, severities | Type definitions |
-| `domain/audit-log.service.ts` | Core logging operations | Creating/searching logs |
-| `data/audit-log.repository.ts` | Database queries | Data access patterns |
-| `jobs/cleanup.job.ts` | 90-day retention cleanup | Retention enforcement |
-
-## Usage
-
-Import the singleton for cross-feature logging:
-
-```typescript
-import { auditLogService } from '../../audit-log';
-
-// Log with convenience methods
-await auditLogService.info('vehicle', userId, 'Vehicle created', 'vehicle', vehicleId);
-await auditLogService.warning('auth', userId, 'Password reset requested');
-await auditLogService.error('system', null, 'Backup failed', 'backup', backupId);
-```
-
-## Categories
-
- `auth`: Login, logout, password changes
- `vehicle`: Vehicle CRUD operations
- `user`: User management actions
- `system`: Backups, imports/exports
- `admin`: Admin-specific actions
-
-## Retention
-
-Logs older than 90 days are automatically deleted by a daily cleanup job (3 AM).
--- a/backend/src/features/audit-log/tests/audit-log.integration.test.ts
+++ b/backend/src/features/audit-log/tests/audit-log.integration.test.ts
@@ -32,7 +32,7 @@ describe('AuditLog Feature Integration', () => {

  describe('Vehicle logging integration', () => {
    it('should create audit log with vehicle category and correct resource', async () => {
-      const userId = 'test-user-vehicle-123';
+      const userId = '550e8400-e29b-41d4-a716-446655440000';
      const vehicleId = 'vehicle-uuid-123';
      const entry = await service.info(
        'vehicle',
@@ -56,7 +56,7 @@ describe('AuditLog Feature Integration', () => {
    });

    it('should log vehicle update with correct fields', async () => {
-      const userId = 'test-user-vehicle-456';
+      const userId = '6ba7b810-9dad-11d1-80b4-00c04fd430c8';
      const vehicleId = 'vehicle-uuid-456';
      const entry = await service.info(
        'vehicle',
@@ -75,7 +75,7 @@ describe('AuditLog Feature Integration', () => {
    });

    it('should log vehicle deletion with vehicle info', async () => {
-      const userId = 'test-user-vehicle-789';
+      const userId = '7c9e6679-7425-40de-944b-e07fc1f90ae7';
      const vehicleId = 'vehicle-uuid-789';
      const entry = await service.info(
        'vehicle',
@@ -96,7 +96,7 @@ describe('AuditLog Feature Integration', () => {

  describe('Auth logging integration', () => {
    it('should create audit log with auth category for signup', async () => {
-      const userId = 'test-user-auth-123';
+      const userId = '550e8400-e29b-41d4-a716-446655440000';
      const entry = await service.info(
        'auth',
        userId,
@@ -116,7 +116,7 @@ describe('AuditLog Feature Integration', () => {
    });

    it('should create audit log for password reset request', async () => {
-      const userId = 'test-user-auth-456';
+      const userId = '6ba7b810-9dad-11d1-80b4-00c04fd430c8';
      const entry = await service.info(
        'auth',
        userId,
@@ -134,14 +134,14 @@ describe('AuditLog Feature Integration', () => {

  describe('Admin logging integration', () => {
    it('should create audit log for admin user creation', async () => {
-      const adminId = 'admin-user-123';
-      const targetAdminSub = 'auth0|target-admin-456';
+      const adminId = '7c9e6679-7425-40de-944b-e07fc1f90ae7';
+      const targetAdminId = '8f14e45f-ceea-367f-a27f-c9a6d0c67e0e';
      const entry = await service.info(
        'admin',
        adminId,
        'Admin user created: newadmin@example.com',
        'admin_user',
-        targetAdminSub,
+        targetAdminId,
        { email: 'newadmin@example.com', role: 'admin' }
      );

@@ -156,14 +156,14 @@ describe('AuditLog Feature Integration', () => {
    });

    it('should create audit log for admin revocation', async () => {
-      const adminId = 'admin-user-123';
-      const targetAdminSub = 'auth0|target-admin-789';
+      const adminId = '7c9e6679-7425-40de-944b-e07fc1f90ae7';
+      const targetAdminId = 'a1b2c3d4-e5f6-7890-1234-567890abcdef';
      const entry = await service.info(
        'admin',
        adminId,
        'Admin user revoked: revoked@example.com',
        'admin_user',
-        targetAdminSub,
+        targetAdminId,
        { email: 'revoked@example.com' }
      );

@@ -174,14 +174,14 @@ describe('AuditLog Feature Integration', () => {
    });

    it('should create audit log for admin reinstatement', async () => {
-      const adminId = 'admin-user-123';
-      const targetAdminSub = 'auth0|target-admin-reinstated';
+      const adminId = '7c9e6679-7425-40de-944b-e07fc1f90ae7';
+      const targetAdminId = 'b2c3d4e5-f6a7-8901-2345-678901bcdef0';
      const entry = await service.info(
        'admin',
        adminId,
        'Admin user reinstated: reinstated@example.com',
        'admin_user',
-        targetAdminSub,
+        targetAdminId,
        { email: 'reinstated@example.com' }
      );

@@ -194,7 +194,7 @@ describe('AuditLog Feature Integration', () => {

  describe('Backup/System logging integration', () => {
    it('should create audit log for backup creation', async () => {
-      const adminId = 'admin-user-backup-123';
+      const adminId = '7c9e6679-7425-40de-944b-e07fc1f90ae7';
      const backupId = 'backup-uuid-123';
      const entry = await service.info(
        'system',
@@ -215,7 +215,7 @@ describe('AuditLog Feature Integration', () => {
    });

    it('should create audit log for backup restore', async () => {
-      const adminId = 'admin-user-backup-456';
+      const adminId = '7c9e6679-7425-40de-944b-e07fc1f90ae7';
      const backupId = 'backup-uuid-456';
      const entry = await service.info(
        'system',
@@ -233,7 +233,7 @@ describe('AuditLog Feature Integration', () => {
    });

    it('should create error-level audit log for backup failure', async () => {
-      const adminId = 'admin-user-backup-789';
+      const adminId = '7c9e6679-7425-40de-944b-e07fc1f90ae7';
      const backupId = 'backup-uuid-789';
      const entry = await service.error(
        'system',
@@ -253,7 +253,7 @@ describe('AuditLog Feature Integration', () => {
    });

    it('should create error-level audit log for restore failure', async () => {
-      const adminId = 'admin-user-restore-fail';
+      const adminId = '7c9e6679-7425-40de-944b-e07fc1f90ae7';
      const backupId = 'backup-uuid-restore-fail';
      const entry = await service.error(
        'system',
--- a/backend/src/features/audit-log/data/audit-log.repository.ts
+++ b/backend/src/features/audit-log/data/audit-log.repository.ts
@@ -126,7 +126,7 @@ export class AuditLogRepository {
             al.resource_type, al.resource_id, al.details, al.created_at,
             up.email as user_email
      FROM audit_logs al
-      LEFT JOIN user_profiles up ON al.user_id = up.auth0_sub
+      LEFT JOIN user_profiles up ON al.user_id = up.id
      ${whereClause}
      ORDER BY al.created_at DESC
      LIMIT $${nextParamIndex} OFFSET $${nextParamIndex + 1}
@@ -170,7 +170,7 @@ export class AuditLogRepository {
             al.resource_type, al.resource_id, al.details, al.created_at,
             up.email as user_email
      FROM audit_logs al
-      LEFT JOIN user_profiles up ON al.user_id = up.auth0_sub
+      LEFT JOIN user_profiles up ON al.user_id = up.id
      ${whereClause}
      ORDER BY al.created_at DESC
      LIMIT ${MAX_EXPORT_RECORDS}
--- a/backend/src/features/auth/CLAUDE.md
+++ b/backend/src/features/auth/CLAUDE.md
@@ -0,0 +1,16 @@
+# auth/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `README.md` | Feature documentation | Understanding auth flow |
+| `index.ts` | Feature barrel export | Importing auth services |
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `api/` | HTTP endpoints and routes | API changes |
+| `domain/` | Business logic, services, types | Core auth logic |
+| `tests/` | Unit and integration tests | Adding or modifying tests |
--- a/backend/src/features/auth/api/auth.controller.ts
+++ b/backend/src/features/auth/api/auth.controller.ts
@@ -110,17 +110,17 @@ export class AuthController {
   */
  async getVerifyStatus(request: FastifyRequest, reply: FastifyReply) {
    try {
-      const userId = (request as any).user.sub;
+      const auth0Sub = (request as any).user.sub;

-      const result = await this.authService.getVerifyStatus(userId);
+      const result = await this.authService.getVerifyStatus(auth0Sub);

-      logger.info('Verification status checked', { userId, emailVerified: result.emailVerified });
+      logger.info('Verification status checked', { userId: request.userContext?.userId, emailVerified: result.emailVerified });

      return reply.code(200).send(result);
    } catch (error: any) {
      logger.error('Failed to get verification status', {
        error,
-        userId: (request as any).user?.sub,
+        userId: request.userContext?.userId,
      });

      return reply.code(500).send({
@@ -137,17 +137,17 @@ export class AuthController {
   */
  async resendVerification(request: FastifyRequest, reply: FastifyReply) {
    try {
-      const userId = (request as any).user.sub;
+      const auth0Sub = (request as any).user.sub;

-      const result = await this.authService.resendVerification(userId);
+      const result = await this.authService.resendVerification(auth0Sub);

-      logger.info('Verification email resent', { userId });
+      logger.info('Verification email resent', { userId: request.userContext?.userId });

      return reply.code(200).send(result);
    } catch (error: any) {
      logger.error('Failed to resend verification email', {
        error,
-        userId: (request as any).user?.sub,
+        userId: request.userContext?.userId,
      });

      return reply.code(500).send({
@@ -199,23 +199,26 @@ export class AuthController {
   */
  async getUserStatus(request: FastifyRequest, reply: FastifyReply) {
    try {
-      const userId = (request as any).user.sub;
+      const auth0Sub = (request as any).user.sub;
+      const userId = request.userContext?.userId;

-      const result = await this.authService.getUserStatus(userId);
+      const result = await this.authService.getUserStatus(auth0Sub);

      // Log login event to audit trail (called once per Auth0 callback)
      const ipAddress = this.getClientIp(request);
-      await auditLogService.info(
-        'auth',
-        userId,
-        'User login',
-        'user',
-        userId,
-        { ipAddress }
-      ).catch(err => logger.error('Failed to log login audit event', { error: err }));
+      if (userId) {
+        await auditLogService.info(
+          'auth',
+          userId,
+          'User login',
+          'user',
+          userId,
+          { ipAddress }
+        ).catch(err => logger.error('Failed to log login audit event', { error: err }));
+      }

      logger.info('User status retrieved', {
-        userId: userId.substring(0, 8) + '...',
+        userId: userId?.substring(0, 8) + '...',
        emailVerified: result.emailVerified,
        onboardingCompleted: result.onboardingCompleted,
      });
@@ -224,7 +227,7 @@ export class AuthController {
    } catch (error: any) {
      logger.error('Failed to get user status', {
        error,
-        userId: (request as any).user?.sub,
+        userId: request.userContext?.userId,
      });

      return reply.code(500).send({
@@ -241,12 +244,12 @@ export class AuthController {
   */
  async getSecurityStatus(request: FastifyRequest, reply: FastifyReply) {
    try {
-      const userId = (request as any).user.sub;
+      const auth0Sub = (request as any).user.sub;

-      const result = await this.authService.getSecurityStatus(userId);
+      const result = await this.authService.getSecurityStatus(auth0Sub);

      logger.info('Security status retrieved', {
-        userId: userId.substring(0, 8) + '...',
+        userId: request.userContext?.userId,
        emailVerified: result.emailVerified,
      });

@@ -254,7 +257,7 @@ export class AuthController {
    } catch (error: any) {
      logger.error('Failed to get security status', {
        error,
-        userId: (request as any).user?.sub,
+        userId: request.userContext?.userId,
      });

      return reply.code(500).send({
@@ -271,28 +274,31 @@ export class AuthController {
   */
  async requestPasswordReset(request: FastifyRequest, reply: FastifyReply) {
    try {
-      const userId = (request as any).user.sub;
+      const auth0Sub = (request as any).user.sub;
+      const userId = request.userContext?.userId;

-      const result = await this.authService.requestPasswordReset(userId);
+      const result = await this.authService.requestPasswordReset(auth0Sub);

      logger.info('Password reset email requested', {
-        userId: userId.substring(0, 8) + '...',
+        userId: userId?.substring(0, 8) + '...',
      });

      // Log password reset request to unified audit log
-      await auditLogService.info(
-        'auth',
-        userId,
-        'Password reset requested',
-        'user',
-        userId
-      ).catch(err => logger.error('Failed to log password reset audit event', { error: err }));
+      if (userId) {
+        await auditLogService.info(
+          'auth',
+          userId,
+          'Password reset requested',
+          'user',
+          userId
+        ).catch(err => logger.error('Failed to log password reset audit event', { error: err }));
+      }

      return reply.code(200).send(result);
    } catch (error: any) {
      logger.error('Failed to request password reset', {
        error,
-        userId: (request as any).user?.sub,
+        userId: request.userContext?.userId,
      });

      return reply.code(500).send({
@@ -312,21 +318,23 @@ export class AuthController {
   */
  async trackLogout(request: FastifyRequest, reply: FastifyReply) {
    try {
-      const userId = (request as any).user.sub;
+      const userId = request.userContext?.userId;
      const ipAddress = this.getClientIp(request);

      // Log logout event to audit trail
-      await auditLogService.info(
-        'auth',
-        userId,
-        'User logout',
-        'user',
-        userId,
-        { ipAddress }
-      ).catch(err => logger.error('Failed to log logout audit event', { error: err }));
+      if (userId) {
+        await auditLogService.info(
+          'auth',
+          userId,
+          'User logout',
+          'user',
+          userId,
+          { ipAddress }
+        ).catch(err => logger.error('Failed to log logout audit event', { error: err }));
+      }

      logger.info('User logout tracked', {
-        userId: userId.substring(0, 8) + '...',
+        userId: userId?.substring(0, 8) + '...',
      });

      return reply.code(200).send({ success: true });
@@ -334,7 +342,7 @@ export class AuthController {
      // Don't block logout on audit failure - always return success
      logger.error('Failed to track logout', {
        error,
-        userId: (request as any).user?.sub,
+        userId: request.userContext?.userId,
      });

      return reply.code(200).send({ success: true });
--- a/backend/src/features/auth/tests/integration/auth.integration.test.ts
+++ b/backend/src/features/auth/tests/integration/auth.integration.test.ts
@@ -19,6 +19,7 @@ jest.mock('../../../../core/plugins/auth.plugin', () => {
  return {
    default: fastifyPlugin(async function (fastify) {
      fastify.decorate('authenticate', async function (request, _reply) {
+        // JWT sub is still auth0|xxx format
        request.user = { sub: 'auth0|test-user-123' };
      });
    }, { name: 'auth-plugin' }),
--- a/backend/src/features/auth/tests/unit/auth.service.test.ts
+++ b/backend/src/features/auth/tests/unit/auth.service.test.ts
@@ -103,6 +103,8 @@ describe('AuthService', () => {
        onboardingCompletedAt: null,
        deactivatedAt: null,
        deactivatedBy: null,
+        deletionRequestedAt: null,
+        deletionScheduledFor: null,
        createdAt: new Date(),
        updatedAt: new Date(),
      });
@@ -116,6 +118,8 @@ describe('AuthService', () => {
        onboardingCompletedAt: null,
        deactivatedAt: null,
        deactivatedBy: null,
+        deletionRequestedAt: null,
+        deletionScheduledFor: null,
        createdAt: new Date(),
        updatedAt: new Date(),
      });
@@ -149,6 +153,8 @@ describe('AuthService', () => {
        onboardingCompletedAt: null,
        deactivatedAt: null,
        deactivatedBy: null,
+        deletionRequestedAt: null,
+        deletionScheduledFor: null,
        createdAt: new Date(),
        updatedAt: new Date(),
      });
--- a/backend/src/features/backup/CLAUDE.md
+++ b/backend/src/features/backup/CLAUDE.md
@@ -1,7 +1,5 @@
 # backup/

-Complete backup and restore system with tiered retention.
-
 ## Files

 | File | What | When to read |
@@ -18,13 +16,3 @@ Complete backup and restore system with tiered retention.
 | `jobs/` | Scheduled job handlers | Cron job modifications |
 | `migrations/` | Database schema | Schema changes |
 | `tests/` | Unit and integration tests | Adding or modifying tests |
-
-## Key Files
-
-| File | What | When to read |
-| ---- | ---- | ------------ |
-| `domain/backup.types.ts` | Types, constants, TIERED_RETENTION | Type definitions |
-| `domain/backup.service.ts` | Core backup operations | Creating/managing backups |
-| `domain/backup-classification.service.ts` | Tiered retention classification | Category/expiration logic |
-| `domain/backup-retention.service.ts` | Retention enforcement | Deletion logic |
-| `data/backup.repository.ts` | Database queries | Data access patterns |
--- a/backend/src/features/backup/api/backup.controller.ts
+++ b/backend/src/features/backup/api/backup.controller.ts
@@ -45,12 +45,12 @@ export class BackupController {
    request: FastifyRequest<{ Body: CreateBackupBody }>,
    reply: FastifyReply
  ): Promise<void> {
-    const adminSub = (request as any).userContext?.auth0Sub;
+    const adminUserId = request.userContext?.userId;

    const result = await this.backupService.createBackup({
      name: request.body.name,
      backupType: 'manual',
-      createdBy: adminSub,
+      createdBy: adminUserId,
      includeDocuments: request.body.includeDocuments,
    });

@@ -58,7 +58,7 @@ export class BackupController {
      // Log backup creation to unified audit log
      await auditLogService.info(
        'system',
-        adminSub || null,
+        adminUserId || null,
        `Backup created: ${request.body.name || 'Manual backup'}`,
        'backup',
        result.backupId,
@@ -74,7 +74,7 @@ export class BackupController {
      // Log backup failure
      await auditLogService.error(
        'system',
-        adminSub || null,
+        adminUserId || null,
        `Backup failed: ${request.body.name || 'Manual backup'}`,
        'backup',
        result.backupId,
@@ -139,7 +139,7 @@ export class BackupController {
    request: FastifyRequest,
    reply: FastifyReply
  ): Promise<void> {
-    const adminSub = (request as any).userContext?.auth0Sub;
+    const adminUserId = request.userContext?.userId;

    // Handle multipart file upload
    const data = await request.file();
@@ -173,7 +173,7 @@ export class BackupController {
      const backup = await this.backupService.importUploadedBackup(
        tempPath,
        filename,
-        adminSub
+        adminUserId
      );

      reply.status(201).send({
@@ -217,7 +217,7 @@ export class BackupController {
    request: FastifyRequest<{ Params: BackupIdParam; Body: RestoreBody }>,
    reply: FastifyReply
  ): Promise<void> {
-    const adminSub = (request as any).userContext?.auth0Sub;
+    const adminUserId = request.userContext?.userId;

    try {
      const result = await this.restoreService.executeRestore({
@@ -229,7 +229,7 @@ export class BackupController {
        // Log successful restore to unified audit log
        await auditLogService.info(
          'system',
-          adminSub || null,
+          adminUserId || null,
          `Backup restored: ${request.params.id}`,
          'backup',
          request.params.id,
@@ -246,7 +246,7 @@ export class BackupController {
        // Log restore failure
        await auditLogService.error(
          'system',
-          adminSub || null,
+          adminUserId || null,
          `Backup restore failed: ${request.params.id}`,
          'backup',
          request.params.id,
--- a/backend/src/features/documents/CLAUDE.md
+++ b/backend/src/features/documents/CLAUDE.md
@@ -0,0 +1,18 @@
+# documents/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `README.md` | Feature documentation | Understanding document management |
+| `index.ts` | Feature barrel export | Importing document services |
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `api/` | HTTP endpoints and routes | API changes |
+| `domain/` | Business logic, services, types | Core document logic |
+| `data/` | Repository, database queries | Database operations |
+| `migrations/` | Database schema | Schema changes |
+| `tests/` | Unit and integration tests | Adding or modifying tests |
--- a/backend/src/features/documents/api/documents.controller.ts
+++ b/backend/src/features/documents/api/documents.controller.ts
@@ -15,7 +15,7 @@ export class DocumentsController {
  private readonly service = new DocumentsService();

  async list(request: FastifyRequest<{ Querystring: ListQuery }>, reply: FastifyReply) {
-    const userId = (request as any).user?.sub as string;
+    const userId = request.userContext!.userId;

    logger.info('Documents list requested', {
      operation: 'documents.list',
@@ -43,7 +43,7 @@ export class DocumentsController {
  }

  async get(request: FastifyRequest<{ Params: IdParams }>, reply: FastifyReply) {
-    const userId = (request as any).user?.sub as string;
+    const userId = request.userContext!.userId;
    const documentId = request.params.id;

    logger.info('Document get requested', {
@@ -74,7 +74,7 @@ export class DocumentsController {
  }

  async create(request: FastifyRequest<{ Body: CreateBody }>, reply: FastifyReply) {
-    const userId = (request as any).user?.sub as string;
+    const userId = request.userContext!.userId;
    const userTier: SubscriptionTier = request.userContext?.subscriptionTier || 'free';

    logger.info('Document create requested', {
@@ -120,7 +120,7 @@ export class DocumentsController {
  }

  async update(request: FastifyRequest<{ Params: IdParams; Body: UpdateBody }>, reply: FastifyReply) {
-    const userId = (request as any).user?.sub as string;
+    const userId = request.userContext!.userId;
    const userTier: SubscriptionTier = request.userContext?.subscriptionTier || 'free';
    const documentId = request.params.id;

@@ -174,7 +174,7 @@ export class DocumentsController {
  }

  async remove(request: FastifyRequest<{ Params: IdParams }>, reply: FastifyReply) {
-    const userId = (request as any).user?.sub as string;
+    const userId = request.userContext!.userId;
    const documentId = request.params.id;

    logger.info('Document delete requested', {
@@ -221,7 +221,7 @@ export class DocumentsController {
  }

  async upload(request: FastifyRequest<{ Params: IdParams }>, reply: FastifyReply) {
-    const userId = (request as any).user?.sub as string;
+    const userId = request.userContext!.userId;
    const documentId = request.params.id;

    logger.info('Document upload requested', {
@@ -272,20 +272,15 @@ export class DocumentsController {
      });
    }

-    // Read first 4100 bytes to detect file type via magic bytes
+    // Collect ALL file chunks first (breaking early from async iterator corrupts stream state)
    const chunks: Buffer[] = [];
-    let totalBytes = 0;
-    const targetBytes = 4100;
-
    for await (const chunk of mp.file) {
      chunks.push(chunk);
-      totalBytes += chunk.length;
-      if (totalBytes >= targetBytes) {
-        break;
-      }
    }
+    const fullBuffer = Buffer.concat(chunks);

-    const headerBuffer = Buffer.concat(chunks);
+    // Use first 4100 bytes for file type detection via magic bytes
+    const headerBuffer = fullBuffer.subarray(0, Math.min(4100, fullBuffer.length));

    // Validate actual file content using magic bytes
    const detectedType = await FileType.fromBuffer(headerBuffer);
@@ -341,15 +336,9 @@ export class DocumentsController {

    const counter = new CountingStream();

-    // Create a new readable stream from the header buffer + remaining file chunks
-    const headerStream = Readable.from([headerBuffer]);
-    const remainingStream = mp.file;
-
-    // Pipe header first, then remaining content through counter
-    headerStream.pipe(counter, { end: false });
-    headerStream.on('end', () => {
-      remainingStream.pipe(counter);
-    });
+    // Create readable stream from the complete buffer and pipe through counter
+    const fileStream = Readable.from([fullBuffer]);
+    fileStream.pipe(counter);

    const storage = getStorageService();
    const bucket = 'documents';
@@ -384,7 +373,7 @@ export class DocumentsController {
  }

  async download(request: FastifyRequest<{ Params: IdParams }>, reply: FastifyReply) {
-    const userId = (request as any).user?.sub as string;
+    const userId = request.userContext!.userId;
    const documentId = request.params.id;

    logger.info('Document download requested', {
@@ -432,6 +421,165 @@ export class DocumentsController {
    const stream = await storage.getObjectStream(doc.storageBucket, doc.storageKey);
    return reply.send(stream);
  }
+
+  async listByVehicle(request: FastifyRequest<{ Params: { vehicleId: string } }>, reply: FastifyReply) {
+    const userId = request.userContext!.userId;
+    const vehicleId = request.params.vehicleId;
+
+    logger.info('Documents by vehicle requested', {
+      operation: 'documents.listByVehicle',
+      userId,
+      vehicleId,
+    });
+
+    try {
+      const docs = await this.service.getDocumentsByVehicle(userId, vehicleId);
+
+      logger.info('Documents by vehicle retrieved', {
+        operation: 'documents.listByVehicle.success',
+        userId,
+        vehicleId,
+        documentCount: docs.length,
+      });
+
+      return reply.code(200).send(docs);
+    } catch (e: any) {
+      if (e.statusCode === 403) {
+        logger.warn('Vehicle not found or not owned', {
+          operation: 'documents.listByVehicle.forbidden',
+          userId,
+          vehicleId,
+        });
+        return reply.code(403).send({ error: 'Forbidden', message: e.message });
+      }
+      throw e;
+    }
+  }
+
+  async addVehicle(request: FastifyRequest<{ Params: { id: string; vehicleId: string } }>, reply: FastifyReply) {
+    const userId = request.userContext!.userId;
+    const { id: documentId, vehicleId } = request.params;
+
+    logger.info('Add vehicle to document requested', {
+      operation: 'documents.addVehicle',
+      userId,
+      documentId,
+      vehicleId,
+    });
+
+    try {
+      const updated = await this.service.addVehicleToDocument(userId, documentId, vehicleId);
+
+      if (!updated) {
+        logger.warn('Document not updated (possibly duplicate vehicle)', {
+          operation: 'documents.addVehicle.not_updated',
+          userId,
+          documentId,
+          vehicleId,
+        });
+        return reply.code(400).send({ error: 'Bad Request', message: 'Vehicle could not be added' });
+      }
+
+      logger.info('Vehicle added to document', {
+        operation: 'documents.addVehicle.success',
+        userId,
+        documentId,
+        vehicleId,
+        sharedVehicleCount: updated.sharedVehicleIds.length,
+      });
+
+      return reply.code(200).send(updated);
+    } catch (e: any) {
+      if (e.statusCode === 404) {
+        logger.warn('Document not found for adding vehicle', {
+          operation: 'documents.addVehicle.not_found',
+          userId,
+          documentId,
+          vehicleId,
+        });
+        return reply.code(404).send({ error: 'Not Found', message: e.message });
+      }
+      if (e.statusCode === 400) {
+        logger.warn('Bad request for adding vehicle', {
+          operation: 'documents.addVehicle.bad_request',
+          userId,
+          documentId,
+          vehicleId,
+          reason: e.message,
+        });
+        return reply.code(400).send({ error: 'Bad Request', message: e.message });
+      }
+      if (e.statusCode === 403) {
+        logger.warn('Forbidden - vehicle not owned', {
+          operation: 'documents.addVehicle.forbidden',
+          userId,
+          documentId,
+          vehicleId,
+        });
+        return reply.code(403).send({ error: 'Forbidden', message: e.message });
+      }
+      throw e;
+    }
+  }
+
+  async removeVehicle(request: FastifyRequest<{ Params: { id: string; vehicleId: string } }>, reply: FastifyReply) {
+    const userId = request.userContext!.userId;
+    const { id: documentId, vehicleId } = request.params;
+
+    logger.info('Remove vehicle from document requested', {
+      operation: 'documents.removeVehicle',
+      userId,
+      documentId,
+      vehicleId,
+    });
+
+    try {
+      const updated = await this.service.removeVehicleFromDocument(userId, documentId, vehicleId);
+
+      if (!updated) {
+        // Document was soft deleted
+        logger.info('Document soft deleted (primary vehicle removed, no shared vehicles)', {
+          operation: 'documents.removeVehicle.deleted',
+          userId,
+          documentId,
+          vehicleId,
+        });
+        return reply.code(204).send();
+      }
+
+      logger.info('Vehicle removed from document', {
+        operation: 'documents.removeVehicle.success',
+        userId,
+        documentId,
+        vehicleId,
+        sharedVehicleCount: updated.sharedVehicleIds.length,
+        primaryVehicleId: updated.vehicleId,
+      });
+
+      return reply.code(200).send(updated);
+    } catch (e: any) {
+      if (e.statusCode === 404) {
+        logger.warn('Document not found for removing vehicle', {
+          operation: 'documents.removeVehicle.not_found',
+          userId,
+          documentId,
+          vehicleId,
+        });
+        return reply.code(404).send({ error: 'Not Found', message: e.message });
+      }
+      if (e.statusCode === 400) {
+        logger.warn('Bad request for removing vehicle', {
+          operation: 'documents.removeVehicle.bad_request',
+          userId,
+          documentId,
+          vehicleId,
+          reason: e.message,
+        });
+        return reply.code(400).send({ error: 'Bad Request', message: e.message });
+      }
+      throw e;
+    }
+  }
 }

 function cryptoRandom(): string {
--- a/backend/src/features/documents/api/documents.routes.ts
+++ b/backend/src/features/documents/api/documents.routes.ts
@@ -22,16 +22,6 @@ export const documentsRoutes: FastifyPluginAsync = async (
    handler: ctrl.get.bind(ctrl)
  });

-  fastify.get<{ Params: any }>('/documents/vehicle/:vehicleId', {
-    preHandler: [requireAuth],
-    handler: async (req, reply) => {
-      const userId = (req as any).user?.sub as string;
-      const query = { vehicleId: (req.params as any).vehicleId };
-      const docs = await ctrl['service'].listDocuments(userId, query);
-      return reply.code(200).send(docs);
-    }
-  });
-
  fastify.post<{ Body: any }>('/documents', {
    preHandler: [requireAuth],
    handler: ctrl.create.bind(ctrl)
@@ -56,4 +46,20 @@ export const documentsRoutes: FastifyPluginAsync = async (
    preHandler: [requireAuth],
    handler: ctrl.download.bind(ctrl)
  });
+
+  // Vehicle management routes
+  fastify.get<{ Params: any }>('/documents/by-vehicle/:vehicleId', {
+    preHandler: [requireAuth],
+    handler: ctrl.listByVehicle.bind(ctrl)
+  });
+
+  fastify.post<{ Params: any }>('/documents/:id/vehicles/:vehicleId', {
+    preHandler: [requireAuth],
+    handler: ctrl.addVehicle.bind(ctrl)
+  });
+
+  fastify.delete<{ Params: any }>('/documents/:id/vehicles/:vehicleId', {
+    preHandler: [requireAuth],
+    handler: ctrl.removeVehicle.bind(ctrl)
+  });
 };
--- a/backend/src/features/documents/api/documents.validation.ts
+++ b/backend/src/features/documents/api/documents.validation.ts
@@ -9,6 +9,10 @@ export const ListQuerySchema = z.object({

 export const IdParamsSchema = z.object({ id: z.string().uuid() });
 export const VehicleParamsSchema = z.object({ vehicleId: z.string().uuid() });
+export const DocumentVehicleParamsSchema = z.object({
+  id: z.string().uuid(),
+  vehicleId: z.string().uuid()
+});

 export const CreateBodySchema = CreateDocumentBodySchema;
 export const UpdateBodySchema = UpdateDocumentBodySchema;
@@ -16,6 +20,7 @@ export const UpdateBodySchema = UpdateDocumentBodySchema;
 export type ListQuery = z.infer<typeof ListQuerySchema>;
 export type IdParams = z.infer<typeof IdParamsSchema>;
 export type VehicleParams = z.infer<typeof VehicleParamsSchema>;
+export type DocumentVehicleParams = z.infer<typeof DocumentVehicleParamsSchema>;
 export type CreateBody = z.infer<typeof CreateBodySchema>;
 export type UpdateBody = z.infer<typeof UpdateBodySchema>;

--- a/backend/src/features/documents/data/documents.repository.ts
+++ b/backend/src/features/documents/data/documents.repository.ts
@@ -28,6 +28,7 @@ export class DocumentsRepository {
      expirationDate: row.expiration_date,
      emailNotifications: row.email_notifications,
      scanForMaintenance: row.scan_for_maintenance,
+      sharedVehicleIds: row.shared_vehicle_ids || [],
      createdAt: row.created_at,
      updatedAt: row.updated_at,
      deletedAt: row.deleted_at
@@ -50,11 +51,12 @@ export class DocumentsRepository {
    expirationDate?: string | null;
    emailNotifications?: boolean;
    scanForMaintenance?: boolean;
+    sharedVehicleIds?: string[];
  }): Promise<DocumentRecord> {
    const res = await this.db.query(
      `INSERT INTO documents (
-        id, user_id, vehicle_id, document_type, title, notes, details, issued_date, expiration_date, email_notifications, scan_for_maintenance
-      ) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11)
+        id, user_id, vehicle_id, document_type, title, notes, details, issued_date, expiration_date, email_notifications, scan_for_maintenance, shared_vehicle_ids
+      ) VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12)
      RETURNING *`,
      [
        doc.id,
@@ -68,6 +70,7 @@ export class DocumentsRepository {
        doc.expirationDate ?? null,
        doc.emailNotifications ?? false,
        doc.scanForMaintenance ?? false,
+        doc.sharedVehicleIds ?? [],
      ]
    );
    return this.mapDocumentRecord(res.rows[0]);
@@ -103,6 +106,7 @@ export class DocumentsRepository {
      expirationDate?: string | null;
      emailNotifications?: boolean;
      scanForMaintenance?: boolean;
+      sharedVehicleIds?: string[];
    }>,
    client?: any
  ): Promise<DocumentRecord[]> {
@@ -128,17 +132,18 @@ export class DocumentsRepository {
        doc.issuedDate ?? null,
        doc.expirationDate ?? null,
        doc.emailNotifications ?? false,
-        doc.scanForMaintenance ?? false
+        doc.scanForMaintenance ?? false,
+        doc.sharedVehicleIds ?? []
      ];

-      const placeholder = `($${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++})`;
+      const placeholder = `($${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++}, $${paramCount++})`;
      placeholders.push(placeholder);
      values.push(...docParams);
    });

    const query = `
      INSERT INTO documents (
-        id, user_id, vehicle_id, document_type, title, notes, details, issued_date, expiration_date, email_notifications, scan_for_maintenance
+        id, user_id, vehicle_id, document_type, title, notes, details, issued_date, expiration_date, email_notifications, scan_for_maintenance, shared_vehicle_ids
      )
      VALUES ${placeholders.join(', ')}
      RETURNING *
@@ -152,7 +157,7 @@ export class DocumentsRepository {
    await this.db.query(`UPDATE documents SET deleted_at = NOW() WHERE id = $1 AND user_id = $2`, [id, userId]);
  }

-  async updateMetadata(id: string, userId: string, patch: Partial<Pick<DocumentRecord, 'title'|'notes'|'details'|'issuedDate'|'expirationDate'|'emailNotifications'|'scanForMaintenance'>>): Promise<DocumentRecord | null> {
+  async updateMetadata(id: string, userId: string, patch: Partial<Pick<DocumentRecord, 'title'|'notes'|'details'|'issuedDate'|'expirationDate'|'emailNotifications'|'scanForMaintenance'|'sharedVehicleIds'>>): Promise<DocumentRecord | null> {
    const fields: string[] = [];
    const params: any[] = [];
    let i = 1;
@@ -163,6 +168,7 @@ export class DocumentsRepository {
    if (patch.expirationDate !== undefined) { fields.push(`expiration_date = $${i++}`); params.push(patch.expirationDate); }
    if (patch.emailNotifications !== undefined) { fields.push(`email_notifications = $${i++}`); params.push(patch.emailNotifications); }
    if (patch.scanForMaintenance !== undefined) { fields.push(`scan_for_maintenance = $${i++}`); params.push(patch.scanForMaintenance); }
+    if (patch.sharedVehicleIds !== undefined) { fields.push(`shared_vehicle_ids = $${i++}`); params.push(patch.sharedVehicleIds); }
    if (!fields.length) return this.findById(id, userId);
    params.push(id, userId);
    const sql = `UPDATE documents SET ${fields.join(', ')} WHERE id = $${i++} AND user_id = $${i++} AND deleted_at IS NULL RETURNING *`;
@@ -187,5 +193,56 @@ export class DocumentsRepository {
    );
    return res.rows[0] ? this.mapDocumentRecord(res.rows[0]) : null;
  }
+
+  // ========================
+  // Shared Vehicle Operations (Atomic)
+  // ========================
+
+  /**
+   * Atomically add a vehicle to the shared_vehicle_ids array.
+   * Uses PostgreSQL array_append() to avoid race conditions.
+   */
+  async addSharedVehicle(docId: string, userId: string, vehicleId: string): Promise<DocumentRecord | null> {
+    const res = await this.db.query(
+      `UPDATE documents
+       SET shared_vehicle_ids = array_append(shared_vehicle_ids, $1::uuid)
+       WHERE id = $2 AND user_id = $3 AND deleted_at IS NULL
+         AND NOT ($1::uuid = ANY(shared_vehicle_ids))
+       RETURNING *`,
+      [vehicleId, docId, userId]
+    );
+    return res.rows[0] ? this.mapDocumentRecord(res.rows[0]) : null;
+  }
+
+  /**
+   * Atomically remove a vehicle from the shared_vehicle_ids array.
+   * Uses PostgreSQL array_remove() to avoid race conditions.
+   */
+  async removeSharedVehicle(docId: string, userId: string, vehicleId: string): Promise<DocumentRecord | null> {
+    const res = await this.db.query(
+      `UPDATE documents
+       SET shared_vehicle_ids = array_remove(shared_vehicle_ids, $1::uuid)
+       WHERE id = $2 AND user_id = $3 AND deleted_at IS NULL
+       RETURNING *`,
+      [vehicleId, docId, userId]
+    );
+    return res.rows[0] ? this.mapDocumentRecord(res.rows[0]) : null;
+  }
+
+  /**
+   * List all documents associated with a vehicle (either as primary or shared).
+   * Returns documents where vehicle_id = vehicleId OR vehicleId = ANY(shared_vehicle_ids).
+   */
+  async listByVehicle(userId: string, vehicleId: string): Promise<DocumentRecord[]> {
+    const res = await this.db.query(
+      `SELECT * FROM documents
+       WHERE user_id = $1
+         AND deleted_at IS NULL
+         AND (vehicle_id = $2 OR $2::uuid = ANY(shared_vehicle_ids))
+       ORDER BY created_at DESC`,
+      [userId, vehicleId]
+    );
+    return res.rows.map(row => this.mapDocumentRecord(row));
+  }
 }

--- a/backend/src/features/documents/domain/documents.service.ts
+++ b/backend/src/features/documents/domain/documents.service.ts
@@ -1,15 +1,32 @@
 import { randomUUID } from 'crypto';
 import type { CreateDocumentBody, DocumentRecord, DocumentType, UpdateDocumentBody } from './documents.types';
 import { DocumentsRepository } from '../data/documents.repository';
+import { OwnershipCostsService } from '../../ownership-costs/domain/ownership-costs.service';
+import type { OwnershipCostType } from '../../ownership-costs/domain/ownership-costs.types';
 import pool from '../../../core/config/database';

 export class DocumentsService {
  private readonly repo = new DocumentsRepository(pool);
+  private readonly ownershipCostsService = new OwnershipCostsService(pool);

  async createDocument(userId: string, body: CreateDocumentBody): Promise<DocumentRecord> {
    await this.assertVehicleOwnership(userId, body.vehicleId);
+
+    // Validate shared vehicles if provided (insurance type only)
+    if (body.sharedVehicleIds && body.sharedVehicleIds.length > 0) {
+      if (body.documentType !== 'insurance') {
+        const err: any = new Error('Shared vehicles are only supported for insurance documents');
+        err.statusCode = 400;
+        throw err;
+      }
+      // Validate ownership of all shared vehicles
+      for (const vid of body.sharedVehicleIds) {
+        await this.assertVehicleOwnership(userId, vid);
+      }
+    }
+
    const id = randomUUID();
-    return this.repo.insert({
+    const doc = await this.repo.insert({
      id,
      userId,
      vehicleId: body.vehicleId,
@@ -21,7 +38,72 @@ export class DocumentsService {
      expirationDate: body.expirationDate ?? null,
      emailNotifications: body.emailNotifications ?? false,
      scanForMaintenance: body.scanForMaintenance ?? false,
+      sharedVehicleIds: body.sharedVehicleIds ?? [],
    });
+
+    // Auto-create ownership_cost when insurance/registration has cost data
+    await this.autoCreateOwnershipCost(userId, doc, body);
+
+    return doc;
+  }
+
+  /**
+   * Auto-creates an ownership_cost record when an insurance or registration
+   * document is created with cost data (premium or cost field in details).
+   */
+  private async autoCreateOwnershipCost(
+    userId: string,
+    doc: DocumentRecord,
+    body: CreateDocumentBody
+  ): Promise<void> {
+    const costType = this.mapDocumentTypeToCostType(body.documentType);
+    if (!costType) return; // Not a cost-linkable document type
+
+    const costAmount = this.extractCostAmount(body);
+    if (!costAmount || costAmount <= 0) return; // No valid cost data
+
+    try {
+      await this.ownershipCostsService.createCost(userId, {
+        vehicleId: body.vehicleId,
+        documentId: doc.id,
+        costType,
+        amount: costAmount,
+        description: doc.title,
+        periodStart: body.issuedDate,
+        periodEnd: body.expirationDate,
+      });
+    } catch (err) {
+      // Log but don't fail document creation if cost creation fails
+      console.error('Failed to auto-create ownership cost for document:', doc.id, err);
+    }
+  }
+
+  /**
+   * Maps document types to ownership cost types.
+   * Returns null for document types that don't auto-create costs.
+   */
+  private mapDocumentTypeToCostType(documentType: string): OwnershipCostType | null {
+    const typeMap: Record<string, OwnershipCostType> = {
+      'insurance': 'insurance',
+      'registration': 'registration',
+    };
+    return typeMap[documentType] || null;
+  }
+
+  /**
+   * Extracts cost amount from document details.
+   * Insurance uses 'premium', registration uses 'cost'.
+   */
+  private extractCostAmount(body: CreateDocumentBody): number | null {
+    if (!body.details) return null;
+
+    const premium = body.details.premium;
+    const cost = body.details.cost;
+
+    if (typeof premium === 'number' && premium > 0) return premium;
+    if (typeof cost === 'number' && cost > 0) return cost;
+
+    return null;
  }

  async getDocument(userId: string, id: string): Promise<DocumentRecord | null> {
@@ -35,16 +117,184 @@ export class DocumentsService {
  async updateDocument(userId: string, id: string, patch: UpdateDocumentBody) {
    const existing = await this.repo.findById(id, userId);
    if (!existing) return null;
+
+    // Validate shared vehicles if provided (insurance type only)
+    if (patch.sharedVehicleIds !== undefined) {
+      if (existing.documentType !== 'insurance') {
+        const err: any = new Error('Shared vehicles are only supported for insurance documents');
+        err.statusCode = 400;
+        throw err;
+      }
+      // Validate ownership of all shared vehicles
+      for (const vid of patch.sharedVehicleIds) {
+        await this.assertVehicleOwnership(userId, vid);
+      }
+    }
+
    if (patch && typeof patch === 'object') {
-      return this.repo.updateMetadata(id, userId, patch as any);
+      const updated = await this.repo.updateMetadata(id, userId, patch as any);
+
+      // Sync cost changes to linked ownership_cost if applicable
+      if (updated && patch.details) {
+        await this.syncOwnershipCost(userId, updated, patch);
+      }
+
+      return updated;
    }
    return existing;
  }

+  /**
+   * Syncs cost data changes to linked ownership_cost record.
+   * If document has linked cost and details.premium/cost changed, update it.
+   */
+  private async syncOwnershipCost(
+    userId: string,
+    doc: DocumentRecord,
+    patch: UpdateDocumentBody
+  ): Promise<void> {
+    const costType = this.mapDocumentTypeToCostType(doc.documentType);
+    if (!costType) return;
+
+    const newCostAmount = this.extractCostAmountFromDetails(patch.details);
+    if (newCostAmount === null) return; // No cost in update
+
+    try {
+      // Find existing linked cost
+      const linkedCosts = await this.ownershipCostsService.getCosts(userId, { documentId: doc.id });
+
+      if (linkedCosts.length > 0 && newCostAmount > 0) {
+        // Update existing linked cost
+        await this.ownershipCostsService.updateCost(userId, linkedCosts[0].id, {
+          amount: newCostAmount,
+          periodStart: patch.issuedDate ?? undefined,
+          periodEnd: patch.expirationDate ?? undefined,
+        });
+      } else if (linkedCosts.length === 0 && newCostAmount > 0) {
+        // Create new cost if none exists
+        await this.ownershipCostsService.createCost(userId, {
+          vehicleId: doc.vehicleId,
+          documentId: doc.id,
+          costType,
+          amount: newCostAmount,
+          description: doc.title,
+          periodStart: patch.issuedDate ?? doc.issuedDate ?? undefined,
+          periodEnd: patch.expirationDate ?? doc.expirationDate ?? undefined,
+        });
+      }
+    } catch (err) {
+      console.error('Failed to sync ownership cost for document:', doc.id, err);
+    }
+  }
+
+  /**
+   * Extracts cost amount from details object (for updates).
+   */
+  private extractCostAmountFromDetails(details?: Record<string, any> | null): number | null {
+    if (!details) return null;
+
+    const premium = details.premium;
+    const cost = details.cost;
+
+    if (typeof premium === 'number') return premium;
+    if (typeof cost === 'number') return cost;
+
+    return null;
+  }
+
  async deleteDocument(userId: string, id: string): Promise<void> {
+    // Note: Linked ownership_cost records are CASCADE deleted via FK
    await this.repo.softDelete(id, userId);
  }

+  async addVehicleToDocument(userId: string, docId: string, vehicleId: string): Promise<DocumentRecord | null> {
+    // Validate document exists and is owned by user
+    const doc = await this.repo.findById(docId, userId);
+    if (!doc) {
+      const err: any = new Error('Document not found');
+      err.statusCode = 404;
+      throw err;
+    }
+
+    // Only insurance documents support shared vehicles
+    if (doc.documentType !== 'insurance') {
+      const err: any = new Error('Shared vehicles are only supported for insurance documents');
+      err.statusCode = 400;
+      throw err;
+    }
+
+    // Validate vehicle ownership
+    await this.assertVehicleOwnership(userId, vehicleId);
+
+    // Check if vehicle is already the primary vehicle
+    if (doc.vehicleId === vehicleId) {
+      const err: any = new Error('Vehicle is already the primary vehicle for this document');
+      err.statusCode = 400;
+      throw err;
+    }
+
+    // Add to shared vehicles (repository handles duplicate check)
+    return this.repo.addSharedVehicle(docId, userId, vehicleId);
+  }
+
+  async removeVehicleFromDocument(userId: string, docId: string, vehicleId: string): Promise<DocumentRecord | null> {
+    // Validate document exists and is owned by user
+    const doc = await this.repo.findById(docId, userId);
+    if (!doc) {
+      const err: any = new Error('Document not found');
+      err.statusCode = 404;
+      throw err;
+    }
+
+    // Context-aware delete logic
+    const isSharedVehicle = doc.sharedVehicleIds.includes(vehicleId);
+    const isPrimaryVehicle = doc.vehicleId === vehicleId;
+
+    if (!isSharedVehicle && !isPrimaryVehicle) {
+      const err: any = new Error('Vehicle is not associated with this document');
+      err.statusCode = 400;
+      throw err;
+    }
+
+    // Case 1: Removing from shared vehicles only
+    if (isSharedVehicle && !isPrimaryVehicle) {
+      return this.repo.removeSharedVehicle(docId, userId, vehicleId);
+    }
+
+    // Case 2: Removing primary vehicle with no shared vehicles -> soft delete document
+    if (isPrimaryVehicle && doc.sharedVehicleIds.length === 0) {
+      await this.repo.softDelete(docId, userId);
+      return null;
+    }
+
+    // Case 3: Removing primary vehicle with shared vehicles -> promote first shared to primary
+    if (isPrimaryVehicle && doc.sharedVehicleIds.length > 0) {
+      const newPrimaryId = doc.sharedVehicleIds[0];
+      const remainingShared = doc.sharedVehicleIds.slice(1);
+
+      // Update primary vehicle and remaining shared vehicles
+      return this.repo.updateMetadata(docId, userId, {
+        sharedVehicleIds: remainingShared,
+      }).then(async () => {
+        // Update vehicle_id separately as it's not part of the metadata update
+        const res = await pool.query(
+          'UPDATE documents SET vehicle_id = $1 WHERE id = $2 AND user_id = $3 AND deleted_at IS NULL RETURNING *',
+          [newPrimaryId, docId, userId]
+        );
+        if (!res.rows[0]) return null;
+        return this.repo.findById(docId, userId);
+      });
+    }
+
+    return null;
+  }
+
+  async getDocumentsByVehicle(userId: string, vehicleId: string): Promise<DocumentRecord[]> {
+    // Validate vehicle ownership
+    await this.assertVehicleOwnership(userId, vehicleId);
+    return this.repo.listByVehicle(userId, vehicleId);
+  }
+
  private async assertVehicleOwnership(userId: string, vehicleId: string) {
    const res = await pool.query('SELECT id FROM vehicles WHERE id = $1 AND user_id = $2', [vehicleId, userId]);
    if (!res.rows[0]) {
--- a/backend/src/features/documents/domain/documents.types.ts
+++ b/backend/src/features/documents/domain/documents.types.ts
@@ -22,6 +22,7 @@ export interface DocumentRecord {
  expirationDate?: string | null;
  emailNotifications?: boolean;
  scanForMaintenance?: boolean;
+  sharedVehicleIds: string[];
  createdAt: string;
  updatedAt: string;
  deletedAt?: string | null;
@@ -38,6 +39,7 @@ export const CreateDocumentBodySchema = z.object({
  expirationDate: z.string().optional(),
  emailNotifications: z.boolean().optional(),
  scanForMaintenance: z.boolean().optional(),
+  sharedVehicleIds: z.array(z.string().uuid()).optional(),
 });
 export type CreateDocumentBody = z.infer<typeof CreateDocumentBodySchema>;

@@ -49,6 +51,7 @@ export const UpdateDocumentBodySchema = z.object({
  expirationDate: z.string().nullable().optional(),
  emailNotifications: z.boolean().optional(),
  scanForMaintenance: z.boolean().optional(),
+  sharedVehicleIds: z.array(z.string().uuid()).optional(),
 });
 export type UpdateDocumentBody = z.infer<typeof UpdateDocumentBodySchema>;

--- a/backend/src/features/documents/migrations/004_add_shared_vehicle_ids.sql
+++ b/backend/src/features/documents/migrations/004_add_shared_vehicle_ids.sql
@@ -0,0 +1,18 @@
+-- Migration: Add shared_vehicle_ids array column for cross-vehicle document sharing
+-- Issue: #31
+-- Allows a document to be shared with multiple vehicles beyond its primary vehicle_id
+
+-- Add shared_vehicle_ids column with default empty array
+ALTER TABLE documents
+  ADD COLUMN shared_vehicle_ids UUID[] DEFAULT '{}' NOT NULL;
+
+-- Add GIN index for efficient array membership queries
+-- This allows fast lookups of "which documents are shared with vehicle X"
+CREATE INDEX idx_documents_shared_vehicle_ids ON documents USING GIN (shared_vehicle_ids array_ops);
+
+-- Example usage:
+-- 1. Find all documents shared with a specific vehicle:
+--    SELECT * FROM documents WHERE 'vehicle-uuid-here' = ANY(shared_vehicle_ids);
+--
+-- 2. Find documents by primary OR shared vehicle:
+--    SELECT * FROM documents WHERE vehicle_id = 'uuid' OR 'uuid' = ANY(shared_vehicle_ids);
--- a/backend/src/features/email-ingestion/api/email-ingestion.controller.ts
+++ b/backend/src/features/email-ingestion/api/email-ingestion.controller.ts
@@ -0,0 +1,188 @@
+/**
+ * @ai-summary Controller for Resend inbound email webhook and user-facing pending association endpoints
+ * @ai-context Webhook handler (public) + pending association CRUD (JWT-authenticated)
+ */
+
+import { FastifyRequest, FastifyReply } from 'fastify';
+import { ResendInboundClient } from '../external/resend-inbound.client';
+import { EmailIngestionRepository } from '../data/email-ingestion.repository';
+import { EmailIngestionService } from '../domain/email-ingestion.service';
+import { logger } from '../../../core/logging/logger';
+import type { ResendWebhookEvent } from '../domain/email-ingestion.types';
+
+export class EmailIngestionController {
+  private resendClient: ResendInboundClient;
+  private repository: EmailIngestionRepository;
+  private service: EmailIngestionService;
+
+  constructor() {
+    this.resendClient = new ResendInboundClient();
+    this.repository = new EmailIngestionRepository();
+    this.service = new EmailIngestionService();
+  }
+
+  // ========================
+  // Pending Association Endpoints (JWT-authenticated)
+  // ========================
+
+  async getPendingAssociations(request: FastifyRequest, reply: FastifyReply): Promise<void> {
+    try {
+      const userId = request.userContext!.userId;
+      const associations = await this.repository.getPendingAssociations(userId);
+      return reply.code(200).send(associations);
+    } catch (error: any) {
+      logger.error('Error listing pending associations', { error: error.message, userId: request.userContext?.userId });
+      return reply.code(500).send({ error: 'Failed to list pending associations' });
+    }
+  }
+
+  async getPendingAssociationCount(request: FastifyRequest, reply: FastifyReply): Promise<void> {
+    try {
+      const userId = request.userContext!.userId;
+      const count = await this.repository.getPendingAssociationCount(userId);
+      return reply.code(200).send({ count });
+    } catch (error: any) {
+      logger.error('Error counting pending associations', { error: error.message, userId: request.userContext?.userId });
+      return reply.code(500).send({ error: 'Failed to count pending associations' });
+    }
+  }
+
+  async resolveAssociation(
+    request: FastifyRequest<{ Params: { id: string }; Body: { vehicleId: string } }>,
+    reply: FastifyReply
+  ): Promise<void> {
+    try {
+      const userId = request.userContext!.userId;
+      const { id } = request.params;
+      const { vehicleId } = request.body;
+
+      if (!vehicleId || typeof vehicleId !== 'string') {
+        return reply.code(400).send({ error: 'vehicleId is required' });
+      }
+
+      const result = await this.service.resolveAssociation(id, vehicleId, userId);
+      return reply.code(200).send(result);
+    } catch (error: any) {
+      const userId = request.userContext?.userId;
+      logger.error('Error resolving pending association', {
+        error: error.message,
+        associationId: request.params.id,
+        userId,
+      });
+
+      if (error.message === 'Pending association not found' || error.message === 'Vehicle not found') {
+        return reply.code(404).send({ error: error.message });
+      }
+      if (error.message === 'Unauthorized') {
+        return reply.code(403).send({ error: 'Not authorized' });
+      }
+      if (error.message === 'Association already resolved') {
+        return reply.code(409).send({ error: error.message });
+      }
+
+      return reply.code(500).send({ error: 'Failed to resolve association' });
+    }
+  }
+
+  async dismissAssociation(
+    request: FastifyRequest<{ Params: { id: string } }>,
+    reply: FastifyReply
+  ): Promise<void> {
+    try {
+      const userId = request.userContext!.userId;
+      const { id } = request.params;
+
+      await this.service.dismissAssociation(id, userId);
+      return reply.code(204).send();
+    } catch (error: any) {
+      const userId = request.userContext?.userId;
+      logger.error('Error dismissing pending association', {
+        error: error.message,
+        associationId: request.params.id,
+        userId,
+      });
+
+      if (error.message === 'Pending association not found') {
+        return reply.code(404).send({ error: error.message });
+      }
+      if (error.message === 'Unauthorized') {
+        return reply.code(403).send({ error: 'Not authorized' });
+      }
+      if (error.message === 'Association already resolved') {
+        return reply.code(409).send({ error: error.message });
+      }
+
+      return reply.code(500).send({ error: 'Failed to dismiss association' });
+    }
+  }
+
+  // ========================
+  // Webhook Endpoint (Public)
+  // ========================
+
+  async handleInboundWebhook(request: FastifyRequest, reply: FastifyReply): Promise<void> {
+    try {
+      const rawBody = (request as any).rawBody;
+      if (!rawBody) {
+        logger.error('Missing raw body in Resend webhook request');
+        return reply.status(400).send({ error: 'Missing raw body' });
+      }
+
+      // Extract Svix headers for signature verification
+      const headers: Record<string, string> = {
+        'svix-id': (request.headers['svix-id'] as string) || '',
+        'svix-timestamp': (request.headers['svix-timestamp'] as string) || '',
+        'svix-signature': (request.headers['svix-signature'] as string) || '',
+      };
+
+      // Verify webhook signature
+      let event: ResendWebhookEvent;
+      try {
+        event = this.resendClient.verifyWebhookSignature(rawBody, headers);
+      } catch (error: any) {
+        logger.warn('Invalid Resend webhook signature', { error: error.message });
+        return reply.status(400).send({ error: 'Invalid signature' });
+      }
+
+      const emailId = event.data.email_id;
+      const senderEmail = event.data.from;
+
+      // Idempotency check: reject if email_id already exists in queue
+      const existing = await this.repository.findByEmailId(emailId);
+      if (existing) {
+        logger.info('Duplicate email webhook received, skipping', { emailId });
+        return reply.status(200).send({ received: true, duplicate: true });
+      }
+
+      // Insert queue record with status=pending via repository
+      await this.repository.insertQueueEntry({
+        emailId,
+        senderEmail,
+        userId: senderEmail, // Resolved to auth0_sub during processing
+        receivedAt: event.data.created_at || new Date().toISOString(),
+        subject: event.data.subject,
+      });
+
+      logger.info('Inbound email queued for processing', { emailId, senderEmail });
+
+      // Return 200 immediately before processing begins
+      reply.status(200).send({ received: true });
+
+      // Trigger async processing via setImmediate
+      setImmediate(() => {
+        this.service.processEmail(emailId, event).catch((error) => {
+          logger.error('Async email processing failed', {
+            emailId,
+            error: error instanceof Error ? error.message : String(error),
+          });
+        });
+      });
+    } catch (error: any) {
+      logger.error('Resend webhook handler error', {
+        error: error.message,
+        stack: error.stack,
+      });
+      return reply.status(500).send({ error: 'Webhook processing failed' });
+    }
+  }
+}
--- a/backend/src/features/email-ingestion/api/email-ingestion.routes.ts
+++ b/backend/src/features/email-ingestion/api/email-ingestion.routes.ts
@@ -0,0 +1,60 @@
+/**
+ * @ai-summary Resend inbound webhook + user-facing pending association routes
+ * @ai-context Public webhook (no JWT) + authenticated CRUD for pending vehicle associations
+ */
+
+import { FastifyPluginAsync } from 'fastify';
+import { EmailIngestionController } from './email-ingestion.controller';
+
+/** Public webhook route - no JWT auth, uses Svix signature verification */
+export const emailIngestionWebhookRoutes: FastifyPluginAsync = async (fastify) => {
+  const controller = new EmailIngestionController();
+
+  // POST /api/webhooks/resend/inbound - PUBLIC endpoint (no JWT auth)
+  // Resend authenticates via webhook signature verification (Svix)
+  // rawBody MUST be enabled for signature verification to work
+  fastify.post(
+    '/webhooks/resend/inbound',
+    {
+      config: {
+        rawBody: true,
+      },
+    },
+    controller.handleInboundWebhook.bind(controller)
+  );
+};
+
+/** Authenticated user-facing routes for pending vehicle associations */
+export const emailIngestionRoutes: FastifyPluginAsync = async (fastify) => {
+  const controller = new EmailIngestionController();
+
+  // GET /api/email-ingestion/pending - List pending associations for authenticated user
+  fastify.get('/email-ingestion/pending', {
+    preHandler: [fastify.authenticate],
+    handler: controller.getPendingAssociations.bind(controller),
+  });
+
+  // GET /api/email-ingestion/pending/count - Get count of pending associations
+  fastify.get('/email-ingestion/pending/count', {
+    preHandler: [fastify.authenticate],
+    handler: controller.getPendingAssociationCount.bind(controller),
+  });
+
+  // POST /api/email-ingestion/pending/:id/resolve - Resolve by selecting vehicle
+  fastify.post<{ Params: { id: string }; Body: { vehicleId: string } }>(
+    '/email-ingestion/pending/:id/resolve',
+    {
+      preHandler: [fastify.authenticate],
+      handler: controller.resolveAssociation.bind(controller),
+    }
+  );
+
+  // DELETE /api/email-ingestion/pending/:id - Dismiss/discard a pending association
+  fastify.delete<{ Params: { id: string } }>(
+    '/email-ingestion/pending/:id',
+    {
+      preHandler: [fastify.authenticate],
+      handler: controller.dismissAssociation.bind(controller),
+    }
+  );
+};
--- a/backend/src/features/email-ingestion/data/email-ingestion.repository.ts
+++ b/backend/src/features/email-ingestion/data/email-ingestion.repository.ts
@@ -0,0 +1,257 @@
+/**
+ * @ai-summary Data access layer for email ingestion queue and pending vehicle associations
+ * @ai-context Provides CRUD operations with standard mapRow() snake_case -> camelCase conversion
+ */
+
+import { Pool } from 'pg';
+import pool from '../../../core/config/database';
+import { logger } from '../../../core/logging/logger';
+import type {
+  EmailIngestionQueueRecord,
+  EmailIngestionStatus,
+  EmailProcessingResult,
+  PendingVehicleAssociation,
+  PendingAssociationStatus,
+  EmailRecordType,
+  ExtractedReceiptData,
+} from '../domain/email-ingestion.types';
+
+export class EmailIngestionRepository {
+  constructor(private readonly db: Pool = pool) {}
+
+  // ========================
+  // Row Mappers
+  // ========================
+
+  private mapQueueRow(row: any): EmailIngestionQueueRecord {
+    return {
+      id: row.id,
+      emailId: row.email_id,
+      senderEmail: row.sender_email,
+      userId: row.user_id,
+      receivedAt: row.received_at,
+      subject: row.subject,
+      status: row.status,
+      processingResult: row.processing_result,
+      errorMessage: row.error_message,
+      retryCount: row.retry_count,
+      createdAt: row.created_at,
+      updatedAt: row.updated_at,
+    };
+  }
+
+  private mapPendingAssociationRow(row: any): PendingVehicleAssociation {
+    return {
+      id: row.id,
+      userId: row.user_id,
+      recordType: row.record_type,
+      extractedData: row.extracted_data,
+      documentId: row.document_id,
+      status: row.status,
+      createdAt: row.created_at,
+      resolvedAt: row.resolved_at,
+    };
+  }
+
+  // ========================
+  // Queue Operations
+  // ========================
+
+  async insertQueueEntry(entry: {
+    emailId: string;
+    senderEmail: string;
+    userId: string;
+    receivedAt: string;
+    subject: string | null;
+  }): Promise<EmailIngestionQueueRecord> {
+    try {
+      const res = await this.db.query(
+        `INSERT INTO email_ingestion_queue
+          (email_id, sender_email, user_id, received_at, subject, status)
+        VALUES ($1, $2, $3, $4, $5, 'pending')
+        RETURNING *`,
+        [
+          entry.emailId,
+          entry.senderEmail,
+          entry.userId,
+          entry.receivedAt,
+          entry.subject,
+        ]
+      );
+      return this.mapQueueRow(res.rows[0]);
+    } catch (error) {
+      logger.error('Error inserting queue entry', { error, emailId: entry.emailId });
+      throw error;
+    }
+  }
+
+  async updateQueueStatus(
+    emailId: string,
+    status: EmailIngestionStatus,
+    updates?: {
+      processingResult?: EmailProcessingResult;
+      errorMessage?: string;
+      retryCount?: number;
+      userId?: string;
+    }
+  ): Promise<EmailIngestionQueueRecord | null> {
+    try {
+      const fields: string[] = ['status = $2'];
+      const params: any[] = [emailId, status];
+      let paramIndex = 3;
+
+      if (updates?.processingResult !== undefined) {
+        fields.push(`processing_result = $${paramIndex++}`);
+        params.push(JSON.stringify(updates.processingResult));
+      }
+      if (updates?.errorMessage !== undefined) {
+        fields.push(`error_message = $${paramIndex++}`);
+        params.push(updates.errorMessage);
+      }
+      if (updates?.retryCount !== undefined) {
+        fields.push(`retry_count = $${paramIndex++}`);
+        params.push(updates.retryCount);
+      }
+      if (updates?.userId !== undefined) {
+        fields.push(`user_id = $${paramIndex++}`);
+        params.push(updates.userId);
+      }
+
+      const res = await this.db.query(
+        `UPDATE email_ingestion_queue
+        SET ${fields.join(', ')}
+        WHERE email_id = $1
+        RETURNING *`,
+        params
+      );
+      return res.rows[0] ? this.mapQueueRow(res.rows[0]) : null;
+    } catch (error) {
+      logger.error('Error updating queue status', { error, emailId, status });
+      throw error;
+    }
+  }
+
+  async getQueueEntry(emailId: string): Promise<EmailIngestionQueueRecord | null> {
+    try {
+      const res = await this.db.query(
+        `SELECT * FROM email_ingestion_queue WHERE email_id = $1`,
+        [emailId]
+      );
+      return res.rows[0] ? this.mapQueueRow(res.rows[0]) : null;
+    } catch (error) {
+      logger.error('Error fetching queue entry', { error, emailId });
+      throw error;
+    }
+  }
+
+  async findByEmailId(emailId: string): Promise<EmailIngestionQueueRecord | null> {
+    return this.getQueueEntry(emailId);
+  }
+
+  async getRetryableEntries(maxRetries: number = 3): Promise<EmailIngestionQueueRecord[]> {
+    try {
+      const res = await this.db.query(
+        `SELECT * FROM email_ingestion_queue
+        WHERE status = 'failed'
+          AND retry_count < $1
+        ORDER BY created_at ASC`,
+        [maxRetries]
+      );
+      return res.rows.map(row => this.mapQueueRow(row));
+    } catch (error) {
+      logger.error('Error fetching retryable entries', { error });
+      throw error;
+    }
+  }
+
+  // ========================
+  // Pending Association Operations
+  // ========================
+
+  async insertPendingAssociation(association: {
+    userId: string;
+    recordType: EmailRecordType;
+    extractedData: ExtractedReceiptData;
+    documentId: string | null;
+  }): Promise<PendingVehicleAssociation> {
+    try {
+      const res = await this.db.query(
+        `INSERT INTO pending_vehicle_associations
+          (user_id, record_type, extracted_data, document_id, status)
+        VALUES ($1, $2, $3, $4, 'pending')
+        RETURNING *`,
+        [
+          association.userId,
+          association.recordType,
+          JSON.stringify(association.extractedData),
+          association.documentId,
+        ]
+      );
+      return this.mapPendingAssociationRow(res.rows[0]);
+    } catch (error) {
+      logger.error('Error inserting pending association', { error, userId: association.userId });
+      throw error;
+    }
+  }
+
+  async getPendingAssociationById(associationId: string): Promise<PendingVehicleAssociation | null> {
+    try {
+      const res = await this.db.query(
+        `SELECT * FROM pending_vehicle_associations WHERE id = $1`,
+        [associationId]
+      );
+      return res.rows[0] ? this.mapPendingAssociationRow(res.rows[0]) : null;
+    } catch (error) {
+      logger.error('Error fetching pending association by id', { error, associationId });
+      throw error;
+    }
+  }
+
+  async getPendingAssociationCount(userId: string): Promise<number> {
+    try {
+      const res = await this.db.query(
+        `SELECT COUNT(*)::int AS count FROM pending_vehicle_associations
+        WHERE user_id = $1 AND status = 'pending'`,
+        [userId]
+      );
+      return res.rows[0]?.count ?? 0;
+    } catch (error) {
+      logger.error('Error counting pending associations', { error, userId });
+      throw error;
+    }
+  }
+
+  async getPendingAssociations(userId: string): Promise<PendingVehicleAssociation[]> {
+    try {
+      const res = await this.db.query(
+        `SELECT * FROM pending_vehicle_associations
+        WHERE user_id = $1 AND status = 'pending'
+        ORDER BY created_at DESC`,
+        [userId]
+      );
+      return res.rows.map(row => this.mapPendingAssociationRow(row));
+    } catch (error) {
+      logger.error('Error fetching pending associations', { error, userId });
+      throw error;
+    }
+  }
+
+  async resolvePendingAssociation(
+    associationId: string,
+    status: PendingAssociationStatus = 'resolved'
+  ): Promise<PendingVehicleAssociation | null> {
+    try {
+      const res = await this.db.query(
+        `UPDATE pending_vehicle_associations
+        SET status = $2, resolved_at = CURRENT_TIMESTAMP
+        WHERE id = $1
+        RETURNING *`,
+        [associationId, status]
+      );
+      return res.rows[0] ? this.mapPendingAssociationRow(res.rows[0]) : null;
+    } catch (error) {
+      logger.error('Error resolving pending association', { error, associationId });
+      throw error;
+    }
+  }
+}
--- a/backend/src/features/email-ingestion/domain/email-ingestion.service.ts
+++ b/backend/src/features/email-ingestion/domain/email-ingestion.service.ts
@@ -0,0 +1,844 @@
+/**
+ * @ai-summary Core processing service for the email-to-record pipeline
+ * @ai-context Orchestrates sender validation, OCR extraction, record classification,
+ *   vehicle association, status tracking, and retry logic. Delegates all notifications
+ *   (emails, in-app, logging) to EmailIngestionNotificationHandler.
+ */
+
+import { Pool } from 'pg';
+import pool from '../../../core/config/database';
+import { logger } from '../../../core/logging/logger';
+import { EmailIngestionRepository } from '../data/email-ingestion.repository';
+import { ResendInboundClient, type ParsedEmailAttachment } from '../external/resend-inbound.client';
+import { UserProfileRepository } from '../../user-profile/data/user-profile.repository';
+import { VehiclesRepository } from '../../vehicles/data/vehicles.repository';
+import { NotificationsRepository } from '../../notifications/data/notifications.repository';
+import { TemplateService } from '../../notifications/domain/template.service';
+import { EmailService } from '../../notifications/domain/email.service';
+import { ocrService } from '../../ocr/domain/ocr.service';
+import type { ReceiptExtractionResponse } from '../../ocr/domain/ocr.types';
+import { ReceiptClassifier } from './receipt-classifier';
+import { EmailIngestionNotificationHandler } from './notification-handler';
+import { FuelLogsService } from '../../fuel-logs/domain/fuel-logs.service';
+import { FuelLogsRepository } from '../../fuel-logs/data/fuel-logs.repository';
+import { FuelType } from '../../fuel-logs/domain/fuel-logs.types';
+import type { EnhancedCreateFuelLogRequest } from '../../fuel-logs/domain/fuel-logs.types';
+import { MaintenanceService } from '../../maintenance/domain/maintenance.service';
+import type { MaintenanceCategory } from '../../maintenance/domain/maintenance.types';
+import { validateSubtypes, getSubtypesForCategory } from '../../maintenance/domain/maintenance.types';
+import type {
+  ResendWebhookEvent,
+  EmailProcessingResult,
+  ExtractedReceiptData,
+  EmailRecordType,
+} from './email-ingestion.types';
+
+/** Supported attachment MIME types */
+const SUPPORTED_ATTACHMENT_TYPES = new Set([
+  'application/pdf',
+  'image/png',
+  'image/jpeg',
+  'image/heic',
+  'image/heif',
+]);
+
+/** Image types that work with receipt-specific OCR */
+const OCR_RECEIPT_IMAGE_TYPES = new Set([
+  'image/jpeg',
+  'image/png',
+  'image/heic',
+  'image/heif',
+]);
+
+const MAX_ATTACHMENT_SIZE = 10 * 1024 * 1024; // 10MB
+const MAX_RETRY_COUNT = 3;
+
+export class EmailIngestionService {
+  private repository: EmailIngestionRepository;
+  private resendClient: ResendInboundClient;
+  private userProfileRepository: UserProfileRepository;
+  private vehiclesRepository: VehiclesRepository;
+  private notificationHandler: EmailIngestionNotificationHandler;
+  private classifier: ReceiptClassifier;
+  private fuelLogsService: FuelLogsService;
+  private maintenanceService: MaintenanceService;
+
+  constructor(dbPool?: Pool) {
+    const p = dbPool || pool;
+    this.repository = new EmailIngestionRepository(p);
+    this.resendClient = new ResendInboundClient();
+    this.userProfileRepository = new UserProfileRepository(p);
+    this.vehiclesRepository = new VehiclesRepository(p);
+    const notificationsRepository = new NotificationsRepository(p);
+    this.notificationHandler = new EmailIngestionNotificationHandler(
+      notificationsRepository,
+      new TemplateService(),
+      new EmailService(),
+    );
+    this.classifier = new ReceiptClassifier();
+    this.fuelLogsService = new FuelLogsService(new FuelLogsRepository(p));
+    this.maintenanceService = new MaintenanceService();
+  }
+
+  // ========================
+  // Main Processing Pipeline
+  // ========================
+
+  /**
+   * Process an inbound email through the full pipeline.
+   * Called asynchronously after webhook receipt is acknowledged.
+   */
+  async processEmail(emailId: string, event: ResendWebhookEvent): Promise<void> {
+    const senderEmail = event.data.from;
+    const subject = event.data.subject;
+
+    try {
+      // 1. Mark as processing
+      await this.repository.updateQueueStatus(emailId, 'processing');
+
+      // 2. Validate sender
+      const userProfile = await this.validateSender(senderEmail);
+      if (!userProfile) {
+        await this.handleUnregisteredSender(emailId, senderEmail);
+        return;
+      }
+
+      const userId = userProfile.auth0Sub;
+      const userName = userProfile.displayName || userProfile.email;
+
+      // Update queue with resolved user_id
+      await this.repository.updateQueueStatus(emailId, 'processing', { userId });
+
+      // 3. Get attachments (from webhook data or by fetching raw email)
+      const attachments = await this.getAttachments(emailId, event);
+
+      // 4. Filter valid attachments
+      const validAttachments = this.filterAttachments(attachments);
+      if (validAttachments.length === 0) {
+        await this.handleNoValidAttachments(emailId, userId, userName, senderEmail);
+        return;
+      }
+
+      // 5. Classify receipt from email text first
+      const emailClassification = this.classifier.classifyFromText(subject, event.data.text);
+      logger.info('Email text classification result', {
+        emailId,
+        type: emailClassification.type,
+        confidence: emailClassification.confidence,
+      });
+
+      // 6. Process attachments through OCR using classification
+      const ocrResult = await this.processAttachmentsWithClassification(
+        userId, validAttachments, emailClassification, emailId
+      );
+      if (!ocrResult) {
+        await this.handleOcrFailure(emailId, userId, userName, senderEmail, 'No receipt data could be extracted from attachments');
+        return;
+      }
+
+      // 7. Build extracted data from OCR result
+      const extractedData = this.mapOcrToExtractedData(ocrResult.response);
+      const recordType = ocrResult.recordType;
+
+      // 8. Handle vehicle association
+      const processingResult = await this.handleVehicleAssociation(
+        userId, userName, senderEmail, recordType, extractedData
+      );
+
+      // 9. Mark as completed
+      await this.repository.updateQueueStatus(emailId, 'completed', {
+        processingResult,
+      });
+
+      logger.info('Email processing completed successfully', {
+        emailId,
+        userId,
+        recordType,
+        vehicleId: processingResult.vehicleId,
+        pendingAssociationId: processingResult.pendingAssociationId,
+      });
+    } catch (error) {
+      await this.handleProcessingError(emailId, senderEmail, subject, error);
+    }
+  }
+
+  // ========================
+  // Sender Validation
+  // ========================
+
+  private async validateSender(senderEmail: string): Promise<{
+    auth0Sub: string;
+    email: string;
+    displayName: string | null;
+  } | null> {
+    // Case-insensitive lookup by lowercasing the sender email
+    const profile = await this.userProfileRepository.getByEmail(senderEmail.toLowerCase());
+    if (profile) {
+      return {
+        auth0Sub: profile.auth0Sub,
+        email: profile.email,
+        displayName: profile.displayName ?? null,
+      };
+    }
+
+    // Try original case as fallback
+    if (senderEmail !== senderEmail.toLowerCase()) {
+      const fallback = await this.userProfileRepository.getByEmail(senderEmail);
+      if (fallback) {
+        return {
+          auth0Sub: fallback.auth0Sub,
+          email: fallback.email,
+          displayName: fallback.displayName ?? null,
+        };
+      }
+    }
+
+    return null;
+  }
+
+  // ========================
+  // Attachment Handling
+  // ========================
+
+  /**
+   * Get attachments from webhook data or by fetching the raw email
+   */
+  private async getAttachments(
+    emailId: string,
+    event: ResendWebhookEvent
+  ): Promise<ParsedEmailAttachment[]> {
+    // If webhook includes attachments with content, use those
+    if (event.data.attachments && event.data.attachments.length > 0) {
+      return event.data.attachments.map(att => ({
+        filename: att.filename,
+        contentType: att.content_type,
+        content: Buffer.from(att.content, 'base64'),
+        size: Buffer.from(att.content, 'base64').length,
+      }));
+    }
+
+    // Otherwise fetch and parse the raw email
+    try {
+      const { downloadUrl } = await this.resendClient.getEmail(emailId);
+      const rawEmail = await this.resendClient.downloadRawEmail(downloadUrl);
+      const parsed = await this.resendClient.parseEmail(rawEmail);
+      return parsed.attachments;
+    } catch (error) {
+      logger.warn('Failed to fetch raw email for attachments', {
+        emailId,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return [];
+    }
+  }
+
+  /**
+   * Filter attachments by supported type and size
+   */
+  private filterAttachments(attachments: ParsedEmailAttachment[]): ParsedEmailAttachment[] {
+    return attachments.filter(att => {
+      if (!SUPPORTED_ATTACHMENT_TYPES.has(att.contentType)) {
+        logger.info('Skipping unsupported attachment type', {
+          filename: att.filename,
+          contentType: att.contentType,
+        });
+        return false;
+      }
+
+      if (att.size > MAX_ATTACHMENT_SIZE) {
+        logger.info('Skipping oversized attachment', {
+          filename: att.filename,
+          size: att.size,
+          maxSize: MAX_ATTACHMENT_SIZE,
+        });
+        return false;
+      }
+
+      return true;
+    });
+  }
+
+  // ========================
+  // OCR Processing
+  // ========================
+
+  /**
+   * Process attachments using classifier-driven OCR extraction.
+   * If email text classification is confident, calls the specific OCR endpoint.
+   * If not, performs general OCR and classifies from rawText.
+   * Returns null if no usable result or receipt is unclassified.
+   */
+  private async processAttachmentsWithClassification(
+    userId: string,
+    attachments: ParsedEmailAttachment[],
+    emailClassification: { type: string; confidence: number },
+    emailId: string
+  ): Promise<{ response: ReceiptExtractionResponse; recordType: EmailRecordType } | null> {
+    const imageAttachments = attachments.filter(att => OCR_RECEIPT_IMAGE_TYPES.has(att.contentType));
+
+    for (const attachment of imageAttachments) {
+      // If email text gave a confident classification, call the specific OCR endpoint first
+      if (emailClassification.type === 'fuel') {
+        const result = await this.extractFuelReceipt(userId, attachment);
+        if (result?.success) return { response: result, recordType: 'fuel_log' };
+        // Fuel OCR failed, try maintenance as fallback
+        const fallbackResult = await this.extractMaintenanceReceipt(userId, attachment);
+        if (fallbackResult?.success) return { response: fallbackResult, recordType: 'maintenance_record' };
+        continue;
+      }
+
+      if (emailClassification.type === 'maintenance') {
+        const result = await this.extractMaintenanceReceipt(userId, attachment);
+        if (result?.success) return { response: result, recordType: 'maintenance_record' };
+        // Maintenance OCR failed, try fuel as fallback
+        const fallbackResult = await this.extractFuelReceipt(userId, attachment);
+        if (fallbackResult?.success) return { response: fallbackResult, recordType: 'fuel_log' };
+        continue;
+      }
+
+      // Email text was not confident - try both OCR endpoints and classify from rawText
+      const fuelResult = await this.extractFuelReceipt(userId, attachment);
+      const maintenanceResult = await this.extractMaintenanceReceipt(userId, attachment);
+
+      // Use rawText from whichever succeeded for secondary classification
+      const rawText = fuelResult?.rawText || maintenanceResult?.rawText || '';
+      if (rawText) {
+        const ocrClassification = this.classifier.classifyFromOcrRawText(rawText);
+        logger.info('OCR rawText classification result', {
+          emailId,
+          type: ocrClassification.type,
+          confidence: ocrClassification.confidence,
+        });
+
+        if (ocrClassification.type === 'fuel' && fuelResult?.success) {
+          return { response: fuelResult, recordType: 'fuel_log' };
+        }
+        if (ocrClassification.type === 'maintenance' && maintenanceResult?.success) {
+          return { response: maintenanceResult, recordType: 'maintenance_record' };
+        }
+      }
+
+      // Both classifiers failed - fall back to field-count heuristic
+      const fallback = this.selectBestResultByFields(fuelResult, maintenanceResult);
+      if (fallback) return fallback;
+    }
+
+    return null;
+  }
+
+  /**
+   * Extract fuel receipt via OCR. Returns null on failure.
+   */
+  private async extractFuelReceipt(
+    userId: string,
+    attachment: ParsedEmailAttachment
+  ): Promise<ReceiptExtractionResponse | null> {
+    try {
+      return await ocrService.extractReceipt(userId, {
+        fileBuffer: attachment.content,
+        contentType: attachment.contentType,
+        receiptType: 'fuel',
+      });
+    } catch (error) {
+      logger.info('Fuel receipt extraction failed', {
+        filename: attachment.filename,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return null;
+    }
+  }
+
+  /**
+   * Extract maintenance receipt via OCR. Returns null on failure.
+   */
+  private async extractMaintenanceReceipt(
+    userId: string,
+    attachment: ParsedEmailAttachment
+  ): Promise<ReceiptExtractionResponse | null> {
+    try {
+      return await ocrService.extractMaintenanceReceipt(userId, {
+        fileBuffer: attachment.content,
+        contentType: attachment.contentType,
+      });
+    } catch (error) {
+      logger.info('Maintenance receipt extraction failed', {
+        filename: attachment.filename,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return null;
+    }
+  }
+
+  /**
+   * Last-resort fallback: select the better OCR result based on domain-specific
+   * fields and field count when keyword classifiers could not decide.
+   */
+  private selectBestResultByFields(
+    fuelResult: ReceiptExtractionResponse | null,
+    maintenanceResult: ReceiptExtractionResponse | null
+  ): { response: ReceiptExtractionResponse; recordType: EmailRecordType } | null {
+    const fuelFieldCount = fuelResult?.success
+      ? Object.keys(fuelResult.extractedFields).length
+      : 0;
+    const maintenanceFieldCount = maintenanceResult?.success
+      ? Object.keys(maintenanceResult.extractedFields).length
+      : 0;
+
+    if (fuelFieldCount === 0 && maintenanceFieldCount === 0) {
+      return null;
+    }
+
+    const hasFuelFields = fuelResult?.extractedFields['gallons'] ||
+      fuelResult?.extractedFields['price_per_gallon'] ||
+      fuelResult?.extractedFields['fuel_type'];
+
+    const hasMaintenanceFields = maintenanceResult?.extractedFields['category'] ||
+      maintenanceResult?.extractedFields['shop_name'] ||
+      maintenanceResult?.extractedFields['description'];
+
+    if (hasFuelFields && !hasMaintenanceFields) {
+      return { response: fuelResult!, recordType: 'fuel_log' };
+    }
+    if (hasMaintenanceFields && !hasFuelFields) {
+      return { response: maintenanceResult!, recordType: 'maintenance_record' };
+    }
+
+    if (fuelFieldCount >= maintenanceFieldCount && fuelResult?.success) {
+      return { response: fuelResult, recordType: 'fuel_log' };
+    }
+    if (maintenanceResult?.success) {
+      return { response: maintenanceResult, recordType: 'maintenance_record' };
+    }
+
+    return null;
+  }
+
+  /**
+   * Map OCR extracted fields to our ExtractedReceiptData format
+   */
+  private mapOcrToExtractedData(response: ReceiptExtractionResponse): ExtractedReceiptData {
+    const fields = response.extractedFields;
+    const getFieldValue = (key: string): string | null =>
+      fields[key]?.value || null;
+    const getFieldNumber = (key: string): number | null => {
+      const val = fields[key]?.value;
+      if (!val) return null;
+      const num = parseFloat(val);
+      return isNaN(num) ? null : num;
+    };
+
+    return {
+      vendor: getFieldValue('vendor') || getFieldValue('shop_name'),
+      date: getFieldValue('date'),
+      total: getFieldNumber('total'),
+      odometerReading: getFieldNumber('odometer') || getFieldNumber('odometer_reading'),
+      gallons: getFieldNumber('gallons'),
+      pricePerGallon: getFieldNumber('price_per_gallon'),
+      fuelType: getFieldValue('fuel_type'),
+      category: getFieldValue('category'),
+      subtypes: fields['subtypes']?.value ? fields['subtypes'].value.split(',').map(s => s.trim()) : null,
+      shopName: getFieldValue('shop_name'),
+      description: getFieldValue('description'),
+    };
+  }
+
+  // ========================
+  // Vehicle Association
+  // ========================
+
+  /**
+   * Handle vehicle association based on user's vehicle count.
+   * No vehicles: send error email.
+   * Single vehicle: auto-associate and create record.
+   * Multiple vehicles: create pending association for user selection.
+   */
+  private async handleVehicleAssociation(
+    userId: string,
+    userName: string,
+    userEmail: string,
+    recordType: EmailRecordType,
+    extractedData: ExtractedReceiptData
+  ): Promise<EmailProcessingResult> {
+    const vehicles = await this.vehiclesRepository.findByUserId(userId);
+
+    // No vehicles: user must add a vehicle first
+    if (vehicles.length === 0) {
+      await this.notificationHandler.notifyNoVehicles(userId, userName, userEmail);
+      return {
+        recordType,
+        vehicleId: null,
+        recordId: null,
+        documentId: null,
+        pendingAssociationId: null,
+        extractedData,
+      };
+    }
+
+    // Single vehicle: auto-associate and create record
+    if (vehicles.length === 1) {
+      const vehicle = vehicles[0];
+      let recordId: string | null = null;
+
+      try {
+        recordId = await this.createRecord(userId, vehicle.id, recordType, extractedData);
+      } catch (error) {
+        logger.error('Failed to create record from email receipt', {
+          userId,
+          vehicleId: vehicle.id,
+          recordType,
+          error: error instanceof Error ? error.message : String(error),
+        });
+      }
+
+      const vehicleName = vehicle.nickname
+        || [vehicle.year, vehicle.make, vehicle.model].filter(Boolean).join(' ')
+        || 'your vehicle';
+
+      await this.notificationHandler.notifyReceiptProcessed({
+        userId,
+        userName,
+        userEmail,
+        vehicleName,
+        recordType,
+        recordId,
+        vehicleId: vehicle.id,
+        extractedData,
+      });
+
+      return {
+        recordType,
+        vehicleId: vehicle.id,
+        recordId,
+        documentId: null,
+        pendingAssociationId: null,
+        extractedData,
+      };
+    }
+
+    // Multiple vehicles: create pending association for user selection
+    const pendingAssociation = await this.repository.insertPendingAssociation({
+      userId,
+      recordType,
+      extractedData,
+      documentId: null,
+    });
+
+    await this.notificationHandler.notifyPendingVehicleSelection({
+      userId,
+      userName,
+      userEmail,
+      recordType,
+      pendingAssociationId: pendingAssociation.id,
+      extractedData,
+    });
+
+    return {
+      recordType,
+      vehicleId: null,
+      recordId: null,
+      documentId: null,
+      pendingAssociationId: pendingAssociation.id,
+      extractedData,
+    };
+  }
+
+  // ========================
+  // Public Resolution API
+  // ========================
+
+  /**
+   * Resolve a pending vehicle association by creating the record with the selected vehicle.
+   * Called from the user-facing API when a multi-vehicle user picks a vehicle.
+   */
+  async resolveAssociation(
+    associationId: string,
+    vehicleId: string,
+    userId: string
+  ): Promise<{ recordId: string; recordType: EmailRecordType }> {
+    const association = await this.repository.getPendingAssociationById(associationId);
+    if (!association) {
+      throw new Error('Pending association not found');
+    }
+    if (association.userId !== userId) {
+      throw new Error('Unauthorized');
+    }
+    if (association.status !== 'pending') {
+      throw new Error('Association already resolved');
+    }
+
+    // Verify vehicle belongs to user
+    const vehicles = await this.vehiclesRepository.findByUserId(userId);
+    const vehicle = vehicles.find(v => v.id === vehicleId);
+    if (!vehicle) {
+      throw new Error('Vehicle not found');
+    }
+
+    // Create the record
+    const recordId = await this.createRecord(userId, vehicleId, association.recordType, association.extractedData);
+
+    // Mark as resolved
+    await this.repository.resolvePendingAssociation(associationId, 'resolved');
+
+    logger.info('Pending association resolved', { associationId, vehicleId, userId, recordType: association.recordType, recordId });
+
+    return { recordId, recordType: association.recordType };
+  }
+
+  /**
+   * Dismiss a pending vehicle association without creating a record.
+   */
+  async dismissAssociation(associationId: string, userId: string): Promise<void> {
+    const association = await this.repository.getPendingAssociationById(associationId);
+    if (!association) {
+      throw new Error('Pending association not found');
+    }
+    if (association.userId !== userId) {
+      throw new Error('Unauthorized');
+    }
+    if (association.status !== 'pending') {
+      throw new Error('Association already resolved');
+    }
+
+    await this.repository.resolvePendingAssociation(associationId, 'expired');
+    logger.info('Pending association dismissed', { associationId, userId });
+  }
+
+  // ========================
+  // Record Creation
+  // ========================
+
+  /**
+   * Create a fuel log or maintenance record from extracted receipt data.
+   * Returns the created record ID.
+   */
+  private async createRecord(
+    userId: string,
+    vehicleId: string,
+    recordType: EmailRecordType,
+    extractedData: ExtractedReceiptData
+  ): Promise<string> {
+    if (recordType === 'fuel_log') {
+      return this.createFuelLogRecord(userId, vehicleId, extractedData);
+    }
+    return this.createMaintenanceRecord(userId, vehicleId, extractedData);
+  }
+
+  /**
+   * Map extracted receipt data to EnhancedCreateFuelLogRequest and create fuel log.
+   */
+  private async createFuelLogRecord(
+    userId: string,
+    vehicleId: string,
+    data: ExtractedReceiptData
+  ): Promise<string> {
+    const fuelUnits = data.gallons ?? 0;
+    const costPerUnit = data.pricePerGallon ?? (data.total && fuelUnits > 0 ? data.total / fuelUnits : 0);
+
+    const request: EnhancedCreateFuelLogRequest = {
+      vehicleId,
+      dateTime: data.date || new Date().toISOString(),
+      fuelType: this.mapFuelType(data.fuelType),
+      fuelUnits,
+      costPerUnit,
+      odometerReading: data.odometerReading ?? undefined,
+      locationData: data.vendor ? { stationName: data.vendor } : undefined,
+      notes: 'Created from emailed receipt',
+    };
+
+    logger.info('Creating fuel log from email receipt', { userId, vehicleId, fuelUnits, costPerUnit });
+    const result = await this.fuelLogsService.createFuelLog(request, userId);
+    return result.id;
+  }
+
+  /**
+   * Map extracted receipt data to CreateMaintenanceRecordRequest and create maintenance record.
+   */
+  private async createMaintenanceRecord(
+    userId: string,
+    vehicleId: string,
+    data: ExtractedReceiptData
+  ): Promise<string> {
+    const category = this.mapMaintenanceCategory(data.category);
+    const subtypes = this.resolveMaintenanceSubtypes(category, data.subtypes);
+
+    const record = await this.maintenanceService.createRecord(userId, {
+      vehicleId,
+      category,
+      subtypes,
+      date: data.date || new Date().toISOString().split('T')[0],
+      odometerReading: data.odometerReading ?? undefined,
+      cost: data.total ?? undefined,
+      shopName: data.shopName || data.vendor || undefined,
+      notes: data.description
+        ? `${data.description}\n\nCreated from emailed receipt`
+        : 'Created from emailed receipt',
+    });
+
+    logger.info('Created maintenance record from email receipt', { userId, vehicleId, recordId: record.id, category });
+    return record.id;
+  }
+
+  /**
+   * Map OCR fuel type string to FuelType enum. Defaults to gasoline.
+   */
+  private mapFuelType(fuelTypeStr: string | null): FuelType {
+    if (!fuelTypeStr) return FuelType.GASOLINE;
+
+    const normalized = fuelTypeStr.toLowerCase().trim();
+    if (normalized.includes('diesel') || normalized === '#1' || normalized === '#2') {
+      return FuelType.DIESEL;
+    }
+    if (normalized.includes('electric') || normalized.includes('ev')) {
+      return FuelType.ELECTRIC;
+    }
+    return FuelType.GASOLINE;
+  }
+
+  /**
+   * Map OCR category string to MaintenanceCategory. Defaults to routine_maintenance.
+   */
+  private mapMaintenanceCategory(categoryStr: string | null): MaintenanceCategory {
+    if (!categoryStr) return 'routine_maintenance';
+
+    const normalized = categoryStr.toLowerCase().trim();
+    if (normalized.includes('repair')) return 'repair';
+    if (normalized.includes('performance') || normalized.includes('upgrade')) return 'performance_upgrade';
+    return 'routine_maintenance';
+  }
+
+  /**
+   * Validate and resolve maintenance subtypes. Falls back to first valid
+   * subtype for the category if OCR subtypes are invalid or missing.
+   */
+  private resolveMaintenanceSubtypes(
+    category: MaintenanceCategory,
+    ocrSubtypes: string[] | null
+  ): string[] {
+    if (ocrSubtypes && ocrSubtypes.length > 0 && validateSubtypes(category, ocrSubtypes)) {
+      return ocrSubtypes;
+    }
+
+    // Attempt to match OCR subtypes against valid options (case-insensitive)
+    if (ocrSubtypes && ocrSubtypes.length > 0) {
+      const validOptions = getSubtypesForCategory(category);
+      const matched = ocrSubtypes
+        .map(s => validOptions.find(v => v.toLowerCase() === s.toLowerCase().trim()))
+        .filter((v): v is string => v !== undefined);
+      if (matched.length > 0) return matched;
+    }
+
+    // Default to first subtype of category
+    const defaults = getSubtypesForCategory(category);
+    return [defaults[0] as string];
+  }
+
+  // ========================
+  // Error Handling & Retries
+  // ========================
+
+  private async handleProcessingError(
+    emailId: string,
+    senderEmail: string,
+    _subject: string | null,
+    error: unknown
+  ): Promise<void> {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    logger.error('Email processing pipeline error', { emailId, error: errorMessage });
+
+    // Get current queue entry for retry count and userId
+    const queueEntry = await this.repository.getQueueEntry(emailId);
+    const currentRetryCount = queueEntry?.retryCount || 0;
+    const newRetryCount = currentRetryCount + 1;
+
+    if (newRetryCount < MAX_RETRY_COUNT) {
+      // Mark for retry
+      await this.repository.updateQueueStatus(emailId, 'failed', {
+        errorMessage,
+        retryCount: newRetryCount,
+      });
+
+      logger.info('Email queued for retry', {
+        emailId,
+        retryCount: newRetryCount,
+        maxRetries: MAX_RETRY_COUNT,
+      });
+    } else {
+      // Max retries exceeded - permanently failed
+      await this.repository.updateQueueStatus(emailId, 'failed', {
+        errorMessage: `Max retries (${MAX_RETRY_COUNT}) exceeded. Last error: ${errorMessage}`,
+        retryCount: newRetryCount,
+      });
+
+      // Send failure notification (email + in-app if userId available)
+      await this.notificationHandler.notifyProcessingFailure({
+        userId: queueEntry?.userId,
+        userEmail: senderEmail,
+        errorReason: errorMessage,
+      }).catch(notifyErr => {
+        logger.error('Failed to send failure notification', {
+          emailId,
+          error: notifyErr instanceof Error ? notifyErr.message : String(notifyErr),
+        });
+      });
+    }
+  }
+
+  private async handleUnregisteredSender(
+    emailId: string,
+    senderEmail: string
+  ): Promise<void> {
+    logger.info('Unregistered sender rejected', { emailId, senderEmail });
+
+    await this.repository.updateQueueStatus(emailId, 'failed', {
+      errorMessage: 'Sender email is not registered with MotoVaultPro',
+    });
+
+    await this.notificationHandler.notifyUnregisteredSender(senderEmail).catch(error => {
+      logger.error('Failed to send unregistered sender notification', {
+        emailId,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    });
+  }
+
+  private async handleNoValidAttachments(
+    emailId: string,
+    userId: string,
+    userName: string,
+    userEmail: string
+  ): Promise<void> {
+    logger.info('No valid attachments found', { emailId });
+
+    await this.repository.updateQueueStatus(emailId, 'failed', {
+      errorMessage: 'No valid attachments found. Supported types: PDF, PNG, JPG, JPEG, HEIC (max 10MB each)',
+    });
+
+    await this.notificationHandler.notifyNoValidAttachments(userId, userName, userEmail).catch(error => {
+      logger.error('Failed to send no-attachments notification', {
+        emailId,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    });
+  }
+
+  private async handleOcrFailure(
+    emailId: string,
+    userId: string,
+    userName: string,
+    userEmail: string,
+    reason: string
+  ): Promise<void> {
+    logger.info('OCR extraction failed for all attachments', { emailId, reason });
+
+    await this.repository.updateQueueStatus(emailId, 'failed', {
+      errorMessage: reason,
+    });
+
+    await this.notificationHandler.notifyOcrFailure(userId, userName, userEmail, reason).catch(error => {
+      logger.error('Failed to send OCR failure notification', {
+        emailId,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    });
+  }
+}
--- a/backend/src/features/email-ingestion/domain/email-ingestion.types.ts
+++ b/backend/src/features/email-ingestion/domain/email-ingestion.types.ts
@@ -0,0 +1,114 @@
+/**
+ * @ai-summary TypeScript types for the email ingestion feature
+ * @ai-context Covers database records, status enums, and Resend webhook payloads
+ */
+
+// ========================
+// Status Enums
+// ========================
+
+export type EmailIngestionStatus = 'pending' | 'processing' | 'completed' | 'failed';
+
+export type PendingAssociationStatus = 'pending' | 'resolved' | 'expired';
+
+export type EmailRecordType = 'fuel_log' | 'maintenance_record';
+
+// ========================
+// Receipt Classification
+// ========================
+
+export type ReceiptClassificationType = 'fuel' | 'maintenance' | 'unclassified';
+
+export interface ClassificationResult {
+  type: ReceiptClassificationType;
+  confidence: number;
+}
+
+// ========================
+// Database Records
+// ========================
+
+export interface EmailIngestionQueueRecord {
+  id: string;
+  emailId: string;
+  senderEmail: string;
+  userId: string;
+  receivedAt: string;
+  subject: string | null;
+  status: EmailIngestionStatus;
+  processingResult: EmailProcessingResult | null;
+  errorMessage: string | null;
+  retryCount: number;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface PendingVehicleAssociation {
+  id: string;
+  userId: string;
+  recordType: EmailRecordType;
+  extractedData: ExtractedReceiptData;
+  documentId: string | null;
+  status: PendingAssociationStatus;
+  createdAt: string;
+  resolvedAt: string | null;
+}
+
+// ========================
+// Processing Results
+// ========================
+
+export interface EmailProcessingResult {
+  recordType: EmailRecordType;
+  vehicleId: string | null;
+  recordId: string | null;
+  documentId: string | null;
+  pendingAssociationId: string | null;
+  extractedData: ExtractedReceiptData;
+}
+
+export interface ExtractedReceiptData {
+  vendor: string | null;
+  date: string | null;
+  total: number | null;
+  odometerReading: number | null;
+  /** Fuel-specific fields */
+  gallons: number | null;
+  pricePerGallon: number | null;
+  fuelType: string | null;
+  /** Maintenance-specific fields */
+  category: string | null;
+  subtypes: string[] | null;
+  shopName: string | null;
+  description: string | null;
+}
+
+// ========================
+// Resend Webhook Payloads
+// ========================
+
+/** Top-level Resend webhook event envelope */
+export interface ResendWebhookEvent {
+  type: string;
+  created_at: string;
+  data: ResendWebhookEventData;
+}
+
+/** Resend email.received webhook event data */
+export interface ResendWebhookEventData {
+  email_id: string;
+  from: string;
+  to: string[];
+  subject: string;
+  text: string | null;
+  html: string | null;
+  created_at: string;
+  attachments: ResendEmailAttachment[];
+}
+
+/** Attachment metadata from Resend inbound email */
+export interface ResendEmailAttachment {
+  filename: string;
+  content_type: string;
+  content: string;
+}
--- a/backend/src/features/email-ingestion/domain/notification-handler.ts
+++ b/backend/src/features/email-ingestion/domain/notification-handler.ts
@@ -0,0 +1,333 @@
+/**
+ * @ai-summary Notification handler for the email ingestion pipeline
+ * @ai-context Encapsulates all email replies, in-app notifications, and notification logging
+ *   for the email-to-record flow. Every email sent is logged to notification_logs.
+ */
+
+import { logger } from '../../../core/logging/logger';
+import { NotificationsRepository } from '../../notifications/data/notifications.repository';
+import { TemplateService } from '../../notifications/domain/template.service';
+import { EmailService } from '../../notifications/domain/email.service';
+import type { TemplateKey } from '../../notifications/domain/notifications.types';
+import type { EmailRecordType, ExtractedReceiptData } from './email-ingestion.types';
+
+export class EmailIngestionNotificationHandler {
+  constructor(
+    private notificationsRepository: NotificationsRepository,
+    private templateService: TemplateService,
+    private emailService: EmailService,
+  ) {}
+
+  // ========================
+  // Success Notifications
+  // ========================
+
+  /**
+   * Notify user that their emailed receipt was successfully processed.
+   * Sends confirmation email + creates in-app notification + logs to notification_logs.
+   */
+  async notifyReceiptProcessed(params: {
+    userId: string;
+    userName: string;
+    userEmail: string;
+    vehicleName: string;
+    recordType: EmailRecordType;
+    recordId: string | null;
+    vehicleId: string;
+    extractedData: ExtractedReceiptData;
+  }): Promise<void> {
+    const { userId, userName, userEmail, vehicleName, recordType, recordId, vehicleId, extractedData } = params;
+    const recordLabel = recordType === 'fuel_log' ? 'Fuel Log' : 'Maintenance Record';
+    const merchantName = extractedData.vendor || extractedData.shopName || 'Unknown';
+
+    // In-app notification
+    const message = recordId
+      ? `Your emailed ${recordLabel.toLowerCase()} receipt from ${merchantName} has been processed and recorded for ${vehicleName}.`
+      : `Your emailed ${recordLabel.toLowerCase()} receipt from ${merchantName} was processed but the record could not be created automatically. Please add it manually.`;
+
+    await this.notificationsRepository.insertUserNotification({
+      userId,
+      notificationType: 'email_ingestion',
+      title: recordId ? 'Receipt Processed' : 'Receipt Partially Processed',
+      message,
+      referenceType: recordType,
+      referenceId: recordId ?? undefined,
+      vehicleId,
+    });
+
+    // Confirmation email
+    await this.sendTemplateEmail({
+      templateKey: 'receipt_processed',
+      userId,
+      userEmail,
+      variables: {
+        userName,
+        vehicleName,
+        recordType: recordLabel,
+        merchantName,
+        totalAmount: extractedData.total?.toFixed(2) || 'N/A',
+        date: extractedData.date || 'N/A',
+      },
+      referenceType: 'email_ingestion',
+      referenceId: recordId ?? undefined,
+    });
+  }
+
+  // ========================
+  // Pending Vehicle Notification
+  // ========================
+
+  /**
+   * Notify multi-vehicle user that their receipt needs vehicle selection.
+   * Sends pending-vehicle email + creates in-app notification + logs to notification_logs.
+   */
+  async notifyPendingVehicleSelection(params: {
+    userId: string;
+    userName: string;
+    userEmail: string;
+    recordType: EmailRecordType;
+    pendingAssociationId: string;
+    extractedData: ExtractedReceiptData;
+  }): Promise<void> {
+    const { userId, userName, userEmail, recordType, pendingAssociationId, extractedData } = params;
+    const recordLabel = recordType === 'fuel_log' ? 'Fuel Log' : 'Maintenance Record';
+    const merchantName = extractedData.vendor || extractedData.shopName || 'Unknown';
+
+    // In-app notification
+    await this.notificationsRepository.insertUserNotification({
+      userId,
+      notificationType: 'email_ingestion',
+      title: 'Vehicle Selection Required',
+      message: `Your emailed receipt from ${merchantName} has been processed. Please select which vehicle this ${recordLabel.toLowerCase()} belongs to.`,
+      referenceType: 'pending_vehicle_association',
+      referenceId: pendingAssociationId,
+    });
+
+    // Pending vehicle email
+    await this.sendTemplateEmail({
+      templateKey: 'receipt_pending_vehicle',
+      userId,
+      userEmail,
+      variables: {
+        userName,
+        recordType: recordLabel,
+        merchantName,
+        totalAmount: extractedData.total?.toFixed(2) || 'N/A',
+        date: extractedData.date || 'N/A',
+      },
+      referenceType: 'email_ingestion',
+      referenceId: pendingAssociationId,
+    });
+  }
+
+  // ========================
+  // Error Notifications
+  // ========================
+
+  /**
+   * Notify unregistered sender that their email was rejected.
+   * Email reply only (no in-app notification since no user account).
+   */
+  async notifyUnregisteredSender(userEmail: string): Promise<void> {
+    await this.sendTemplateEmail({
+      templateKey: 'receipt_failed',
+      userEmail,
+      variables: {
+        userName: 'MotoVaultPro User',
+        errorReason: 'This email address is not registered with MotoVaultPro.',
+        guidance: 'Please send receipts from the email address associated with your account. You can check your registered email in your MotoVaultPro profile settings.',
+      },
+      referenceType: 'email_ingestion',
+    });
+  }
+
+  /**
+   * Notify user that they must add a vehicle before emailing receipts.
+   * Sends error email + creates in-app notification + logs to notification_logs.
+   */
+  async notifyNoVehicles(userId: string, userName: string, userEmail: string): Promise<void> {
+    // In-app notification
+    await this.notificationsRepository.insertUserNotification({
+      userId,
+      notificationType: 'email_ingestion',
+      title: 'Receipt Processing Failed',
+      message: 'Your emailed receipt could not be processed because you have no vehicles registered. Please add a vehicle first, then re-send your receipt.',
+    });
+
+    // Error email
+    await this.sendTemplateEmail({
+      templateKey: 'receipt_failed',
+      userId,
+      userEmail,
+      variables: {
+        userName,
+        errorReason: 'You do not have any vehicles registered in MotoVaultPro.',
+        guidance: 'Please add a vehicle first in the MotoVaultPro app, then re-send your receipt.',
+      },
+      referenceType: 'email_ingestion',
+    });
+  }
+
+  /**
+   * Notify user that no valid attachments were found in their email.
+   * Sends error email + creates in-app notification + logs to notification_logs.
+   */
+  async notifyNoValidAttachments(userId: string, userName: string, userEmail: string): Promise<void> {
+    // In-app notification
+    await this.notificationsRepository.insertUserNotification({
+      userId,
+      notificationType: 'email_ingestion',
+      title: 'Receipt Processing Failed',
+      message: 'No valid attachments were found in your email. Please attach receipt images (PNG, JPG, JPEG, HEIC) or PDFs under 10MB.',
+    });
+
+    // Error email
+    await this.sendTemplateEmail({
+      templateKey: 'receipt_failed',
+      userId,
+      userEmail,
+      variables: {
+        userName,
+        errorReason: 'No valid attachments were found in your email.',
+        guidance: 'Please attach receipt images (PNG, JPG, JPEG, HEIC) or PDFs under 10MB. Make sure your receipt is clearly visible in the image.',
+      },
+      referenceType: 'email_ingestion',
+    });
+  }
+
+  /**
+   * Notify user that OCR extraction failed after all attempts.
+   * Sends error email + creates in-app notification + logs to notification_logs.
+   */
+  async notifyOcrFailure(userId: string, userName: string, userEmail: string, reason: string): Promise<void> {
+    // In-app notification
+    await this.notificationsRepository.insertUserNotification({
+      userId,
+      notificationType: 'email_ingestion',
+      title: 'Receipt Processing Failed',
+      message: `We could not extract data from your receipt: ${reason}`,
+    });
+
+    // Error email
+    await this.sendTemplateEmail({
+      templateKey: 'receipt_failed',
+      userId,
+      userEmail,
+      variables: {
+        userName,
+        errorReason: reason,
+        guidance: 'Please try again with a clearer image or PDF. Tips: use a well-lit, high-contrast photo; ensure text is legible and not cut off; PDF receipts work best.',
+      },
+      referenceType: 'email_ingestion',
+    });
+  }
+
+  /**
+   * Notify user of a general processing failure (after max retries exceeded).
+   * Sends error email + creates in-app notification (if userId available) + logs.
+   */
+  async notifyProcessingFailure(params: {
+    userId?: string;
+    userName?: string;
+    userEmail: string;
+    errorReason: string;
+  }): Promise<void> {
+    const { userId, userName, userEmail, errorReason } = params;
+
+    // In-app notification (only if we have a userId)
+    if (userId) {
+      await this.notificationsRepository.insertUserNotification({
+        userId,
+        notificationType: 'email_ingestion',
+        title: 'Receipt Processing Failed',
+        message: `Your emailed receipt could not be processed: ${errorReason}`,
+      });
+    }
+
+    // Error email
+    await this.sendTemplateEmail({
+      templateKey: 'receipt_failed',
+      userId,
+      userEmail,
+      variables: {
+        userName: userName || 'MotoVaultPro User',
+        errorReason,
+        guidance: 'Please try again or upload the receipt directly through the MotoVaultPro app.',
+      },
+      referenceType: 'email_ingestion',
+    });
+  }
+
+  // ========================
+  // Internal Helpers
+  // ========================
+
+  /**
+   * Send a templated email and log to notification_logs.
+   * Swallows errors to prevent notification failures from breaking the pipeline.
+   */
+  private async sendTemplateEmail(params: {
+    templateKey: TemplateKey;
+    userId?: string;
+    userEmail: string;
+    variables: Record<string, string | number | boolean | null | undefined>;
+    referenceType?: string;
+    referenceId?: string;
+  }): Promise<void> {
+    const { templateKey, userId, userEmail, variables, referenceType, referenceId } = params;
+
+    try {
+      const template = await this.notificationsRepository.getEmailTemplateByKey(templateKey);
+      if (!template || !template.isActive) {
+        logger.warn('Email template not found or inactive', { templateKey });
+        return;
+      }
+
+      const renderedSubject = this.templateService.render(template.subject, variables);
+      const renderedHtml = this.templateService.renderEmailHtml(template.body, variables);
+
+      await this.emailService.send(userEmail, renderedSubject, renderedHtml);
+
+      // Log successful send
+      if (userId) {
+        await this.notificationsRepository.insertNotificationLog({
+          user_id: userId,
+          notification_type: 'email',
+          template_key: templateKey,
+          recipient_email: userEmail,
+          subject: renderedSubject,
+          reference_type: referenceType,
+          reference_id: referenceId,
+          status: 'sent',
+        });
+      }
+
+      logger.info('Email ingestion notification sent', { templateKey, userEmail });
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      logger.error('Failed to send email ingestion notification', {
+        templateKey,
+        userEmail,
+        error: errorMessage,
+      });
+
+      // Log failed send
+      if (userId) {
+        await this.notificationsRepository.insertNotificationLog({
+          user_id: userId,
+          notification_type: 'email',
+          template_key: templateKey,
+          recipient_email: userEmail,
+          reference_type: referenceType,
+          reference_id: referenceId,
+          status: 'failed',
+          error_message: errorMessage,
+        }).catch(logErr => {
+          logger.error('Failed to log notification failure', {
+            error: logErr instanceof Error ? logErr.message : String(logErr),
+          });
+        });
+      }
+    }
+  }
+}
--- a/backend/src/features/email-ingestion/domain/receipt-classifier.ts
+++ b/backend/src/features/email-ingestion/domain/receipt-classifier.ts
@@ -0,0 +1,130 @@
+/**
+ * @ai-summary Classifies receipt type from email text or OCR raw text
+ * @ai-context Uses keyword matching to determine fuel vs maintenance receipts
+ *   before falling back to OCR-based classification. Returns confidence score.
+ */
+
+import { logger } from '../../../core/logging/logger';
+import type { ClassificationResult, ReceiptClassificationType } from './email-ingestion.types';
+
+/** Fuel-related keywords (case-insensitive matching) */
+const FUEL_KEYWORDS: string[] = [
+  'gas',
+  'fuel',
+  'gallons',
+  'octane',
+  'pump',
+  'diesel',
+  'unleaded',
+  'shell',
+  'chevron',
+  'exxon',
+  'bp',
+];
+
+/** Maintenance-related keywords (case-insensitive matching). Multi-word entries matched as phrases. */
+const MAINTENANCE_KEYWORDS: string[] = [
+  'oil change',
+  'brake',
+  'alignment',
+  'tire',
+  'rotation',
+  'inspection',
+  'labor',
+  'parts',
+  'service',
+  'repair',
+  'transmission',
+  'coolant',
+];
+
+/** Minimum keyword matches required for a confident classification */
+const CONFIDENCE_THRESHOLD = 2;
+
+export class ReceiptClassifier {
+  /**
+   * Classify receipt type from email subject and body text.
+   * Returns a confident result if >= 2 keyword matches for one type.
+   */
+  classifyFromText(subject: string | null, body: string | null): ClassificationResult {
+    const text = [subject || '', body || ''].join(' ');
+    return this.classifyText(text, 'email');
+  }
+
+  /**
+   * Classify receipt type from OCR raw text output.
+   * Uses same keyword matching as email text classification.
+   */
+  classifyFromOcrRawText(rawText: string): ClassificationResult {
+    return this.classifyText(rawText, 'ocr');
+  }
+
+  /**
+   * Core keyword matching logic shared by email and OCR classification.
+   */
+  private classifyText(text: string, source: 'email' | 'ocr'): ClassificationResult {
+    const normalizedText = text.toLowerCase();
+
+    const fuelMatches = this.countKeywordMatches(normalizedText, FUEL_KEYWORDS);
+    const maintenanceMatches = this.countKeywordMatches(normalizedText, MAINTENANCE_KEYWORDS);
+
+    logger.info('Receipt classification keyword analysis', {
+      source,
+      fuelMatches,
+      maintenanceMatches,
+      textLength: text.length,
+    });
+
+    // Both below threshold - unclassified
+    if (fuelMatches < CONFIDENCE_THRESHOLD && maintenanceMatches < CONFIDENCE_THRESHOLD) {
+      return { type: 'unclassified', confidence: 0 };
+    }
+
+    // Clear winner with threshold met
+    if (fuelMatches >= CONFIDENCE_THRESHOLD && fuelMatches > maintenanceMatches) {
+      return {
+        type: 'fuel',
+        confidence: Math.min(fuelMatches / (fuelMatches + maintenanceMatches), 1),
+      };
+    }
+
+    if (maintenanceMatches >= CONFIDENCE_THRESHOLD && maintenanceMatches > fuelMatches) {
+      return {
+        type: 'maintenance',
+        confidence: Math.min(maintenanceMatches / (fuelMatches + maintenanceMatches), 1),
+      };
+    }
+
+    // Tie with both meeting threshold - unclassified (ambiguous)
+    if (fuelMatches >= CONFIDENCE_THRESHOLD && maintenanceMatches >= CONFIDENCE_THRESHOLD) {
+      return { type: 'unclassified', confidence: 0 };
+    }
+
+    return { type: 'unclassified', confidence: 0 };
+  }
+
+  /**
+   * Count how many keywords from the list appear in the text.
+   * Multi-word keywords are matched as phrases.
+   */
+  private countKeywordMatches(normalizedText: string, keywords: string[]): number {
+    let matches = 0;
+    for (const keyword of keywords) {
+      if (normalizedText.includes(keyword)) {
+        matches++;
+      }
+    }
+    return matches;
+  }
+
+  /**
+   * Map classifier type to the EmailRecordType used in the processing pipeline.
+   */
+  static toRecordType(classificationType: ReceiptClassificationType): 'fuel_log' | 'maintenance_record' | null {
+    switch (classificationType) {
+      case 'fuel': return 'fuel_log';
+      case 'maintenance': return 'maintenance_record';
+      case 'unclassified': return null;
+    }
+  }
+}
--- a/backend/src/features/email-ingestion/external/resend-inbound.client.ts
+++ b/backend/src/features/email-ingestion/external/resend-inbound.client.ts
@@ -0,0 +1,110 @@
+/**
+ * @ai-summary Resend inbound email client for webhook verification and email parsing
+ * @ai-context Verifies Resend webhook signatures via Svix, fetches raw emails, parses with mailparser
+ */
+
+import { Webhook } from 'svix';
+import { simpleParser } from 'mailparser';
+import { logger } from '../../../core/logging/logger';
+import type { ResendWebhookEvent } from '../domain/email-ingestion.types';
+
+export interface ParsedEmailResult {
+  text: string | null;
+  html: string | null;
+  attachments: ParsedEmailAttachment[];
+}
+
+export interface ParsedEmailAttachment {
+  filename: string;
+  contentType: string;
+  content: Buffer;
+  size: number;
+}
+
+export class ResendInboundClient {
+  private webhookSecret: string | undefined;
+  private apiKey: string;
+
+  constructor() {
+    this.apiKey = process.env['RESEND_API_KEY'] || '';
+    this.webhookSecret = process.env['RESEND_WEBHOOK_SECRET'];
+  }
+
+  /**
+   * Verify Resend webhook signature using Svix
+   * @throws Error if signature is invalid or secret is not configured
+   */
+  verifyWebhookSignature(rawBody: string | Buffer, headers: Record<string, string>): ResendWebhookEvent {
+    if (!this.webhookSecret) {
+      throw new Error('RESEND_WEBHOOK_SECRET is not configured');
+    }
+
+    const wh = new Webhook(this.webhookSecret);
+    const verified = wh.verify(
+      typeof rawBody === 'string' ? rawBody : rawBody.toString(),
+      {
+        'svix-id': headers['svix-id'] || '',
+        'svix-timestamp': headers['svix-timestamp'] || '',
+        'svix-signature': headers['svix-signature'] || '',
+      }
+    );
+
+    return verified as unknown as ResendWebhookEvent;
+  }
+
+  /**
+   * Fetch email metadata from Resend API including raw download URL
+   */
+  async getEmail(emailId: string): Promise<{ downloadUrl: string }> {
+    const response = await fetch(`https://api.resend.com/emails/${emailId}`, {
+      headers: { 'Authorization': `Bearer ${this.apiKey}` },
+    });
+
+    if (!response.ok) {
+      throw new Error(`Failed to fetch email ${emailId}: ${response.status} ${response.statusText}`);
+    }
+
+    const data = await response.json() as { raw?: { download_url?: string } };
+    const downloadUrl = data.raw?.download_url;
+
+    if (!downloadUrl) {
+      throw new Error(`No download URL for email ${emailId}`);
+    }
+
+    logger.info('Fetched email metadata from Resend', { emailId });
+    return { downloadUrl };
+  }
+
+  /**
+   * Download raw RFC 5322 email content from Resend download URL
+   */
+  async downloadRawEmail(downloadUrl: string): Promise<string> {
+    const response = await fetch(downloadUrl);
+
+    if (!response.ok) {
+      throw new Error(`Failed to download raw email: ${response.status} ${response.statusText}`);
+    }
+
+    const rawEmail = await response.text();
+    logger.info('Downloaded raw email', { size: rawEmail.length });
+    return rawEmail;
+  }
+
+  /**
+   * Parse raw RFC 5322 email into structured text/html body and attachments
+   */
+  async parseEmail(rawEmail: string): Promise<ParsedEmailResult> {
+    const parsed = await simpleParser(rawEmail);
+
+    return {
+      text: parsed.text || null,
+      html: typeof parsed.html === 'string' ? parsed.html : null,
+      attachments: (parsed.attachments || []).map((att) => ({
+        filename: att.filename || 'unnamed',
+        contentType: att.contentType || 'application/octet-stream',
+        content: att.content,
+        size: att.size,
+      })),
+    };
+  }
+}
--- a/backend/src/features/email-ingestion/index.ts
+++ b/backend/src/features/email-ingestion/index.ts
@@ -0,0 +1,22 @@
+/**
+ * @ai-summary Email ingestion feature barrel export
+ * @ai-context Exports webhook routes, services, and types for Resend inbound email processing
+ */
+
+export { emailIngestionWebhookRoutes, emailIngestionRoutes } from './api/email-ingestion.routes';
+export { EmailIngestionService } from './domain/email-ingestion.service';
+export { EmailIngestionRepository } from './data/email-ingestion.repository';
+export { ReceiptClassifier } from './domain/receipt-classifier';
+export { ResendInboundClient } from './external/resend-inbound.client';
+export type { ParsedEmailResult, ParsedEmailAttachment } from './external/resend-inbound.client';
+export type {
+  ClassificationResult,
+  EmailIngestionQueueRecord,
+  EmailIngestionStatus,
+  EmailProcessingResult,
+  ExtractedReceiptData,
+  PendingVehicleAssociation,
+  ReceiptClassificationType,
+  ResendWebhookEvent,
+  ResendWebhookEventData,
+} from './domain/email-ingestion.types';
--- a/backend/src/features/email-ingestion/migrations/001_create_email_ingestion_tables.sql
+++ b/backend/src/features/email-ingestion/migrations/001_create_email_ingestion_tables.sql
@@ -0,0 +1,71 @@
+/**
+ * Migration: Create email ingestion tables
+ * @ai-summary Creates email_ingestion_queue and pending_vehicle_associations tables
+ * @ai-context Supports inbound email receipt processing via Resend webhooks
+ */
+
+-- email_ingestion_queue: Tracks inbound emails from Resend webhooks
+CREATE TABLE IF NOT EXISTS email_ingestion_queue (
+  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+  email_id VARCHAR(255) NOT NULL,
+  sender_email VARCHAR(255) NOT NULL,
+  user_id VARCHAR(255) NOT NULL,
+  received_at TIMESTAMP WITH TIME ZONE NOT NULL,
+  subject VARCHAR(500),
+  status VARCHAR(20) NOT NULL DEFAULT 'pending' CHECK (status IN (
+    'pending', 'processing', 'completed', 'failed'
+  )),
+  processing_result JSONB,
+  error_message TEXT,
+  retry_count INTEGER NOT NULL DEFAULT 0,
+  created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
+);
+
+-- Unique constraint on email_id to prevent duplicate processing
+ALTER TABLE email_ingestion_queue
+  ADD CONSTRAINT uq_email_ingestion_queue_email_id UNIQUE (email_id);
+
+-- Trigger for updated_at (reuses update_updated_at_column() from vehicles feature)
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_trigger WHERE tgname = 'set_timestamp_email_ingestion_queue'
+  ) THEN
+    CREATE TRIGGER set_timestamp_email_ingestion_queue
+    BEFORE UPDATE ON email_ingestion_queue
+    FOR EACH ROW
+    EXECUTE FUNCTION update_updated_at_column();
+  END IF;
+END $$;
+
+-- Indexes
+CREATE INDEX IF NOT EXISTS idx_email_ingestion_queue_user_id ON email_ingestion_queue(user_id);
+CREATE INDEX IF NOT EXISTS idx_email_ingestion_queue_status ON email_ingestion_queue(status);
+CREATE INDEX IF NOT EXISTS idx_email_ingestion_queue_sender ON email_ingestion_queue(sender_email);
+CREATE INDEX IF NOT EXISTS idx_email_ingestion_queue_received_at ON email_ingestion_queue(received_at DESC);
+
+-- pending_vehicle_associations: Holds records needing vehicle selection (multi-vehicle users)
+CREATE TABLE IF NOT EXISTS pending_vehicle_associations (
+  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+  user_id VARCHAR(255) NOT NULL,
+  record_type VARCHAR(30) NOT NULL CHECK (record_type IN (
+    'fuel_log', 'maintenance_record'
+  )),
+  extracted_data JSONB NOT NULL,
+  document_id UUID REFERENCES documents(id) ON DELETE SET NULL,
+  status VARCHAR(20) NOT NULL DEFAULT 'pending' CHECK (status IN (
+    'pending', 'resolved', 'expired'
+  )),
+  created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
+  resolved_at TIMESTAMP WITH TIME ZONE
+);
+
+-- Trigger for pending_vehicle_associations does not need updated_at (uses resolved_at instead)
+
+-- Indexes
+CREATE INDEX IF NOT EXISTS idx_pending_vehicle_assoc_user_id ON pending_vehicle_associations(user_id);
+CREATE INDEX IF NOT EXISTS idx_pending_vehicle_assoc_status ON pending_vehicle_associations(status)
+  WHERE status = 'pending';
+CREATE INDEX IF NOT EXISTS idx_pending_vehicle_assoc_document_id ON pending_vehicle_associations(document_id)
+  WHERE document_id IS NOT NULL;
--- a/backend/src/features/email-ingestion/migrations/002_create_email_templates.sql
+++ b/backend/src/features/email-ingestion/migrations/002_create_email_templates.sql
@@ -0,0 +1,233 @@
+/**
+ * Migration: Add email ingestion email templates
+ * @ai-summary Extends email_templates CHECK constraint and seeds 3 receipt templates
+ * @ai-context Templates for receipt processing confirmations, failures, and pending vehicle selection
+ */
+
+-- Extend template_key CHECK constraint to include email ingestion templates
+ALTER TABLE email_templates
+DROP CONSTRAINT IF EXISTS email_templates_template_key_check;
+
+ALTER TABLE email_templates
+ADD CONSTRAINT email_templates_template_key_check
+CHECK (template_key IN (
+  'maintenance_due_soon', 'maintenance_overdue',
+  'document_expiring', 'document_expired',
+  'payment_failed_immediate', 'payment_failed_7day', 'payment_failed_1day',
+  'subscription_tier_change',
+  'receipt_processed', 'receipt_failed', 'receipt_pending_vehicle'
+));
+
+-- Insert email ingestion templates
+INSERT INTO email_templates (template_key, name, description, subject, body, variables, html_body) VALUES
+  (
+    'receipt_processed',
+    'Receipt Processed Successfully',
+    'Sent when an emailed receipt is successfully processed and recorded',
+    'MotoVaultPro: Receipt Processed for {{vehicleName}}',
+    'Hi {{userName}},
+
+Your emailed receipt has been successfully processed.
+
+Vehicle: {{vehicleName}}
+Record Type: {{recordType}}
+Merchant: {{merchantName}}
+Date: {{date}}
+Amount: ${{totalAmount}}
+
+The record has been added to your vehicle history.
+
+Best regards,
+MotoVaultPro Team',
+    '["userName", "vehicleName", "recordType", "merchantName", "totalAmount", "date"]',
+    '<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Receipt Processed</title>
+</head>
+<body style="margin: 0; padding: 0; font-family: Arial, sans-serif; background-color: #f4f4f4;">
+  <table width="100%" cellpadding="0" cellspacing="0" style="background-color: #f4f4f4; padding: 20px;">
+    <tr>
+      <td align="center">
+        <table width="600" cellpadding="0" cellspacing="0" style="background-color: #ffffff; border-radius: 8px; overflow: hidden; box-shadow: 0 2px 4px rgba(0,0,0,0.1);">
+          <tr>
+            <td style="background-color: #2e7d32; padding: 30px; text-align: center;">
+              <h1 style="color: #ffffff; margin: 0; font-size: 24px;">Receipt Processed</h1>
+            </td>
+          </tr>
+          <tr>
+            <td style="padding: 40px 30px;">
+              <p style="color: #333333; font-size: 16px; line-height: 1.6; margin: 0 0 20px 0;">Hi {{userName}},</p>
+              <p style="color: #333333; font-size: 16px; line-height: 1.6; margin: 0 0 20px 0;">Your emailed receipt has been successfully processed.</p>
+              <table cellpadding="0" cellspacing="0" style="margin: 20px 0; width: 100%;">
+                <tr>
+                  <td style="padding: 15px; background-color: #f9f9f9; border-left: 4px solid #2e7d32;">
+                    <p style="margin: 0 0 10px 0; color: #666666; font-size: 14px;"><strong>Vehicle:</strong> {{vehicleName}}</p>
+                    <p style="margin: 0 0 10px 0; color: #666666; font-size: 14px;"><strong>Record Type:</strong> {{recordType}}</p>
+                    <p style="margin: 0 0 10px 0; color: #666666; font-size: 14px;"><strong>Merchant:</strong> {{merchantName}}</p>
+                    <p style="margin: 0 0 10px 0; color: #666666; font-size: 14px;"><strong>Date:</strong> {{date}}</p>
+                    <p style="margin: 0; color: #666666; font-size: 14px;"><strong>Amount:</strong> ${{totalAmount}}</p>
+                  </td>
+                </tr>
+              </table>
+              <p style="color: #333333; font-size: 16px; line-height: 1.6; margin: 20px 0;">The record has been added to your vehicle history.</p>
+            </td>
+          </tr>
+          <tr>
+            <td style="padding: 20px 30px; background-color: #f9f9f9; border-top: 1px solid #e0e0e0;">
+              <p style="color: #666666; font-size: 14px; line-height: 1.6; margin: 0;">Best regards,<br>MotoVaultPro Team</p>
+            </td>
+          </tr>
+        </table>
+      </td>
+    </tr>
+  </table>
+</body>
+</html>'
+  ),
+  (
+    'receipt_failed',
+    'Receipt Processing Failed',
+    'Sent when an emailed receipt fails OCR processing or validation',
+    'MotoVaultPro: Unable to Process Your Receipt',
+    'Hi {{userName}},
+
+We were unable to process the receipt you emailed to us.
+
+Error: {{errorReason}}
+
+{{guidance}}
+
+Best regards,
+MotoVaultPro Team',
+    '["userName", "errorReason", "guidance"]',
+    '<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Receipt Processing Failed</title>
+</head>
+<body style="margin: 0; padding: 0; font-family: Arial, sans-serif; background-color: #f4f4f4;">
+  <table width="100%" cellpadding="0" cellspacing="0" style="background-color: #f4f4f4; padding: 20px;">
+    <tr>
+      <td align="center">
+        <table width="600" cellpadding="0" cellspacing="0" style="background-color: #ffffff; border-radius: 8px; overflow: hidden; box-shadow: 0 2px 4px rgba(0,0,0,0.1);">
+          <tr>
+            <td style="background-color: #d32f2f; padding: 30px; text-align: center;">
+              <h1 style="color: #ffffff; margin: 0; font-size: 24px;">Processing Failed</h1>
+            </td>
+          </tr>
+          <tr>
+            <td style="padding: 40px 30px;">
+              <p style="color: #333333; font-size: 16px; line-height: 1.6; margin: 0 0 20px 0;">Hi {{userName}},</p>
+              <p style="color: #333333; font-size: 16px; line-height: 1.6; margin: 0 0 20px 0;">We were unable to process the receipt you emailed to us.</p>
+              <table cellpadding="0" cellspacing="0" style="margin: 20px 0; width: 100%;">
+                <tr>
+                  <td style="padding: 15px; background-color: #f9f9f9; border-left: 4px solid #d32f2f;">
+                    <p style="margin: 0; color: #666666; font-size: 14px;"><strong>Error:</strong> {{errorReason}}</p>
+                  </td>
+                </tr>
+              </table>
+              <div style="background-color: #f5f5f5; padding: 20px; border-radius: 4px; margin: 20px 0;">
+                <p style="color: #333333; font-size: 14px; font-weight: bold; margin: 0 0 10px 0;">What to do next:</p>
+                <p style="color: #666666; font-size: 14px; line-height: 1.8; margin: 0;">{{guidance}}</p>
+              </div>
+            </td>
+          </tr>
+          <tr>
+            <td style="padding: 20px 30px; background-color: #f9f9f9; border-top: 1px solid #e0e0e0;">
+              <p style="color: #666666; font-size: 14px; line-height: 1.6; margin: 0;">Best regards,<br>MotoVaultPro Team</p>
+            </td>
+          </tr>
+        </table>
+      </td>
+    </tr>
+  </table>
+</body>
+</html>'
+  ),
+  (
+    'receipt_pending_vehicle',
+    'Receipt Pending Vehicle Selection',
+    'Sent when a multi-vehicle user needs to select which vehicle a receipt belongs to',
+    'MotoVaultPro: Select Vehicle for Your Receipt',
+    'Hi {{userName}},
+
+Your emailed receipt has been processed, but we need your help to complete the record.
+
+Since you have multiple vehicles, please log in to MotoVaultPro and select which vehicle this receipt belongs to.
+
+Record Type: {{recordType}}
+Merchant: {{merchantName}}
+Date: {{date}}
+Amount: ${{totalAmount}}
+
+You can find the pending receipt in your notifications.
+
+Best regards,
+MotoVaultPro Team',
+    '["userName", "recordType", "merchantName", "totalAmount", "date"]',
+    '<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Select Vehicle for Receipt</title>
+</head>
+<body style="margin: 0; padding: 0; font-family: Arial, sans-serif; background-color: #f4f4f4;">
+  <table width="100%" cellpadding="0" cellspacing="0" style="background-color: #f4f4f4; padding: 20px;">
+    <tr>
+      <td align="center">
+        <table width="600" cellpadding="0" cellspacing="0" style="background-color: #ffffff; border-radius: 8px; overflow: hidden; box-shadow: 0 2px 4px rgba(0,0,0,0.1);">
+          <tr>
+            <td style="background-color: #f57c00; padding: 30px; text-align: center;">
+              <h1 style="color: #ffffff; margin: 0; font-size: 24px;">Vehicle Selection Needed</h1>
+            </td>
+          </tr>
+          <tr>
+            <td style="padding: 40px 30px;">
+              <p style="color: #333333; font-size: 16px; line-height: 1.6; margin: 0 0 20px 0;">Hi {{userName}},</p>
+              <p style="color: #333333; font-size: 16px; line-height: 1.6; margin: 0 0 20px 0;">Your emailed receipt has been processed, but we need your help to complete the record.</p>
+              <div style="background-color: #fff3e0; border-left: 4px solid #f57c00; padding: 20px; margin: 20px 0;">
+                <p style="color: #e65100; font-size: 16px; font-weight: bold; margin: 0 0 10px 0;">Action Required</p>
+                <p style="color: #333333; font-size: 14px; margin: 0;">Since you have multiple vehicles, please select which vehicle this receipt belongs to.</p>
+              </div>
+              <table cellpadding="0" cellspacing="0" style="margin: 20px 0; width: 100%;">
+                <tr>
+                  <td style="padding: 15px; background-color: #f9f9f9; border-left: 4px solid #f57c00;">
+                    <p style="margin: 0 0 10px 0; color: #666666; font-size: 14px;"><strong>Record Type:</strong> {{recordType}}</p>
+                    <p style="margin: 0 0 10px 0; color: #666666; font-size: 14px;"><strong>Merchant:</strong> {{merchantName}}</p>
+                    <p style="margin: 0 0 10px 0; color: #666666; font-size: 14px;"><strong>Date:</strong> {{date}}</p>
+                    <p style="margin: 0; color: #666666; font-size: 14px;"><strong>Amount:</strong> ${{totalAmount}}</p>
+                  </td>
+                </tr>
+              </table>
+              <p style="color: #333333; font-size: 16px; line-height: 1.6; margin: 20px 0;">You can find the pending receipt in your notifications.</p>
+              <div style="text-align: center; margin: 30px 0;">
+                <a href="https://motovaultpro.com/notifications" style="display: inline-block; padding: 14px 28px; background-color: #f57c00; color: #ffffff; text-decoration: none; border-radius: 4px; font-weight: bold;">Select Vehicle</a>
+              </div>
+            </td>
+          </tr>
+          <tr>
+            <td style="padding: 20px 30px; background-color: #f9f9f9; border-top: 1px solid #e0e0e0;">
+              <p style="color: #666666; font-size: 14px; line-height: 1.6; margin: 0;">Best regards,<br>MotoVaultPro Team</p>
+            </td>
+          </tr>
+        </table>
+      </td>
+    </tr>
+  </table>
+</body>
+</html>'
+  )
+ON CONFLICT (template_key) DO UPDATE SET
+  name = EXCLUDED.name,
+  description = EXCLUDED.description,
+  subject = EXCLUDED.subject,
+  body = EXCLUDED.body,
+  variables = EXCLUDED.variables,
+  html_body = EXCLUDED.html_body,
+  updated_at = NOW();
--- a/backend/src/features/fuel-logs/CLAUDE.md
+++ b/backend/src/features/fuel-logs/CLAUDE.md
@@ -0,0 +1,21 @@
+# fuel-logs/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `README.md` | Feature documentation | Understanding fuel log tracking |
+| `index.ts` | Feature barrel export | Importing fuel-log services |
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `api/` | HTTP endpoints and routes | API changes |
+| `domain/` | Business logic, services, types | Core fuel-log logic |
+| `data/` | Repository, database queries | Database operations |
+| `docs/` | Feature-specific documentation | Fuel-log design details |
+| `events/` | Event handlers and emitters | Cross-feature event integration |
+| `external/` | External service integrations | Third-party API work |
+| `migrations/` | Database schema | Schema changes |
+| `tests/` | Unit and integration tests | Adding or modifying tests |
--- a/backend/src/features/fuel-logs/api/fuel-logs.controller.ts
+++ b/backend/src/features/fuel-logs/api/fuel-logs.controller.ts
@@ -20,12 +20,12 @@ export class FuelLogsController {
  
  async createFuelLog(request: FastifyRequest<{ Body: EnhancedCreateFuelLogRequest }>, reply: FastifyReply) {
    try {
-      const userId = (request as any).user.sub;
+      const userId = request.userContext!.userId;
      const fuelLog = await this.fuelLogsService.createFuelLog(request.body, userId);
      
      return reply.code(201).send(fuelLog);
    } catch (error: any) {
-      logger.error('Error creating fuel log', { error, userId: (request as any).user?.sub });
+      logger.error('Error creating fuel log', { error, userId: request.userContext?.userId });
      
      if (error.message.includes('not found')) {
        return reply.code(404).send({
@@ -49,14 +49,14 @@ export class FuelLogsController {
  
  async getFuelLogsByVehicle(request: FastifyRequest<{ Params: VehicleParams }>, reply: FastifyReply) {
    try {
-      const userId = (request as any).user.sub;
+      const userId = request.userContext!.userId;
      const { vehicleId } = request.params;
      
      const fuelLogs = await this.fuelLogsService.getFuelLogsByVehicle(vehicleId, userId);
      
      return reply.code(200).send(fuelLogs);
    } catch (error: any) {
-      logger.error('Error listing fuel logs', { error, vehicleId: request.params.vehicleId, userId: (request as any).user?.sub });
+      logger.error('Error listing fuel logs', { error, vehicleId: request.params.vehicleId, userId: request.userContext?.userId });
      
      if (error.message.includes('not found')) {
        return reply.code(404).send({
@@ -80,12 +80,12 @@ export class FuelLogsController {
  
  async getUserFuelLogs(request: FastifyRequest, reply: FastifyReply) {
    try {
-      const userId = (request as any).user.sub;
+      const userId = request.userContext!.userId;
      const fuelLogs = await this.fuelLogsService.getUserFuelLogs(userId);
      
      return reply.code(200).send(fuelLogs);
    } catch (error: any) {
-      logger.error('Error listing all fuel logs', { error, userId: (request as any).user?.sub });
+      logger.error('Error listing all fuel logs', { error, userId: request.userContext?.userId });
      return reply.code(500).send({
        error: 'Internal server error',
        message: 'Failed to get fuel logs'
@@ -95,14 +95,14 @@ export class FuelLogsController {
  
  async getFuelLog(request: FastifyRequest<{ Params: FuelLogParams }>, reply: FastifyReply) {
    try {
-      const userId = (request as any).user.sub;
+      const userId = request.userContext!.userId;
      const { id } = request.params;
      
      const fuelLog = await this.fuelLogsService.getFuelLog(id, userId);
      
      return reply.code(200).send(fuelLog);
    } catch (error: any) {
-      logger.error('Error getting fuel log', { error, fuelLogId: request.params.id, userId: (request as any).user?.sub });
+      logger.error('Error getting fuel log', { error, fuelLogId: request.params.id, userId: request.userContext?.userId });
      
      if (error.message === 'Fuel log not found') {
        return reply.code(404).send({
@@ -126,14 +126,14 @@ export class FuelLogsController {
  
  async updateFuelLog(request: FastifyRequest<{ Params: FuelLogParams; Body: EnhancedUpdateFuelLogRequest }>, reply: FastifyReply) {
    try {
-      const userId = (request as any).user.sub;
+      const userId = request.userContext!.userId;
      const { id } = request.params;

      const updatedFuelLog = await this.fuelLogsService.updateFuelLog(id, request.body, userId);

      return reply.code(200).send(updatedFuelLog);
    } catch (error: any) {
-      logger.error('Error updating fuel log', { error, fuelLogId: request.params.id, userId: (request as any).user?.sub });
+      logger.error('Error updating fuel log', { error, fuelLogId: request.params.id, userId: request.userContext?.userId });

      if (error.message.includes('not found')) {
        return reply.code(404).send({
@@ -163,14 +163,14 @@ export class FuelLogsController {
  
  async deleteFuelLog(request: FastifyRequest<{ Params: FuelLogParams }>, reply: FastifyReply) {
    try {
-      const userId = (request as any).user.sub;
+      const userId = request.userContext!.userId;
      const { id } = request.params;
      
      await this.fuelLogsService.deleteFuelLog(id, userId);
      
      return reply.code(204).send();
    } catch (error: any) {
-      logger.error('Error deleting fuel log', { error, fuelLogId: request.params.id, userId: (request as any).user?.sub });
+      logger.error('Error deleting fuel log', { error, fuelLogId: request.params.id, userId: request.userContext?.userId });
      
      if (error.message.includes('not found')) {
        return reply.code(404).send({
@@ -194,14 +194,14 @@ export class FuelLogsController {
  
  async getFuelStats(request: FastifyRequest<{ Params: VehicleParams }>, reply: FastifyReply) {
    try {
-      const userId = (request as any).user.sub;
+      const userId = request.userContext!.userId;
      const { vehicleId } = request.params;
      
      const stats = await this.fuelLogsService.getVehicleStats(vehicleId, userId);
      
      return reply.code(200).send(stats);
    } catch (error: any) {
-      logger.error('Error getting fuel stats', { error, vehicleId: request.params.vehicleId, userId: (request as any).user?.sub });
+      logger.error('Error getting fuel stats', { error, vehicleId: request.params.vehicleId, userId: request.userContext?.userId });
      
      if (error.message.includes('not found')) {
        return reply.code(404).send({
--- a/backend/src/features/fuel-logs/data/fuel-logs.repository.ts
+++ b/backend/src/features/fuel-logs/data/fuel-logs.repository.ts
@@ -293,7 +293,7 @@ export class FuelLogsRepository {
      data.notes ?? null
    ];
    const res = await this.pool.query(query, values);
-    return res.rows[0] ? this.mapRow(res.rows[0]) : null;
+    return res.rows[0] ?? null;
  }

  async findByVehicleIdEnhanced(vehicleId: string): Promise<any[]> {
@@ -301,7 +301,7 @@ export class FuelLogsRepository {
      `SELECT * FROM fuel_logs WHERE vehicle_id = $1 ORDER BY date_time DESC NULLS LAST, date DESC NULLS LAST, created_at DESC`,
      [vehicleId]
    );
-    return res.rows.map(row => this.mapRow(row));
+    return res.rows;
  }

  async findByUserIdEnhanced(userId: string): Promise<any[]> {
@@ -309,12 +309,12 @@ export class FuelLogsRepository {
      `SELECT * FROM fuel_logs WHERE user_id = $1 ORDER BY date_time DESC NULLS LAST, date DESC NULLS LAST, created_at DESC`,
      [userId]
    );
-    return res.rows.map(row => this.mapRow(row));
+    return res.rows;
  }

  async findByIdEnhanced(id: string): Promise<any | null> {
    const res = await this.pool.query(`SELECT * FROM fuel_logs WHERE id = $1`, [id]);
-    return res.rows[0] ? this.mapRow(res.rows[0]) : null;
+    return res.rows[0] ?? null;
  }

  async getPreviousLogByOdometer(vehicleId: string, odometerReading: number): Promise<any | null> {
@@ -322,7 +322,7 @@ export class FuelLogsRepository {
      `SELECT * FROM fuel_logs WHERE vehicle_id = $1 AND odometer IS NOT NULL AND odometer < $2 ORDER BY odometer DESC LIMIT 1`,
      [vehicleId, odometerReading]
    );
-    return res.rows[0] ? this.mapRow(res.rows[0]) : null;
+    return res.rows[0] ?? null;
  }

  async getLatestLogForVehicle(vehicleId: string): Promise<any | null> {
@@ -330,7 +330,7 @@ export class FuelLogsRepository {
      `SELECT * FROM fuel_logs WHERE vehicle_id = $1 ORDER BY date_time DESC NULLS LAST, date DESC NULLS LAST, created_at DESC LIMIT 1`,
      [vehicleId]
    );
-    return res.rows[0] ? this.mapRow(res.rows[0]) : null;
+    return res.rows[0] ?? null;
  }

  async updateEnhanced(id: string, data: {
@@ -416,6 +416,6 @@ export class FuelLogsRepository {
      return null;
    }

-    return this.mapRow(result.rows[0]);
+    return result.rows[0];
  }
 }
--- a/backend/src/features/fuel-logs/domain/fuel-logs.service.ts
+++ b/backend/src/features/fuel-logs/domain/fuel-logs.service.ts
@@ -282,8 +282,8 @@ export class FuelLogsService {
      tripDistance: row.trip_distance ?? undefined,
      fuelType: row.fuel_type as FuelType,
      fuelGrade: row.fuel_grade ?? undefined,
-      fuelUnits: row.fuel_units,
-      costPerUnit: row.cost_per_unit,
+      fuelUnits: Number(row.fuel_units),
+      costPerUnit: Number(row.cost_per_unit),
      totalCost: Number(row.total_cost),
      locationData: row.location_data ?? undefined,
      notes: row.notes ?? undefined,
--- a/backend/src/features/fuel-logs/tests/fixtures/fuel-logs.fixtures.json
+++ b/backend/src/features/fuel-logs/tests/fixtures/fuel-logs.fixtures.json
@@ -73,7 +73,7 @@
  },
  "responseWithEfficiency": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
-    "userId": "auth0|user123",
+    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "vehicleId": "550e8400-e29b-41d4-a716-446655440000",
    "dateTime": "2024-01-15T10:30:00Z",
    "odometerReading": 52000,
--- a/backend/src/features/maintenance/CLAUDE.md
+++ b/backend/src/features/maintenance/CLAUDE.md
@@ -0,0 +1,21 @@
+# maintenance/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `README.md` | Feature documentation | Understanding maintenance tracking |
+| `index.ts` | Feature barrel export | Importing maintenance services |
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `api/` | HTTP endpoints and routes | API changes |
+| `domain/` | Business logic, services, types | Core maintenance logic |
+| `data/` | Repository, database queries | Database operations |
+| `docs/` | Feature-specific documentation | Maintenance design details |
+| `events/` | Event handlers and emitters | Cross-feature event integration |
+| `external/` | External service integrations | Third-party API work |
+| `migrations/` | Database schema | Schema changes |
+| `tests/` | Unit and integration tests | Adding or modifying tests |
--- a/backend/src/features/maintenance/api/maintenance.controller.ts
+++ b/backend/src/features/maintenance/api/maintenance.controller.ts
@@ -18,7 +18,7 @@ export class MaintenanceController {
    request: FastifyRequest<{ Querystring: { vehicleId?: string; category?: string } }>,
    reply: FastifyReply
  ) {
-    const userId = (request as any).user?.sub as string;
+    const userId = request.userContext!.userId;

    logger.info('Maintenance records list requested', {
      operation: 'maintenance.records.list',
@@ -58,7 +58,7 @@ export class MaintenanceController {
  }

  async getRecord(request: FastifyRequest<{ Params: { id: string } }>, reply: FastifyReply) {
-    const userId = (request as any).user?.sub as string;
+    const userId = request.userContext!.userId;
    const recordId = request.params.id;

    logger.info('Maintenance record get requested', {
@@ -102,7 +102,7 @@ export class MaintenanceController {
    request: FastifyRequest<{ Params: { vehicleId: string } }>,
    reply: FastifyReply
  ) {
-    const userId = (request as any).user?.sub as string;
+    const userId = request.userContext!.userId;
    const vehicleId = request.params.vehicleId;

    logger.info('Maintenance records by vehicle requested', {
@@ -134,7 +134,7 @@ export class MaintenanceController {
  }

  async createRecord(request: FastifyRequest<{ Body: unknown }>, reply: FastifyReply) {
-    const userId = (request as any).user?.sub as string;
+    const userId = request.userContext!.userId;

    logger.info('Maintenance record create requested', {
      operation: 'maintenance.records.create',
@@ -190,7 +190,7 @@ export class MaintenanceController {
    request: FastifyRequest<{ Params: { id: string }; Body: unknown }>,
    reply: FastifyReply
  ) {
-    const userId = (request as any).user?.sub as string;
+    const userId = request.userContext!.userId;
    const recordId = request.params.id;

    logger.info('Maintenance record update requested', {
@@ -255,7 +255,7 @@ export class MaintenanceController {
  }

  async deleteRecord(request: FastifyRequest<{ Params: { id: string } }>, reply: FastifyReply) {
-    const userId = (request as any).user?.sub as string;
+    const userId = request.userContext!.userId;
    const recordId = request.params.id;

    logger.info('Maintenance record delete requested', {
@@ -289,7 +289,7 @@ export class MaintenanceController {
    request: FastifyRequest<{ Params: { vehicleId: string } }>,
    reply: FastifyReply
  ) {
-    const userId = (request as any).user?.sub as string;
+    const userId = request.userContext!.userId;
    const vehicleId = request.params.vehicleId;

    logger.info('Maintenance schedules by vehicle requested', {
@@ -321,7 +321,7 @@ export class MaintenanceController {
  }

  async createSchedule(request: FastifyRequest<{ Body: unknown }>, reply: FastifyReply) {
-    const userId = (request as any).user?.sub as string;
+    const userId = request.userContext!.userId;

    logger.info('Maintenance schedule create requested', {
      operation: 'maintenance.schedules.create',
@@ -377,7 +377,7 @@ export class MaintenanceController {
    request: FastifyRequest<{ Params: { id: string }; Body: unknown }>,
    reply: FastifyReply
  ) {
-    const userId = (request as any).user?.sub as string;
+    const userId = request.userContext!.userId;
    const scheduleId = request.params.id;

    logger.info('Maintenance schedule update requested', {
@@ -442,7 +442,7 @@ export class MaintenanceController {
  }

  async deleteSchedule(request: FastifyRequest<{ Params: { id: string } }>, reply: FastifyReply) {
-    const userId = (request as any).user?.sub as string;
+    const userId = request.userContext!.userId;
    const scheduleId = request.params.id;

    logger.info('Maintenance schedule delete requested', {
@@ -476,7 +476,7 @@ export class MaintenanceController {
    request: FastifyRequest<{ Params: { vehicleId: string }; Querystring: { currentMileage?: string } }>,
    reply: FastifyReply
  ) {
-    const userId = (request as any).user?.sub as string;
+    const userId = request.userContext!.userId;
    const vehicleId = request.params.vehicleId;
    const currentMileage = request.query.currentMileage ? parseInt(request.query.currentMileage, 10) : undefined;

@@ -510,7 +510,7 @@ export class MaintenanceController {
  }

  async getSubtypes(request: FastifyRequest<{ Params: { category: string } }>, reply: FastifyReply) {
-    const userId = (request as any).user?.sub as string;
+    const userId = request.userContext!.userId;
    const category = request.params.category;

    logger.info('Maintenance subtypes requested', {
--- a/backend/src/features/maintenance/data/maintenance.repository.ts
+++ b/backend/src/features/maintenance/data/maintenance.repository.ts
@@ -21,6 +21,7 @@ export class MaintenanceRepository {
      cost: row.cost,
      shopName: row.shop_name,
      notes: row.notes,
+      receiptDocumentId: row.receipt_document_id,
      createdAt: row.created_at,
      updatedAt: row.updated_at
    };
@@ -66,11 +67,12 @@ export class MaintenanceRepository {
    cost?: number | null;
    shopName?: string | null;
    notes?: string | null;
+    receiptDocumentId?: string | null;
  }): Promise<MaintenanceRecord> {
    const res = await this.db.query(
      `INSERT INTO maintenance_records (
-        id, user_id, vehicle_id, category, subtypes, date, odometer_reading, cost, shop_name, notes
-      ) VALUES ($1, $2, $3, $4, $5::text[], $6, $7, $8, $9, $10)
+        id, user_id, vehicle_id, category, subtypes, date, odometer_reading, cost, shop_name, notes, receipt_document_id
+      ) VALUES ($1, $2, $3, $4, $5::text[], $6, $7, $8, $9, $10, $11)
      RETURNING *`,
      [
        record.id,
@@ -83,6 +85,7 @@ export class MaintenanceRepository {
        record.cost ?? null,
        record.shopName ?? null,
        record.notes ?? null,
+        record.receiptDocumentId ?? null,
      ]
    );
    return this.mapMaintenanceRecord(res.rows[0]);
@@ -96,6 +99,26 @@ export class MaintenanceRepository {
    return res.rows[0] ? this.mapMaintenanceRecord(res.rows[0]) : null;
  }

+  async findRecordByIdWithDocument(id: string, userId: string): Promise<{ record: MaintenanceRecord; receiptDocument: { documentId: string; fileName: string; contentType: string; storageKey: string } | null } | null> {
+    const res = await this.db.query(
+      `SELECT mr.*, d.id AS doc_id, d.file_name AS doc_file_name, d.content_type AS doc_content_type, d.storage_key AS doc_storage_key
+       FROM maintenance_records mr
+       LEFT JOIN documents d ON mr.receipt_document_id = d.id
+       WHERE mr.id = $1 AND mr.user_id = $2`,
+      [id, userId]
+    );
+    if (!res.rows[0]) return null;
+    const row = res.rows[0];
+    const record = this.mapMaintenanceRecord(row);
+    const receiptDocument = row.doc_id ? {
+      documentId: row.doc_id,
+      fileName: row.doc_file_name,
+      contentType: row.doc_content_type,
+      storageKey: row.doc_storage_key,
+    } : null;
+    return { record, receiptDocument };
+  }
+
  async findRecordsByUserId(
    userId: string,
    filters?: { vehicleId?: string; category?: MaintenanceCategory }
--- a/backend/src/features/maintenance/domain/maintenance.service.ts
+++ b/backend/src/features/maintenance/domain/maintenance.service.ts
@@ -9,7 +9,9 @@ import type {
  MaintenanceRecordResponse,
  MaintenanceScheduleResponse,
  MaintenanceCategory,
-  ScheduleType
+  ScheduleType,
+  MaintenanceCostStats,
+  ReceiptDocumentMeta
 } from './maintenance.types';
 import { validateSubtypes } from './maintenance.types';
 import { MaintenanceRepository } from '../data/maintenance.repository';
@@ -39,6 +41,7 @@ export class MaintenanceService {
      cost: body.cost,
      shopName: body.shopName,
      notes: body.notes,
+      receiptDocumentId: body.receiptDocumentId,
    });

    // Auto-link: Find and update matching 'time_since_last' schedules
@@ -48,9 +51,9 @@ export class MaintenanceService {
  }

  async getRecord(userId: string, id: string): Promise<MaintenanceRecordResponse | null> {
-    const record = await this.repo.findRecordById(id, userId);
-    if (!record) return null;
-    return this.toRecordResponse(record);
+    const result = await this.repo.findRecordByIdWithDocument(id, userId);
+    if (!result) return null;
+    return this.toRecordResponse(result.record, result.receiptDocument);
  }

  async getRecords(userId: string, filters?: { vehicleId?: string; category?: MaintenanceCategory }): Promise<MaintenanceRecordResponse[]> {
@@ -63,6 +66,19 @@ export class MaintenanceService {
    return records.map(r => this.toRecordResponse(r));
  }

+  async getVehicleMaintenanceCosts(vehicleId: string, userId: string): Promise<MaintenanceCostStats> {
+    const records = await this.repo.findRecordsByVehicleId(vehicleId, userId);
+    const totalCost = records.reduce((sum, r) => {
+      if (r.cost === null || r.cost === undefined) return sum;
+      const cost = Number(r.cost);
+      if (isNaN(cost)) {
+        throw new Error(`Invalid cost value for maintenance record ${r.id}`);
+      }
+      return sum + cost;
+    }, 0);
+    return { totalCost, recordCount: records.length };
+  }
+
  async updateRecord(userId: string, id: string, patch: UpdateMaintenanceRecordRequest): Promise<MaintenanceRecordResponse | null> {
    const existing = await this.repo.findRecordById(id, userId);
    if (!existing) return null;
@@ -258,10 +274,11 @@ export class MaintenanceService {
    return { nextDueDate, nextDueMileage };
  }

-  private toRecordResponse(record: MaintenanceRecord): MaintenanceRecordResponse {
+  private toRecordResponse(record: MaintenanceRecord, receiptDocument?: ReceiptDocumentMeta | null): MaintenanceRecordResponse {
    return {
      ...record,
      subtypeCount: record.subtypes.length,
+      receiptDocument: receiptDocument ?? null,
    };
  }

--- a/backend/src/features/maintenance/domain/maintenance.types.ts
+++ b/backend/src/features/maintenance/domain/maintenance.types.ts
@@ -68,6 +68,7 @@ export interface MaintenanceRecord {
  cost?: number;
  shopName?: string;
  notes?: string;
+  receiptDocumentId?: string | null;
  createdAt: string;
  updatedAt: string;
 }
@@ -113,6 +114,7 @@ export const CreateMaintenanceRecordSchema = z.object({
  cost: z.number().positive().optional(),
  shopName: z.string().max(200).optional(),
  notes: z.string().max(10000).optional(),
+  receiptDocumentId: z.string().uuid().optional(),
 });
 export type CreateMaintenanceRecordRequest = z.infer<typeof CreateMaintenanceRecordSchema>;

@@ -157,9 +159,24 @@ export const UpdateScheduleSchema = z.object({
 });
 export type UpdateScheduleRequest = z.infer<typeof UpdateScheduleSchema>;

+// Receipt document metadata returned on GET
+export interface ReceiptDocumentMeta {
+  documentId: string;
+  fileName: string;
+  contentType: string;
+  storageKey: string;
+}
+
 // Response types
 export interface MaintenanceRecordResponse extends MaintenanceRecord {
  subtypeCount: number;
+  receiptDocument?: ReceiptDocumentMeta | null;
+}
+
+// TCO aggregation stats
+export interface MaintenanceCostStats {
+  totalCost: number;
+  recordCount: number;
 }

 export interface MaintenanceScheduleResponse extends MaintenanceSchedule {
--- a/backend/src/features/maintenance/migrations/004_add_receipt_document_id.sql
+++ b/backend/src/features/maintenance/migrations/004_add_receipt_document_id.sql
@@ -0,0 +1,7 @@
+-- Add receipt_document_id FK to link maintenance records to scanned receipt documents
+ALTER TABLE maintenance_records
+  ADD COLUMN receipt_document_id UUID REFERENCES documents(id) ON DELETE SET NULL;
+
+-- Index for querying records by receipt document
+CREATE INDEX idx_maintenance_records_receipt_document_id ON maintenance_records(receipt_document_id)
+  WHERE receipt_document_id IS NOT NULL;
--- a/backend/src/features/maintenance/tests/fixtures/maintenance.fixtures.json
+++ b/backend/src/features/maintenance/tests/fixtures/maintenance.fixtures.json
@@ -99,7 +99,7 @@
  },
  "maintenanceScheduleResponse": {
    "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
-    "userId": "auth0|user123",
+    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "vehicleId": "550e8400-e29b-41d4-a716-446655440000",
    "type": "oil_change",
    "category": "routine_maintenance",
--- a/backend/src/features/notifications/CLAUDE.md
+++ b/backend/src/features/notifications/CLAUDE.md
@@ -0,0 +1,19 @@
+# notifications/
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `README.md` | Feature documentation | Understanding notification system |
+| `index.ts` | Feature barrel export | Importing notification services |
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `api/` | HTTP endpoints and routes | API changes |
+| `domain/` | Business logic, email layout, types | Core notification logic |
+| `data/` | Repository, database queries | Database operations |
+| `jobs/` | Scheduled notification jobs | Background notification processing |
+| `migrations/` | Database schema | Schema changes |
+| `tests/` | Unit and integration tests | Adding or modifying tests |
--- a/backend/src/features/notifications/README.md
+++ b/backend/src/features/notifications/README.md
@@ -97,7 +97,7 @@ Templates use `{{variableName}}` syntax for variable substitution.

 ### Environment Variables
 - `RESEND_API_KEY` - Resend API key (required, stored in secrets)
- `FROM_EMAIL` - Sender email address (default: noreply@motovaultpro.com)
+- `FROM_EMAIL` - Sender email address (default: hello@notify.motovaultpro.com)

 ### Email Delivery
 - Uses Resend API for transactional emails
--- a/backend/src/features/notifications/api/notifications.controller.ts
+++ b/backend/src/features/notifications/api/notifications.controller.ts
@@ -24,7 +24,7 @@ export class NotificationsController {
  // ========================

  async getSummary(request: FastifyRequest, reply: FastifyReply) {
-    const userId = request.user.sub;
+    const userId = request.userContext!.userId;

    try {
      const summary = await this.service.getNotificationSummary(userId);
@@ -38,7 +38,7 @@ export class NotificationsController {
  }

  async getDueMaintenanceItems(request: FastifyRequest, reply: FastifyReply) {
-    const userId = request.user.sub;
+    const userId = request.userContext!.userId;

    try {
      const items = await this.service.getDueMaintenanceItems(userId);
@@ -52,7 +52,7 @@ export class NotificationsController {
  }

  async getExpiringDocuments(request: FastifyRequest, reply: FastifyReply) {
-    const userId = request.user.sub;
+    const userId = request.userContext!.userId;

    try {
      const documents = await this.service.getExpiringDocuments(userId);
@@ -70,7 +70,7 @@ export class NotificationsController {
  // ========================

  async getInAppNotifications(request: FastifyRequest, reply: FastifyReply) {
-    const userId = request.user!.sub!;
+    const userId = request.userContext!.userId;
    const query = request.query as { limit?: string; includeRead?: string };
    const limit = query.limit ? parseInt(query.limit, 10) : 20;
    const includeRead = query.includeRead === 'true';
@@ -85,7 +85,7 @@ export class NotificationsController {
  }

  async getUnreadCount(request: FastifyRequest, reply: FastifyReply) {
-    const userId = request.user!.sub!;
+    const userId = request.userContext!.userId;

    try {
      const count = await this.service.getUnreadCount(userId);
@@ -97,7 +97,7 @@ export class NotificationsController {
  }

  async markAsRead(request: FastifyRequest<{ Params: { id: string } }>, reply: FastifyReply) {
-    const userId = request.user!.sub!;
+    const userId = request.userContext!.userId;
    const notificationId = request.params.id;

    try {
@@ -113,7 +113,7 @@ export class NotificationsController {
  }

  async markAllAsRead(request: FastifyRequest, reply: FastifyReply) {
-    const userId = request.user!.sub!;
+    const userId = request.userContext!.userId;

    try {
      const count = await this.service.markAllAsRead(userId);
@@ -125,7 +125,7 @@ export class NotificationsController {
  }

  async deleteNotification(request: FastifyRequest<{ Params: { id: string } }>, reply: FastifyReply) {
-    const userId = request.user!.sub!;
+    const userId = request.userContext!.userId;
    const notificationId = request.params.id;

    try {
--- a/backend/src/features/notifications/domain/email-layout/base-layout.ts
+++ b/backend/src/features/notifications/domain/email-layout/base-layout.ts
@@ -7,7 +7,7 @@
 import { EMAIL_STYLES } from './email-styles';

 // External logo URL - hosted on GitHub for reliability
-const LOGO_URL = 'https://raw.githubusercontent.com/ericgullickson/images/c58b0e4773e8395b532f97f6ab529e38ea4dc8be/motovaultpro-auth0-small.png';
+const LOGO_URL = 'https://motovaultpro.com/images/logos/motovaultpro-auth0-small.png';

 /**
 * Renders the complete HTML email layout with branding
@@ -65,10 +65,10 @@ export function renderEmailLayout(content: string): string {
                      <a href="https://motovaultpro.com" style="${EMAIL_STYLES.footerLink}" target="_blank">Login to MotoVaultPro</a>
                    </p>
                    <p style="${EMAIL_STYLES.footerText}">
-                      <a href="{{unsubscribeUrl}}" style="${EMAIL_STYLES.footerLink}" target="_blank">Manage Email Preferences</a>
+                      <a href="https://motovaultpro.com/settings" style="${EMAIL_STYLES.footerLink}" target="_blank">Manage Email Preferences</a>
                    </p>
                    <p style="${EMAIL_STYLES.copyright}">
-                      &copy; {new Date().getFullYear()} MotoVaultPro. All rights reserved.
+                      &copy; ${new Date().getFullYear()} MotoVaultPro. All rights reserved.
                    </p>
                  </td>
                </tr>
--- a/backend/src/features/notifications/domain/email.service.ts
+++ b/backend/src/features/notifications/domain/email.service.ts
@@ -16,7 +16,7 @@ export class EmailService {
    }

    this.resend = new Resend(apiKey);
-    this.fromEmail = process.env['FROM_EMAIL'] || 'noreply@motovaultpro.com';
+    this.fromEmail = process.env['FROM_EMAIL'] || 'hello@notify.motovaultpro.com';
  }

  /**
@@ -33,6 +33,10 @@ export class EmailService {
        to,
        subject,
        html,
+        headers: {
+          'List-Unsubscribe': '<https://motovaultpro.com/settings>',
+          'List-Unsubscribe-Post': 'List-Unsubscribe=One-Click',
+        },
      });
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
--- a/backend/src/features/notifications/domain/notifications.service.ts
+++ b/backend/src/features/notifications/domain/notifications.service.ts
@@ -227,6 +227,141 @@ export class NotificationsService {
    }
  }

+  /**
+   * Send tier change notification (email + in-app) when subscription tier changes
+   * @param userId User ID
+   * @param userEmail User email address
+   * @param userName User display name
+   * @param previousTier Previous subscription tier
+   * @param newTier New subscription tier
+   * @param reason Reason for change (admin_override, user_upgrade, user_downgrade, grace_period_expiration)
+   */
+  async sendTierChangeNotification(
+    userId: string,
+    userEmail: string,
+    userName: string,
+    previousTier: string,
+    newTier: string,
+    reason: 'admin_override' | 'user_upgrade' | 'user_downgrade' | 'grace_period_expiration'
+  ): Promise<void> {
+    const templateKey: TemplateKey = 'subscription_tier_change';
+
+    const template = await this.repository.getEmailTemplateByKey(templateKey);
+    if (!template || !template.isActive) {
+      // Log but don't throw - notifications are non-critical
+      console.warn(`Template ${templateKey} not found or inactive, skipping tier change notification`);
+      return;
+    }
+
+    const isDowngrade = this.getTierRank(newTier) < this.getTierRank(previousTier);
+    const isUpgrade = this.getTierRank(newTier) > this.getTierRank(previousTier);
+    const changeType = isUpgrade ? 'Upgraded' : isDowngrade ? 'Downgraded' : 'Changed';
+
+    const reasonDisplayMap: Record<string, string> = {
+      admin_override: 'Administrator adjustment',
+      user_upgrade: 'Subscription upgrade',
+      user_downgrade: 'Subscription downgrade',
+      grace_period_expiration: 'Payment grace period expired',
+    };
+
+    const vehicleLimitMap: Record<string, string> = {
+      free: '2',
+      pro: '5',
+      enterprise: 'unlimited',
+    };
+
+    // Build additional info based on change type
+    let additionalInfo = '';
+    if (isDowngrade) {
+      const vehicleLimit = vehicleLimitMap[newTier.toLowerCase()] || '2';
+      additionalInfo = `As a result of this change, you now have access to ${vehicleLimit} vehicles. Any vehicles beyond this limit will be hidden but your data remains safe.`;
+    } else if (isUpgrade) {
+      additionalInfo = `You now have access to all the features included in the ${this.formatTierName(newTier)} tier. Enjoy your enhanced MotoVaultPro experience!`;
+    }
+
+    const variables = {
+      userName,
+      changeType,
+      previousTier: this.formatTierName(previousTier),
+      newTier: this.formatTierName(newTier),
+      reason: reasonDisplayMap[reason] || reason,
+      additionalInfo,
+    };
+
+    const subject = this.templateService.render(template.subject, variables);
+    const htmlBody = this.templateService.renderEmailHtml(template.body, variables);
+
+    // Send email notification
+    try {
+      await this.emailService.send(userEmail, subject, htmlBody);
+
+      await this.repository.insertNotificationLog({
+        user_id: userId,
+        notification_type: 'email',
+        template_key: templateKey,
+        recipient_email: userEmail,
+        subject,
+        reference_type: 'subscription',
+        status: 'sent',
+      });
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+      console.error(`Failed to send tier change email to ${userEmail}: ${errorMessage}`);
+
+      await this.repository.insertNotificationLog({
+        user_id: userId,
+        notification_type: 'email',
+        template_key: templateKey,
+        recipient_email: userEmail,
+        subject,
+        reference_type: 'subscription',
+        status: 'failed',
+        error_message: errorMessage,
+      });
+    }
+
+    // Create in-app notification
+    try {
+      const title = `Subscription ${changeType}`;
+      const message = `Your subscription has been ${changeType.toLowerCase()} from ${this.formatTierName(previousTier)} to ${this.formatTierName(newTier)}. ${reasonDisplayMap[reason]}.`;
+
+      await this.repository.insertUserNotification({
+        userId,
+        notificationType: 'subscription',
+        title,
+        message,
+        referenceType: 'subscription',
+      });
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+      console.error(`Failed to create in-app tier change notification for ${userId}: ${errorMessage}`);
+    }
+  }
+
+  /**
+   * Get numeric rank for tier comparison
+   */
+  private getTierRank(tier: string): number {
+    const ranks: Record<string, number> = {
+      free: 1,
+      pro: 2,
+      enterprise: 3,
+    };
+    return ranks[tier.toLowerCase()] || 0;
+  }
+
+  /**
+   * Format tier name for display
+   */
+  private formatTierName(tier: string): string {
+    const names: Record<string, string> = {
+      free: 'Free',
+      pro: 'Pro',
+      enterprise: 'Enterprise',
+    };
+    return names[tier.toLowerCase()] || tier;
+  }
+
  /**
   * Send a test email for a template to verify email configuration
   * @param key Template key to test
@@ -301,6 +436,38 @@ export class NotificationsService {
          documentTitle: 'State Farm Auto Policy',
          expirationDate: new Date(Date.now() + 14 * 24 * 60 * 60 * 1000).toLocaleDateString(),
        };
+      case 'subscription_tier_change':
+        return {
+          ...baseVariables,
+          changeType: 'Upgraded',
+          previousTier: 'Free',
+          newTier: 'Pro',
+          reason: 'Subscription upgrade',
+          additionalInfo: 'You now have access to all the features included in the Pro tier. Enjoy your enhanced MotoVaultPro experience!',
+        };
+      case 'receipt_processed':
+        return {
+          ...baseVariables,
+          vehicleName: '2024 Toyota Camry',
+          recordType: 'Fuel Log',
+          merchantName: 'Shell Gas Station',
+          totalAmount: '45.50',
+          date: new Date().toLocaleDateString(),
+        };
+      case 'receipt_failed':
+        return {
+          ...baseVariables,
+          errorReason: 'Unable to extract receipt data from the attached image.',
+          guidance: 'Please try again with a clearer image or PDF. Tips: use a well-lit, high-contrast photo; ensure text is legible and not cut off; PDF receipts work best.',
+        };
+      case 'receipt_pending_vehicle':
+        return {
+          ...baseVariables,
+          recordType: 'Maintenance Record',
+          merchantName: 'AutoZone',
+          totalAmount: '89.99',
+          date: new Date().toLocaleDateString(),
+        };
      default:
        return baseVariables;
    }
--- a/backend/src/features/notifications/domain/notifications.types.ts
+++ b/backend/src/features/notifications/domain/notifications.types.ts
@@ -10,7 +10,11 @@ export type TemplateKey =
  | 'maintenance_due_soon'
  | 'maintenance_overdue'
  | 'document_expiring'
-  | 'document_expired';
+  | 'document_expired'
+  | 'subscription_tier_change'
+  | 'receipt_processed'
+  | 'receipt_failed'
+  | 'receipt_pending_vehicle';

 // Email template API response type (camelCase for frontend)
 export interface EmailTemplate {
@@ -84,7 +88,11 @@ export const TemplateKeySchema = z.enum([
  'maintenance_due_soon',
  'maintenance_overdue',
  'document_expiring',
-  'document_expired'
+  'document_expired',
+  'subscription_tier_change',
+  'receipt_processed',
+  'receipt_failed',
+  'receipt_pending_vehicle'
 ]);

 export const UpdateEmailTemplateSchema = z.object({
--- a/backend/src/features/notifications/migrations/006_payment_email_templates.sql
+++ b/backend/src/features/notifications/migrations/006_payment_email_templates.sql
@@ -0,0 +1,239 @@
+/**
+ * Migration: Add payment failure email templates
+ * @ai-summary Adds email templates for payment failures during grace period
+ * @ai-context Three templates: immediate, 7-day warning, 1-day warning
+ */
+
+-- Extend template_key CHECK constraint to include payment failure templates
+ALTER TABLE email_templates
+DROP CONSTRAINT IF EXISTS email_templates_template_key_check;
+
+ALTER TABLE email_templates
+ADD CONSTRAINT email_templates_template_key_check
+CHECK (template_key IN (
+  'maintenance_due_soon', 'maintenance_overdue',
+  'document_expiring', 'document_expired',
+  'payment_failed_immediate', 'payment_failed_7day', 'payment_failed_1day'
+));
+
+-- Insert payment failure email templates
+INSERT INTO email_templates (template_key, name, description, subject, body, variables, html_body) VALUES
+  (
+    'payment_failed_immediate',
+    'Payment Failed - Immediate Notice',
+    'Sent immediately when a subscription payment fails',
+    'MotoVaultPro: Payment Failed - Action Required',
+    'Hi {{userName}},
+
+We were unable to process your payment for your {{tier}} subscription.
+
+Your subscription will remain active for 30 days while we attempt to collect payment. After 30 days, your subscription will be downgraded to the free tier.
+
+Please update your payment method to avoid interruption of service.
+
+Amount Due: ${{amount}}
+Next Retry: {{retryDate}}
+
+Best regards,
+MotoVaultPro Team',
+    '["userName", "tier", "amount", "retryDate"]',
+    '<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Payment Failed</title>
+</head>
+<body style="margin: 0; padding: 0; font-family: Arial, sans-serif; background-color: #f4f4f4;">
+  <table width="100%" cellpadding="0" cellspacing="0" style="background-color: #f4f4f4; padding: 20px;">
+    <tr>
+      <td align="center">
+        <table width="600" cellpadding="0" cellspacing="0" style="background-color: #ffffff; border-radius: 8px; overflow: hidden; box-shadow: 0 2px 4px rgba(0,0,0,0.1);">
+          <tr>
+            <td style="background-color: #d32f2f; padding: 30px; text-align: center;">
+              <h1 style="color: #ffffff; margin: 0; font-size: 24px;">Payment Failed</h1>
+            </td>
+          </tr>
+          <tr>
+            <td style="padding: 40px 30px;">
+              <p style="color: #333333; font-size: 16px; line-height: 1.6; margin: 0 0 20px 0;">Hi {{userName}},</p>
+              <p style="color: #333333; font-size: 16px; line-height: 1.6; margin: 0 0 20px 0;">We were unable to process your payment for your <strong>{{tier}}</strong> subscription.</p>
+              <p style="color: #333333; font-size: 16px; line-height: 1.6; margin: 0 0 20px 0;">Your subscription will remain active for <strong>30 days</strong> while we attempt to collect payment. After 30 days, your subscription will be downgraded to the free tier.</p>
+              <p style="color: #333333; font-size: 16px; line-height: 1.6; margin: 0 0 20px 0;">Please update your payment method to avoid interruption of service.</p>
+              <table cellpadding="0" cellspacing="0" style="margin: 20px 0; width: 100%;">
+                <tr>
+                  <td style="padding: 15px; background-color: #f9f9f9; border-left: 4px solid #d32f2f;">
+                    <p style="margin: 0 0 10px 0; color: #666666; font-size: 14px;"><strong>Amount Due:</strong> ${{amount}}</p>
+                    <p style="margin: 0; color: #666666; font-size: 14px;"><strong>Next Retry:</strong> {{retryDate}}</p>
+                  </td>
+                </tr>
+              </table>
+              <div style="text-align: center; margin: 30px 0;">
+                <a href="https://app.motovaultpro.com/settings/billing" style="display: inline-block; padding: 14px 28px; background-color: #1976d2; color: #ffffff; text-decoration: none; border-radius: 4px; font-weight: bold;">Update Payment Method</a>
+              </div>
+            </td>
+          </tr>
+          <tr>
+            <td style="padding: 20px 30px; background-color: #f9f9f9; border-top: 1px solid #e0e0e0;">
+              <p style="color: #666666; font-size: 14px; line-height: 1.6; margin: 0;">Best regards,<br>MotoVaultPro Team</p>
+            </td>
+          </tr>
+        </table>
+      </td>
+    </tr>
+  </table>
+</body>
+</html>'
+  ),
+  (
+    'payment_failed_7day',
+    'Payment Failed - 7 Days Left',
+    'Sent 7 days before grace period ends',
+    'MotoVaultPro: Urgent - 7 Days Until Downgrade',
+    'Hi {{userName}},
+
+This is an urgent reminder that your {{tier}} subscription payment is still outstanding.
+
+Your subscription will be downgraded to the free tier in 7 days if payment is not received.
+
+Amount Due: ${{amount}}
+Grace Period Ends: {{gracePeriodEnd}}
+
+Please update your payment method immediately to avoid losing access to premium features.
+
+Best regards,
+MotoVaultPro Team',
+    '["userName", "tier", "amount", "gracePeriodEnd"]',
+    '<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Payment Reminder - 7 Days Left</title>
+</head>
+<body style="margin: 0; padding: 0; font-family: Arial, sans-serif; background-color: #f4f4f4;">
+  <table width="100%" cellpadding="0" cellspacing="0" style="background-color: #f4f4f4; padding: 20px;">
+    <tr>
+      <td align="center">
+        <table width="600" cellpadding="0" cellspacing="0" style="background-color: #ffffff; border-radius: 8px; overflow: hidden; box-shadow: 0 2px 4px rgba(0,0,0,0.1);">
+          <tr>
+            <td style="background-color: #f57c00; padding: 30px; text-align: center;">
+              <h1 style="color: #ffffff; margin: 0; font-size: 24px;">Urgent: 7 Days Until Downgrade</h1>
+            </td>
+          </tr>
+          <tr>
+            <td style="padding: 40px 30px;">
+              <p style="color: #333333; font-size: 16px; line-height: 1.6; margin: 0 0 20px 0;">Hi {{userName}},</p>
+              <p style="color: #333333; font-size: 16px; line-height: 1.6; margin: 0 0 20px 0;">This is an urgent reminder that your <strong>{{tier}}</strong> subscription payment is still outstanding.</p>
+              <div style="background-color: #fff3e0; border-left: 4px solid #f57c00; padding: 20px; margin: 20px 0;">
+                <p style="color: #e65100; font-size: 18px; font-weight: bold; margin: 0 0 10px 0;">Your subscription will be downgraded in 7 days</p>
+                <p style="color: #333333; font-size: 14px; margin: 0;">If payment is not received by {{gracePeriodEnd}}, you will lose access to premium features.</p>
+              </div>
+              <table cellpadding="0" cellspacing="0" style="margin: 20px 0; width: 100%;">
+                <tr>
+                  <td style="padding: 15px; background-color: #f9f9f9; border-left: 4px solid #f57c00;">
+                    <p style="margin: 0 0 10px 0; color: #666666; font-size: 14px;"><strong>Amount Due:</strong> ${{amount}}</p>
+                    <p style="margin: 0; color: #666666; font-size: 14px;"><strong>Grace Period Ends:</strong> {{gracePeriodEnd}}</p>
+                  </td>
+                </tr>
+              </table>
+              <div style="text-align: center; margin: 30px 0;">
+                <a href="https://app.motovaultpro.com/settings/billing" style="display: inline-block; padding: 14px 28px; background-color: #f57c00; color: #ffffff; text-decoration: none; border-radius: 4px; font-weight: bold;">Update Payment Now</a>
+              </div>
+            </td>
+          </tr>
+          <tr>
+            <td style="padding: 20px 30px; background-color: #f9f9f9; border-top: 1px solid #e0e0e0;">
+              <p style="color: #666666; font-size: 14px; line-height: 1.6; margin: 0;">Best regards,<br>MotoVaultPro Team</p>
+            </td>
+          </tr>
+        </table>
+      </td>
+    </tr>
+  </table>
+</body>
+</html>'
+  ),
+  (
+    'payment_failed_1day',
+    'Payment Failed - Final Notice',
+    'Sent 1 day before grace period ends',
+    'MotoVaultPro: FINAL NOTICE - Downgrade Tomorrow',
+    'Hi {{userName}},
+
+FINAL NOTICE: Your {{tier}} subscription will be downgraded to the free tier tomorrow if payment is not received.
+
+Amount Due: ${{amount}}
+Grace Period Ends: {{gracePeriodEnd}}
+
+This is your last chance to update your payment method and keep your premium features.
+
+After downgrade:
+- Access to premium features will be lost
+- Data remains safe but with reduced vehicle limits
+- You can resubscribe at any time
+
+Please update your payment method now to avoid interruption.
+
+Best regards,
+MotoVaultPro Team',
+    '["userName", "tier", "amount", "gracePeriodEnd"]',
+    '<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Final Notice - Downgrade Tomorrow</title>
+</head>
+<body style="margin: 0; padding: 0; font-family: Arial, sans-serif; background-color: #f4f4f4;">
+  <table width="100%" cellpadding="0" cellspacing="0" style="background-color: #f4f4f4; padding: 20px;">
+    <tr>
+      <td align="center">
+        <table width="600" cellpadding="0" cellspacing="0" style="background-color: #ffffff; border-radius: 8px; overflow: hidden; box-shadow: 0 2px 4px rgba(0,0,0,0.1);">
+          <tr>
+            <td style="background-color: #c62828; padding: 30px; text-align: center;">
+              <h1 style="color: #ffffff; margin: 0; font-size: 24px;">FINAL NOTICE</h1>
+              <p style="color: #ffffff; margin: 10px 0 0 0; font-size: 16px;">Downgrade Tomorrow</p>
+            </td>
+          </tr>
+          <tr>
+            <td style="padding: 40px 30px;">
+              <p style="color: #333333; font-size: 16px; line-height: 1.6; margin: 0 0 20px 0;">Hi {{userName}},</p>
+              <div style="background-color: #ffebee; border: 2px solid #c62828; border-radius: 4px; padding: 20px; margin: 20px 0;">
+                <p style="color: #b71c1c; font-size: 18px; font-weight: bold; margin: 0 0 10px 0;">FINAL NOTICE</p>
+                <p style="color: #333333; font-size: 16px; margin: 0;">Your <strong>{{tier}}</strong> subscription will be downgraded to the free tier <strong>tomorrow</strong> if payment is not received.</p>
+              </div>
+              <table cellpadding="0" cellspacing="0" style="margin: 20px 0; width: 100%;">
+                <tr>
+                  <td style="padding: 15px; background-color: #f9f9f9; border-left: 4px solid #c62828;">
+                    <p style="margin: 0 0 10px 0; color: #666666; font-size: 14px;"><strong>Amount Due:</strong> ${{amount}}</p>
+                    <p style="margin: 0; color: #666666; font-size: 14px;"><strong>Grace Period Ends:</strong> {{gracePeriodEnd}}</p>
+                  </td>
+                </tr>
+              </table>
+              <p style="color: #333333; font-size: 16px; line-height: 1.6; margin: 20px 0;">This is your last chance to update your payment method and keep your premium features.</p>
+              <div style="background-color: #f5f5f5; padding: 20px; border-radius: 4px; margin: 20px 0;">
+                <p style="color: #333333; font-size: 14px; font-weight: bold; margin: 0 0 10px 0;">After downgrade:</p>
+                <ul style="color: #666666; font-size: 14px; line-height: 1.8; margin: 0; padding-left: 20px;">
+                  <li>Access to premium features will be lost</li>
+                  <li>Data remains safe but with reduced vehicle limits</li>
+                  <li>You can resubscribe at any time</li>
+                </ul>
+              </div>
+              <div style="text-align: center; margin: 30px 0;">
+                <a href="https://app.motovaultpro.com/settings/billing" style="display: inline-block; padding: 14px 28px; background-color: #c62828; color: #ffffff; text-decoration: none; border-radius: 4px; font-weight: bold; font-size: 16px;">Update Payment Now</a>
+              </div>
+            </td>
+          </tr>
+          <tr>
+            <td style="padding: 20px 30px; background-color: #f9f9f9; border-top: 1px solid #e0e0e0;">
+              <p style="color: #666666; font-size: 14px; line-height: 1.6; margin: 0;">Best regards,<br>MotoVaultPro Team</p>
+            </td>
+          </tr>
+        </table>
+      </td>
+    </tr>
+  </table>
+</body>
+</html>'
+  );
--- a/backend/src/features/notifications/migrations/007_subscription_tier_change_template.sql
+++ b/backend/src/features/notifications/migrations/007_subscription_tier_change_template.sql
@@ -0,0 +1,97 @@
+/**
+ * Migration: Add subscription tier change email template
+ * @ai-summary Adds email template for subscription tier change notifications
+ * @ai-context Template sent when tier changes via admin, user action, or grace period expiration
+ */
+
+-- Extend template_key CHECK constraint to include subscription_tier_change
+ALTER TABLE email_templates
+DROP CONSTRAINT IF EXISTS email_templates_template_key_check;
+
+ALTER TABLE email_templates
+ADD CONSTRAINT email_templates_template_key_check
+CHECK (template_key IN (
+  'maintenance_due_soon', 'maintenance_overdue',
+  'document_expiring', 'document_expired',
+  'payment_failed_immediate', 'payment_failed_7day', 'payment_failed_1day',
+  'subscription_tier_change'
+));
+
+-- Insert or update subscription tier change email template
+INSERT INTO email_templates (template_key, name, description, subject, body, variables, html_body) VALUES
+  (
+    'subscription_tier_change',
+    'Subscription Tier Change',
+    'Sent when user subscription tier changes (upgrade, downgrade, or admin override)',
+    'MotoVaultPro: Your Subscription Has Been {{changeType}}',
+    'Hi {{userName}},
+
+Your MotoVaultPro subscription has been {{changeType}}.
+
+Previous Tier: {{previousTier}}
+New Tier: {{newTier}}
+Reason: {{reason}}
+
+{{additionalInfo}}
+
+If you have any questions, please contact support.
+
+Best regards,
+MotoVaultPro Team',
+    '["userName", "changeType", "previousTier", "newTier", "reason", "additionalInfo"]',
+    '<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Subscription Tier Change</title>
+</head>
+<body style="margin: 0; padding: 0; font-family: Arial, sans-serif; background-color: #f4f4f4;">
+  <table width="100%" cellpadding="0" cellspacing="0" style="background-color: #f4f4f4; padding: 20px;">
+    <tr>
+      <td align="center">
+        <table width="600" cellpadding="0" cellspacing="0" style="background-color: #ffffff; border-radius: 8px; overflow: hidden; box-shadow: 0 2px 4px rgba(0,0,0,0.1);">
+          <tr>
+            <td style="background-color: #1976d2; padding: 30px; text-align: center;">
+              <h1 style="color: #ffffff; margin: 0; font-size: 24px;">Subscription {{changeType}}</h1>
+            </td>
+          </tr>
+          <tr>
+            <td style="padding: 40px 30px;">
+              <p style="color: #333333; font-size: 16px; line-height: 1.6; margin: 0 0 20px 0;">Hi {{userName}},</p>
+              <p style="color: #333333; font-size: 16px; line-height: 1.6; margin: 0 0 20px 0;">Your MotoVaultPro subscription has been <strong>{{changeType}}</strong>.</p>
+              <table cellpadding="0" cellspacing="0" style="margin: 20px 0; width: 100%;">
+                <tr>
+                  <td style="padding: 15px; background-color: #f9f9f9; border-left: 4px solid #1976d2;">
+                    <p style="margin: 0 0 10px 0; color: #666666; font-size: 14px;"><strong>Previous Tier:</strong> {{previousTier}}</p>
+                    <p style="margin: 0 0 10px 0; color: #666666; font-size: 14px;"><strong>New Tier:</strong> {{newTier}}</p>
+                    <p style="margin: 0; color: #666666; font-size: 14px;"><strong>Reason:</strong> {{reason}}</p>
+                  </td>
+                </tr>
+              </table>
+              <p style="color: #333333; font-size: 16px; line-height: 1.6; margin: 20px 0;">If you have any questions about this change, please contact our support team.</p>
+              <div style="text-align: center; margin: 30px 0;">
+                <a href="https://motovaultpro.com/settings/billing" style="display: inline-block; padding: 14px 28px; background-color: #1976d2; color: #ffffff; text-decoration: none; border-radius: 4px; font-weight: bold;">View Subscription</a>
+              </div>
+            </td>
+          </tr>
+          <tr>
+            <td style="padding: 20px 30px; background-color: #f9f9f9; border-top: 1px solid #e0e0e0;">
+              <p style="color: #666666; font-size: 14px; line-height: 1.6; margin: 0;">Best regards,<br>MotoVaultPro Team</p>
+            </td>
+          </tr>
+        </table>
+      </td>
+    </tr>
+  </table>
+</body>
+</html>'
+  )
+ON CONFLICT (template_key) DO UPDATE SET
+  name = EXCLUDED.name,
+  description = EXCLUDED.description,
+  subject = EXCLUDED.subject,
+  body = EXCLUDED.body,
+  variables = EXCLUDED.variables,
+  html_body = EXCLUDED.html_body,
+  updated_at = NOW();
--- a/backend/src/features/ocr/CLAUDE.md
+++ b/backend/src/features/ocr/CLAUDE.md
@@ -0,0 +1,47 @@
+# ocr/
+
+Backend proxy for the Python OCR microservice. Handles authentication, tier gating, file validation, and request forwarding for VIN extraction, fuel receipt scanning, and maintenance manual extraction.
+
+## Files
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `README.md` | Feature documentation with architecture diagrams | Understanding OCR proxy, data flows |
+| `index.ts` | Feature barrel export | Importing OCR services |
+
+## Subdirectories
+
+| Directory | What | When to read |
+| --------- | ---- | ------------ |
+| `api/` | HTTP endpoints, routes, request validation | API changes, adding endpoints |
+| `domain/` | Business logic, TypeScript types | Core OCR proxy logic, type definitions |
+| `external/` | HTTP client to Python OCR service | OCR service integration, error handling |
+| `tests/` | Unit tests for receipt and manual extraction | Test changes, adding test coverage |
+
+## api/
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `ocr.controller.ts` | Request handlers for all OCR endpoints (extract, extractVin, extractReceipt, extractManual, submitJob, getJobStatus) | Adding/modifying endpoint behavior |
+| `ocr.routes.ts` | Fastify route registration with auth and tier guard preHandlers | Route configuration, middleware changes |
+| `ocr.validation.ts` | Request/response type definitions for route schemas | Changing request/response shapes |
+
+## domain/
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `ocr.service.ts` | Business logic layer: file validation, size limits (10MB sync, 200MB async), content type checks, service delegation | Core logic changes, validation rules |
+| `ocr.types.ts` | TypeScript types: OcrResponse, VinExtractionResponse, ReceiptExtractionResponse, ManualExtractionResult, JobResponse, ManualJobResponse | Type changes, adding new response shapes |
+
+## external/
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `ocr-client.ts` | HTTP client to mvp-ocr Python service (extract, extractVin, extractReceipt, decodeVin, submitJob, submitManualJob, getJobStatus, isHealthy) | OCR service communication, error handling |
+
+## tests/
+
+| File | What | When to read |
+| ---- | ---- | ------------ |
+| `unit/ocr-receipt.test.ts` | Receipt extraction tests with mock client | Receipt flow changes |
+| `unit/ocr-manual.test.ts` | Manual PDF extraction tests | Manual extraction flow changes |
--- a/Show More
+++ b/Show More