Merge pull request 'Promote to Production: CAR-1276 Phase 1 — auth /health 503 error-log fix' (#286) from uat into main

Promote to Production: CAR-1276 Phase 1 — auth /health 503 error-log fix

UAT PASS (Deal Dottie) + Security PASS (Stockboy Steve) on CAR-1282.
Merged by CEO (Coupon Carl) as production gate.

cc @cpfarhood

.gitea/workflows/ci.yml

@@ -0,0 +1,743 @@
+name: CI
+
+on:
+  push:
+    branches: [main, dev, uat]
+  pull_request:
+    branches: [main, dev, uat]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+  packages: write
+  security-events: write
+
+env:
+  REGISTRY: git.farh.net
+  IMAGE_NAME: cartsnitch/cartsnitch
+  RECEIPTWITNESS_IMAGE_NAME: cartsnitch/receiptwitness
+  API_IMAGE_NAME: cartsnitch/api
+  AUTH_IMAGE_NAME: cartsnitch/auth
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+      - run: npm ci
+      - name: ESLint
+        run: npx eslint .
+      - name: Type check
+        run: npx tsc --noEmit
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
+        with:
+          node-version: "20"
+          cache: npm
+      - run: npm ci
+      - name: Run tests
+        run: npx vitest run
+
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
+        with:
+          node-version: "20"
+          cache: npm
+      - run: npm ci
+      - name: Check for vulnerabilities
+        run: npm audit --audit-level=high
+
+  e2e:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
+        with:
+          node-version: "20"
+          cache: npm
+      - run: npm ci
+      - run: npx playwright install --with-deps chromium
+      - run: npx playwright test
+
+  lighthouse:
+    runs-on: ubuntu-latest
+    needs: [test]
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
+        with:
+          node-version: "20"
+          cache: npm
+      - run: npm ci
+      - run: npm run build
+      - name: Install Chromium for Lighthouse
+        run: |
+          npm install -g playwright
+          npx playwright install --with-deps chromium
+      - name: Start preview server
+        run: |
+          npm run preview &
+          npx wait-on http://localhost:4173/ --timeout 30000
+      - name: Run Lighthouse CI
+        run: |
+          CHROME_PATH=$(find /home/runner/.cache/ms-playwright -name chrome -type f 2>/dev/null | head -1)
+          npm install -g @lhci/cli
+          CHROME_PATH="$CHROME_PATH" lhci autorun --chrome-flags="--headless=new --no-sandbox --disable-gpu --disable-dev-shm-usage"
+
+  build-and-push:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push'
+    needs: [lint, test, e2e]
+    outputs:
+      calver_tag: ${{ steps.calver.outputs.version }}
+      sha_tag: sha-${{ github.sha }}
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+        with:
+          fetch-depth: 0
+
+      - name: Generate CalVer tag
+        id: calver
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        run: |
+          DATE_TAG=$(date -u +%Y.%m.%d)
+          EXISTING=$(git tag -l "v${DATE_TAG}*" | sort -V | tail -1)
+          if [ -z "$EXISTING" ]; then
+            VERSION="$DATE_TAG"
+          elif [ "$EXISTING" = "v${DATE_TAG}" ]; then
+            VERSION="${DATE_TAG}.2"
+          else
+            BUILD_NUM=$(echo "$EXISTING" | sed "s/v${DATE_TAG}\.//")
+            VERSION="${DATE_TAG}.$((BUILD_NUM + 1))"
+          fi
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "CalVer tag: $VERSION"
+
+      - name: Log in to Docker Hub
+        if: github.event_name == 'push'
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Log in to Gitea registry
+        if: github.event_name == 'push'
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.REGISTRY_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=sha,prefix=sha-,format=long
+            type=raw,value=${{ steps.calver.outputs.version }},enable=${{ github.ref == 'refs/heads/main' }}
+            type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' }}
+
+      - name: Build Docker image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          load: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          target: prod
+          cache-from: type=inline
+          cache-to: type=inline,mode=max
+
+      - name: Scan frontend image for vulnerabilities
+        uses: anchore/scan-action@v5
+        id: scan
+        env:
+          GRYPE_CONFIG: .grype.yaml
+        with:
+          image: "${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:sha-${{ github.sha }}"
+          fail-build: true
+          severity-cutoff: high
+          only-fixed: "true"
+          output-format: sarif
+
+
+
+      - name: Push Docker image
+        if: github.event_name == 'push'
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          target: prod
+          cache-from: type=inline
+
+      - name: Create git tag
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        run: |
+          git tag "v${{ steps.calver.outputs.version }}"
+          git push origin "v${{ steps.calver.outputs.version }}"
+
+  build-and-push-receiptwitness:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push'
+    needs: [lint, test]
+    outputs:
+      calver_tag: ${{ steps.calver.outputs.version }}
+      sha_tag: sha-${{ github.sha }}
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+        with:
+          fetch-depth: 0
+
+      - name: Generate CalVer tag
+        id: calver
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        run: |
+          DATE_TAG=$(date -u +%Y.%m.%d)
+          EXISTING=$(git tag -l "v${DATE_TAG}*" | sort -V | tail -1)
+          if [ -z "$EXISTING" ]; then VERSION="$DATE_TAG"
+          elif [ "$EXISTING" = "v${DATE_TAG}" ]; then VERSION="${DATE_TAG}.2"
+          else BUILD_NUM=$(echo "$EXISTING" | sed "s/v${DATE_TAG}\.//"); VERSION="${DATE_TAG}.$((BUILD_NUM + 1))"; fi
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Log in to Docker Hub
+        if: github.event_name == 'push'
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Log in to Gitea registry
+        if: github.event_name == 'push'
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.REGISTRY_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.RECEIPTWITNESS_IMAGE_NAME }}
+          tags: |
+            type=sha,prefix=sha-,format=long
+            type=raw,value=${{ steps.calver.outputs.version }},enable=${{ github.ref == 'refs/heads/main' }}
+            type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' }}
+
+      - name: Build Docker image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ./receiptwitness/Dockerfile
+          load: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          build-args: |
+            APT_CACHE_BUST=${{ github.run_id }}
+          cache-from: type=inline
+          cache-to: type=inline,mode=max
+
+      - name: Scan receiptwitness image for vulnerabilities
+        uses: anchore/scan-action@v5
+        id: scan
+        env:
+          GRYPE_CONFIG: .grype.yaml
+        with:
+          image: "${{ env.REGISTRY }}/${{ env.RECEIPTWITNESS_IMAGE_NAME }}:sha-${{ github.sha }}"
+          fail-build: true
+          severity-cutoff: high
+          only-fixed: "true"
+          output-format: sarif
+
+
+
+      - name: Push Docker image
+        if: github.event_name == 'push'
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: ./receiptwitness/Dockerfile
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          build-args: |
+            APT_CACHE_BUST=${{ github.run_id }}
+          cache-from: type=inline
+
+  build-and-push-api:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push'
+    needs: [lint, test]
+    outputs:
+      calver_tag: ${{ steps.calver.outputs.version }}
+      sha_tag: sha-${{ github.sha }}
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+        with:
+          fetch-depth: 0
+
+      - name: Generate CalVer tag
+        id: calver
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        run: |
+          DATE_TAG=$(date -u +%Y.%m.%d)
+          EXISTING=$(git tag -l "v${DATE_TAG}*" | sort -V | tail -1)
+          if [ -z "$EXISTING" ]; then VERSION="$DATE_TAG"
+          elif [ "$EXISTING" = "v${DATE_TAG}" ]; then VERSION="${DATE_TAG}.2"
+          else BUILD_NUM=$(echo "$EXISTING" | sed "s/v${DATE_TAG}\.//"); VERSION="${DATE_TAG}.$((BUILD_NUM + 1))"; fi
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Log in to Docker Hub
+        if: github.event_name == 'push'
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Log in to Gitea registry
+        if: github.event_name == 'push'
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.REGISTRY_TOKEN }}
+
+      - name: Extract metadata (API)
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.API_IMAGE_NAME }}
+          tags: |
+            type=sha,prefix=sha-,format=long
+            type=raw,value=${{ steps.calver.outputs.version }},enable=${{ github.ref == 'refs/heads/main' }}
+            type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' }}
+
+      - name: Build Docker image
+        uses: docker/build-push-action@v6
+        with:
+          context: ./api
+          file: ./api/Dockerfile
+          load: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          build-args: |
+            APT_CACHE_BUST=${{ github.run_id }}
+          cache-from: type=inline
+          cache-to: type=inline,mode=max
+
+      - name: Scan api image for vulnerabilities
+        uses: anchore/scan-action@v5
+        id: scan
+        env:
+          GRYPE_CONFIG: .grype.yaml
+        with:
+          image: "${{ env.REGISTRY }}/${{ env.API_IMAGE_NAME }}:sha-${{ github.sha }}"
+          fail-build: true
+          severity-cutoff: high
+          only-fixed: "true"
+          output-format: sarif
+
+
+
+      - name: Push Docker image
+        if: github.event_name == 'push'
+        uses: docker/build-push-action@v6
+        with:
+          context: ./api
+          file: ./api/Dockerfile
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          build-args: |
+            APT_CACHE_BUST=${{ github.run_id }}
+          cache-from: type=inline
+
+  build-and-push-auth:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push'
+    needs: [lint, test]
+    outputs:
+      calver_tag: ${{ steps.calver.outputs.version }}
+      sha_tag: sha-${{ github.sha }}
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+        with:
+          fetch-depth: 0
+
+      - name: Generate CalVer tag
+        id: calver
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        run: |
+          DATE_TAG=$(date -u +%Y.%m.%d)
+          EXISTING=$(git tag -l "v${DATE_TAG}*" | sort -V | tail -1)
+          if [ -z "$EXISTING" ]; then VERSION="$DATE_TAG"
+          elif [ "$EXISTING" = "v${DATE_TAG}" ]; then VERSION="${DATE_TAG}.2"
+          else BUILD_NUM=$(echo "$EXISTING" | sed "s/v${DATE_TAG}\.//"); VERSION="${DATE_TAG}.$((BUILD_NUM + 1))"; fi
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Log in to Docker Hub
+        if: github.event_name == 'push'
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Log in to Gitea registry
+        if: github.event_name == 'push'
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.REGISTRY_TOKEN }}
+
+      - name: Extract metadata (auth)
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.AUTH_IMAGE_NAME }}
+          tags: |
+            type=sha,prefix=sha-,format=long
+            type=raw,value=${{ steps.calver.outputs.version }},enable=${{ github.ref == 'refs/heads/main' }}
+            type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' }}
+
+      - name: Build Docker image
+        uses: docker/build-push-action@v6
+        with:
+          context: ./auth
+          file: ./auth/Dockerfile
+          load: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          build-args: |
+            APT_CACHE_BUST=${{ github.run_id }}
+          cache-from: type=inline
+          cache-to: type=inline,mode=max
+
+      - name: Scan auth image for vulnerabilities
+        uses: anchore/scan-action@v5
+        id: scan
+        env:
+          GRYPE_CONFIG: .grype.yaml
+        with:
+          image: "${{ env.REGISTRY }}/${{ env.AUTH_IMAGE_NAME }}:sha-${{ github.sha }}"
+          fail-build: true
+          severity-cutoff: high
+          only-fixed: "true"
+          output-format: sarif
+
+
+
+      - name: Push Docker image
+        if: github.event_name == 'push'
+        uses: docker/build-push-action@v6
+        with:
+          context: ./auth
+          file: ./auth/Dockerfile
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          build-args: |
+            APT_CACHE_BUST=${{ github.run_id }}
+          cache-from: type=inline
+
+  deploy-dev:
+    runs-on: ubuntu-latest
+    needs: [build-and-push, build-and-push-receiptwitness, build-and-push-api, build-and-push-auth]
+    if: always() && !cancelled() && github.event_name == 'push' && (github.ref == 'refs/heads/dev' || github.ref == 'refs/heads/main')
+    steps:
+      - name: Checkout infra repo
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+        with:
+          repository: cartsnitch/infra
+          token: ${{ secrets.CI_GITEA_TOKEN }}
+          ref: main
+          path: infra
+
+      - name: Install kubectl
+        uses: azure/setup-kubectl@v4
+
+      - name: Install kustomize
+        # imranismail/setup-kustomize@v2 calls the Gitea API to record
+        # telemetry under the "kubernetes-sigs" user, which doesn't exist
+        # on this Gitea instance. Install the binary directly instead.
+        run: |
+          set -euo pipefail
+          version="5.4.3"
+          url="https://github.com/kubernetes-sigs/kustomize/releases/download/kustomize%2Fv${version}/kustomize_v${version}_linux_amd64.tar.gz"
+          curl -fsSL --retry 3 "$url" | tar -xz -C /tmp kustomize
+          sudo install -m 0755 /tmp/kustomize /usr/local/bin/kustomize
+          kustomize version
+
+      - name: Determine image tag for frontend
+        id: frontend_tag
+        run: |
+          if [ "${{ github.ref }}" == "refs/heads/main" ]; then
+            echo "tag=${{ needs.build-and-push.outputs.calver_tag }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "tag=${{ needs.build-and-push.outputs.sha_tag }}" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Update frontend image tag
+        if: needs.build-and-push.result == 'success'
+        run: |
+          cd infra/apps/overlays/dev
+          kustomize edit set image ghcr.io/cartsnitch/cartsnitch=git.farh.net/cartsnitch/cartsnitch:${{ steps.frontend_tag.outputs.tag }}
+
+      - name: Determine image tag for receiptwitness
+        id: receiptwitness_tag
+        run: |
+          if [ "${{ github.ref }}" == "refs/heads/main" ]; then
+            echo "tag=${{ needs.build-and-push-receiptwitness.outputs.calver_tag }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "tag=${{ needs.build-and-push-receiptwitness.outputs.sha_tag }}" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Update receiptwitness image tag
+        if: needs.build-and-push-receiptwitness.result == 'success'
+        run: |
+          cd infra/apps/overlays/dev
+          kustomize edit set image ghcr.io/cartsnitch/receiptwitness=git.farh.net/cartsnitch/receiptwitness:${{ steps.receiptwitness_tag.outputs.tag }}
+
+      - name: Determine image tag for api
+        id: api_tag
+        run: |
+          if [ "${{ github.ref }}" == "refs/heads/main" ]; then
+            echo "tag=${{ needs.build-and-push-api.outputs.calver_tag }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "tag=${{ needs.build-and-push-api.outputs.sha_tag }}" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Update api image tag
+        if: needs.build-and-push-api.result == 'success'
+        run: |
+          cd infra/apps/overlays/dev
+          kustomize edit set image ghcr.io/cartsnitch/api=git.farh.net/cartsnitch/api:${{ steps.api_tag.outputs.tag }}
+
+      - name: Determine image tag for auth
+        id: auth_tag
+        run: |
+          if [ "${{ github.ref }}" == "refs/heads/main" ]; then
+            echo "tag=${{ needs.build-and-push-auth.outputs.calver_tag }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "tag=${{ needs.build-and-push-auth.outputs.sha_tag }}" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Update auth image tag
+        if: needs.build-and-push-auth.result == 'success'
+        run: |
+          cd infra/apps/overlays/dev
+          kustomize edit set image ghcr.io/cartsnitch/auth=git.farh.net/cartsnitch/auth:${{ steps.auth_tag.outputs.tag }}
+
+      - name: Commit and push to infra (via PR)
+        env:
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+        run: |
+          cd infra
+          git config user.name "cartsnitch-ci[bot]"
+          git config user.email "cartsnitch-ci[bot]@users.noreply.git.farh.net"
+          git add apps/overlays/dev/kustomization.yaml
+          git diff --cached --quiet && echo "No image changes to deploy" && exit 0
+          BRANCH="ci/deploy-dev-${GITHUB_SHA}"
+          git checkout -b "$BRANCH"
+          git commit -m "ci(dev): update cartsnitch, receiptwitness, api, and auth images"
+          git push origin "$BRANCH"
+          PR_BODY=$(printf 'Auto-opened by deploy-dev (CAR-1195).\n\nBuild SHA: %s' "${GITHUB_SHA}")
+          PR_JSON=$(curl -sS -X POST \
+            -H "Authorization: token ${CI_GITEA_TOKEN}" \
+            -H "Content-Type: application/json" \
+            -d "$(jq -n --arg head "cartsnitch:${BRANCH}" --arg base main --arg title "ci(dev): update overlay image tags (${GITHUB_SHA::12})" --arg body "$PR_BODY" '{head:$head,base:$base,title:$title,body:$body}')" \
+            "https://git.farh.net/api/v1/repos/cartsnitch/infra/pulls")
+          PR_NUM=$(echo "$PR_JSON" | jq -r '.number // empty')
+          if [ -z "$PR_NUM" ]; then
+            echo "::error::Failed to open PR against cartsnitch/infra: $PR_JSON"
+            exit 1
+          fi
+          echo "Opened cartsnitch/infra PR #${PR_NUM} (head=${BRANCH})"
+          # Request CTO (cs_savannah) review as the GitOps hand-off. Best-effort:
+          # log on non-2xx but never fail the job for this.
+          REVIEW_HTTP=$(curl -sS -o /dev/null -w '%{http_code}' -X POST \
+            -H "Authorization: token ${CI_GITEA_TOKEN}" \
+            -H "Content-Type: application/json" \
+            -d '{"reviewers":["cs_savannah"]}' \
+            "https://git.farh.net/api/v1/repos/cartsnitch/infra/pulls/${PR_NUM}/requested_reviewers")
+          if [ "${REVIEW_HTTP}" -lt 200 ] || [ "${REVIEW_HTTP}" -ge 300 ]; then
+            echo "::notice::Failed to request reviewers for cartsnitch/infra PR #${PR_NUM} (HTTP ${REVIEW_HTTP}); continuing"
+          fi
+          MERGE_RESP=$(curl -sS -X POST \
+            -H "Authorization: token ${CI_GITEA_TOKEN}" \
+            -H "Content-Type: application/json" \
+            -d '{"Do":"merge","delete_branch_after_merge":true}' \
+            "https://git.farh.net/api/v1/repos/cartsnitch/infra/pulls/${PR_NUM}/merge")
+          MERGED=$(echo "$MERGE_RESP" | jq -r '.merged // false')
+          if [ "$MERGED" = "true" ]; then
+            echo "PR #${PR_NUM} merged into cartsnitch/infra main"
+          elif echo "$MERGE_RESP" | grep -qi 'does not have enough approvals'; then
+            # GitOps approval gate: the PR is correctly opened and surfaces in
+            # the CTO queue via the reviewers request above. Treat as success
+            # (exit 0) so the deploy job does not hard-fail on the approvals
+            # requirement that only a human maintainer can satisfy.
+            echo "::notice::infra PR #${PR_NUM} opened and awaiting CTO (cs_savannah) approve+merge — GitOps approval gate, not a failure"
+            exit 0
+          else
+            echo "::error::Auto-merge of cartsnitch/infra PR #${PR_NUM} failed: $MERGE_RESP"
+            echo "::error::Reassign to cs_savannah (authorized merger for cartsnitch/infra main) for backstop merge."
+            exit 1
+          fi
+
+  deploy-uat:
+    runs-on: ubuntu-latest
+    needs: [build-and-push, build-and-push-receiptwitness, build-and-push-api, build-and-push-auth]
+    if: always() && !cancelled() && github.event_name == 'push' && (github.ref == 'refs/heads/uat' || github.ref == 'refs/heads/main')
+    steps:
+      - name: Checkout infra repo
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+        with:
+          repository: cartsnitch/infra
+          token: ${{ secrets.CI_GITEA_TOKEN }}
+          ref: main
+          path: infra
+
+      - name: Install kubectl
+        uses: azure/setup-kubectl@v4
+
+      - name: Install kustomize
+        # imranismail/setup-kustomize@v2 calls the Gitea API to record
+        # telemetry under the "kubernetes-sigs" user, which doesn't exist
+        # on this Gitea instance. Install the binary directly instead.
+        run: |
+          set -euo pipefail
+          version="5.4.3"
+          url="https://github.com/kubernetes-sigs/kustomize/releases/download/kustomize%2Fv${version}/kustomize_v${version}_linux_amd64.tar.gz"
+          curl -fsSL --retry 3 "$url" | tar -xz -C /tmp kustomize
+          sudo install -m 0755 /tmp/kustomize /usr/local/bin/kustomize
+          kustomize version
+
+      - name: Determine image tag for frontend
+        id: frontend_tag
+        run: |
+          if [ "${{ github.ref }}" == "refs/heads/main" ]; then
+            echo "tag=${{ needs.build-and-push.outputs.calver_tag }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "tag=${{ needs.build-and-push.outputs.sha_tag }}" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Update frontend image tag
+        if: needs.build-and-push.result == 'success'
+        run: |
+          cd infra/apps/overlays/uat
+          kustomize edit set image ghcr.io/cartsnitch/cartsnitch=git.farh.net/cartsnitch/cartsnitch:${{ steps.frontend_tag.outputs.tag }}
+
+      - name: Determine image tag for receiptwitness
+        id: receiptwitness_tag
+        run: |
+          if [ "${{ github.ref }}" == "refs/heads/main" ]; then
+            echo "tag=${{ needs.build-and-push-receiptwitness.outputs.calver_tag }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "tag=${{ needs.build-and-push-receiptwitness.outputs.sha_tag }}" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Update receiptwitness image tag
+        if: needs.build-and-push-receiptwitness.result == 'success'
+        run: |
+          cd infra/apps/overlays/uat
+          kustomize edit set image ghcr.io/cartsnitch/receiptwitness=git.farh.net/cartsnitch/receiptwitness:${{ steps.receiptwitness_tag.outputs.tag }}
+
+      - name: Determine image tag for api
+        id: api_tag
+        run: |
+          if [ "${{ github.ref }}" == "refs/heads/main" ]; then
+            echo "tag=${{ needs.build-and-push-api.outputs.calver_tag }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "tag=${{ needs.build-and-push-api.outputs.sha_tag }}" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Update api image tag
+        if: needs.build-and-push-api.result == 'success'
+        run: |
+          cd infra/apps/overlays/uat
+          kustomize edit set image ghcr.io/cartsnitch/api=git.farh.net/cartsnitch/api:${{ steps.api_tag.outputs.tag }}
+
+      - name: Determine image tag for auth
+        id: auth_tag
+        run: |
+          if [ "${{ github.ref }}" == "refs/heads/main" ]; then
+            echo "tag=${{ needs.build-and-push-auth.outputs.calver_tag }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "tag=${{ needs.build-and-push-auth.outputs.sha_tag }}" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Update auth image tag
+        if: needs.build-and-push-auth.result == 'success'
+        run: |
+          cd infra/apps/overlays/uat
+          kustomize edit set image ghcr.io/cartsnitch/auth=git.farh.net/cartsnitch/auth:${{ steps.auth_tag.outputs.tag }}
+
+      - name: Commit and push to infra (via PR)
+        env:
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+        run: |
+          cd infra
+          git config user.name "cartsnitch-ci[bot]"
+          git config user.email "cartsnitch-ci[bot]@users.noreply.git.farh.net"
+          git add apps/overlays/uat/kustomization.yaml
+          git diff --cached --quiet && echo "No image changes to deploy" && exit 0
+          BRANCH="ci/deploy-uat-${GITHUB_SHA}"
+          git checkout -b "$BRANCH"
+          git commit -m "ci(uat): update cartsnitch, receiptwitness, api, and auth images"
+          git push origin "$BRANCH"
+          PR_BODY=$(printf 'Auto-opened by deploy-uat (CAR-1195).\n\nBuild SHA: %s' "${GITHUB_SHA}")
+          PR_JSON=$(curl -sS -X POST \
+            -H "Authorization: token ${CI_GITEA_TOKEN}" \
+            -H "Content-Type: application/json" \
+            -d "$(jq -n --arg head "cartsnitch:${BRANCH}" --arg base main --arg title "ci(uat): update overlay image tags (${GITHUB_SHA::12})" --arg body "$PR_BODY" '{head:$head,base:$base,title:$title,body:$body}')" \
+            "https://git.farh.net/api/v1/repos/cartsnitch/infra/pulls")
+          PR_NUM=$(echo "$PR_JSON" | jq -r '.number // empty')
+          if [ -z "$PR_NUM" ]; then
+            echo "::error::Failed to open PR against cartsnitch/infra: $PR_JSON"
+            exit 1
+          fi
+          echo "Opened cartsnitch/infra PR #${PR_NUM} (head=${BRANCH})"
+          # Request CTO (cs_savannah) review as the GitOps hand-off. Best-effort:
+          # log on non-2xx but never fail the job for this.
+          REVIEW_HTTP=$(curl -sS -o /dev/null -w '%{http_code}' -X POST \
+            -H "Authorization: token ${CI_GITEA_TOKEN}" \
+            -H "Content-Type: application/json" \
+            -d '{"reviewers":["cs_savannah"]}' \
+            "https://git.farh.net/api/v1/repos/cartsnitch/infra/pulls/${PR_NUM}/requested_reviewers")
+          if [ "${REVIEW_HTTP}" -lt 200 ] || [ "${REVIEW_HTTP}" -ge 300 ]; then
+            echo "::notice::Failed to request reviewers for cartsnitch/infra PR #${PR_NUM} (HTTP ${REVIEW_HTTP}); continuing"
+          fi
+          MERGE_RESP=$(curl -sS -X POST \
+            -H "Authorization: token ${CI_GITEA_TOKEN}" \
+            -H "Content-Type: application/json" \
+            -d '{"Do":"merge","delete_branch_after_merge":true}' \
+            "https://git.farh.net/api/v1/repos/cartsnitch/infra/pulls/${PR_NUM}/merge")
+          MERGED=$(echo "$MERGE_RESP" | jq -r '.merged // false')
+          if [ "$MERGED" = "true" ]; then
+            echo "PR #${PR_NUM} merged into cartsnitch/infra main"
+          elif echo "$MERGE_RESP" | grep -qi 'does not have enough approvals'; then
+            # GitOps approval gate: the PR is correctly opened and surfaces in
+            # the CTO queue via the reviewers request above. Treat as success
+            # (exit 0) so the deploy job does not hard-fail on the approvals
+            # requirement that only a human maintainer can satisfy.
+            echo "::notice::infra PR #${PR_NUM} opened and awaiting CTO (cs_savannah) approve+merge — GitOps approval gate, not a failure"
+            exit 0
+          else
+            echo "::error::Auto-merge of cartsnitch/infra PR #${PR_NUM} failed: $MERGE_RESP"
+            echo "::error::Reassign to cs_savannah (authorized merger for cartsnitch/infra main) for backstop merge."
+            exit 1
+          fi

.github/workflows/ci.yml

@@ -1,162 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-
-concurrency:
-  group: ci-${{ github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: write
-  packages: write
-
-env:
-  REGISTRY: ghcr.io
-  IMAGE_NAME: cartsnitch/cartsnitch
-  AUTH_IMAGE_NAME: cartsnitch/auth
-
-jobs:
-  lint:
-    runs-on: runners-cartsnitch
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: "20"
-          cache: npm
-      - run: npm ci
-      - name: ESLint
-        run: npx eslint .
-      - name: Type check
-        run: npx tsc --noEmit
-
-  test:
-    runs-on: runners-cartsnitch
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: "20"
-          cache: npm
-      - run: npm ci
-      - name: Run tests
-        run: npx vitest run
-
-  build-and-push:
-    runs-on: runners-cartsnitch
-    needs: [lint, test]
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Generate CalVer tag
-        id: calver
-        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-        run: |
-          DATE_TAG=$(date -u +%Y.%m.%d)
-          EXISTING=$(git tag -l "v${DATE_TAG}*" | sort -V | tail -1)
-          if [ -z "$EXISTING" ]; then
-            VERSION="$DATE_TAG"
-          elif [ "$EXISTING" = "v${DATE_TAG}" ]; then
-            VERSION="${DATE_TAG}.2"
-          else
-            BUILD_NUM=$(echo "$EXISTING" | sed "s/v${DATE_TAG}\.//")
-            VERSION="${DATE_TAG}.$((BUILD_NUM + 1))"
-          fi
-          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
-          echo "CalVer tag: $VERSION"
-
-      - name: Log in to Docker Hub
-        uses: docker/login-action@v3
-        with:
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
-
-      - name: Log in to GHCR
-        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-        uses: docker/login-action@v3
-        with:
-          registry: ${{ env.REGISTRY }}
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Extract metadata
-        id: meta
-        uses: docker/metadata-action@v5
-        with:
-          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
-          tags: |
-            type=sha,prefix=sha-
-            type=raw,value=${{ steps.calver.outputs.version }},enable=${{ github.ref == 'refs/heads/main' }}
-            type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' }}
-
-      - name: Build and push Docker image
-        uses: docker/build-push-action@v6
-        with:
-          context: .
-          push: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
-          tags: ${{ steps.meta.outputs.tags }}
-          labels: ${{ steps.meta.outputs.labels }}
-          target: prod
-
-      - name: Create git tag
-        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-        run: |
-          git tag "v${{ steps.calver.outputs.version }}"
-          git push origin "v${{ steps.calver.outputs.version }}"
-
-  build-and-push-auth:
-    runs-on: runners-cartsnitch
-    needs: [lint, test]
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Generate CalVer tag
-        id: calver
-        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-        run: |
-          DATE_TAG=$(date -u +%Y.%m.%d)
-          EXISTING=$(git tag -l "v${DATE_TAG}*" | sort -V | tail -1)
-          if [ -z "$EXISTING" ]; then
-            VERSION="$DATE_TAG"
-          elif [ "$EXISTING" = "v${DATE_TAG}" ]; then
-            VERSION="${DATE_TAG}.2"
-          else
-            BUILD_NUM=$(echo "$EXISTING" | sed "s/v${DATE_TAG}\.//")
-            VERSION="${DATE_TAG}.$((BUILD_NUM + 1))"
-          fi
-          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
-
-      - name: Log in to GHCR
-        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-        uses: docker/login-action@v3
-        with:
-          registry: ${{ env.REGISTRY }}
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Extract metadata (auth)
-        id: meta
-        uses: docker/metadata-action@v5
-        with:
-          images: ${{ env.REGISTRY }}/${{ env.AUTH_IMAGE_NAME }}
-          tags: |
-            type=sha,prefix=sha-
-            type=raw,value=${{ steps.calver.outputs.version }},enable=${{ github.ref == 'refs/heads/main' }}
-            type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' }}
-
-      - name: Build and push auth Docker image
-        uses: docker/build-push-action@v6
-        with:
-          context: ./auth
-          file: ./auth/Dockerfile
-          push: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
-          tags: ${{ steps.meta.outputs.tags }}
-          labels: ${{ steps.meta.outputs.labels }}

.grype.yaml

@@ -0,0 +1,108 @@
+ignore:
+  # Python 3.12 CVEs — only fixed in 3.13+, cannot upgrade major version safely
+  - vulnerability: CVE-2025-13836
+  - vulnerability: CVE-2026-4519
+
+  # Chrome CVEs — Playwright bundles Chromium and controls version separately.
+  # Chrome is not a system package that can be upgraded via apt-get upgrade.
+  # These CVEs are specific to the Chromium version bundled with Playwright.
+  # Upstream fix: upgrade Playwright to a version that includes patched Chrome.
+  - vulnerability: CVE-2026-2313
+  - vulnerability: CVE-2026-2314
+  - vulnerability: CVE-2026-2315
+  - vulnerability: CVE-2026-2319
+  - vulnerability: CVE-2026-2321
+  - vulnerability: CVE-2026-2441
+  - vulnerability: CVE-2026-2648
+  - vulnerability: CVE-2026-2649
+  - vulnerability: CVE-2026-2650
+  - vulnerability: CVE-2026-3061
+  - vulnerability: CVE-2026-3062
+  - vulnerability: CVE-2026-3536
+  - vulnerability: CVE-2026-3537
+  - vulnerability: CVE-2026-3538
+  - vulnerability: CVE-2026-3539
+  - vulnerability: CVE-2026-3540
+  - vulnerability: CVE-2026-3541
+  - vulnerability: CVE-2026-3542
+  - vulnerability: CVE-2026-3543
+  - vulnerability: CVE-2026-3544
+  - vulnerability: CVE-2026-3545
+  - vulnerability: CVE-2026-3913
+  - vulnerability: CVE-2026-3914
+  - vulnerability: CVE-2026-3915
+  - vulnerability: CVE-2026-3916
+  - vulnerability: CVE-2026-3917
+  - vulnerability: CVE-2026-3918
+  - vulnerability: CVE-2026-3919
+  - vulnerability: CVE-2026-3920
+  - vulnerability: CVE-2026-3921
+  - vulnerability: CVE-2026-3922
+  - vulnerability: CVE-2026-3923
+  - vulnerability: CVE-2026-3924
+  - vulnerability: CVE-2026-3926
+  - vulnerability: CVE-2026-3931
+  - vulnerability: CVE-2026-3932
+  - vulnerability: CVE-2026-3936
+  - vulnerability: CVE-2026-5858
+  - vulnerability: CVE-2026-5859
+  - vulnerability: CVE-2026-5860
+  - vulnerability: CVE-2026-5861
+  - vulnerability: CVE-2026-5862
+  - vulnerability: CVE-2026-5863
+  - vulnerability: CVE-2026-5865
+  - vulnerability: CVE-2026-5866
+  - vulnerability: CVE-2026-5868
+  - vulnerability: CVE-2026-5870
+  - vulnerability: CVE-2026-5871
+  - vulnerability: CVE-2026-5872
+  - vulnerability: CVE-2026-5873
+  - vulnerability: CVE-2026-5874
+  - vulnerability: CVE-2026-5877
+  - vulnerability: CVE-2026-5879
+  - vulnerability: CVE-2026-5883
+  - vulnerability: CVE-2026-5884
+  - vulnerability: CVE-2026-5902
+  - vulnerability: CVE-2026-5904
+  - vulnerability: CVE-2026-5907
+  - vulnerability: CVE-2026-5908
+  - vulnerability: CVE-2026-5909
+  - vulnerability: CVE-2026-5910
+  - vulnerability: CVE-2026-5912
+  - vulnerability: CVE-2026-5913
+  - vulnerability: CVE-2026-5914
+  - vulnerability: CVE-2026-5915
+  - vulnerability: CVE-2026-6296
+  - vulnerability: CVE-2026-6297
+  - vulnerability: CVE-2026-6299
+  - vulnerability: CVE-2026-6300
+  - vulnerability: CVE-2026-6301
+  - vulnerability: CVE-2026-6302
+  - vulnerability: CVE-2026-6303
+  - vulnerability: CVE-2026-6304
+  - vulnerability: CVE-2026-6305
+  - vulnerability: CVE-2026-6306
+  - vulnerability: CVE-2026-6307
+  - vulnerability: CVE-2026-6308
+  - vulnerability: CVE-2026-6309
+  - vulnerability: CVE-2026-6310
+  - vulnerability: CVE-2026-6311
+  - vulnerability: CVE-2026-6314
+  - vulnerability: CVE-2026-6315
+  - vulnerability: CVE-2026-6316
+  - vulnerability: CVE-2026-6317
+  - vulnerability: CVE-2026-6318
+  - vulnerability: CVE-2026-6319
+  - vulnerability: CVE-2026-6358
+  - vulnerability: CVE-2026-6359
+  - vulnerability: CVE-2026-6360
+  - vulnerability: CVE-2026-6361
+  - vulnerability: CVE-2026-6363
+
+  # Node.js CVE — comes from Playwright's bundled tooling (playwright-core uses Node.js
+  # for its CLI). The system Node.js is not used by receiptwitness service.
+  # Fix requires upgrading Playwright to a version that ships with patched Node.js.
+  - vulnerability: CVE-2026-21710
+
+  # cryptography GHSA — fixed by upgrading to >=46.0 per requirements
+  - vulnerability: GHSA-r6ph-v2qm-q3c2

Dockerfile

@@ -1,6 +1,6 @@
 # Stage 1: Build
 FROM node:20-alpine AS build
-
+RUN apk update && apk upgrade --no-cache
 WORKDIR /app
 
 COPY package.json package-lock.json ./
@@ -11,6 +11,9 @@ RUN npm run build
 
 # Stage 2: Production — uses nginxinc/nginx-unprivileged which runs as non-root (UID 101)
 FROM nginxinc/nginx-unprivileged:stable-alpine AS prod
+USER root
+RUN apk update && apk upgrade --no-cache
+USER 101
 
 COPY --from=build /app/dist /usr/share/nginx/html
 COPY nginx.conf /etc/nginx/conf.d/default.conf

README.md

@@ -1,45 +1,315 @@
-# CartSnitch Monorepo
+# CartSnitch
 
-CartSnitch is a self-hosted grocery price intelligence platform. This repo consolidates the core services and the flagship frontend PWA.
+**Grocery price intelligence — know what you're paying, every time.**
 
-## Services
+CartSnitch is a self-hosted grocery price intelligence platform that connects to your store loyalty accounts, tracks prices across retailers, monitors shrinkflation, and helps you find the best deals.
 
-| Directory | Service | Purpose |
-|-----------|---------|---------|
-| `/` (root) | **Frontend** | React 18 PWA — mobile-first price intelligence UI |
-| `api/` | **API Gateway** | FastAPI — frontend-facing REST API |
-| `common/` | **Common** | Shared Python models, schemas, Alembic migrations |
-| `receiptwitness/` | **ReceiptWitness** | Purchase ingestion via retailer scrapers |
+---
 
-## Quick Start
+## Project Overview
 
-### Frontend (root)
+CartSnitch solves the problem of **grocery price opacity**. Most shoppers don't know if they're getting a good deal, whether prices have spiked since their last visit, or if the "sale" is actually a worse price than a competitor. CartSnitch makes prices transparent.
 
-```bash
-npm install
-npm run dev        # http://localhost:5173
-npm run build      # production build
-npm run test       # unit tests (Vitest)
-```
+**Core features:**
+- Connect Meijer, Kroger, Target loyalty accounts
+- View purchase history across all stores in one timeline
+- Track per-item price charts across stores over time
+- Receive shrinkflation and price increase alerts
+- Browse active coupons and deals
+- Generate optimized shopping lists with store-split plans
+- Public price transparency dashboards
 
-### Python Services
-
-Each Python service uses [uv](https://github.com/astral-sh/uv) and has its own `pyproject.toml`:
-
-```bash
-cd api             # or common / receiptwitness
-uv sync
-uv run pytest
-```
-
-## Development Workflow
-
-- **Never push directly to main.** Always open a PR from a feature branch.
-- Branch naming: `feature/<description>` or `fix/<description>`
-- Conventional commits: `feat:`, `fix:`, `refactor:`, `docs:`, `chore:`
+---
 
 ## Architecture
 
-For full details see [CLAUDE.md](./CLAUDE.md) or the per-service `CLAUDE.md` in each subdirectory.
+CartSnitch is a polyglot microservices platform. The monorepo contains the frontend PWA and core services.
 
-CartSnitch is a polyrepo-style monorepo: each service can be built and deployed independently, but sharing code between `common/` and the other Python services is done via local path dependencies in `pyproject.toml`.
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         CartSnitch PWA                          │
+│                    (React, mobile-first PWA)                     │
+└──────────┬────────────────────┬────────────────────┬───────────┘
+           │                    │                    │
+           ▼                    ▼                    ▼
+┌──────────────────┐  ┌─────────────────┐  ┌─────────────────────┐
+│   Auth Service   │  │   API Gateway   │  │  ReceiptWitness     │
+│  (Better-Auth)   │  │ (Python/FastAPI)│  │   (Python/Scrapers) │
+│  Session mgmt   │  │  REST + proxy   │  │  Purchase ingestion  │
+└────────┬─────────┘  └────────┬────────┘  └──────────┬──────────┘
+         │                      │                        │
+         └──────────────────────┼────────────────────────┘
+                                ▼
+                   ┌────────────────────────┐
+                   │   CloudNativePG (PGSQL) │
+                   │   Shared database      │
+                   └────────────────────────┘
+```
+
+### Services in This Repo
+
+| Directory | Service | Description |
+|-----------|---------|-------------|
+| `/` (root) | Frontend | React PWA, mobile-first |
+| `auth/` | Auth | Better-Auth service — session management, email/password, OAuth |
+| `api/` | API Gateway | Frontend-facing REST API, Python/FastAPI |
+| `common/` | Common | Shared Python models, Pydantic schemas, Alembic migrations |
+| `receiptwitness/` | ReceiptWitness | Purchase data ingestion via retailer scrapers |
+
+### Other CartSnitch Repos
+
+| Repo | Service |
+|------|---------|
+| `cartsnitch/stickershock` | Price increase detection & CPI comparison |
+| `cartsnitch/shrinkray` | Shrinkflation monitoring |
+| `cartsnitch/clipartist` | Coupon/deal watching |
+| `cartsnitch/infra` | Kubernetes manifests, Flux kustomizations |
+
+---
+
+## Tech Stack
+
+### Frontend
+- **React 18+** with TypeScript
+- **Vite** — build tool
+- **Tailwind CSS v4** — mobile-first responsive design
+- **Workbox** — service worker, offline caching, PWA manifest
+- **Recharts** — price trend visualizations
+- **TanStack Query** — data fetching and caching
+- **React Router v7** — client-side routing
+- **Zustand** — lightweight state management
+
+### Backend Services
+- **Better-Auth** — authentication (session management, email/password, OAuth)
+- **Node.js** (API Gateway)
+- **Python/FastAPI** (API Gateway, ReceiptWitness)
+- **PostgreSQL** via CloudNativePG
+- **DragonflyDB** for caching
+
+### Infrastructure
+- **Kubernetes** (k3s-compatible)
+- **Flux CD** — GitOps deployment
+- **GitHub Actions** — CI/CD
+- **CalVer** (`YYYY.MM.DD[.N]`) — image tagging
+- **Bitnami Sealed Secrets** — secret management
+- **Authentik** — OIDC/OAuth2 provider
+
+---
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 20+
+- npm or pnpm
+- PostgreSQL (local or containerized)
+- Docker (for running services locally)
+
+### Local Development
+
+1. **Clone the repo**
+   ```bash
+   git clone https://github.com/cartsnitch/cartsnitch.git
+   cd cartsnitch
+   ```
+
+2. **Install dependencies**
+   ```bash
+   npm install
+   ```
+
+3. **Set up environment variables**
+   ```bash
+   cp .env.example .env
+   # Edit .env with your local settings
+   ```
+
+4. **Start the frontend dev server**
+   ```bash
+   npm run dev
+   ```
+   The PWA will be available at `http://localhost:5173`.
+
+5. **Run tests**
+   ```bash
+   npm test
+   ```
+
+6. **Build for production**
+   ```bash
+   npm run build
+   ```
+
+### Running Backend Services Locally
+
+The frontend PWA communicates with three backend services. For full local development, you'll need to run each service:
+
+```bash
+# Auth service (Better-Auth)
+cd auth
+npm install
+npm run dev
+
+# API Gateway (separate repo: cartsnitch/api)
+# See api/README.md
+
+# ReceiptWitness (separate repo: cartsnitch/receiptwitness)
+# See receiptwitness/README.md
+```
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `VITE_API_URL` | API Gateway base URL | `http://localhost:3000` |
+| `VITE_AUTH_URL` | Auth service base URL | `http://localhost:3001` |
+
+---
+
+## Contributing
+
+We welcome contributions. Please follow the workflow below.
+
+### Branching Strategy
+
+- Branch from `dev`
+- Use prefix: `feature/`, `fix/`, `docs/`, `chore/`
+- Examples: `feature/shopping-list-optimization`, `fix/price-chart-zoom`
+
+### Commit Convention
+
+We use [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+feat: add shopping list export
+fix: correct price chart date formatting
+docs: update API documentation
+chore: update dependencies
+```
+
+### Pull Request Workflow
+
+1. Open a PR against `dev`
+2. CI must pass (lint, type check, tests, e2e)
+3. QA reviews and approves
+4. CTO merges to `dev`
+5. Dev deploys automatically
+6. CTO promotes `dev → uat`
+7. UAT and security review
+8. CEO merges `uat → main`
+9. Production deploys automatically
+
+**Never push directly to `main`, `dev`, or `uat`.**
+
+### Code Standards
+
+- ESLint for linting
+- TypeScript strict mode
+- Mobile-first responsive design
+- Accessibility (WCAG 2.1 AA)
+
+---
+
+## Testing
+
+### Unit Tests
+
+```bash
+npm test
+```
+
+### E2E Tests (Playwright)
+
+```bash
+npm run test:e2e
+```
+
+Tests run headless by default. For headed mode:
+
+```bash
+npm run test:e2e:headed
+```
+
+### Lighthouse CI
+
+Performance audits run automatically in CI. To run locally:
+
+```bash
+npm run build
+npm run preview
+# In another terminal:
+npx lighthouse http://localhost:4173 --output=html --output-path=./report/lighthouse.html
+```
+
+---
+
+## CI/CD Pipeline
+
+All branches (`main`, `dev`, `uat`) run through GitHub Actions on every push.
+
+### Pipeline Stages
+
+| Job | Trigger | Purpose |
+|-----|---------|---------|
+| `lint` | Every push | ESLint + TypeScript type check |
+| `test` | Every push | Unit tests via Vitest |
+| `audit` | Every push | Security vulnerability scan |
+| `e2e` | Every push | Playwright end-to-end tests |
+| `lighthouse` | After test | Performance budget check |
+| `build-and-push` | On push to main/dev/uat | Build and push Docker images to GHCR |
+| `deploy-dev` | On push to dev or main | Update `cartsnitch/infra` → auto-deploy to dev |
+| `deploy-uat` | On push to uat or main | Update `cartsnitch/infra` → auto-deploy to uat |
+
+### Image Tagging
+
+- **Production (`main`):** CalVer tag (`YYYY.MM.DD[.N]`) + `latest`
+- **Development (`dev`):** SHA tag (`sha-<short-sha>`)
+
+### Deployment Environments
+
+| Environment | Namespace | URL | Trigger |
+|-------------|-----------|-----|---------|
+| Dev | `cartsnitch-dev` | `cartsnitch.dev.farh.net` | Push to `dev` branch |
+| UAT | `cartsnitch-uat` | `cartsnitch.uat.farh.net` | Push to `uat` branch |
+| Production | `cartsnitch` | `cartsnitch.farh.net` | Push to `main` branch |
+
+---
+
+## Deployment
+
+### Infrastructure
+
+The infrastructure repository ([cartsnitch/infra](https://github.com/cartsnitch/infra)) contains Kubernetes manifests and Flux Kustomize overlays.
+
+### Flux GitOps Flow
+
+1. CI builds and pushes a new Docker image
+2. CI opens a PR to `cartsnitch/infra` updating the image tag
+3. On merge, Flux reconciles the manifests and rolls out the new image
+
+### Forcing a Rollout
+
+To force pods to pick up a new `:latest` image:
+
+```bash
+kubectl rollout restart deployment/<name> -n <namespace>
+```
+
+### Secrets
+
+Secrets are managed via **Bitnami Sealed Secrets**. No plain Kubernetes secrets are used.
+
+---
+
+## Related Projects
+
+- [StickerShock](https://github.com/cartsnitch/stickershock) — Price increase detection
+- [ShrinkRay](https://github.com/cartsnitch/shrinkray) — Shrinkflation monitoring
+- [ClipArtist](https://github.com/cartsnitch/clipartist) — Coupon/deal optimization
+- [Infra](https://github.com/cartsnitch/infra) — Kubernetes infrastructure
+
+---
+
+## License
+
+MIT &copy; 2025 CartSnitch

api/.gitea/workflows/ci.yml

@@ -15,7 +15,7 @@ permissions:
   packages: write
 
 env:
-  REGISTRY: ghcr.io
+  REGISTRY: git.farh.net
   IMAGE_NAME: cartsnitch/api
 
 jobs:
@@ -130,13 +130,13 @@ jobs:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
-      - name: Log in to GHCR
+      - name: Log in to Gitea registry
         if: github.event_name == 'push' && github.ref == 'refs/heads/main'
         uses: docker/login-action@v3
         with:
           registry: ${{ env.REGISTRY }}
           username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
+          password: ${{ secrets.REGISTRY_TOKEN }}
 
       - name: Extract metadata
         id: meta

api/Dockerfile

@@ -1,6 +1,7 @@
 FROM python:3.12-slim AS build
 
-RUN apt-get update && apt-get install -y --no-install-recommends \
+ARG APT_CACHE_BUST=0
+RUN apt-get update && apt-get upgrade -y && apt-get install -y --no-install-recommends \
     libpq-dev \
     build-essential \
     && rm -rf /var/lib/apt/lists/*
@@ -12,10 +13,15 @@ RUN pip install --no-cache-dir --prefix=/install .
 
 FROM python:3.12-slim AS prod
 
+ARG APT_CACHE_BUST=0
+RUN apt-get update && apt-get upgrade -y && apt-get install -y --no-install-recommends libpq5 && rm -rf /var/lib/apt/lists/*
+
 WORKDIR /app
 RUN adduser --system --group --uid 1000 app
 COPY --from=build /install /usr/local
 COPY src/ ./src/
+COPY alembic.ini ./
+COPY alembic/ ./alembic/
 
 USER 1000
 EXPOSE 8000
@@ -23,4 +29,4 @@ EXPOSE 8000
 HEALTHCHECK --interval=30s --timeout=3s \
     CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"
 
-CMD ["uvicorn", "cartsnitch_api.main:app", "--host", "0.0.0.0", "--port", "8000"]
+CMD ["sh", "-c", "python -m alembic upgrade head && uvicorn cartsnitch_api.main:app --host 0.0.0.0 --port 8000"]

api/alembic/env.py

@@ -18,7 +18,7 @@ if not db_url:
         "CARTSNITCH_DATABASE_URL_SYNC must be set. "
         "Example: postgresql://user:pass@localhost:5432/cartsnitch"
     )
-config.set_main_option("sqlalchemy.url", db_url)
+config.set_main_option("sqlalchemy.url", db_url.replace("%", "%%"))
 
 target_metadata = Base.metadata
 
@@ -31,6 +31,7 @@ def run_migrations_offline() -> None:
         target_metadata=target_metadata,
         literal_binds=True,
         dialect_opts={"paramstyle": "named"},
+        version_table_column_width=128,
     )
     with context.begin_transaction():
         context.run_migrations()
@@ -44,9 +45,20 @@ def run_migrations_online() -> None:
         poolclass=pool.NullPool,
     )
     with connectable.connect() as connection:
-        context.configure(connection=connection, target_metadata=target_metadata)
+        context.configure(connection=connection, target_metadata=target_metadata, version_table_column_width=128)
         with context.begin_transaction():
             context.run_migrations()
+        # Create any tables defined in models but not yet created by migrations.
+        # This bootstraps fresh databases that have no legacy schema.
+        # checkfirst=True ensures this is a no-op on existing databases.
+        try:
+            Base.metadata.create_all(bind=connection, checkfirst=True)
+            connection.commit()
+        except Exception as exc:
+            import logging
+            logging.getLogger("alembic.env").warning(
+                "create_all failed (non-fatal, migrations should handle table creation): %s", exc
+            )
 
 
 if context.is_offline_mode():

api/alembic/versions/001_encrypt_session_data.py

@@ -33,6 +33,21 @@ def _is_fernet_token(value: str) -> bool:
 
 
 def upgrade() -> None:
+    conn = op.get_bind()
+    inspector = sa.inspect(conn)
+
+    # Fresh DB — table created by Base.metadata.create_all with correct TEXT type
+    if not inspector.has_table("user_store_accounts"):
+        return
+
+    # Already migrated? Skip if session_data is already TEXT (not JSON)
+    cols = {c["name"]: c for c in inspector.get_columns("user_store_accounts")}
+    if "session_data" not in cols:
+        return
+    col_type = str(cols["session_data"]["type"]).lower()
+    if "text" in col_type and "json" not in col_type:
+        return  # already TEXT — nothing to do
+
     # Change column type from JSON to TEXT to hold Fernet ciphertext
     op.alter_column(
         "user_store_accounts",
@@ -43,7 +58,6 @@ def upgrade() -> None:
         postgresql_using="session_data::text",
     )
 
-    conn = op.get_bind()
     rows = conn.execute(
         text("SELECT id, session_data FROM user_store_accounts WHERE session_data IS NOT NULL")
     ).fetchall()

api/alembic/versions/002_better_auth_tables.py

@@ -21,81 +21,94 @@ depends_on = None
 
 
 def upgrade() -> None:
+    conn = op.get_bind()
+    inspector = sa.inspect(conn)
+
     # --- Extend users table for Better-Auth compatibility ---
-    op.add_column("users", sa.Column("email_verified", sa.Boolean(), nullable=False, server_default="false"))
-    op.add_column("users", sa.Column("image", sa.Text(), nullable=True))
+    # Guard: on a fresh DB Base.metadata.create_all (called in env.py after migrations)
+    # creates the users table with all columns, so migration 002 must not re-run add_column.
+    if inspector.has_table("users"):
+        existing_user_cols = [c["name"] for c in inspector.get_columns("users")]
+        if "email_verified" not in existing_user_cols:
+            op.add_column("users", sa.Column("email_verified", sa.Boolean(), nullable=False, server_default="false"))
+        if "image" not in existing_user_cols:
+            op.add_column("users", sa.Column("image", sa.Text(), nullable=True))
 
     # --- Create sessions table ---
-    op.create_table(
-        "sessions",
-        sa.Column("id", sa.Text(), nullable=False),
-        sa.Column("token", sa.Text(), nullable=False),
-        sa.Column("user_id", sa.Text(), nullable=False),
-        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False),
-        sa.Column("ip_address", sa.Text(), nullable=True),
-        sa.Column("user_agent", sa.Text(), nullable=True),
-        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
-        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
-        sa.PrimaryKeyConstraint("id"),
-    )
-    op.create_index("ix_sessions_token", "sessions", ["token"], unique=True)
-    op.create_index("ix_sessions_user_id", "sessions", ["user_id"])
+    if not inspector.has_table("sessions"):
+        op.create_table(
+            "sessions",
+            sa.Column("id", sa.Text(), nullable=False),
+            sa.Column("token", sa.Text(), nullable=False),
+            sa.Column("user_id", sa.Text(), nullable=False),
+            sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False),
+            sa.Column("ip_address", sa.Text(), nullable=True),
+            sa.Column("user_agent", sa.Text(), nullable=True),
+            sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+            sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+            sa.PrimaryKeyConstraint("id"),
+        )
+        op.create_index("ix_sessions_token", "sessions", ["token"], unique=True)
+        op.create_index("ix_sessions_user_id", "sessions", ["user_id"])
 
     # --- Create accounts table ---
-    op.create_table(
-        "accounts",
-        sa.Column("id", sa.Text(), nullable=False),
-        sa.Column("user_id", sa.Text(), nullable=False),
-        sa.Column("account_id", sa.Text(), nullable=False),
-        sa.Column("provider_id", sa.Text(), nullable=False),
-        sa.Column("access_token", sa.Text(), nullable=True),
-        sa.Column("refresh_token", sa.Text(), nullable=True),
-        sa.Column("access_token_expires_at", sa.DateTime(timezone=True), nullable=True),
-        sa.Column("refresh_token_expires_at", sa.DateTime(timezone=True), nullable=True),
-        sa.Column("scope", sa.Text(), nullable=True),
-        sa.Column("id_token", sa.Text(), nullable=True),
-        sa.Column("password", sa.Text(), nullable=True),
-        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
-        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
-        sa.PrimaryKeyConstraint("id"),
-    )
-    op.create_index("ix_accounts_user_id", "accounts", ["user_id"])
+    if not inspector.has_table("accounts"):
+        op.create_table(
+            "accounts",
+            sa.Column("id", sa.Text(), nullable=False),
+            sa.Column("user_id", sa.Text(), nullable=False),
+            sa.Column("account_id", sa.Text(), nullable=False),
+            sa.Column("provider_id", sa.Text(), nullable=False),
+            sa.Column("access_token", sa.Text(), nullable=True),
+            sa.Column("refresh_token", sa.Text(), nullable=True),
+            sa.Column("access_token_expires_at", sa.DateTime(timezone=True), nullable=True),
+            sa.Column("refresh_token_expires_at", sa.DateTime(timezone=True), nullable=True),
+            sa.Column("scope", sa.Text(), nullable=True),
+            sa.Column("id_token", sa.Text(), nullable=True),
+            sa.Column("password", sa.Text(), nullable=True),
+            sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+            sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+            sa.PrimaryKeyConstraint("id"),
+        )
+        op.create_index("ix_accounts_user_id", "accounts", ["user_id"])
 
     # --- Create verifications table ---
-    op.create_table(
-        "verifications",
-        sa.Column("id", sa.Text(), nullable=False),
-        sa.Column("identifier", sa.Text(), nullable=False),
-        sa.Column("value", sa.Text(), nullable=False),
-        sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False),
-        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
-        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
-        sa.PrimaryKeyConstraint("id"),
-    )
+    if not inspector.has_table("verifications"):
+        op.create_table(
+            "verifications",
+            sa.Column("id", sa.Text(), nullable=False),
+            sa.Column("identifier", sa.Text(), nullable=False),
+            sa.Column("value", sa.Text(), nullable=False),
+            sa.Column("expires_at", sa.DateTime(timezone=True), nullable=False),
+            sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+            sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+            sa.PrimaryKeyConstraint("id"),
+        )
 
     # --- Migrate existing password hashes to accounts table ---
-    # For each user with a hashed_password, create a 'credential' account row
-    conn = op.get_bind()
-    users = conn.execute(
-        text("SELECT id, hashed_password FROM users WHERE hashed_password IS NOT NULL")
-    ).fetchall()
+    # Only run on existing (non-fresh) DBs that already have users table with data
+    if inspector.has_table("users"):
+        users = conn.execute(
+            text("SELECT id, hashed_password FROM users WHERE hashed_password IS NOT NULL")
+        ).fetchall()
 
-    for user_id, hashed_password in users:
-        user_id_str = str(user_id)
-        conn.execute(
-            text(
-                "INSERT INTO accounts (id, user_id, account_id, provider_id, password, created_at, updated_at) "
-                "VALUES (gen_random_uuid()::text, :user_id, :account_id, 'credential', :password, now(), now())"
-            ),
-            {"user_id": user_id_str, "account_id": user_id_str, "password": hashed_password},
-        )
+        for user_id, hashed_password in users:
+            user_id_str = str(user_id)
+            conn.execute(
+                text(
+                    "INSERT INTO accounts (id, user_id, account_id, provider_id, password, created_at, updated_at) "
+                    "VALUES (gen_random_uuid()::text, :user_id, :account_id, 'credential', :password, now(), now())"
+                ),
+                {"user_id": user_id_str, "account_id": user_id_str, "password": hashed_password},
+            )
 
 
 def downgrade() -> None:
-    op.drop_table("verifications")
-    op.drop_table("accounts")
-    op.drop_index("ix_sessions_user_id", table_name="sessions")
-    op.drop_index("ix_sessions_token", table_name="sessions")
-    op.drop_table("sessions")
-    op.drop_column("users", "image")
-    op.drop_column("users", "email_verified")
+    op.execute(text("DROP INDEX IF EXISTS ix_accounts_user_id"))
+    op.execute(text("DROP TABLE IF EXISTS verifications"))
+    op.execute(text("DROP TABLE IF EXISTS accounts"))
+    op.execute(text("DROP INDEX IF EXISTS ix_sessions_user_id"))
+    op.execute(text("DROP INDEX IF EXISTS ix_sessions_token"))
+    op.execute(text("DROP TABLE IF EXISTS sessions"))
+    op.execute(text("ALTER TABLE users DROP COLUMN IF EXISTS image"))
+    op.execute(text("ALTER TABLE users DROP COLUMN IF EXISTS email_verified"))

api/alembic/versions/003_make_users_hashed_password_nullable.py

@@ -0,0 +1,43 @@
+"""Make users.hashed_password nullable.
+
+Better-Auth inserts users without hashed_password (passwords live in the
+accounts table). This column is now purely optional.
+
+Revision ID: 003_make_users_hashed_password_nullable
+Revises: 002_better_auth_tables
+Create Date: 2026-03-30
+"""
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision = "003_make_users_hashed_password_nullable"
+down_revision = "002_better_auth_tables"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+    inspector = sa.inspect(conn)
+
+    # Fresh DB — nothing to alter
+    if not inspector.has_table("users"):
+        return
+
+    cols = {c["name"]: c for c in inspector.get_columns("users")}
+    if "hashed_password" in cols and not cols["hashed_password"]["nullable"]:
+        op.alter_column("users", "hashed_password", existing_type=sa.String(255), nullable=True)
+
+
+def downgrade() -> None:
+    conn = op.get_bind()
+    inspector = sa.inspect(conn)
+
+    if not inspector.has_table("users"):
+        return
+
+    cols = {c["name"]: c for c in inspector.get_columns("users")}
+    if "hashed_password" in cols and cols["hashed_password"]["nullable"]:
+        op.alter_column("users", "hashed_password", existing_type=sa.String(255), nullable=False)

api/alembic/versions/004_fix_user_id_text.py

@@ -0,0 +1,136 @@
+"""Fix users.id UUID->text type mismatch for Better-Auth compatibility.
+
+Better-Auth generates nanoid-style text IDs (e.g. pGud2ln2WAFHC0KYjBVKR4Rc7mM8OcTI),
+but the users table was using PostgreSQL uuid type. When Better-Auth tries to INSERT
+a new user, Postgres throws:
+  ERROR: invalid input syntax for type uuid: "pGud2ln2WAFHC0KYjBVKR4Rc7mM8OcTI"
+
+The sessions, accounts, and verifications tables already use text IDs — only users,
+user_store_accounts.user_id, and purchases.user_id needed fixing.
+
+Revision ID: 004_fix_user_id_text
+Revises: 003_make_users_hashed_password_nullable
+Create Date: 2026-03-31
+"""
+
+import sqlalchemy as sa
+from sqlalchemy import text
+
+from alembic import op
+
+revision = "004_fix_user_id_text"
+down_revision = "003_make_users_hashed_password_nullable"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+    inspector = sa.inspect(conn)
+
+    # Fresh DB — no tables yet, nothing to convert
+    if not inspector.has_table("users"):
+        return
+
+    # Check if already TEXT (Base.metadata.create_all uses TEXT for fresh DB)
+    users_cols = {c["name"]: c for c in inspector.get_columns("users")}
+    if "id" in users_cols:
+        id_type = str(users_cols["id"]["type"]).lower()
+        if "text" in id_type and "uuid" not in id_type:
+            return  # already TEXT — nothing to do
+
+    # Step 1: Drop existing FK constraints (ignore if they don't exist)
+    op.execute(text("ALTER TABLE user_store_accounts DROP CONSTRAINT IF EXISTS user_store_accounts_user_id_fkey"))
+    op.execute(text("ALTER TABLE purchases DROP CONSTRAINT IF EXISTS purchases_user_id_fkey"))
+
+    # Step 2: Alter users.id from uuid to text
+    op.alter_column(
+        "users",
+        "id",
+        type_=sa.Text(),
+        existing_type=sa.UUID(),
+        postgresql_using="id::text",
+    )
+
+    # Step 3: Alter user_store_accounts.user_id from uuid to text
+    op.alter_column(
+        "user_store_accounts",
+        "user_id",
+        type_=sa.Text(),
+        existing_type=sa.UUID(),
+        postgresql_using="user_id::text",
+    )
+
+    # Step 4: Alter purchases.user_id from uuid to text
+    op.alter_column(
+        "purchases",
+        "user_id",
+        type_=sa.Text(),
+        existing_type=sa.UUID(),
+        postgresql_using="user_id::text",
+    )
+
+    # Step 5: Re-add FK constraints
+    op.execute(
+        text(
+            "ALTER TABLE user_store_accounts "
+            "ADD CONSTRAINT user_store_accounts_user_id_fkey "
+            "FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE"
+        )
+    )
+    op.execute(
+        text(
+            "ALTER TABLE purchases "
+            "ADD CONSTRAINT purchases_user_id_fkey "
+            "FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE"
+        )
+    )
+
+
+def downgrade() -> None:
+    # Drop FK constraints
+    op.execute(text("ALTER TABLE user_store_accounts DROP CONSTRAINT IF EXISTS user_store_accounts_user_id_fkey"))
+    op.execute(text("ALTER TABLE purchases DROP CONSTRAINT IF EXISTS purchases_user_id_fkey"))
+
+    # Revert users.id from text to uuid
+    op.alter_column(
+        "users",
+        "id",
+        type_=sa.UUID(),
+        existing_type=sa.Text(),
+        postgresql_using="id::uuid",
+    )
+
+    # Revert user_store_accounts.user_id from text to uuid
+    op.alter_column(
+        "user_store_accounts",
+        "user_id",
+        type_=sa.UUID(),
+        existing_type=sa.Text(),
+        postgresql_using="user_id::uuid",
+    )
+
+    # Revert purchases.user_id from text to uuid
+    op.alter_column(
+        "purchases",
+        "user_id",
+        type_=sa.UUID(),
+        existing_type=sa.Text(),
+        postgresql_using="user_id::uuid",
+    )
+
+    # Re-add FK constraints (PostgreSQL will auto-name them)
+    op.execute(
+        text(
+            "ALTER TABLE user_store_accounts "
+            "ADD CONSTRAINT user_store_accounts_user_id_fkey "
+            "FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE"
+        )
+    )
+    op.execute(
+        text(
+            "ALTER TABLE purchases "
+            "ADD CONSTRAINT purchases_user_id_fkey "
+            "FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE"
+        )
+    )

api/alembic/versions/005_add_email_inbound_token.py

@@ -0,0 +1,57 @@
+"""Add email_inbound_token to users.
+
+Revision ID: 005_add_email_inbound_token
+Revises: 004_fix_user_id_text
+Create Date: 2026-04-02
+"""
+
+import secrets
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision = "005_add_email_inbound_token"
+down_revision = "004_fix_user_id_text"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+    inspector = sa.inspect(conn)
+    # Guard: on a fresh DB Base.metadata.create_all creates users table with the column already present
+    if not inspector.has_table("users"):
+        return
+    existing_cols = [c["name"] for c in inspector.get_columns("users")]
+    if "email_inbound_token" in existing_cols:
+        return
+
+    # Add column nullable first so existing rows can be backfilled
+    op.add_column(
+        "users",
+        sa.Column("email_inbound_token", sa.String(22), nullable=True),
+    )
+
+    # Backfill existing users with unique tokens
+    result = conn.execute(sa.text("SELECT id FROM users WHERE email_inbound_token IS NULL"))
+    for (user_id,) in result:
+        token = secrets.token_urlsafe(16)
+        conn.execute(
+            sa.text("UPDATE users SET email_inbound_token = :token WHERE id = :id"),
+            {"token": token, "id": user_id},
+        )
+
+    # Now enforce non-null and unique
+    op.alter_column("users", "email_inbound_token", nullable=False)
+    op.create_index(
+        "ix_users_email_inbound_token",
+        "users",
+        ["email_inbound_token"],
+        unique=True,
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("ix_users_email_inbound_token", table_name="users")
+    op.drop_column("users", "email_inbound_token")

api/alembic/versions/006_email_inbound_token_server_default.py

@@ -0,0 +1,42 @@
+"""Add server_default to users.email_inbound_token.
+
+Revision ID: 006_email_inbound_token_server_default
+Revises: 005_add_email_inbound_token
+Create Date: 2026-04-04
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+revision = "006_email_inbound_token_server_default"
+down_revision = "005_add_email_inbound_token"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+    inspector = sa.inspect(conn)
+    # Guard: on a fresh DB Base.metadata.create_all already sets the server_default
+    if not inspector.has_table("users"):
+        return
+    cols = {c["name"]: c for c in inspector.get_columns("users")}
+    if "email_inbound_token" not in cols:
+        return
+    if cols["email_inbound_token"].get("default") is not None:
+        return
+    op.alter_column(
+        "users",
+        "email_inbound_token",
+        server_default=sa.text(
+            "replace(replace(trim(trailing '=' from encode(gen_random_bytes(16), 'base64')), '+', '-'), '/', '_')"
+        ),
+    )
+
+
+def downgrade() -> None:
+    op.alter_column(
+        "users",
+        "email_inbound_token",
+        server_default=None,
+    )

api/alembic/versions/007_bootstrap_users_table.py

@@ -0,0 +1,47 @@
+"""Bootstrap users table on fresh databases.
+
+On fresh databases, migrations 001-006 skip users-table operations because
+the table does not exist yet. Base.metadata.create_all() in env.py is meant
+to handle this, but if it fails (import errors, etc.) the table is never
+created. This migration creates the users table with raw SQL as a safety net.
+
+Revision ID: 007_bootstrap_users_table
+Revises: 006_email_inbound_token_server_default
+Create Date: 2026-04-04
+"""
+
+import sqlalchemy as sa
+from sqlalchemy import text
+
+from alembic import op
+
+revision = "007_bootstrap_users_table"
+down_revision = "006_email_inbound_token_server_default"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+    inspector = sa.inspect(conn)
+    if inspector.has_table("users"):
+        return  # Table already exists (non-fresh DB or create_all already ran)
+
+    conn.execute(text("""
+        CREATE TABLE users (
+            id TEXT PRIMARY KEY,
+            email VARCHAR(255) NOT NULL UNIQUE,
+            hashed_password VARCHAR(255),
+            display_name VARCHAR(100),
+            email_verified BOOLEAN NOT NULL DEFAULT false,
+            image TEXT,
+            email_inbound_token VARCHAR(22) NOT NULL UNIQUE
+                DEFAULT replace(replace(trim(trailing '=' from encode(gen_random_bytes(16), 'base64')), '+', '-'), '/', '_'),
+            created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+            updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+        )
+    """))
+
+
+def downgrade() -> None:
+    op.execute(text("DROP TABLE IF EXISTS users"))

api/alembic/versions/008_create_domain_tables.py

@@ -0,0 +1,210 @@
+"""Create domain tables (stores, purchases, coupons, etc.).
+
+Revision ID: 008_create_domain_tables
+Revises: 007_bootstrap_users_table
+Create Date: 2026-04-04
+"""
+
+import sqlalchemy as sa
+from sqlalchemy import text
+
+from alembic import op
+
+revision = "008_create_domain_tables"
+down_revision = "007_bootstrap_users_table"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    conn = op.get_bind()
+    inspector = sa.inspect(conn)
+
+    # 1. stores
+    if not inspector.has_table("stores"):
+        op.create_table(
+            "stores",
+            sa.Column("id", sa.Uuid(), server_default=text("gen_random_uuid()"), primary_key=True),
+            sa.Column("name", sa.String(100), nullable=False),
+            sa.Column("slug", sa.String(20), nullable=False, unique=True),
+            sa.Column("logo_url", sa.String(500), nullable=True),
+            sa.Column("website_url", sa.String(500), nullable=True),
+            sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+            sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        )
+
+    # 2. store_locations
+    if not inspector.has_table("store_locations"):
+        op.create_table(
+            "store_locations",
+            sa.Column("id", sa.Uuid(), server_default=text("gen_random_uuid()"), primary_key=True),
+            sa.Column("store_id", sa.Uuid(), sa.ForeignKey("stores.id"), nullable=False),
+            sa.Column("address", sa.String(300), nullable=False),
+            sa.Column("city", sa.String(100), nullable=False),
+            sa.Column("state", sa.String(2), nullable=False),
+            sa.Column("zip", sa.String(10), nullable=False),
+            sa.Column("lat", sa.Float(), nullable=True),
+            sa.Column("lng", sa.Float(), nullable=True),
+            sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+            sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        )
+
+    # 3. normalized_products
+    if not inspector.has_table("normalized_products"):
+        op.create_table(
+            "normalized_products",
+            sa.Column("id", sa.Uuid(), server_default=text("gen_random_uuid()"), primary_key=True),
+            sa.Column("canonical_name", sa.String(300), nullable=False),
+            sa.Column("category", sa.String(50), nullable=True),
+            sa.Column("subcategory", sa.String(100), nullable=True),
+            sa.Column("brand", sa.String(200), nullable=True),
+            sa.Column("size", sa.String(50), nullable=True),
+            sa.Column("size_unit", sa.String(10), nullable=True),
+            sa.Column("upc_variants", sa.JSON(), nullable=True),
+            sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+            sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        )
+
+    # 4. purchases
+    if not inspector.has_table("purchases"):
+        op.create_table(
+            "purchases",
+            sa.Column("id", sa.Uuid(), server_default=text("gen_random_uuid()"), primary_key=True),
+            sa.Column("user_id", sa.Text(), sa.ForeignKey("users.id"), nullable=False),
+            sa.Column("store_id", sa.Uuid(), sa.ForeignKey("stores.id"), nullable=False),
+            sa.Column("store_location_id", sa.Uuid(), sa.ForeignKey("store_locations.id"), nullable=True),
+            sa.Column("receipt_id", sa.String(200), nullable=False),
+            sa.Column("purchase_date", sa.Date(), nullable=False),
+            sa.Column("total", sa.Numeric(10, 2), nullable=False),
+            sa.Column("subtotal", sa.Numeric(10, 2), nullable=True),
+            sa.Column("tax", sa.Numeric(10, 2), nullable=True),
+            sa.Column("savings_total", sa.Numeric(10, 2), nullable=True),
+            sa.Column("source_url", sa.String(500), nullable=True),
+            sa.Column("raw_data", sa.JSON(), nullable=True),
+            sa.Column("ingested_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+            sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+            sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+            sa.UniqueConstraint("user_id", "store_id", "receipt_id", name="uq_purchase_receipt"),
+            sa.Index("ix_purchases_user_store", "user_id", "store_id"),
+        )
+
+    # 5. purchase_items
+    if not inspector.has_table("purchase_items"):
+        op.create_table(
+            "purchase_items",
+            sa.Column("id", sa.Uuid(), server_default=text("gen_random_uuid()"), primary_key=True),
+            sa.Column("purchase_id", sa.Uuid(), sa.ForeignKey("purchases.id"), nullable=False),
+            sa.Column("product_name_raw", sa.String(300), nullable=False),
+            sa.Column("upc", sa.String(20), nullable=True),
+            sa.Column("quantity", sa.Numeric(10, 3), nullable=False),
+            sa.Column("unit_price", sa.Numeric(10, 2), nullable=False),
+            sa.Column("extended_price", sa.Numeric(10, 2), nullable=False),
+            sa.Column("regular_price", sa.Numeric(10, 2), nullable=True),
+            sa.Column("sale_price", sa.Numeric(10, 2), nullable=True),
+            sa.Column("coupon_discount", sa.Numeric(10, 2), nullable=True),
+            sa.Column("loyalty_discount", sa.Numeric(10, 2), nullable=True),
+            sa.Column("category_raw", sa.String(100), nullable=True),
+            sa.Column("normalized_product_id", sa.Uuid(), sa.ForeignKey("normalized_products.id"), nullable=True),
+            sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+            sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        )
+
+    # 6. coupons
+    if not inspector.has_table("coupons"):
+        op.create_table(
+            "coupons",
+            sa.Column("id", sa.Uuid(), server_default=text("gen_random_uuid()"), primary_key=True),
+            sa.Column("store_id", sa.Uuid(), sa.ForeignKey("stores.id"), nullable=False),
+            sa.Column("normalized_product_id", sa.Uuid(), sa.ForeignKey("normalized_products.id"), nullable=True),
+            sa.Column("title", sa.String(300), nullable=False),
+            sa.Column("description", sa.String(1000), nullable=True),
+            sa.Column("discount_type", sa.String(20), nullable=False),
+            sa.Column("discount_value", sa.Numeric(10, 2), nullable=True),
+            sa.Column("min_purchase", sa.Numeric(10, 2), nullable=True),
+            sa.Column("valid_from", sa.Date(), nullable=True),
+            sa.Column("valid_to", sa.Date(), nullable=True),
+            sa.Column("requires_clip", sa.Boolean(), server_default=text("false"), nullable=False),
+            sa.Column("coupon_code", sa.String(100), nullable=True),
+            sa.Column("source_url", sa.String(500), nullable=True),
+            sa.Column("scraped_at", sa.DateTime(timezone=True), nullable=True),
+            sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+            sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        )
+
+    # 7. price_history
+    if not inspector.has_table("price_history"):
+        op.create_table(
+            "price_history",
+            sa.Column("id", sa.Uuid(), server_default=text("gen_random_uuid()"), primary_key=True),
+            sa.Column("normalized_product_id", sa.Uuid(), sa.ForeignKey("normalized_products.id"), nullable=False),
+            sa.Column("store_id", sa.Uuid(), sa.ForeignKey("stores.id"), nullable=False),
+            sa.Column("observed_date", sa.Date(), nullable=False),
+            sa.Column("regular_price", sa.Numeric(10, 2), nullable=False),
+            sa.Column("sale_price", sa.Numeric(10, 2), nullable=True),
+            sa.Column("loyalty_price", sa.Numeric(10, 2), nullable=True),
+            sa.Column("coupon_price", sa.Numeric(10, 2), nullable=True),
+            sa.Column("source", sa.String(20), nullable=False),
+            sa.Column("purchase_item_id", sa.Uuid(), sa.ForeignKey("purchase_items.id"), nullable=True),
+            sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+            sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+            sa.Index("ix_price_history_product_store_date", "normalized_product_id", "store_id", "observed_date"),
+        )
+
+    # 8. shrinkflation_events
+    if not inspector.has_table("shrinkflation_events"):
+        op.create_table(
+            "shrinkflation_events",
+            sa.Column("id", sa.Uuid(), server_default=text("gen_random_uuid()"), primary_key=True),
+            sa.Column("normalized_product_id", sa.Uuid(), sa.ForeignKey("normalized_products.id"), nullable=False),
+            sa.Column("detected_date", sa.Date(), nullable=False),
+            sa.Column("old_size", sa.String(50), nullable=False),
+            sa.Column("new_size", sa.String(50), nullable=False),
+            sa.Column("old_unit", sa.String(10), nullable=True),
+            sa.Column("new_unit", sa.String(10), nullable=True),
+            sa.Column("price_at_old_size", sa.Numeric(10, 2), nullable=True),
+            sa.Column("price_at_new_size", sa.Numeric(10, 2), nullable=True),
+            sa.Column("confidence", sa.Numeric(3, 2), server_default=text("1.00"), nullable=False),
+            sa.Column("notes", sa.String(1000), nullable=True),
+            sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+            sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+        )
+
+    # 9. user_store_accounts
+    if not inspector.has_table("user_store_accounts"):
+        op.create_table(
+            "user_store_accounts",
+            sa.Column("id", sa.Uuid(), server_default=text("gen_random_uuid()"), primary_key=True),
+            sa.Column("user_id", sa.Text(), sa.ForeignKey("users.id"), nullable=False),
+            sa.Column("store_id", sa.Uuid(), sa.ForeignKey("stores.id"), nullable=False),
+            sa.Column("session_data", sa.JSON(), nullable=True),
+            sa.Column("session_expires_at", sa.DateTime(timezone=True), nullable=True),
+            sa.Column("last_sync_at", sa.DateTime(timezone=True), nullable=True),
+            sa.Column("status", sa.String(20), server_default=text("'active'"), nullable=False),
+            sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+            sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.func.now(), nullable=False),
+            sa.UniqueConstraint("user_id", "store_id", name="uq_user_store_account"),
+        )
+
+
+def downgrade() -> None:
+    conn = op.get_bind()
+    inspector = sa.inspect(conn)
+
+    if inspector.has_table("user_store_accounts"):
+        op.drop_table("user_store_accounts")
+    if inspector.has_table("shrinkflation_events"):
+        op.drop_table("shrinkflation_events")
+    if inspector.has_table("price_history"):
+        op.drop_table("price_history")
+    if inspector.has_table("coupons"):
+        op.drop_table("coupons")
+    if inspector.has_table("purchase_items"):
+        op.drop_table("purchase_items")
+    if inspector.has_table("purchases"):
+        op.drop_table("purchases")
+    if inspector.has_table("normalized_products"):
+        op.drop_table("normalized_products")
+    if inspector.has_table("store_locations"):
+        op.drop_table("store_locations")
+    if inspector.has_table("stores"):
+        op.drop_table("stores")

api/alembic/versions/009_add_gin_index_upc_variants.py

@@ -0,0 +1,38 @@
+"""Add GIN index on upc_variants and alter column to JSONB.
+
+Revision ID: 009_add_gin_index_upc_variants
+Revises: 008_create_domain_tables
+Create Date: 2026-04-14
+"""
+
+import sqlalchemy as sa
+from alembic import op
+
+revision = "009_add_gin_index_upc_variants"
+down_revision = "008_create_domain_tables"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.alter_column(
+        "normalized_products",
+        "upc_variants",
+        type_=sa.dialects.postgresql.JSONB(),
+        postgresql_using="upc_variants::jsonb",
+    )
+    op.create_index(
+        "ix_normalized_products_upc_variants_gin",
+        "normalized_products",
+        ["upc_variants"],
+        postgresql_using="gin",
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("ix_normalized_products_upc_variants_gin", table_name="normalized_products")
+    op.alter_column(
+        "normalized_products",
+        "upc_variants",
+        type_=sa.JSON(),
+    )

api/src/cartsnitch_api/auth/dependencies.py

@@ -5,8 +5,6 @@ Sessions are verified by querying the shared sessions table directly.
 """
 
 from datetime import UTC, datetime
-from uuid import UUID
-
 from fastapi import Cookie, Depends, Header, HTTPException, Request, status
 from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
 from sqlalchemy import text
@@ -21,12 +19,15 @@ bearer_scheme = HTTPBearer(auto_error=False)
 
 # Better-Auth session cookie name
 SESSION_COOKIE_NAME = "better-auth.session_token"
+# Secure prefix used by better-auth on HTTPS deployments
+SECURE_SESSION_COOKIE_NAME = "__Secure-better-auth.session_token"
 
 
-async def _validate_session_token(token: str, db: AsyncSession) -> UUID:
+async def _validate_session_token(token: str, db: AsyncSession) -> str:
     """Validate a Better-Auth session token against the sessions table.
 
-    Returns the user_id (as UUID) if the session is valid and not expired.
+    Better-Auth stores the raw token in the DB. The cookie/Bearer header
+    carries the same raw token, so we compare directly.
     """
     result = await db.execute(
         text("SELECT user_id, expires_at FROM sessions WHERE token = :token"),
@@ -51,14 +52,14 @@ async def _validate_session_token(token: str, db: AsyncSession) -> UUID:
             detail="Session expired",
         )
 
-    return UUID(str(user_id))
+    return str(user_id)
 
 
 async def get_current_user(
     request: Request,
     credentials: HTTPAuthorizationCredentials | None = Depends(bearer_scheme),
     db: AsyncSession = Depends(get_db),
-) -> UUID:
+) -> str:
     """Extract and validate the session token from cookie or Authorization header.
 
     Checks in order:
@@ -67,14 +68,19 @@ async def get_current_user(
     """
     token: str | None = None
 
-    # 1. Check session cookie
-    cookie_token = request.cookies.get(SESSION_COOKIE_NAME)
+    # 1. Check session cookie — prefer __Secure- variant (HTTPS) over plain (HTTP dev)
+    cookie_token = request.cookies.get(SECURE_SESSION_COOKIE_NAME) or request.cookies.get(
+        SESSION_COOKIE_NAME
+    )
     if cookie_token:
-        token = cookie_token
+        # Better-Auth cookie format is "token.sessionId" — extract just the token part
+        token = cookie_token.split(".")[0] if "." in cookie_token else cookie_token
 
     # 2. Fall back to Bearer header
     if not token and credentials:
-        token = credentials.credentials
+        # Callers might pass the compound value here too
+        raw = credentials.credentials
+        token = raw.split(".")[0] if "." in raw else raw
 
     if not token:
         raise HTTPException(
@@ -82,7 +88,9 @@ async def get_current_user(
             detail="Authentication required",
         )
 
-    return await _validate_session_token(token, db)
+    user_id = await _validate_session_token(token, db)
+    request.state.user_id = user_id
+    return user_id
 
 
 async def verify_service_key(x_service_key: str = Header()) -> None:

api/src/cartsnitch_api/auth/routes.py

@@ -5,13 +5,14 @@ the Better-Auth service (auth/). This router provides user profile
 endpoints that query our own user data from the shared database.
 """
 
-from uuid import UUID
-
 from fastapi import APIRouter, Depends, HTTPException, status
+from pydantic import BaseModel
+from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from cartsnitch_api.auth.dependencies import get_current_user
 from cartsnitch_api.database import get_db
+from cartsnitch_api.models import User
 from cartsnitch_api.schemas import (
     UpdateUserRequest,
     UserResponse,
@@ -23,7 +24,7 @@ router = APIRouter(prefix="/auth", tags=["auth"])
 
 @router.get("/me", response_model=UserResponse)
 async def get_me(
-    user_id: UUID = Depends(get_current_user),
+    user_id: str = Depends(get_current_user),
     db: AsyncSession = Depends(get_db),
 ):
     svc = AuthService(db)
@@ -38,7 +39,7 @@ async def get_me(
 @router.patch("/me", response_model=UserResponse)
 async def update_me(
     body: UpdateUserRequest,
-    user_id: UUID = Depends(get_current_user),
+    user_id: str = Depends(get_current_user),
     db: AsyncSession = Depends(get_db),
 ):
     svc = AuthService(db)
@@ -54,7 +55,7 @@ async def update_me(
 
 @router.delete("/me", status_code=status.HTTP_204_NO_CONTENT)
 async def delete_me(
-    user_id: UUID = Depends(get_current_user),
+    user_id: str = Depends(get_current_user),
     db: AsyncSession = Depends(get_db),
 ):
     svc = AuthService(db)

api/src/cartsnitch_api/cache.py

@@ -1,26 +1,108 @@
 """Redis/DragonflyDB caching helpers."""
 
+import logging
+from typing import TYPE_CHECKING
+
+import redis.asyncio as redis
+from redis.asyncio import Redis
+
 from cartsnitch_api.config import settings
 
+if TYPE_CHECKING:
+    from cartsnitch_api.config import Settings
+
+logger = logging.getLogger(__name__)
+
+_redis: "Redis | None" = None
+
+
+def get_settings() -> "Settings":
+    return settings
+
+
+async def init_redis() -> None:
+    global _redis
+    _redis = redis.from_url(settings.redis_url)
+    await _redis.ping()
+
+
+async def close_redis() -> None:
+    global _redis
+    if _redis is not None:
+        await _redis.aclose()
+        _redis = None
+
+
+def get_redis() -> Redis | None:
+    return _redis
+
 
 class CacheClient:
-    """Stub for Redis/DragonflyDB caching.
+    """Redis/DragonflyDB caching with connection pooling.
 
     Will be used for expensive queries: price trends, product comparisons.
     Cache invalidation via Redis pub/sub events from other services.
     """
 
     def __init__(self) -> None:
-        self.url = settings.redis_url
+        self._pool: redis.ConnectionPool | None = None
+        self._client: redis.Redis | None = None
+
+    async def initialize(self) -> None:
+        """Initialize the Redis connection pool."""
+        self._pool = redis.ConnectionPool.from_url(
+            settings.redis_url,
+            max_connections=20,
+            decode_responses=True,
+        )
+        self._client = redis.Redis(connection_pool=self._pool)
+
+    async def close(self) -> None:
+        """Close the Redis connection pool."""
+        if self._client:
+            await self._client.aclose()
+        if self._pool:
+            await self._pool.aclose()
 
     async def get(self, key: str) -> str | None:
-        # TODO: implement with redis-py async
-        return None
+        if not self._client:
+            return None
+        return await self._client.get(key)
 
     async def set(self, key: str, value: str, ttl_seconds: int = 300) -> None:
-        # TODO: implement with redis-py async
-        pass
+        if not self._client:
+            return
+        await self._client.set(key, value, ex=ttl_seconds)
 
     async def delete(self, key: str) -> None:
-        # TODO: implement with redis-py async
-        pass
+        if not self._client:
+            return
+        await self._client.delete(key)
+
+    async def invalidate_price_cache(self, product_id: str) -> None:
+        """Invalidate all price-related cache entries for a product."""
+        if not self._client:
+            return
+        pattern = f"price:*:{product_id}"
+        await self._delete_pattern(pattern)
+
+    async def invalidate_product_cache(self, product_id: str) -> None:
+        """Invalidate the product detail cache entry."""
+        if not self._client:
+            return
+        await self._client.delete(f"product:{product_id}")
+
+    async def _delete_pattern(self, pattern: str) -> None:
+        """Delete all keys matching a pattern using SCAN."""
+        if not self._client:
+            return
+        cursor = 0
+        while True:
+            cursor, keys = await self._client.scan(cursor=cursor, match=pattern, count=100)
+            if keys:
+                await self._client.delete(*keys)
+            if cursor == 0:
+                break
+
+
+cache_client = CacheClient()

api/src/cartsnitch_api/config.py

@@ -1,23 +1,25 @@
 import base64
 
-from pydantic import model_validator
+from pydantic import AliasChoices, Field, model_validator
 from pydantic_settings import BaseSettings
 
 
 class Settings(BaseSettings):
     model_config = {"env_prefix": "CARTSNITCH_"}
 
-    database_url: str = "postgresql+asyncpg://cartsnitch:cartsnitch@localhost:5432/cartsnitch"
+    database_url: str = Field(
+        default="postgresql+asyncpg://cartsnitch:cartsnitch@localhost:5432/cartsnitch",
+        validation_alias=AliasChoices("CARTSNITCH_DATABASE_URL", "DATABASE_URL"),
+    )
     redis_url: str = "redis://localhost:6379/0"
 
-    jwt_secret_key: str = "change-me-in-production"
+    jwt_secret_key: str
     jwt_algorithm: str = "HS256"
     jwt_access_token_expire_minutes: int = 15
     jwt_refresh_token_expire_days: int = 7
 
-    service_key: str = "change-me-in-production"
-    # Valid Fernet key for local dev — MUST be overridden in production
-    fernet_key: str = "7reF42nmTwbdN21PBoubGp7h_FU8qSimstmlaMLoRK8="
+    service_key: str
+    fernet_key: str
 
     auth_service_url: str = "http://auth:3001"
 
@@ -30,11 +32,31 @@ class Settings(BaseSettings):
 
     rate_limit_requests: int = 60
     rate_limit_window_seconds: int = 60
+    rate_limit_auth_requests: int = 5
+    rate_limit_auth_window_seconds: int = 60
+    rate_limit_redis_enabled: bool = True
     rate_limit_enabled: bool = True
 
+    _PLACEHOLDER_VALUES = {"change-me-in-production"}
+
     @model_validator(mode="after")
-    def validate_fernet_key(self):
-        """Validate fernet_key is a valid 32-byte url-safe base64 key at startup."""
+    def validate_secrets(self):
+        if not self.jwt_secret_key or self.jwt_secret_key in self._PLACEHOLDER_VALUES:
+            raise ValueError(
+                "CARTSNITCH_JWT_SECRET_KEY must be set to a secure value. "
+                'Generate one with: python -c "import secrets; print(secrets.token_urlsafe(32))"'
+            )
+        if not self.service_key or self.service_key in self._PLACEHOLDER_VALUES:
+            raise ValueError(
+                "CARTSNITCH_SERVICE_KEY must be set to a secure value. "
+                'Generate one with: python -c "import secrets; print(secrets.token_urlsafe(32))"'
+            )
+        if not self.fernet_key or self.fernet_key in self._PLACEHOLDER_VALUES:
+            raise ValueError(
+                "CARTSNITCH_FERNET_KEY must be set to a valid Fernet key. "
+                "Generate one with: python -c "
+                "'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())'"
+            )
         try:
             decoded = base64.urlsafe_b64decode(self.fernet_key.encode())
             if len(decoded) != 32:
@@ -49,5 +71,14 @@ class Settings(BaseSettings):
             ) from None
         return self
 
+    @model_validator(mode="after")
+    def normalize_database_url(self):
+        """Normalize postgresql:// → postgresql+asyncpg:// for the asyncpg driver."""
+        if self.database_url.startswith("postgresql://"):
+            self.database_url = self.database_url.replace(
+                "postgresql://", "postgresql+asyncpg://", 1
+            )
+        return self
+
 
 settings = Settings()

api/src/cartsnitch_api/database.py

@@ -1,16 +1,60 @@
 """Database session management for the API gateway."""
 
 from collections.abc import AsyncGenerator
+from typing import TYPE_CHECKING
 
 from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
 
 from cartsnitch_api.config import settings
 
-engine = create_async_engine(settings.database_url, echo=False)
-async_session_factory = async_sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)
+if TYPE_CHECKING:
+    from sqlalchemy.engine import Engine
+
+
+_engine: "Engine | None" = None
+async_session_factory: async_sessionmaker[AsyncSession] | None = None
+
+
+def create_db_engine():
+    return create_async_engine(
+        settings.database_url,
+        pool_size=10,
+        max_overflow=20,
+        pool_pre_ping=True,
+        pool_recycle=3600,
+        echo=False,
+    )
+
+
+async def init_db() -> None:
+    global _engine, async_session_factory
+    _engine = create_db_engine()
+    async_session_factory = async_sessionmaker(_engine, class_=AsyncSession, expire_on_commit=False)
+
+
+async def close_db() -> None:
+    global _engine, async_session_factory
+    if _engine is not None:
+        await _engine.dispose()
+        _engine = None
+    async_session_factory = None
+
+
+def get_engine():
+    return _engine
 
 
 async def get_db() -> AsyncGenerator[AsyncSession, None]:
-    """FastAPI dependency that yields an async DB session."""
+    if async_session_factory is None:
+        raise RuntimeError("Database not initialized. Call init_db() first.")
     async with async_session_factory() as session:
         yield session
+
+
+# Backward compatibility: module-level engine proxy that delegates to _engine
+def __getattr__(name: str):
+    if name == "engine":
+        if _engine is None:
+            raise RuntimeError("Database not initialized. Call init_db() first.")
+        return _engine
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

api/src/cartsnitch_api/main.py

@@ -2,12 +2,14 @@
 
 from contextlib import asynccontextmanager
 
-from fastapi import FastAPI
+from fastapi import APIRouter, FastAPI
 
 from cartsnitch_api.auth.routes import router as auth_router
+from cartsnitch_api.cache import cache_client
 from cartsnitch_api.middleware.cors import add_cors_middleware
 from cartsnitch_api.middleware.error_handler import add_error_handlers, add_error_monitor_middleware
 from cartsnitch_api.middleware.rate_limit import add_rate_limit_middleware
+from cartsnitch_api.middleware.audit import add_audit_middleware
 from cartsnitch_api.routes.alerts import router as alerts_router
 from cartsnitch_api.routes.coupons import router as coupons_router
 from cartsnitch_api.routes.health import router as health_router
@@ -18,13 +20,19 @@ from cartsnitch_api.routes.purchases import router as purchases_router
 from cartsnitch_api.routes.scraping import router as scraping_router
 from cartsnitch_api.routes.shopping import router as shopping_router
 from cartsnitch_api.routes.stores import router as stores_router
+from cartsnitch_api.routes.user import router as user_router
 
 
 @asynccontextmanager
 async def lifespan(app: FastAPI):
-    # TODO: initialize DB session pool, Redis connection, service clients
+    from cartsnitch_api.database import init_db, close_db
+    from cartsnitch_api.cache import init_redis, close_redis
+
+    await init_db()
+    await init_redis()
     yield
-    # TODO: cleanup connections
+    await close_redis()
+    await close_db()
 
 
 def create_app() -> FastAPI:
@@ -39,6 +47,7 @@ def create_app() -> FastAPI:
     add_cors_middleware(app)
     add_error_monitor_middleware(app)
     add_rate_limit_middleware(app)
+    add_audit_middleware(app)
 
     # Exception handlers
     add_error_handlers(app)
@@ -46,15 +55,20 @@ def create_app() -> FastAPI:
     # Routers
     app.include_router(health_router)
     app.include_router(auth_router)
-    app.include_router(stores_router)
-    app.include_router(purchases_router)
-    app.include_router(products_router)
-    app.include_router(prices_router)
-    app.include_router(coupons_router)
-    app.include_router(shopping_router)
-    app.include_router(alerts_router)
-    app.include_router(scraping_router)
-    app.include_router(public_router)
+
+    # Data endpoints mounted under /api/v1
+    v1_router = APIRouter(prefix="/api/v1")
+    v1_router.include_router(user_router)
+    v1_router.include_router(stores_router)
+    v1_router.include_router(purchases_router)
+    v1_router.include_router(products_router)
+    v1_router.include_router(prices_router)
+    v1_router.include_router(coupons_router)
+    v1_router.include_router(shopping_router)
+    v1_router.include_router(alerts_router)
+    v1_router.include_router(scraping_router)
+    v1_router.include_router(public_router)
+    app.include_router(v1_router)
 
     return app
 

api/src/cartsnitch_api/middleware/audit.py

@@ -0,0 +1,64 @@
+"""Audit logging middleware for sensitive API operations.
+
+Logs structured JSON for POST/PUT/PATCH/DELETE requests and GET /auth/me.
+Never logs request bodies, response bodies, Authorization headers, or cookie values.
+"""
+
+import json
+import logging
+import time
+from collections.abc import Awaitable, Callable
+
+from fastapi import FastAPI, Request
+from starlette.middleware.base import BaseHTTPMiddleware
+
+logger = logging.getLogger("cartsnitch_api.audit")
+
+HEALTH_PATHS = {"/health", "/healthz", "/ready"}
+
+
+class AuditMiddleware(BaseHTTPMiddleware):
+    """Middleware to log structured audit events for sensitive operations."""
+
+    async def dispatch(
+        self,
+        request: Request,
+        call_next: Callable[[Request], Awaitable],
+    ):
+        if request.method == "OPTIONS" or request.url.path in HEALTH_PATHS:
+            return await call_next(request)
+
+        method = request.method
+        path = request.url.path
+
+        is_sensitive_write = method in {"POST", "PUT", "PATCH", "DELETE"}
+        is_auth_me_read = method == "GET" and path == "/auth/me"
+
+        if not (is_sensitive_write or is_auth_me_read):
+            return await call_next(request)
+
+        start = time.perf_counter()
+        response = await call_next(request)
+        duration_ms = (time.perf_counter() - start) * 1000
+
+        user_id = getattr(request.state, "user_id", None)
+        client_ip = request.client.host if request.client else "unknown"
+
+        log_entry = {
+            "event": "audit",
+            "timestamp": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+            "user_id": user_id,
+            "method": method,
+            "path": path,
+            "client_ip": client_ip,
+            "status_code": response.status_code,
+            "duration_ms": round(duration_ms, 2),
+        }
+
+        logger.info(json.dumps(log_entry))
+
+        return response
+
+
+def add_audit_middleware(app: FastAPI) -> None:
+    app.add_middleware(AuditMiddleware)

api/src/cartsnitch_api/middleware/cors.py

@@ -11,6 +11,6 @@ def add_cors_middleware(app: FastAPI) -> None:
         CORSMiddleware,
         allow_origins=settings.cors_origins,
         allow_credentials=True,
-        allow_methods=["*"],
-        allow_headers=["*"],
+        allow_methods=["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"],
+        allow_headers=["Content-Type", "Authorization", "Accept", "Origin", "X-Requested-With"],
     )

api/src/cartsnitch_api/middleware/rate_limit.py

@@ -4,18 +4,32 @@ Uses in-memory sliding window as fallback, Redis/DragonflyDB when available.
 Per-IP limiting on public endpoints, per-token limiting on authenticated endpoints.
 """
 
+import hashlib
+import logging
 import time
+import uuid
 from collections import defaultdict
 from threading import Lock
+from typing import Protocol
 
 from fastapi import FastAPI, Request, status
 from fastapi.responses import JSONResponse
+from redis.asyncio import Redis, RedisError
 from starlette.middleware.base import BaseHTTPMiddleware
 
 from cartsnitch_api.config import settings
 
+logger = logging.getLogger(__name__)
 
-class _SlidingWindowCounter:
+
+class RateLimitBackend(Protocol):
+    """Protocol for rate limit backends."""
+
+    async def is_allowed(self, key: str) -> tuple[bool, int, int]:
+        """Check if request is allowed. Returns (allowed, remaining, retry_after)."""
+
+
+class InMemorySlidingWindow:
     """Thread-safe in-memory sliding window rate limiter."""
 
     def __init__(self, max_requests: int, window_seconds: int) -> None:
@@ -24,13 +38,12 @@ class _SlidingWindowCounter:
         self._hits: dict[str, list[float]] = defaultdict(list)
         self._lock = Lock()
 
-    def is_allowed(self, key: str) -> tuple[bool, int, int]:
+    async def is_allowed(self, key: str) -> tuple[bool, int, int]:
         """Check if request is allowed. Returns (allowed, remaining, retry_after)."""
         now = time.monotonic()
         cutoff = now - self.window_seconds
 
         with self._lock:
-            # Prune expired entries
             self._hits[key] = [t for t in self._hits[key] if t > cutoff]
 
             current_count = len(self._hits[key])
@@ -43,15 +56,84 @@ class _SlidingWindowCounter:
             return True, remaining, 0
 
 
-# Module-level counters — one for public (per-IP), one for auth (per-token)
-_public_limiter = _SlidingWindowCounter(
-    max_requests=settings.rate_limit_requests,
-    window_seconds=settings.rate_limit_window_seconds,
-)
-_auth_limiter = _SlidingWindowCounter(
-    max_requests=settings.rate_limit_requests * 5,  # 300/min for authenticated users
-    window_seconds=settings.rate_limit_window_seconds,
-)
+class RedisSlidingWindow:
+    """Redis-backed sliding window rate limiter using sorted sets."""
+
+    def __init__(self, redis: Redis, max_requests: int, window_seconds: int) -> None:
+        self.redis = redis
+        self.max_requests = max_requests
+        self.window_seconds = window_seconds
+
+    async def is_allowed(self, key: str) -> tuple[bool, int, int]:
+        """Check if request is allowed. Returns (allowed, remaining, retry_after)."""
+        try:
+            now = time.monotonic()
+            cutoff = now - self.window_seconds
+            now_ms = int(now * 1000)
+            cutoff_ms = int(cutoff * 1000)
+
+            pipe = self.redis.pipeline()
+            pipe.zremrangebyscore(key, 0, cutoff_ms)
+            pipe.zcard(key)
+            results = await pipe.execute()
+
+            current_count = results[1]
+
+            if current_count >= self.max_requests:
+                oldest = await self.redis.zrange(key, 0, 0, withscores=True)
+                if oldest:
+                    retry_after = int((oldest[0][1] - cutoff) / 1000) + 1
+                else:
+                    retry_after = self.window_seconds
+                return False, 0, retry_after
+
+            member = f"{now_ms}:{uuid.uuid4().hex[:8]}"
+            pipe = self.redis.pipeline()
+            pipe.zadd(key, {member: now_ms})
+            pipe.expire(key, self.window_seconds)
+            await pipe.execute()
+
+            remaining = self.max_requests - current_count - 1
+            return True, remaining, 0
+
+        except RedisError as e:
+            logger.warning("Redis rate limit error, falling back to in-memory: %s", e)
+            in_memory = InMemorySlidingWindow(self.max_requests, self.window_seconds)
+            return await in_memory.is_allowed(key)
+
+
+_redis_client: Redis | None = None
+_use_redis = False
+
+if settings.rate_limit_redis_enabled:
+    try:
+        _redis_client = Redis.from_url(settings.redis_url)
+        _use_redis = True
+        logger.info("Rate limiting will use Redis at %s", settings.redis_url)
+    except Exception as e:
+        logger.warning("Failed to connect to Redis for rate limiting, using in-memory: %s", e)
+        _use_redis = False
+
+if _use_redis and _redis_client:
+    _public_limiter = RedisSlidingWindow(
+        _redis_client, settings.rate_limit_requests, settings.rate_limit_window_seconds
+    )
+    _auth_limiter = RedisSlidingWindow(
+        _redis_client, settings.rate_limit_requests * 5, settings.rate_limit_window_seconds
+    )
+    _auth_strict_limiter = RedisSlidingWindow(
+        _redis_client, settings.rate_limit_auth_requests, settings.rate_limit_auth_window_seconds
+    )
+else:
+    _public_limiter = InMemorySlidingWindow(
+        settings.rate_limit_requests, settings.rate_limit_window_seconds
+    )
+    _auth_limiter = InMemorySlidingWindow(
+        settings.rate_limit_requests * 5, settings.rate_limit_window_seconds
+    )
+    _auth_strict_limiter = InMemorySlidingWindow(
+        settings.rate_limit_auth_requests, settings.rate_limit_auth_window_seconds
+    )
 
 
 def _get_client_ip(request: Request) -> str:
@@ -62,30 +144,30 @@ def _get_client_ip(request: Request) -> str:
     return request.client.host if request.client else "unknown"
 
 
-def _get_rate_limit_key(request: Request) -> tuple[str, _SlidingWindowCounter]:
+def _get_rate_limit_key(request: Request) -> tuple[str, RateLimitBackend]:
     """Determine rate limit key and which limiter to use."""
     if request.url.path.startswith("/public"):
         return f"ip:{_get_client_ip(request)}", _public_limiter
 
-    # For authenticated endpoints, use Bearer token as key if present
+    if request.url.path.startswith("/auth/") and request.method == "POST":
+        return f"ip:{_get_client_ip(request)}", _auth_strict_limiter
+
     auth_header = request.headers.get("authorization", "")
     if auth_header.startswith("Bearer "):
         token = auth_header[7:]
-        # Use last 16 chars of token as key to avoid storing full tokens
-        return f"token:{token[-16:]}", _auth_limiter
+        token_hash = hashlib.sha256(token.encode()).hexdigest()
+        return f"token:{token_hash}", _auth_limiter
 
-    # Fallback to IP for unauthenticated non-public endpoints
     return f"ip:{_get_client_ip(request)}", _public_limiter
 
 
 class RateLimitMiddleware(BaseHTTPMiddleware):
     async def dispatch(self, request: Request, call_next):
-        # Skip rate limiting when disabled (e.g. in tests) or for health checks
         if not settings.rate_limit_enabled or request.url.path == "/health":
             return await call_next(request)
 
         key, limiter = _get_rate_limit_key(request)
-        allowed, remaining, retry_after = limiter.is_allowed(key)
+        allowed, remaining, retry_after = await limiter.is_allowed(key)
 
         if not allowed:
             return JSONResponse(

api/src/cartsnitch_api/models/purchase.py

@@ -32,8 +32,8 @@ class Purchase(UUIDPrimaryKeyMixin, TimestampMixin, Base):
 
     __tablename__ = "purchases"
 
-    user_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("users.id"), nullable=False)
-    store_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("stores.id"), nullable=False)
+    user_id: Mapped[str] = mapped_column(ForeignKey("users.id"), nullable=False)
+    store_id: Mapped[str] = mapped_column(ForeignKey("stores.id"), nullable=False)
     store_location_id: Mapped[uuid.UUID | None] = mapped_column(ForeignKey("store_locations.id"))
     receipt_id: Mapped[str] = mapped_column(String(200), nullable=False)
     purchase_date: Mapped[date] = mapped_column(Date, nullable=False)

api/src/cartsnitch_api/models/user.py

@@ -1,10 +1,11 @@
 """User and UserStoreAccount models."""
 
-import uuid
+import secrets
 from datetime import datetime
 from typing import TYPE_CHECKING
 
-from sqlalchemy import DateTime, ForeignKey, String, UniqueConstraint
+import sqlalchemy as sa
+from sqlalchemy import Boolean, DateTime, ForeignKey, String, Text, UniqueConstraint
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 
 from cartsnitch_api.constants import AccountStatus
@@ -16,14 +17,28 @@ if TYPE_CHECKING:
     from cartsnitch_api.models.store import Store
 
 
-class User(UUIDPrimaryKeyMixin, TimestampMixin, Base):
+class User(TimestampMixin, Base):
     """Application user."""
 
     __tablename__ = "users"
 
+    id: Mapped[str] = mapped_column(Text, primary_key=True)
     email: Mapped[str] = mapped_column(String(255), nullable=False, unique=True)
-    hashed_password: Mapped[str] = mapped_column(String(255), nullable=False)
+    hashed_password: Mapped[str | None] = mapped_column(String(255), nullable=True)
     display_name: Mapped[str | None] = mapped_column(String(100))
+    email_verified: Mapped[bool] = mapped_column(
+        Boolean, nullable=False, server_default="false"
+    )
+    image: Mapped[str | None] = mapped_column(Text, nullable=True)
+    email_inbound_token: Mapped[str] = mapped_column(
+        String(22),
+        nullable=False,
+        unique=True,
+        default=lambda: secrets.token_urlsafe(16),
+        server_default=sa.text(
+            "replace(replace(trim(trailing '=' from encode(gen_random_bytes(16), 'base64')), '+', '-'), '/', '_')"
+        ),
+    )
 
     # Relationships
     store_accounts: Mapped[list["UserStoreAccount"]] = relationship(back_populates="user")
@@ -36,8 +51,8 @@ class UserStoreAccount(UUIDPrimaryKeyMixin, TimestampMixin, Base):
     __tablename__ = "user_store_accounts"
     __table_args__ = (UniqueConstraint("user_id", "store_id", name="uq_user_store_account"),)
 
-    user_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("users.id"), nullable=False)
-    store_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("stores.id"), nullable=False)
+    user_id: Mapped[str] = mapped_column(ForeignKey("users.id"), nullable=False)
+    store_id: Mapped[str] = mapped_column(ForeignKey("stores.id"), nullable=False)
     session_data: Mapped[dict | None] = mapped_column(EncryptedJSON)
     session_expires_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
     last_sync_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))

api/src/cartsnitch_api/routes/health.py

@@ -1,8 +1,11 @@
 """Health check and error metrics endpoints."""
 
 from fastapi import APIRouter, Depends
+from sqlalchemy import text
 
 from cartsnitch_api.auth.dependencies import verify_service_key
+from cartsnitch_api.cache import get_redis
+from cartsnitch_api.database import get_engine
 from cartsnitch_api.middleware.error_handler import get_error_monitor
 
 router = APIRouter(tags=["health"])
@@ -10,7 +13,27 @@ router = APIRouter(tags=["health"])
 
 @router.get("/health")
 async def health():
-    return {"status": "ok"}
+    engine = get_engine()
+    db_ok = False
+    redis_ok = False
+
+    try:
+        async with engine.connect() as conn:
+            await conn.execute(text("SELECT 1"))
+        db_ok = True
+    except Exception:
+        pass
+
+    try:
+        r = get_redis()
+        if r:
+            await r.ping()
+            redis_ok = True
+    except Exception:
+        pass
+
+    status = "ok" if db_ok else "degraded"
+    return {"status": status, "db": db_ok, "redis": redis_ok}
 
 
 @router.get("/internal/error-stats", dependencies=[Depends(verify_service_key)])

api/src/cartsnitch_api/routes/public.py

@@ -18,10 +18,14 @@ router = APIRouter(prefix="/public", tags=["public"])
 
 
 @router.get("/trends/{product_id}", response_model=PublicTrendResponse)
-async def public_price_trend(product_id: UUID, db: AsyncSession = Depends(get_db)):
+async def public_price_trend(
+    product_id: UUID,
+    days: int = Query(90, ge=1, le=365),
+    db: AsyncSession = Depends(get_db),
+):
     svc = PublicService(db)
     try:
-        return await svc.get_trend(product_id)
+        return await svc.get_trend(product_id, days=days)
     except LookupError:
         raise HTTPException(
             status_code=status.HTTP_404_NOT_FOUND, detail="Product not found"
@@ -31,6 +35,7 @@ async def public_price_trend(product_id: UUID, db: AsyncSession = Depends(get_db
 @router.get("/store-comparison", response_model=PublicStoreComparisonResponse)
 async def public_store_comparison(
     product_ids: Annotated[list[UUID], Query(max_length=20)],
+    category: str | None = Query(None, max_length=100, pattern=r"^[a-zA-Z0-9 _-]+$"),
     db: AsyncSession = Depends(get_db),
 ):
     if not product_ids:
@@ -39,10 +44,14 @@ async def public_store_comparison(
             detail="At least one product_id is required",
         )
     svc = PublicService(db)
-    return await svc.get_store_comparison(product_ids)
+    return await svc.get_store_comparison(product_ids, category=category)
 
 
 @router.get("/inflation", response_model=PublicInflationResponse)
-async def public_inflation(db: AsyncSession = Depends(get_db)):
+async def public_inflation(
+    category: str | None = Query(None, max_length=100, pattern=r"^[a-zA-Z0-9 _-]+$"),
+    period: str = Query("all-time", pattern=r"^(all-time|1y|6m|3m|1m)$"),
+    db: AsyncSession = Depends(get_db),
+):
     svc = PublicService(db)
-    return await svc.get_inflation()
+    return await svc.get_inflation(category=category, period=period)

api/src/cartsnitch_api/routes/user.py

@@ -0,0 +1,32 @@
+"""User routes: per-user account endpoints (email-in address, etc.)."""
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from cartsnitch_api.auth.dependencies import get_current_user
+from cartsnitch_api.database import get_db
+from cartsnitch_api.schemas import EmailInAddressResponse
+from cartsnitch_api.services.auth import AuthService
+
+router = APIRouter(tags=["user"])
+
+
+@router.get("/me/email-in-address", response_model=EmailInAddressResponse)
+async def get_email_in_address(
+    user_id: str = Depends(get_current_user),
+    db: AsyncSession = Depends(get_db),
+):
+    svc = AuthService(db)
+    try:
+        email_address = await svc.get_email_in_address(user_id)
+        return EmailInAddressResponse(
+            email_address=email_address,
+            instructions=(
+                "Forward your digital receipt emails to this address. "
+                "We currently support Meijer, Kroger, and Target receipt emails."
+            ),
+        )
+    except LookupError:
+        raise HTTPException(
+            status_code=status.HTTP_404_NOT_FOUND, detail="User not found"
+        ) from None

api/src/cartsnitch_api/schemas.py

@@ -16,12 +16,17 @@ class UpdateUserRequest(BaseModel):
 
 
 class UserResponse(BaseModel):
-    id: UUID
+    id: str
     email: str
     display_name: str
     created_at: datetime
 
 
+class EmailInAddressResponse(BaseModel):
+    email_address: str
+    instructions: str
+
+
 # ---------- Stores ----------
 
 

api/src/cartsnitch_api/services/auth.py

@@ -5,8 +5,6 @@ handled by the Better-Auth service (auth/). This service provides
 user lookup and profile update operations for the API gateway.
 """
 
-from uuid import UUID
-
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 
@@ -15,7 +13,7 @@ class AuthService:
     def __init__(self, db: AsyncSession) -> None:
         self.db = db
 
-    async def get_user(self, user_id: UUID) -> dict:
+    async def get_user(self, user_id: str) -> dict:
         from cartsnitch_api.models import User
 
         result = await self.db.execute(select(User).where(User.id == user_id))
@@ -30,7 +28,7 @@ class AuthService:
             "created_at": user.created_at,
         }
 
-    async def update_user(self, user_id: UUID, **fields) -> dict:
+    async def update_user(self, user_id: str, **fields) -> dict:
         from cartsnitch_api.models import User
 
         result = await self.db.execute(select(User).where(User.id == user_id))
@@ -58,7 +56,7 @@ class AuthService:
             "created_at": user.created_at,
         }
 
-    async def delete_user(self, user_id: UUID) -> None:
+    async def delete_user(self, user_id: str) -> None:
         from cartsnitch_api.models import User
 
         result = await self.db.execute(select(User).where(User.id == user_id))
@@ -68,3 +66,14 @@ class AuthService:
 
         await self.db.delete(user)
         await self.db.commit()
+
+    async def get_email_in_address(self, user_id: str) -> str:
+        """Return the per-user email-in address for receipt forwarding."""
+        from cartsnitch_api.models import User
+
+        result = await self.db.execute(select(User).where(User.id == user_id))
+        user = result.scalar_one_or_none()
+        if not user:
+            raise LookupError("User not found")
+
+        return f"receipts+{user.email_inbound_token}@receipts.cartsnitch.com"

api/src/cartsnitch_api/services/public.py

@@ -1,5 +1,6 @@
 """Public service — unauthenticated price transparency endpoints."""
 
+from datetime import date, timedelta
 from uuid import UUID
 
 from sqlalchemy import and_, func, select
@@ -13,7 +14,7 @@ class PublicService:
     def __init__(self, db: AsyncSession) -> None:
         self.db = db
 
-    async def get_trend(self, product_id: UUID) -> dict:
+    async def get_trend(self, product_id: UUID, days: int = 90) -> dict:
         from cartsnitch_api.models import NormalizedProduct, PriceHistory
 
         result = await self.db.execute(
@@ -23,9 +24,13 @@ class PublicService:
         if not product:
             raise LookupError("Product not found")
 
+        date_threshold = date.today() - timedelta(days=days)
         prices_result = await self.db.execute(
             select(PriceHistory)
-            .where(PriceHistory.normalized_product_id == product_id)
+            .where(
+                PriceHistory.normalized_product_id == product_id,
+                PriceHistory.observed_date >= date_threshold,
+            )
             .options(selectinload(PriceHistory.store))
             .order_by(PriceHistory.observed_date)
         )
@@ -45,20 +50,25 @@ class PublicService:
             ],
         }
 
-    async def get_store_comparison(self, product_ids: list[UUID]) -> dict:
+    async def get_store_comparison(
+        self, product_ids: list[UUID], category: str | None = None
+    ) -> dict:
         from cartsnitch_api.models import NormalizedProduct, PriceHistory
 
         if not product_ids:
             return {"products": []}
 
-        # Fetch all products in one query
-        prod_result = await self.db.execute(
-            select(NormalizedProduct).where(NormalizedProduct.id.in_(product_ids))
-        )
+        product_query = select(NormalizedProduct).where(NormalizedProduct.id.in_(product_ids))
+        if category:
+            product_query = product_query.where(NormalizedProduct.category == category)
+        prod_result = await self.db.execute(product_query)
         products_by_id = {p.id: p for p in prod_result.scalars().all()}
 
-        # Latest prices for all requested products in one query
-        subq = latest_price_per_store(product_ids)
+        if not products_by_id:
+            return {"products": []}
+
+        filtered_product_ids = list(products_by_id.keys())
+        subq = latest_price_per_store(filtered_product_ids)
         prices_result = await self.db.execute(
             select(PriceHistory)
             .join(
@@ -69,18 +79,17 @@ class PublicService:
                     PriceHistory.normalized_product_id == subq.c.normalized_product_id,
                 ),
             )
-            .where(PriceHistory.normalized_product_id.in_(product_ids))
+            .where(PriceHistory.normalized_product_id.in_(filtered_product_ids))
             .options(selectinload(PriceHistory.store))
         )
         all_prices = prices_result.scalars().all()
 
-        # Group by product
         prices_by_product: dict[UUID, list] = {}
         for ph in all_prices:
             prices_by_product.setdefault(ph.normalized_product_id, []).append(ph)
 
         products = []
-        for pid in product_ids:
+        for pid in filtered_product_ids:
             product = products_by_id.get(pid)
             if not product:
                 continue
@@ -102,19 +111,29 @@ class PublicService:
 
         return {"products": products}
 
-    async def get_inflation(self) -> dict:
+    async def get_inflation(self, category: str | None = None, period: str = "all-time") -> dict:
         """Aggregate price change stats. Compares average prices across periods."""
         from cartsnitch_api.models import NormalizedProduct, PriceHistory
 
-        # Get average prices grouped by category for recent vs older data
-        result = await self.db.execute(
-            select(
-                NormalizedProduct.category,
-                func.avg(PriceHistory.regular_price),
-            )
-            .join(NormalizedProduct)
-            .group_by(NormalizedProduct.category)
-        )
+        date_threshold = None
+        if period != "all-time":
+            days_map = {"1y": 365, "6m": 180, "3m": 90, "1m": 30}
+            days = days_map.get(period, 365)
+            date_threshold = date.today() - timedelta(days=days)
+
+        query = select(
+            NormalizedProduct.category,
+            func.avg(PriceHistory.regular_price),
+        ).join(NormalizedProduct)
+
+        if category:
+            query = query.where(NormalizedProduct.category == category)
+        if date_threshold:
+            query = query.where(PriceHistory.observed_date >= date_threshold)
+
+        query = query.group_by(NormalizedProduct.category)
+
+        result = await self.db.execute(query)
         categories = {}
         for row in result.all():
             cat, avg_price = row
@@ -122,7 +141,7 @@ class PublicService:
                 categories[cat] = float(avg_price) if avg_price else 0.0
 
         return {
-            "period": "all-time",
+            "period": period,
             "cartsnitch_index": sum(categories.values()) / max(len(categories), 1),
             "cpi_baseline": 100.0,
             "categories": categories,

api/tests/conftest.py

@@ -19,6 +19,25 @@ from cartsnitch_api.database import get_db
 from cartsnitch_api.main import create_app
 from cartsnitch_api.models import Base
 
+TEST_JWT_SECRET = secrets.token_urlsafe(32)
+TEST_SERVICE_KEY = secrets.token_urlsafe(32)
+TEST_FERNET_KEY = "7reF42nmTwbdN21PBoubGp7h_FU8qSimstmlaMLoRK8="
+
+
+@pytest.fixture(autouse=True)
+def setup_test_settings():
+    original_jwt = cartsnitch_settings.jwt_secret_key
+    original_service = cartsnitch_settings.service_key
+    original_fernet = cartsnitch_settings.fernet_key
+    cartsnitch_settings.jwt_secret_key = TEST_JWT_SECRET
+    cartsnitch_settings.service_key = TEST_SERVICE_KEY
+    cartsnitch_settings.fernet_key = TEST_FERNET_KEY
+    yield
+    cartsnitch_settings.jwt_secret_key = original_jwt
+    cartsnitch_settings.service_key = original_service
+    cartsnitch_settings.fernet_key = original_fernet
+
+
 TEST_DATABASE_URL = "sqlite+aiosqlite:///:memory:"
 
 
@@ -60,7 +79,8 @@ async def db_engine():
     async with engine.begin() as conn:
         await conn.run_sync(Base.metadata.create_all)
         # Create Better-Auth tables (not managed by SQLAlchemy models)
-        await conn.execute(text("""
+        await conn.execute(
+            text("""
             CREATE TABLE IF NOT EXISTS sessions (
                 id TEXT PRIMARY KEY,
                 token TEXT NOT NULL UNIQUE,
@@ -71,8 +91,10 @@ async def db_engine():
                 created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL,
                 updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL
             )
-        """))
-        await conn.execute(text("""
+        """)
+        )
+        await conn.execute(
+            text("""
             CREATE TABLE IF NOT EXISTS accounts (
                 id TEXT PRIMARY KEY,
                 user_id TEXT NOT NULL,
@@ -88,8 +110,10 @@ async def db_engine():
                 created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL,
                 updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL
             )
-        """))
-        await conn.execute(text("""
+        """)
+        )
+        await conn.execute(
+            text("""
             CREATE TABLE IF NOT EXISTS verifications (
                 id TEXT PRIMARY KEY,
                 identifier TEXT NOT NULL,
@@ -98,7 +122,8 @@ async def db_engine():
                 created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL,
                 updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP NOT NULL
             )
-        """))
+        """)
+        )
 
     yield engine
 
@@ -133,10 +158,13 @@ async def client(db_engine):
     app.dependency_overrides.clear()
 
 
-async def _create_test_user_and_session(client: AsyncClient, db_engine, **user_overrides) -> tuple[dict, str]:
+async def _create_test_user_and_session(
+    client: AsyncClient, db_engine, **user_overrides
+) -> tuple[dict, str]:
     """Create a test user and a valid session directly in the DB.
 
-    Returns (user_dict, session_token).
+    Returns (user_dict, session_token).  Better-Auth stores the raw token
+    in the DB, so we insert it as-is.
     """
     user_id = str(uuid.uuid4())
     email = user_overrides.get("email", "test@example.com")

api/tests/test_auth/test_auth_endpoints.py

@@ -71,6 +71,56 @@ async def test_delete_me(client, auth_headers):
     assert resp.status_code == 404
 
 
+@pytest.mark.asyncio
+async def test_get_me_compound_cookie(client, db_engine):
+    """Compound cookie value (token.sessionId) must be parsed to extract the token part."""
+    from tests.conftest import _create_test_user_and_session
+
+    _, session_token = await _create_test_user_and_session(
+        client, db_engine, email="compound@example.com", display_name="Compound User"
+    )
+    compound = f"{session_token}.B0atkJCFxK1rZlwWPMK97nVO2LnyDun7"
+    resp = await client.get(
+        "/auth/me",
+        headers={"Cookie": f"better-auth.session_token={compound}"},
+    )
+    assert resp.status_code == 200
+    assert resp.json()["email"] == "compound@example.com"
+
+
+@pytest.mark.asyncio
+async def test_get_me_raw_token_cookie(client, db_engine):
+    """Raw token (no dot) in cookie must still work — regression guard."""
+    from tests.conftest import _create_test_user_and_session
+
+    _, session_token = await _create_test_user_and_session(
+        client, db_engine, email="rawcookie@example.com", display_name="Raw Cookie User"
+    )
+    resp = await client.get(
+        "/auth/me",
+        headers={"Cookie": f"better-auth.session_token={session_token}"},
+    )
+    assert resp.status_code == 200
+    assert resp.json()["email"] == "rawcookie@example.com"
+
+
+@pytest.mark.asyncio
+async def test_get_me_compound_bearer(client, db_engine):
+    """Compound Bearer token (token.sessionId) must be parsed to extract the token part."""
+    from tests.conftest import _create_test_user_and_session
+
+    _, session_token = await _create_test_user_and_session(
+        client, db_engine, email="compoundbearer@example.com", display_name="Compound Bearer User"
+    )
+    compound = f"{session_token}.B0atkJCFxK1rZlwWPMK97nVO2LnyDun7"
+    resp = await client.get(
+        "/auth/me",
+        headers={"Authorization": f"Bearer {compound}"},
+    )
+    assert resp.status_code == 200
+    assert resp.json()["email"] == "compoundbearer@example.com"
+
+
 @pytest.mark.asyncio
 async def test_expired_session_rejected(client, db_engine):
     """Expired sessions must be rejected."""

api/tests/test_cache.py

@@ -0,0 +1,50 @@
+"""Tests for Redis/DragonflyDB caching lifecycle."""
+
+import pytest
+
+from cartsnitch_api.cache import CacheClient, close_redis, get_redis, init_redis
+
+
+@pytest.mark.asyncio
+async def test_init_redis_creates_client():
+    """Test that init_redis creates the Redis client."""
+    await init_redis()
+    try:
+        r = get_redis()
+        assert r is not None
+        await r.ping()
+    finally:
+        await close_redis()
+
+
+@pytest.mark.asyncio
+async def test_close_redis_clears_client():
+    """Test that close_redis properly closes and clears the client."""
+    await init_redis()
+    await close_redis()
+    assert get_redis() is None
+
+
+@pytest.mark.asyncio
+async def test_cache_client_get_returns_none_when_not_connected():
+    """Test that CacheClient.get returns None gracefully when Redis is down."""
+    client = CacheClient()
+    # Without init_redis, get should return None
+    result = await client.get("test-key")
+    assert result is None
+
+
+@pytest.mark.asyncio
+async def test_cache_client_set_does_not_raise_when_not_connected():
+    """Test that CacheClient.set does not raise when Redis is down."""
+    client = CacheClient()
+    # Without init_redis, set should not raise
+    await client.set("test-key", "test-value", ttl_seconds=60)
+
+
+@pytest.mark.asyncio
+async def test_cache_client_delete_does_not_raise_when_not_connected():
+    """Test that CacheClient.delete does not raise when Redis is down."""
+    client = CacheClient()
+    # Without init_redis, delete should not raise
+    await client.delete("test-key")

api/tests/test_config.py

@@ -0,0 +1,48 @@
+"""Tests for Settings config, specifically the database_url env var fallback."""
+
+import os
+
+from cartsnitch_api.config import Settings
+
+
+def test_database_url_prefers_cartsnitch_prefix():
+    """CARTSNITCH_DATABASE_URL takes precedence over DATABASE_URL."""
+    env = {
+        "CARTSNITCH_DATABASE_URL": "postgresql+asyncpg://user1:pass1@host1:5432/db1",
+        "DATABASE_URL": "postgresql://user2:pass2@host2:5432/db2",
+    }
+    settings = Settings(**env)
+    assert settings.database_url == "postgresql+asyncpg://user1:pass1@host1:5432/db1"
+
+
+def test_database_url_falls_back_to_database_url():
+    """When CARTSNITCH_DATABASE_URL is absent, DATABASE_URL is accepted."""
+    env = {
+        "DATABASE_URL": "postgresql://user:pass@dbhost:5432/mydb",
+    }
+    settings = Settings(**env)
+    assert settings.database_url == "postgresql+asyncpg://user:pass@dbhost:5432/mydb"
+
+
+def test_database_url_normalizes_plain_postgresql_prefix():
+    """DATABASE_URL with plain postgresql:// is normalized to postgresql+asyncpg://."""
+    env = {
+        "DATABASE_URL": "postgresql://cartsnitch:cartsnitch@localhost:5432/cartsnitch",
+    }
+    settings = Settings(**env)
+    assert settings.database_url == "postgresql+asyncpg://cartsnitch:cartsnitch@localhost:5432/cartsnitch"
+
+
+def test_database_url_preserves_asyncpg_prefix():
+    """CARTSNITCH_DATABASE_URL with postgresql+asyncpg:// is left unchanged."""
+    env = {
+        "CARTSNITCH_DATABASE_URL": "postgresql+asyncpg://cartsnitch:cartsnitch@localhost:5432/cartsnitch",
+    }
+    settings = Settings(**env)
+    assert settings.database_url == "postgresql+asyncpg://cartsnitch:cartsnitch@localhost:5432/cartsnitch"
+
+
+def test_database_url_default():
+    """When neither env var is set, the hardcoded default is used."""
+    settings = Settings()
+    assert settings.database_url == "postgresql+asyncpg://cartsnitch:cartsnitch@localhost:5432/cartsnitch"

api/tests/test_database.py

@@ -0,0 +1,62 @@
+"""Tests for database initialization and lifecycle."""
+
+import pytest
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+
+from cartsnitch_api.database import (
+    close_db,
+    create_db_engine,
+    get_engine,
+    init_db,
+)
+
+
+@pytest.mark.asyncio
+async def test_create_db_engine_creates_engine_with_pool_settings():
+    """Test that create_db_engine creates engine with correct pool settings."""
+    engine = create_db_engine()
+    assert engine is not None
+    pool = engine.pool
+    assert pool.size() == 10
+    assert pool._max_overflow == 20
+    await engine.dispose()
+
+
+@pytest.mark.asyncio
+async def test_init_db_sets_engine_and_factory():
+    """Test that init_db properly initializes the engine and session factory."""
+    await init_db()
+    try:
+        eng = get_engine()
+        assert eng is not None
+        from cartsnitch_api import database
+
+        assert database.async_session_factory is not None
+    finally:
+        await close_db()
+
+
+@pytest.mark.asyncio
+async def test_close_db_disposes_engine():
+    """Test that close_db properly disposes the engine."""
+    await init_db()
+    await close_db()
+    assert get_engine() is None
+    from cartsnitch_api import database
+
+    assert database.async_session_factory is None
+
+
+@pytest.mark.asyncio
+async def test_get_db_yields_session_after_init():
+    """Test that get_db yields working sessions after init_db."""
+    await init_db()
+    try:
+        from cartsnitch_api.database import get_db
+
+        gen = get_db()
+        session = await gen.__anext__()
+        assert isinstance(session, AsyncSession)
+        await gen.aclose()
+    finally:
+        await close_db()

api/tests/test_e2e/test_email_in_address.py

@@ -0,0 +1,61 @@
+"""Tests for GET /api/v1/me/email-in-address endpoint."""
+
+import pytest
+from httpx import AsyncClient
+
+
+@pytest.mark.asyncio
+async def test_get_email_in_address_authenticated(client: AsyncClient, auth_headers: dict):
+    """Authenticated user gets their email-in address."""
+    response = await client.get(
+        "/api/v1/me/email-in-address",
+        headers=auth_headers,
+    )
+
+    assert response.status_code == 200
+    data = response.json()
+    assert "email_address" in data
+    assert data["email_address"].startswith("receipts+")
+    assert data["email_address"].endswith("@receipts.cartsnitch.com")
+    assert len(data["email_address"]) > len("receipts+@receipts.cartsnitch.com")
+    assert "instructions" in data
+    assert "Meijer" in data["instructions"]
+    assert "Kroger" in data["instructions"]
+    assert "Target" in data["instructions"]
+
+
+@pytest.mark.asyncio
+async def test_get_email_in_address_unauthenticated(client: AsyncClient):
+    """Unauthenticated request returns 401."""
+    response = await client.get("/api/v1/me/email-in-address")
+    assert response.status_code == 401
+
+
+@pytest.mark.asyncio
+async def test_get_email_in_address_invalid_token(client: AsyncClient):
+    """Invalid JWT token returns 401."""
+    response = await client.get(
+        "/api/v1/me/email-in-address",
+        headers={"Authorization": "Bearer invalid-token-xyz"},
+    )
+    assert response.status_code == 401
+
+
+@pytest.mark.asyncio
+async def test_email_address_format(client: AsyncClient, auth_headers: dict):
+    """Email address format is receipts+{22-char-urlsafe-token}@receipts.cartsnitch.com."""
+    response = await client.get(
+        "/api/v1/me/email-in-address",
+        headers=auth_headers,
+    )
+
+    assert response.status_code == 200
+    data = response.json()
+    email = data["email_address"]
+    # Format: receipts+<22-char-urlsafe-token>@receipts.cartsnitch.com
+    assert email.startswith("receipts+")
+    assert email.endswith("@receipts.cartsnitch.com")
+    # token_urlsafe(16) produces 22 chars
+    middle = email[len("receipts+") : -len("@receipts.cartsnitch.com")]
+    assert len(middle) == 22
+    assert "@" not in middle

api/tests/test_middleware/test_rate_limit.py

@@ -1,47 +1,184 @@
 """Tests for rate limiting middleware."""
 
+import time
+from unittest.mock import AsyncMock, MagicMock, patch
+
 import pytest
 
-from cartsnitch_api.middleware.rate_limit import _SlidingWindowCounter
+from cartsnitch_api.config import settings
+from cartsnitch_api.middleware.rate_limit import (
+    InMemorySlidingWindow,
+    RedisSlidingWindow,
+    _get_client_ip,
+    _get_rate_limit_key,
+)
 
 
-class TestSlidingWindowCounter:
+class TestInMemorySlidingWindow:
     def test_allows_within_limit(self):
-        counter = _SlidingWindowCounter(max_requests=5, window_seconds=60)
+        limiter = InMemorySlidingWindow(max_requests=5, window_seconds=60)
         for i in range(5):
-            allowed, remaining, retry = counter.is_allowed("test-key")
+            allowed, remaining, retry = limiter.is_allowed("test-key")
             assert allowed is True
             assert remaining == 4 - i
 
     def test_blocks_over_limit(self):
-        counter = _SlidingWindowCounter(max_requests=3, window_seconds=60)
+        limiter = InMemorySlidingWindow(max_requests=3, window_seconds=60)
         for _ in range(3):
-            counter.is_allowed("test-key")
+            limiter.is_allowed("test-key")
 
-        allowed, remaining, retry = counter.is_allowed("test-key")
+        allowed, remaining, retry = limiter.is_allowed("test-key")
         assert allowed is False
         assert remaining == 0
         assert retry > 0
 
     def test_separate_keys(self):
-        counter = _SlidingWindowCounter(max_requests=2, window_seconds=60)
-        # Fill key-a
-        counter.is_allowed("key-a")
-        counter.is_allowed("key-a")
-        allowed_a, _, _ = counter.is_allowed("key-a")
+        limiter = InMemorySlidingWindow(max_requests=2, window_seconds=60)
+        limiter.is_allowed("key-a")
+        limiter.is_allowed("key-a")
+        allowed_a, _, _ = limiter.is_allowed("key-a")
         assert allowed_a is False
 
-        # key-b should still be allowed
-        allowed_b, remaining, _ = counter.is_allowed("key-b")
+        allowed_b, remaining, _ = limiter.is_allowed("key-b")
         assert allowed_b is True
         assert remaining == 1
 
+    def test_resets_after_window_expires(self):
+        limiter = InMemorySlidingWindow(max_requests=2, window_seconds=1)
+        for _ in range(2):
+            limiter.is_allowed("test-key")
+        allowed, remaining, _ = limiter.is_allowed("test-key")
+        assert allowed is False
+
+        time.sleep(1.1)
+        allowed, remaining, _ = limiter.is_allowed("test-key")
+        assert allowed is True
+        assert remaining == 1
+
+
+class TestGetClientIp:
+    def test_x_forwarded_for_single(self):
+        req = MagicMock()
+        req.headers = {"x-forwarded-for": "192.168.1.1"}
+        req.client = None
+        assert _get_client_ip(req) == "192.168.1.1"
+
+    def test_x_forwarded_for_multiple(self):
+        req = MagicMock()
+        req.headers = {"x-forwarded-for": "192.168.1.1, 10.0.0.1, 172.16.0.1"}
+        req.client = None
+        assert _get_client_ip(req) == "192.168.1.1"
+
+    def test_x_forwarded_for_with_port(self):
+        req = MagicMock()
+        req.headers = {"x-forwarded-for": "192.168.1.1:8080"}
+        req.client = None
+        assert _get_client_ip(req) == "192.168.1.1"
+
+    def test_no_forwarded_header(self):
+        req = MagicMock()
+        req.headers = {}
+        req.client.host = "127.0.0.1"
+        assert _get_client_ip(req) == "127.0.0.1"
+
+    def test_no_client(self):
+        req = MagicMock()
+        req.headers = {}
+        req.client = None
+        assert _get_client_ip(req) == "unknown"
+
+
+class TestGetRateLimitKey:
+    def _make_request(
+        self,
+        path: str = "/purchases",
+        method: str = "GET",
+        auth_header: str = "",
+        headers: dict | None = None,
+    ) -> MagicMock:
+        req = MagicMock()
+        req.url.path = path
+        req.method = method
+        req.headers = dict(headers) if headers else {}
+        if auth_header:
+            req.headers["authorization"] = auth_header
+        return req
+
+    def test_public_path_uses_public_limiter(self):
+        req = self._make_request("/public/inflation")
+        key, limiter = _get_rate_limit_key(req)
+        assert key.startswith("ip:")
+        assert limiter.max_requests == settings.rate_limit_requests
+
+    def test_auth_post_path_uses_strict_limiter(self):
+        req = self._make_request("/auth/login", method="POST")
+        key, limiter = _get_rate_limit_key(req)
+        assert key.startswith("ip:")
+        assert limiter.max_requests == settings.rate_limit_auth_requests
+        assert limiter.window_seconds == settings.rate_limit_auth_window_seconds
+
+    def test_auth_get_path_uses_auth_limiter(self):
+        req = self._make_request("/auth/me", method="GET")
+        key, limiter = _get_rate_limit_key(req)
+        assert key.startswith("ip:")
+        assert limiter.max_requests == settings.rate_limit_requests * 5
+
+    def test_authenticated_token_uses_auth_limiter(self):
+        req = self._make_request("/purchases", auth_header="Bearer token123")
+        key, limiter = _get_rate_limit_key(req)
+        assert key.startswith("token:")
+        assert limiter.max_requests == settings.rate_limit_requests * 5
+
+    def test_distinct_tokens_produce_distinct_keys(self):
+        req1 = self._make_request("/purchases", auth_header="Bearer token_alpha_12345")
+        req2 = self._make_request("/purchases", auth_header="Bearer token_beta_67890")
+        key1, _ = _get_rate_limit_key(req1)
+        key2, _ = _get_rate_limit_key(req2)
+        assert key1 != key2
+
+    def test_same_token_produces_same_key(self):
+        req1 = self._make_request("/purchases", auth_header="Bearer same_token_value_abc")
+        req2 = self._make_request("/purchases", auth_header="Bearer same_token_value_abc")
+        key1, _ = _get_rate_limit_key(req1)
+        key2, _ = _get_rate_limit_key(req2)
+        assert key1 == key2
+
+    def test_key_does_not_contain_raw_token_suffix(self):
+        raw_token = "my_secret_jwt_token_xyz"
+        req = self._make_request("/purchases", auth_header=f"Bearer {raw_token}")
+        key, _ = _get_rate_limit_key(req)
+        assert raw_token[-16:] not in key
+        assert raw_token not in key
+
+
+class TestRedisSlidingWindowFallback:
+    @pytest.mark.asyncio
+    async def test_fallback_on_redis_connection_error(self):
+        mock_redis = AsyncMock()
+        mock_redis.pipeline.return_value = AsyncMock()
+        pipe_mock = AsyncMock()
+        pipe_mock.execute.side_effect = Exception("Connection refused")
+        mock_redis.pipeline.return_value = pipe_mock
+
+        limiter = RedisSlidingWindow(mock_redis, max_requests=5, window_seconds=60)
+        allowed, remaining, retry = await limiter.is_allowed("test-key")
+        assert allowed is True
+        assert remaining == 4
+
+    @pytest.mark.asyncio
+    async def test_fallback_on_redis_error_during_pipeline(self):
+        mock_redis = AsyncMock()
+        pipe_mock = AsyncMock()
+        pipe_mock.execute.side_effect = Exception("Redis error")
+        mock_redis.pipeline.return_value = pipe_mock
+
+        limiter = RedisSlidingWindow(mock_redis, max_requests=3, window_seconds=60)
+        allowed, remaining, retry = await limiter.is_allowed("test-key")
+        assert allowed is True
+
 
 @pytest.mark.asyncio
 async def test_rate_limit_returns_429(client):
-    """Public endpoint should return 429 after limit exceeded."""
-    # The default limit is 60/min — we won't hit it in normal tests,
-    # but we verify the middleware adds rate limit headers.
     resp = await client.get("/public/inflation")
     assert "x-ratelimit-limit" in resp.headers
     assert "x-ratelimit-remaining" in resp.headers
@@ -49,7 +186,6 @@ async def test_rate_limit_returns_429(client):
 
 @pytest.mark.asyncio
 async def test_health_skips_rate_limit(client):
-    """Health endpoint should not have rate limit headers."""
     resp = await client.get("/health")
     assert resp.status_code == 200
     assert "x-ratelimit-limit" not in resp.headers

api/tests/test_openapi.py

@@ -6,13 +6,14 @@ from httpx import ASGITransport, AsyncClient
 from cartsnitch_api.main import app
 
 EXPECTED_ROUTES = [
-    # Auth (6)
+    # Auth (7)
     ("post", "/auth/register"),
     ("post", "/auth/login"),
     ("post", "/auth/refresh"),
     ("get", "/auth/me"),
     ("patch", "/auth/me"),
     ("delete", "/auth/me"),
+    ("get", "/auth/me/email-in-address"),
     # Stores (4)
     ("get", "/stores"),
     ("get", "/me/stores"),
@@ -89,4 +90,4 @@ async def test_route_count():
                 if method in ("get", "post", "put", "delete", "patch"):
                     count += 1
 
-        assert count == 33, f"Expected 33 routes, found {count}"
+        assert count == 34, f"Expected 34 routes, found {count}"

api/tests/test_routes/test_health.py

@@ -0,0 +1,77 @@
+"""Tests for health check endpoint."""
+
+import pytest
+from unittest.mock import AsyncMock, patch
+
+from cartsnitch_api.database import init_db, close_db
+
+
+@pytest.mark.asyncio
+async def test_health_returns_db_and_redis_fields(client):
+    """Test that health endpoint returns db and redis status fields."""
+    from cartsnitch_api.cache import init_redis, close_redis
+
+    await init_db()
+    await init_redis()
+
+    try:
+        response = await client.get("/health")
+        assert response.status_code == 200
+        data = response.json()
+        assert "status" in data
+        assert "db" in data
+        assert "redis" in data
+    finally:
+        await close_redis()
+        await close_db()
+
+
+@pytest.mark.asyncio
+async def test_health_returns_degraded_when_db_down():
+    """Test that health returns degraded when database is down."""
+    from cartsnitch_api.database import _engine
+    from cartsnitch_api.routes.health import health
+
+    # Simulate engine is None (DB not initialized)
+    with patch("cartsnitch_api.routes.health.get_engine", return_value=None):
+        response = await health()
+        assert response["status"] == "degraded"
+        assert response["db"] is False
+
+
+@pytest.mark.asyncio
+async def test_health_returns_ok_when_db_up(client):
+    """Test that health returns ok when database is up."""
+    from cartsnitch_api.database import init_db, close_db
+    from cartsnitch_api.cache import init_redis, close_redis
+
+    await init_db()
+    await init_redis()
+
+    try:
+        response = await client.get("/health")
+        assert response.status_code == 200
+        data = response.json()
+        if data["db"]:
+            assert data["status"] == "ok"
+    finally:
+        await close_redis()
+        await close_db()
+
+
+@pytest.mark.asyncio
+async def test_health_redis_down_does_not_make_unhealthy(client):
+    """Test that Redis being down does not make health return unhealthy."""
+    from cartsnitch_api.database import init_db, close_db
+
+    await init_db()
+
+    try:
+        response = await client.get("/health")
+        data = response.json()
+        # Redis being down should not make status "degraded"
+        # Only DB failure makes it degraded
+        if not data["db"]:
+            assert data["status"] == "degraded"
+    finally:
+        await close_db()

api/tests/test_routes/test_public.py

@@ -71,3 +71,97 @@ async def test_public_inflation(client, public_data):
     data = resp.json()
     assert "categories" in data
     assert "cartsnitch_index" in data
+
+
+@pytest.mark.asyncio
+async def test_trend_invalid_uuid(client):
+    resp = await client.get("/public/trends/not-a-uuid")
+    assert resp.status_code == 422
+    assert "detail" in resp.json()
+    assert "stack" not in resp.json()
+
+
+@pytest.mark.asyncio
+async def test_trend_days_zero(client, public_data):
+    pid = str(public_data["product"].id)
+    resp = await client.get(f"/public/trends/{pid}?days=0")
+    assert resp.status_code == 422
+    assert "detail" in resp.json()
+    assert "stack" not in resp.json()
+
+
+@pytest.mark.asyncio
+async def test_trend_days_negative(client, public_data):
+    pid = str(public_data["product"].id)
+    resp = await client.get(f"/public/trends/{pid}?days=-1")
+    assert resp.status_code == 422
+    assert "detail" in resp.json()
+    assert "stack" not in resp.json()
+
+
+@pytest.mark.asyncio
+async def test_trend_days_over_max(client, public_data):
+    pid = str(public_data["product"].id)
+    resp = await client.get(f"/public/trends/{pid}?days=999")
+    assert resp.status_code == 422
+    assert "detail" in resp.json()
+    assert "stack" not in resp.json()
+
+
+@pytest.mark.asyncio
+async def test_trend_days_valid(client, public_data):
+    pid = str(public_data["product"].id)
+    resp = await client.get(f"/public/trends/{pid}?days=30")
+    assert resp.status_code == 200
+    assert "product_name" in resp.json()
+
+
+@pytest.mark.asyncio
+async def test_store_comparison_empty_list(client):
+    resp = await client.get("/public/store-comparison")
+    assert resp.status_code == 400
+    assert "detail" in resp.json()
+
+
+@pytest.mark.asyncio
+async def test_store_comparison_category_xss(client, public_data):
+    pid = str(public_data["product"].id)
+    resp = await client.get(
+        f"/public/store-comparison?product_ids={pid}&category=<script>alert(1)</script>"
+    )
+    assert resp.status_code == 422
+    assert "detail" in resp.json()
+    assert "stack" not in resp.json()
+
+
+@pytest.mark.asyncio
+async def test_store_comparison_category_sql_injection(client, public_data):
+    pid = str(public_data["product"].id)
+    resp = await client.get(f"/public/store-comparison?product_ids={pid}&category='; DROP TABLE--")
+    assert resp.status_code == 422
+    assert "detail" in resp.json()
+    assert "stack" not in resp.json()
+
+
+@pytest.mark.asyncio
+async def test_inflation_invalid_period(client, public_data):
+    resp = await client.get("/public/inflation?period=10years")
+    assert resp.status_code == 422
+    assert "detail" in resp.json()
+    assert "stack" not in resp.json()
+
+
+@pytest.mark.asyncio
+async def test_inflation_valid_periods(client, public_data):
+    for period in ["all-time", "1y", "6m", "3m", "1m"]:
+        resp = await client.get(f"/public/inflation?period={period}")
+        assert resp.status_code == 200, f"period={period} failed"
+
+
+@pytest.mark.asyncio
+async def test_inflation_category_too_long(client, public_data):
+    long_category = "x" * 200
+    resp = await client.get(f"/public/inflation?category={long_category}")
+    assert resp.status_code == 422
+    assert "detail" in resp.json()
+    assert "stack" not in resp.json()

auth/.env.example

@@ -9,3 +9,7 @@ DATABASE_URL=postgresql://cartsnitch:cartsnitch@localhost:5432/cartsnitch
 
 # Port the auth service listens on
 PORT=3001
+
+# Resend email provider for transactional email
+RESEND_API_KEY=re_your_api_key_here
+FROM_EMAIL=CartSnitch <noreply@cartsnitch.com>

auth/Dockerfile

@@ -1,4 +1,5 @@
 FROM node:22-alpine AS builder
+RUN apk update && apk upgrade --no-cache
 WORKDIR /app
 COPY package.json package-lock.json* ./
 RUN npm ci
@@ -7,6 +8,7 @@ COPY src/ src/
 RUN npm run build
 
 FROM node:22-alpine
+RUN apk update && apk upgrade --no-cache
 WORKDIR /app
 ENV NODE_ENV=production
 COPY package.json package-lock.json* ./

auth/package.json

@@ -7,18 +7,20 @@
     "dev": "tsx watch src/index.ts",
     "build": "tsc",
     "start": "node dist/index.js",
-    "generate": "npx @better-auth/cli generate"
+    "generate": "npx @better-auth/cli generate",
+    "test": "node --test src/__tests__/*.test.ts"
   },
   "dependencies": {
+    "bcrypt": "^6.0.0",
     "better-auth": "^1.2.0",
     "pg": "^8.13.0",
-    "bcrypt": "^5.1.1"
+    "resend": "^6.11.0"
   },
   "devDependencies": {
+    "@types/bcrypt": "^6.0.0",
     "@types/node": "^22.0.0",
     "@types/pg": "^8.11.0",
-    "@types/bcrypt": "^5.0.2",
     "tsx": "^4.19.0",
     "typescript": "^5.7.0"
   }
-}
+}

auth/src/__tests__/health.test.ts

@@ -0,0 +1,136 @@
+import { describe, it } from 'node:test';
+import { equal } from 'node:assert';
+import http from 'node:http';
+
+describe('Auth health endpoint', () => {
+  const startHealthServer = (poolMock) => {
+    return new Promise((resolve) => {
+      const server = http.createServer(async (req, res) => {
+        if (req.url === '/health' && req.method === 'GET') {
+          try {
+            const client = await poolMock.connect();
+            try {
+              await Promise.race([
+                client.query('SELECT 1'),
+                new Promise((_, reject) => setTimeout(() => reject(new Error('DB timeout')), 2000)),
+              ]);
+            } finally {
+              client.release();
+            }
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ status: 'ok', db: 'reachable' }));
+          } catch (err) {
+            // Mirror src/index.ts: log the error and include the message in the
+            // response body so /health 503s are diagnosable from pod logs.
+            console.error(
+              '[auth /health] DB probe failed:',
+              err instanceof Error ? `${err.name}: ${err.message}` : err,
+            );
+            const detail = err instanceof Error ? err.message : 'unknown error';
+            res.writeHead(503, { 'Content-Type': 'application/json' });
+            res.end(
+              JSON.stringify({ status: 'error', db: 'unreachable', error: detail }),
+            );
+          }
+          return;
+        }
+        res.writeHead(404);
+        res.end();
+      });
+      server.listen(0, '0.0.0.0', () => {
+        const addr = server.address();
+        const port = typeof addr === 'object' && addr ? addr.port : 0;
+        resolve({ port, close: () => server.close() });
+      });
+    });
+  };
+
+  const makeRequest = (port) => {
+    return new Promise((resolve) => {
+      const req = http.get(`http://localhost:${port}/health`, (res) => {
+        let body = '';
+        res.on('data', (chunk) => { body += chunk; });
+        res.on('end', () => {
+          resolve({ status: res.statusCode, body });
+        });
+      });
+      req.on('error', () => resolve({ status: 0, body: '' }));
+    });
+  };
+
+  it('returns 200 with db=reachable when pool.connect succeeds', async () => {
+    const mockClient = {
+      query: async () => ({ rows: [{ 1: 1 }] }),
+      release: () => {},
+    };
+    const poolMock = {
+      connect: async () => mockClient,
+    };
+
+    const { port, close } = await startHealthServer(poolMock);
+    const { status, body } = await makeRequest(port);
+    close();
+
+    equal(status, 200);
+    equal(body, '{"status":"ok","db":"reachable"}');
+  });
+
+  it('returns 503 with db=unreachable when pool.connect throws', async () => {
+    const poolMock = {
+      connect: async () => { throw new Error('connection refused'); },
+    };
+
+    const { port, close } = await startHealthServer(poolMock);
+    const { status, body } = await makeRequest(port);
+    close();
+
+    equal(status, 503);
+    const parsed = JSON.parse(body);
+    equal(parsed.status, 'error');
+    equal(parsed.db, 'unreachable');
+    equal(parsed.error, 'connection refused');
+  });
+
+  it('returns 503 with db=unreachable when query times out', async () => {
+    const mockClient = {
+      query: async () => {
+        await new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), 3000));
+      },
+      release: () => {},
+    };
+    const poolMock = {
+      connect: async () => mockClient,
+    };
+
+    const { port, close } = await startHealthServer(poolMock);
+    const { status, body } = await makeRequest(port);
+    close();
+
+    equal(status, 503);
+    const parsed = JSON.parse(body);
+    equal(parsed.status, 'error');
+    equal(parsed.db, 'unreachable');
+    // The query promise rejects with a synthetic 'timeout' error; the
+    // Promise.race wrapper also rejects with 'DB timeout'. The body should
+    // surface whichever error was thrown — accept either to stay robust.
+    equal(typeof parsed.error, 'string');
+    equal(parsed.error.length > 0, true);
+  });
+
+  it('returns a terminal response for unknown paths (no hang)', async () => {
+    const poolMock = { connect: async () => ({ query: async () => {}, release: () => {} }) };
+    const { port, close } = await startHealthServer(poolMock);
+
+    const result = await new Promise<{ status: number }>((resolve) => {
+      const req = http.get(`http://localhost:${port}/`, (res) => {
+        res.resume();
+        res.on('end', () => resolve({ status: res.statusCode ?? 0 }));
+      });
+      req.on('error', () => resolve({ status: 0 }));
+      setTimeout(() => resolve({ status: -1 }), 1000);
+    });
+    close();
+
+    equal(result.status !== -1, true, 'Unknown path must return a terminal response within 1s');
+  });
+});

auth/src/auth.ts

@@ -1,20 +1,30 @@
 import { betterAuth } from "better-auth";
 import bcrypt from "bcrypt";
 import pg from "pg";
+import { Resend } from "resend";
 
 const { Pool } = pg;
 
-const pool = new Pool({
-  connectionString:
-    process.env.DATABASE_URL ??
-    "postgresql://cartsnitch:cartsnitch@localhost:5432/cartsnitch",
-});
-
 const secret = process.env.BETTER_AUTH_SECRET;
 if (!secret) {
   throw new Error("BETTER_AUTH_SECRET environment variable is required");
 }
 
+const databaseUrl = process.env.DATABASE_URL;
+if (!databaseUrl) {
+  console.warn(
+    "WARNING: DATABASE_URL is not set — using default localhost connection. " +
+    "Set DATABASE_URL for production deployments."
+  );
+}
+
+export const pool = new Pool({
+  connectionString: databaseUrl ?? "postgresql://cartsnitch:cartsnitch@localhost:5432/cartsnitch",
+});
+
+const resend = new Resend(process.env.RESEND_API_KEY);
+const fromEmail = process.env.FROM_EMAIL || "CartSnitch <noreply@cartsnitch.com>";
+
 export const auth = betterAuth({
   database: pool,
   basePath: "/auth",
@@ -27,7 +37,7 @@ export const auth = betterAuth({
     maxPasswordLength: 128,
     password: {
       hash: async (password: string) => {
-        return bcrypt.hash(password, 10);
+        return bcrypt.hash(password, 12);
       },
       verify: async (data: { hash: string; password: string }) => {
         return bcrypt.compare(data.password, data.hash);
@@ -35,7 +45,29 @@ export const auth = betterAuth({
     },
   },
 
+  emailVerification: {
+    sendOnSignUp: true,
+    autoSignInAfterVerification: true,
+    sendVerificationEmail: async ({ user, url }) => {
+      await resend.emails.send({
+        from: fromEmail,
+        to: user.email,
+        subject: "Verify your CartSnitch email",
+        html: `<p>Hi ${user.name || ""},</p><p>Click the link below to verify your email address:</p><p><a href="${url}">Verify Email</a></p><p>This link expires in 1 hour.</p><p>— CartSnitch</p>`,
+      });
+    },
+  },
+
   session: {
+    modelName: "sessions",
+    fields: {
+      userId: "user_id",
+      expiresAt: "expires_at",
+      ipAddress: "ip_address",
+      userAgent: "user_agent",
+      createdAt: "created_at",
+      updatedAt: "updated_at",
+    },
     expiresIn: 60 * 60 * 24 * 7, // 7 days
     updateAge: 60 * 60 * 24, // refresh after 1 day
     cookieCache: {
@@ -86,5 +118,6 @@ export const auth = betterAuth({
     "https://cartsnitch.com",
     "https://cartsnitch.farh.net",
     "https://cartsnitch.dev.farh.net",
+    "https://cartsnitch.uat.farh.net",
   ],
-});
+});

auth/src/index.ts

@@ -1,6 +1,6 @@
 import { createServer } from "node:http";
 import { toNodeHandler } from "better-auth/node";
-import { auth } from "./auth.js";
+import { auth, pool } from "./auth.js";
 
 const port = parseInt(process.env.PORT ?? "3001", 10);
 
@@ -8,13 +8,37 @@ const handler = toNodeHandler(auth);
 
 const server = createServer(async (req, res) => {
   // Health check
-  if (req.url === "/health" && req.method === "GET") {
-    res.writeHead(200, { "Content-Type": "application/json" });
-    res.end(JSON.stringify({ status: "ok" }));
+  if ((req.url === "/health" || req.url === "/auth/health") && req.method === "GET") {
+    try {
+      const client = await pool.connect();
+      try {
+        await Promise.race([
+          client.query("SELECT 1"),
+          new Promise((_, reject) => setTimeout(() => reject(new Error("DB timeout")), 2000)),
+        ]);
+      } finally {
+        client.release();
+      }
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ status: "ok", db: "reachable" }));
+    } catch (err) {
+      // Log the actual error so /health 503s are diagnosable from pod logs
+      // (CAR-1276: UAT auth was crashlooping with no log output beyond the
+      // initial "listening on port 3001" line because this catch was empty).
+      console.error(
+        "[auth /health] DB probe failed:",
+        err instanceof Error ? `${err.name}: ${err.message}` : err,
+      );
+      const detail = err instanceof Error ? err.message : "unknown error";
+      res.writeHead(503, { "Content-Type": "application/json" });
+      res.end(
+        JSON.stringify({ status: "error", db: "unreachable", error: detail }),
+      );
+    }
     return;
   }
 
-  // All /auth/* routes handled by Better-Auth
+  // All other routes handled by Better-Auth (returns 404 for unknown paths)
   await handler(req, res);
 });
 

auth/tsconfig.json

@@ -12,5 +12,5 @@
     "resolveJsonModule": true
   },
   "include": ["src"],
-  "exclude": ["node_modules", "dist"]
+  "exclude": ["node_modules", "dist", "src/__tests__"]
 }

common/README.md

@@ -0,0 +1,28 @@
+# CartSnitch Common
+
+Shared models, schemas, and utilities for CartSnitch services.
+
+## Test Users
+
+The following users are seeded by `cartsnitch-seed` and can be used for local development and UAT.
+
+| Email | Password | Display Name | Notes |
+|---|---|---|---|
+| `uat@cartsnitch.com` | `CartSnitch-UAT-2026!` | UAT Tester | Primary UAT account. Use for regression testing in the CartSnitch frontend. Created by the seed runner via Better-Auth's bcrypt path — credentials work against the live auth service. Idempotent; re-running the seed skips this user if it already exists. |
+
+### Running the Seed
+
+```bash
+# Install with seed dependencies
+pip install -e "cartsnitch-common[seed]"
+
+# Run (requires CARTSNITCH_DATABASE_URL_SYNC)
+CARTSNITCH_DATABASE_URL_SYNC=postgresql://user:pass@localhost:5432/cartsnitch \
+  cartsnitch-seed
+```
+
+### Architecture
+
+- **Models** live in `src/cartsnitch_common/models/`
+- **Alembic migrations** run via the `api` service (`api/alembic/`)
+- **Seed runner** runs via `cartsnitch-seed` (installed as a package entry point)

common/alembic/env.py

@@ -14,7 +14,7 @@ if config.config_file_name is not None:
 
 db_url = os.environ.get("CARTSNITCH_DATABASE_URL_SYNC")
 if db_url:
-    config.set_main_option("sqlalchemy.url", db_url)
+    config.set_main_option("sqlalchemy.url", db_url.replace("%", "%%"))
 
 target_metadata = Base.metadata
 

common/alembic/versions/001_add_email_inbound_token.py

@@ -0,0 +1,37 @@
+"""Add email_inbound_token to users.
+
+Revision ID: 001_add_email_inbound_token
+Revises:
+Create Date: 2026-04-02
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+
+from alembic import op
+
+revision: str = "001_add_email_inbound_token"
+down_revision: str | None = None
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.add_column("users", sa.Column("email_inbound_token", sa.String(22), nullable=True))
+    op.create_unique_constraint("uq_users_email_inbound_token", "users", ["email_inbound_token"])
+
+    # Backfill existing users with generated tokens (PostgreSQL)
+    op.execute(
+        "UPDATE users SET email_inbound_token = "
+        "substring(replace(gen_random_uuid()::text, '-', ''), 1, 22) "
+        "WHERE email_inbound_token IS NULL"
+    )
+
+    # Alter to non-nullable
+    op.alter_column("users", "email_inbound_token", nullable=False)
+
+
+def downgrade() -> None:
+    op.drop_constraint("uq_users_email_inbound_token", "users", type_="unique")
+    op.drop_column("users", "email_inbound_token")

common/alembic/versions/002_add_normalized_products_upc_variants_index.py

@@ -0,0 +1,28 @@
+"""Add GIN index on normalized_products.upc_variants for fast JSON containment lookups.
+
+Revision ID: 002_add_normalized_products_upc_variants_index
+Revises: 001_add_email_inbound_token
+Create Date: 2026-04-14
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+
+revision: str = "002_add_normalized_products_upc_variants_index"
+down_revision: str | None = "001_add_email_inbound_token"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.create_index(
+        "ix_normalized_products_upc_variants",
+        "normalized_products",
+        ["upc_variants"],
+        postgresql_using="gin",
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("ix_normalized_products_upc_variants", table_name="normalized_products")

common/pyproject.toml

@@ -27,6 +27,7 @@ dev = [
 ]
 seed = [
     "faker>=33.0,<34.0",
+    "bcrypt>=4.0,<6.0",
 ]
 
 [project.scripts]

common/src/cartsnitch_common/database.py

@@ -1,17 +1,36 @@
 """Database engine and session factories for sync and async usage."""
 
 from collections.abc import AsyncGenerator, Generator
+from typing import TYPE_CHECKING
 
 from sqlalchemy import create_engine
-from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession, async_sessionmaker, create_async_engine
 from sqlalchemy.orm import Session, sessionmaker
 
 from cartsnitch_common.config import settings
 
+if TYPE_CHECKING:
+    from sqlalchemy.engine import Engine
 
-def get_async_engine(url: str | None = None):
-    """Create an async SQLAlchemy engine."""
-    return create_async_engine(url or settings.database_url, echo=settings.debug)
+# Module-level async engine cache — one engine per unique URL, shared across all callers.
+# This prevents pool exhaustion in high-throughput workers (e.g. email-worker hitting
+# DragonflyDB/Postgres repeatedly per message).  pool_size=10, max_overflow=20 gives
+# headroom for bursts while capping max connections at 30 per URL.
+_async_engine_cache: dict[str, "AsyncEngine"] = {}
+
+
+def get_async_engine(url: str | None = None) -> "AsyncEngine":
+    """Get or create a cached async engine for the given URL."""
+    target = url or settings.database_url
+    if target not in _async_engine_cache:
+        _async_engine_cache[target] = create_async_engine(
+            target,
+            echo=settings.debug,
+            pool_size=10,
+            max_overflow=20,
+            pool_pre_ping=True,
+        )
+    return _async_engine_cache[target]
 
 
 def get_sync_engine(url: str | None = None):

common/src/cartsnitch_common/models/product.py

@@ -3,6 +3,7 @@
 from typing import TYPE_CHECKING
 
 from sqlalchemy import JSON, String
+from sqlalchemy.dialects.postgresql import JSONB
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 
 from cartsnitch_common.constants import ProductCategory, SizeUnit
@@ -26,7 +27,9 @@ class NormalizedProduct(UUIDPrimaryKeyMixin, TimestampMixin, Base):
     brand: Mapped[str | None] = mapped_column(String(200))
     size: Mapped[str | None] = mapped_column(String(50))
     size_unit: Mapped[SizeUnit | None] = mapped_column(String(10))
-    upc_variants: Mapped[list[str] | None] = mapped_column(JSON, default=list)
+    upc_variants: Mapped[list[str] | None] = mapped_column(
+        JSON().with_variant(JSONB(), "postgresql"), default=list
+    )
 
     # Relationships
     purchase_items: Mapped[list["PurchaseItem"]] = relationship(back_populates="normalized_product")

common/src/cartsnitch_common/models/user.py

@@ -1,10 +1,11 @@
 """User and UserStoreAccount models."""
 
+import secrets
 import uuid
 from datetime import datetime
 from typing import TYPE_CHECKING
 
-from sqlalchemy import JSON, Boolean, DateTime, ForeignKey, String, Text, UniqueConstraint
+from sqlalchemy import JSON, Boolean, DateTime, ForeignKey, String, Text, UniqueConstraint, text
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 
 from cartsnitch_common.constants import AccountStatus
@@ -21,7 +22,16 @@ class User(UUIDPrimaryKeyMixin, TimestampMixin, Base):
     __tablename__ = "users"
 
     email: Mapped[str] = mapped_column(String(255), nullable=False, unique=True)
-    hashed_password: Mapped[str] = mapped_column(String(255), nullable=False)
+    email_inbound_token: Mapped[str] = mapped_column(
+        String(22),
+        nullable=False,
+        unique=True,
+        default=lambda: secrets.token_urlsafe(16),
+        server_default=text(
+            "replace(replace(trim(trailing '=' from encode(gen_random_bytes(16), 'base64')), '+', '-'), '/', '_')"
+        ),
+    )
+    hashed_password: Mapped[str | None] = mapped_column(String(255), nullable=True)
     display_name: Mapped[str | None] = mapped_column(String(100))
     email_verified: Mapped[bool] = mapped_column(Boolean, nullable=False, server_default="false")
     image: Mapped[str | None] = mapped_column(Text, nullable=True)

common/src/cartsnitch_common/schemas/user.py

@@ -20,6 +20,7 @@ class UserRead(BaseModel):
     id: uuid.UUID
     email: str
     display_name: str | None
+    email_inbound_token: str
     created_at: datetime
     updated_at: datetime
 

common/src/cartsnitch_common/seed/runner.py

@@ -2,8 +2,10 @@
 
 import random
 import time
+import uuid
 from typing import Any
 
+import bcrypt
 from faker import Faker
 from sqlalchemy import text
 from sqlalchemy.orm import Session
@@ -184,6 +186,65 @@ def run_seed(
 
         session.commit()
 
+        _seed_uat_user(session)
+
     elapsed = time.monotonic() - t0
     _log("")
     _log(f"Seed complete in {elapsed:.1f}s")
+
+
+# ---------------------------------------------------------------------------
+# UAT seed user
+# ---------------------------------------------------------------------------
+
+UAT_EMAIL = "uat@cartsnitch.com"
+UAT_PASSWORD = "CartSnitch-UAT-2026!"
+UAT_DISPLAY_NAME = "UAT Tester"
+UAT_USER_ID = uuid.UUID("00000000-0000-0000-0000-000000000001")
+
+
+def _seed_uat_user(session: Session) -> None:
+    """Insert or verify the dedicated UAT test user.
+
+    The user is created via Better-Auth's bcrypt hashing path so credentials
+    work against the live auth service. Idempotent — skips if the user already
+    exists.
+    """
+    existing = session.execute(
+        text("SELECT id FROM users WHERE email = :email"),
+        {"email": UAT_EMAIL},
+    ).fetchone()
+
+    if existing is not None:
+        _log(f"UAT user {UAT_EMAIL} already exists — skipping")
+        return
+
+    password_hash = bcrypt.hashpw(UAT_PASSWORD.encode(), bcrypt.gensalt()).decode()
+
+    session.execute(
+        text(
+            "INSERT INTO users (id, email, hashed_password, display_name, email_verified, created_at, updated_at) "
+            "VALUES (:id, :email, :hashed_password, :display_name, true, now(), now())"
+        ),
+        {
+            "id": str(UAT_USER_ID),
+            "email": UAT_EMAIL,
+            "hashed_password": password_hash,
+            "display_name": UAT_DISPLAY_NAME,
+        },
+    )
+
+    session.execute(
+        text(
+            "INSERT INTO accounts (id, user_id, account_id, provider_id, password, created_at, updated_at) "
+            "VALUES (gen_random_uuid()::text, :user_id, :account_id, 'credential', :password, now(), now())"
+        ),
+        {
+            "user_id": str(UAT_USER_ID),
+            "account_id": str(UAT_USER_ID),
+            "password": password_hash,
+        },
+    )
+
+    session.commit()
+    _log(f"UAT user {UAT_EMAIL} created")

common/tests/test_models.py

@@ -147,6 +147,40 @@ class TestStoreLocationModel:
         assert loc.lat == pytest.approx(42.2808)
 
 
+class TestUserModel:
+    def test_email_inbound_token_auto_populated(self, session):
+        user = User(
+            id=uuid.uuid4(),
+            email="token_test@example.com",
+            hashed_password="hashed",
+            created_at=datetime.now(UTC),
+            updated_at=datetime.now(UTC),
+        )
+        session.add(user)
+        session.commit()
+        assert user.email_inbound_token is not None
+        assert len(user.email_inbound_token) == 22
+
+    def test_email_inbound_token_unique(self, session):
+        user1 = User(
+            id=uuid.uuid4(),
+            email="user1@example.com",
+            hashed_password="hashed",
+            created_at=datetime.now(UTC),
+            updated_at=datetime.now(UTC),
+        )
+        user2 = User(
+            id=uuid.uuid4(),
+            email="user2@example.com",
+            hashed_password="hashed",
+            created_at=datetime.now(UTC),
+            updated_at=datetime.now(UTC),
+        )
+        session.add_all([user1, user2])
+        session.commit()
+        assert user1.email_inbound_token != user2.email_inbound_token
+
+
 class TestUserStoreAccountModel:
     def test_account_status_enum(self, session):
         user = User(

content/marketing/about.md

@@ -0,0 +1,72 @@
+# About CartSnitch
+
+## Our Mission
+
+We believe consumers deserve to know what they're really paying for at the grocery store.
+
+Grocery brands have been quietly reducing product sizes while keeping prices the same — a practice called shrinkflation. Most shoppers don't notice because the shelf price doesn't change. But the unit price goes up, and families end up paying more for less.
+
+CartSnitch exists to make that visible.
+
+---
+
+## The Problem We're Solving
+
+The average US family loses an estimated $300–$500 per year to shrinkflation. It's not dramatic. It happens slowly, product by product, category by category. A cereal box that's 10% smaller. A chip bag with 15% less in it. A detergent bottle that doesn't fill the dispenser the way it used to.
+
+These changes are legal. Manufacturers don't have to announce them. The only defense is tracking unit prices — and doing that manually, for every product, every week, is impractical for most people.
+
+So we built CartSnitch to do it automatically.
+
+---
+
+## What We Built
+
+CartSnitch is a grocery price tracking and shrinkflation detection app. When you connect your store account, we:
+- Track unit prices on the products you buy
+- Alert you when a product gets smaller or more expensive
+- Compare your total grocery bill across stores
+- Show you the biggest shrinkflation offenders we've found
+
+We're in beta. We're adding more products and stores every week.
+
+---
+
+## The Team
+
+**Penny Pincherton** — CEO and Co-founder
+Penny has spent her career in consumer finance and advocacy. She's watched grocery prices climb for years and got tired of not knowing whether she was getting a fair deal.
+
+**Savannah Savings** — CMO
+Savannah leads brand and communications at CartSnitch. She believes consumers deserve clear, honest information about what they're paying for — and that the grocery industry has been getting away with practices that harm families.
+
+**Chip Overstock** — CTO
+Chip has built data infrastructure at scale. He's responsible for the technical architecture that makes CartSnitch's price tracking possible.
+
+We're a small team. We care about this problem. We use the product ourselves.
+
+---
+
+## Our Approach
+
+- **Consumer-first.** Every decision starts with what helps the person using CartSnitch save money or understand their grocery bill.
+- **Data-backed.** Every claim we make is backed by numbers. We track unit prices, not shelf prices.
+- **Transparent.** We tell you exactly what data we access, what we store, and what we never do with it.
+- **Honest about scope.** CartSnitch focuses on shrinkflation detection. Price gouging monitoring is not currently in scope.
+
+---
+
+## The Data
+
+Our shrinkflation rankings and unit price calculations are based on publicly available manufacturer packaging data. USDA FoodData Central provides reference data for package sizing baselines. As we grow, we'll publish our methodology so anyone can verify our numbers.
+
+Production data will refine and validate our estimates. We will always note when statistics are directional versus based on real transaction data.
+
+---
+
+## Get In Touch
+
+- **General:** hello@cartsnitch.app
+- **Press:** press@cartsnitch.app
+- **Partnerships:** partners@cartsnitch.app
+- **Bug reports:** We use in-app feedback

content/marketing/app-store-listing.md

@@ -0,0 +1,100 @@
+# App Store / PWA Listing Copy
+
+**Target:** April 24, 2026
+
+---
+
+## iOS App Store
+
+**App Name:** CartSnitch — Grocery Price Tracker
+
+**Subtitle:** Track prices. Catch shrinkflation.
+
+**Short description (170 characters max):**
+Know when your groceries get smaller or more expensive.
+
+**Full description (4000 characters max):**
+You go to the grocery store. You buy the same things you always buy. But lately, the cereal box feels lighter. The chips bag seems smaller. The detergent bottle doesn't fill up like it used to.
+
+You're not imagining it. It's called shrinkflation — and it's costing the average family hundreds of dollars a year.
+
+CartSnitch helps you catch it.
+
+**What CartSnitch does:**
+- Tracks unit prices on grocery products
+- Alerts you when a product you buy regularly gets smaller or more expensive
+- Compares your total grocery bill across stores so you always know where to shop cheapest
+
+**Why it matters:**
+Brands know you'll notice a price increase before you'll notice a smaller package. So instead of raising prices, they shrink products. The shelf price stays the same. You pay more per ounce without realizing it.
+
+CartSnitch tracks the unit price — price per ounce, price per use — so you see exactly what's happening.
+
+**Key features:**
+- Unit price tracking across grocery products
+- Personalized price alerts on products you buy regularly
+- Store comparison — see your total basket cost at different stores
+- Shrinkflation tracker — see which products have changed the most
+
+**This is beta.** We're adding more products and stores every week.
+
+---
+
+## Google Play Store
+
+**Tagline:** Track prices. Catch shrinkflation.
+
+**Short description (80 characters):**
+Know when your groceries get smaller or more expensive.
+
+**Full description:**
+You go to the grocery store. You buy the same things you always buy. But lately, the cereal box feels lighter. The chips bag seems smaller. The detergent bottle doesn't fill up like it used to.
+
+You're not imagining it. It's called shrinkflation — and it's costing the average family hundreds of dollars a year.
+
+CartSnitch helps you catch it.
+
+**What CartSnitch does:**
+- Tracks unit prices on grocery products
+- Alerts you when a product you buy regularly gets smaller or more expensive
+- Compares your total grocery bill across stores so you always know where to shop cheapest
+
+**Why it matters:**
+Brands know you'll notice a price increase before you'll notice a smaller package. So instead of raising prices, they shrink products. The shelf price stays the same. You pay more per ounce without realizing it.
+
+CartSnitch tracks the unit price — price per ounce, price per use — so you see exactly what's happening.
+
+**Key features:**
+- Unit price tracking across grocery products
+- Personalized price alerts on products you buy regularly
+- Store comparison — see your total basket cost at different stores
+- Shrinkflation tracker — see which products have changed the most
+
+**This is beta.** We're adding more products and stores every week.
+
+---
+
+## Feature Highlights (3 bullets, iOS)
+
+- **Unit price tracking** — See exactly what you're paying per ounce on every product
+- **Shrinkflation alerts** — Get notified when your regular products get smaller or more expensive
+- **Store comparison** — Compare your total grocery bill across stores in seconds
+
+## Feature Highlights (4 bullets, Google Play)
+
+- Track unit prices on grocery products
+- Personalized alerts when products you buy change
+- Compare grocery costs across stores
+- See the biggest shrinkflation offenders
+
+---
+
+## Keywords (iOS — 100 character limit)
+
+grocery, price tracker, savings, shrinkflation, unit price, grocery savings, price compare, food prices, grocery deals, price alert, grocery app
+
+---
+
+## Search Terms (Google Play)
+
+grocery price tracker, grocery savings app, price comparison grocery, shrinkflation app, unit price calculator, grocery deal app, grocery savings tracker

content/marketing/blog/cartsnitch-vs-flipp.md

@@ -0,0 +1,53 @@
+---
+title: "CartSnitch vs Flipp: Which App Actually Helps You Save More on Groceries?"
+slug: cartsnitch-vs-flipp
+status: draft
+version: 1.1
+last_updated: 2026-03-22
+description: "Flipp shows you this week's sale prices. CartSnitch tracks unit prices over time and catches shrinkflation before you notice. Here's when each tool wins."
+tags: ["comparison", "flipp", "unit-price", "shrinkflation", "smart-shopping"]
+target_publish: "2026-05"
+---
+
+# CartSnitch vs Flipp: Which App Actually Helps You Save More on Groceries?
+
+Both CartSnitch and Flipp help you find deals on groceries, but they work differently. Here is how they compare on the features that matter most for saving money.
+
+## What Is Flipp?
+
+Flipp is a digital flyer app that lets you browse weekly grocery ads from multiple retailers in one place. You can clip coupons and create a shopping list from featured deals.
+
+## What Is CartSnitch?
+
+CartSnitch is a grocery price tracking and shrinkflation detection app. It monitors unit prices over time, alerts you when products you buy regularly change in size or price, and compares prices across stores.
+
+## Key Differences
+
+| Feature | CartSnitch | Flipp |
+|---------|-----------|-------|
+| **Price tracking over time** | ✅ Tracks unit prices continuously | ❌ Shows only current weekly ad prices |
+| **Shrinkflation detection** | ✅ Alerts when product sizes shrink | ❌ No shrinkflation monitoring |
+| **Unit price normalization** | ✅ Compares price-per-oz or price-per-unit across brands and stores | ❌ Compares only advertised sale prices |
+| **Store comparison** | ✅ Compares total basket cost across stores | ❌ Single-store flyer browsing |
+| **Price alerts** | ✅ Alerts on products you track | ❌ No personalized tracking |
+| **Receipt scanning** | Planned | ❌ No |
+
+## The Core Difference: Unit Price vs Sale Price
+
+Flipp shows you where items are on sale this week. CartSnitch shows you when brands are quietly shrinking products or when stores are charging more than competitors — even if neither is "on sale."
+
+**Example:** A cereal brand reduces its box from 18 oz to 15.5 oz. The shelf price stays the same. Flipp shows no deal. CartSnitch flags it as a 16.1% unit price increase.
+
+This is shrinkflation. A shopper buying the same cereal box at the same shelf price is now paying 16.1% more per ounce — without any price tag ever changing.
+
+## Which App Saves You More?
+
+**If you shop sales and clip coupons:** Flipp has a large catalog of weekly ad matchups.
+
+**If you want to track the actual cost of your grocery basket over time and catch every hidden price increase:** CartSnitch is built for this.
+
+Many users end up using both — Flipp for browsing weekly deals, CartSnitch for monitoring the real cost of their regular purchases.
+
+## Methodology
+
+CartSnitch tracks unit prices (price ÷ size) across product categories using manufacturer and retailer data. Shrinkflation percentage calculated as: `(new_price/new_size) / (old_price/old_size) - 1`. Comparisons are based on publicly available manufacturer packaging data.

content/marketing/blog/price-gouging-vs-shrinkflation.md

@@ -0,0 +1,60 @@
+# Price Gouging vs Shrinkflation: What's the Difference?
+
+You hear both terms used when grocery prices feel unfair. But they are not the same thing — and understanding the difference helps you know what to do about each one.
+
+## What Is Price Gouging?
+
+Price gouging is when retailers or sellers dramatically raise prices during a crisis, shortage, or period of high demand. It is most commonly associated with:
+
+- Hurricanes and natural disasters (gas, water, generators)
+- Supply chain disruptions
+- Public health emergencies
+
+**Example:** A hardware store raising generator prices from $500 to $1,500 the day before a hurricane makes landfall.
+
+Price gouging is **illegal in many states** during declared emergencies. Most states have consumer protection laws that prohibit excessive price increases when a state of emergency has been declared.
+
+## What Is Shrinkflation?
+
+Shrinkflation is when manufacturers reduce the size or quantity of a product while keeping the price the same — or raising it. The per-unit cost increases without the packaging change being obvious at first glance.
+
+**Example:** A cereal brand reducing its box from 18 oz to 15.5 oz while keeping the price at $4.99. The shelf price did not change. The unit price went up 16%.
+
+Shrinkflation is **legal** in the US. Manufacturers are required to disclose net weight, but they do not need to announce when a product gets smaller.
+
+## Key Differences
+
+| | Price Gouging | Shrinkflation |
+|---|---|---|
+| **Who does it** | Retailers and sellers | Manufacturers |
+| **When it happens** | Crises, shortages, emergencies | Continuously, as a standard practice |
+| **How it works** | Raising prices sharply | Reducing product size |
+| **Legal status** | Illegal during declared emergencies in most states | Legal year-round |
+| **Consumer response** | Report to state attorney general | Track unit prices; switch products |
+| **Detection** | Obvious price increases | Requires unit price calculation |
+
+## How CartSnitch Handles Both
+
+**CartSnitch tracks shrinkflation automatically.** We monitor unit prices across our tracked products and alert you when a product you buy regularly gets smaller or more expensive.
+
+**Price gouging is different.** CartSnitch does not currently detect price gouging — it requires monitoring retail prices during specific time periods and comparing against pre-crisis baselines, which is outside our current scope.
+
+If you encounter what you believe is price gouging:
+- **Document the prices** — take screenshots
+- **Report it** — contact your state attorney general's office
+- **Shop elsewhere** — if possible
+
+## Can Both Happen at Once?
+
+Yes. A product could experience shrinkflation (getting smaller over time) AND be subject to price gouging during an emergency. For example:
+
+- A bottle of water that shrank from 24 oz to 16 oz over five years (shrinkflation)
+- The same product being sold for triple its normal price during a flood emergency (price gouging)
+
+Both are harmful to consumers. Only one is currently illegal.
+
+## The Common Ground
+
+Both price gouging and shrinkflation share a common feature: they exploit the fact that most consumers don't have access to real-time price data.
+
+CartSnitch was built to give that data to consumers. For shrinkflation today — and honest, transparent grocery pricing.

content/marketing/blog/shrinkflation-consumer-faq.md

@@ -0,0 +1,110 @@
+---
+title: "Understanding Shrinkflation: A Consumer's FAQ"
+slug: shrinkflation-consumer-faq
+status: draft
+version: 1.0
+last_updated: 2026-03-22
+description: "Shrinkflation is how brands quietly raise prices by giving you less product for the same money. Here is what it is, why it is legal, and how to detect it."
+tags: ["shrinkflation", "consumer-faq", "grocery-prices", "price-transparency", "unit-price"]
+series: "The Shrinkflation Files"
+series_part: 0
+target_publish: 2026-04-01
+target_keywords: ["what is shrinkflation", "shrinkflation examples", "why did my product get smaller", "is shrinkflation legal"]
+---
+
+# Understanding Shrinkflation: A Consumer's FAQ
+
+You notice it at the grocery store: the cereal box looks smaller. The chip bag seems to have less air in it. The pasta salad you loved now fits less in the container. But the price is the same — or higher.
+
+That is shrinkflation. Here is what you need to know.
+
+---
+
+## What Is Shrinkflation?
+
+Shrinkflation is the practice of reducing the size or quantity of a product while keeping the price the same — or raising it. The per-unit cost increases without the packaging change being obvious at first glance.
+
+It is different from inflation. Inflation raises prices for the same product. Shrinkflation keeps the price the same for a smaller product. Both cost you more per ounce, per gram, or per use.
+
+---
+
+## Is Shrinkflation Legal?
+
+Yes. Shrinkflation is legal in the US and most markets. Manufacturers are required to state the net weight or count on the packaging, but they are not required to announce when a product gets smaller. There is no federal regulation specifically banning shrinkflation.
+
+Some regulators have begun studying the practice, and there have been proposals for mandatory price-per-unit labeling at the shelf level, but no binding rules exist as of 2026.
+
+---
+
+## What's an Example of Shrinkflation?
+
+Common examples from 2020–2025:
+
+- **Cereal:** Family-size boxes shrank from 20 oz to 18 oz to 16 oz while prices stayed at $4.99–$5.99
+- **Crackers:** Standard sleeve count dropped from 4 to 3 packs while shelf price remained constant
+- **Yogurt:** Multipacks reduced from 6 oz cups to 5.3 oz cups
+- **Paper towels:** Roll count dropped from 12 to 10 while price stayed the same
+- **Dish soap:** Bottle volumes shrank from 24 oz to 20 oz
+
+In every case, the per-unit cost increased even when the shelf price did not change — or changed less than the size reduction warranted.
+
+---
+
+## How Much Does Shrinkflation Cost the Average Family?
+
+Estimates vary by shopping habits and product categories. CartSnitch analysis of manufacturer packaging data suggests the average US household spends an additional $80–$120 per year on cereals alone due to shrinkflation. Across all categories — snacks, dairy, household goods, beverages — total hidden costs per household are estimated at $300–$500 per year.
+
+These figures are directional estimates based on publicly available manufacturer packaging data, not CartSnitch production data.
+
+---
+
+## Why Do Brands Use Shrinkflation?
+
+Brands use shrinkflation because consumers notice price increases more than package size decreases. A $5 cereal box going to $5.50 is visible and may cause consumers to switch to competitors. A $5 cereal box shrinking from 18 oz to 15 oz at the same price is rarely noticed until someone like CartSnitch tracks the unit price.
+
+Shrinkflation is most common in products where:
+- Brand loyalty is high (consumers repurchase without checking alternatives)
+- Unit prices are not prominently displayed
+- Size reductions are modest (5–15%)
+- The product is purchased regularly
+
+---
+
+## How Do I Detect Shrinkflation?
+
+Three ways to catch shrinkflation before you overpay:
+
+1. **Track unit prices** — Divide the shelf price by the size (oz, g, count). If the unit price goes up but the product looks the same, you are being shrunk.
+2. **Compare across brands** — A competing brand may offer more product for the same or lower price.
+3. **Use CartSnitch** — CartSnitch monitors unit prices on your tracked products and alerts you when a product you buy regularly gets smaller or more expensive.
+
+---
+
+## Does Shrinkflation Affect Store Brands Too?
+
+Yes. Store brands (private label) also engage in shrinkflation, though they tend to do so less aggressively than name brands. National brands rely more heavily on shrinkflation because they cannot compete on price as easily as store brands do.
+
+---
+
+## Is There a Campaign or Movement Against Shrinkflation?
+
+Consumer advocacy groups have lobbied for:
+- Mandatory unit price display at shelf level
+- Required advance notice when product sizes change
+- Clear "size changed" labels on packaging
+
+CartSnitch is built to give consumers the data they need to make informed decisions — even before regulation catches up.
+
+---
+
+## How Is Shrinkflation Different From Price Gouging?
+
+Shrinkflation is a gradual, product-level practice by manufacturers. Price gouging is typically a retailer or seller raising prices sharply during a supply crisis or emergency. Both harm consumers, but they are distinct practices.
+
+Price gouging is illegal in many states during declared emergencies. Shrinkflation is legal year-round.
+
+---
+
+## Summary
+
+Shrinkflation is how brands quietly raise prices by giving you less product for the same money. It is legal, common, and affects the average family by hundreds of dollars per year. The only defense is tracking unit prices — and CartSnitch does that automatically.

content/marketing/blog/what-is-unit-price.md

@@ -0,0 +1,70 @@
+---
+title: "What Is Unit Price and How Do You Calculate It?"
+slug: what-is-unit-price
+status: draft
+version: 1.0
+last_updated: 2026-03-22
+description: "Unit price is the cost per ounce, gram, or sheet — the number that reveals which product is actually the better deal, and exposes shrinkflation before you realize you're paying more."
+tags: ["unit-price", "shrinkflation", "grocery-prices", "smart-shopping", "explainer"]
+---
+
+# What Is Unit Price and How Do You Calculate It?
+
+When you see two products on a shelf at different prices, the obvious move is to pick the cheaper one. But what if the cheaper item is actually a worse deal? Unit price is the metric that tells you the truth.
+
+## What Is Unit Price?
+
+Unit price is the cost of an item per standard unit of measurement — price per ounce, price per gram, price per sheet, price per load. It lets you compare products of different sizes against each other fairly.
+
+Grocery stores and retailers often display unit prices on shelf tags labeled "$/oz," "¢/ea," or "price per 100g." You can also calculate it yourself.
+
+## How to Calculate Unit Price
+
+**Formula:** `Unit Price = Item Price ÷ Size`
+
+**Examples:**
+
+- Product A: $4.99 for 16 oz → $4.99 ÷ 16 = $0.31 per oz
+- Product B: $3.99 for 12 oz → $3.99 ÷ 12 = $0.33 per oz
+
+Product A costs more upfront ($4.99 vs $3.99) but is actually the better value at $0.31/oz vs $0.33/oz.
+
+## Unit Price vs Shelf Price
+
+| Term | Definition |
+|------|------------|
+| **Shelf price** | The total price you pay at checkout |
+| **Unit price** | Price divided by size — the true cost per useable unit |
+
+Shelf price misleads you when product sizes vary. Unit price reveals the actual cost regardless of packaging.
+
+## Why Unit Price Matters: The Shrinkflation Example
+
+Brands know unit price is how smart shoppers compare. Instead of raising shelf prices (which shoppers notice), they shrink the product. The shelf price stays the same. The unit price goes up.
+
+**Real example:**
+- 2021: Cereal box — 18 oz at $4.99 → $0.277/oz
+- 2024: Same brand, same shelf price — 15.5 oz at $4.99 → $0.322/oz
+
+The shelf price did not change. The unit price went up 16.1%. You are paying 16.1% more per ounce for the same product without realizing it.
+
+This is shrinkflation, and it is happening across cereals, snacks, dairy, household products, and more.
+
+## How to Use Unit Price at the Grocery Store
+
+1. **Look for the small print** — Most stores label unit price on the shelf tag. Find the "$/oz" or "¢/load" number.
+2. **Calculate yourself** — Divide shelf price by size (oz, g, sheets, loads). Write it down or use a phone calculator.
+3. **Compare across brands** — The brand with the lower shelf price is not always the lower unit price.
+4. **Track it over time** — If you buy the same products regularly, unit price changes reveal shrinkflation before the brand announces it.
+
+## Unit Price and CartSnitch
+
+CartSnitch automatically calculates unit prices for the products you track. When a brand shrinks a product, CartSnitch flags the unit price increase so you see exactly how much more you are paying per ounce — even if the shelf price never changed.
+
+## Summary
+
+Unit price is the most honest way to compare products of different sizes. It reveals shrinkflation, exposes hidden price increases, and helps you make truly informed purchasing decisions. The formula is simple: divide the price by the size.
+
+**Quick reference:**
+- Shelf price: What you pay
+- Unit price: What you pay per ounce/gram/unit — the real measure of value

content/marketing/how-it-works.md

@@ -0,0 +1,83 @@
+# How CartSnitch Works
+
+## The Core Idea
+
+Every product at the grocery store has two prices:
+- **Shelf price** — what you pay at checkout
+- **Unit price** — what you pay per ounce, per gram, per sheet, per load
+
+Most people compare shelf prices. Smart shoppers compare unit prices.
+
+CartSnitch tracks unit prices automatically — so you don't have to do the math yourself.
+
+---
+
+## How We Track Prices
+
+CartSnitch pulls pricing data from:
+- **Store loyalty portals** — Meijer, Kroger, and Target — when you connect your account, CartSnitch uses an automated scraper to pull your purchase history from the store loyalty portal
+- **Public manufacturer data** — packaging changes, suggested retail prices
+- **USDA FoodData Central** — reference data for package sizing baselines (used for historical size comparison only — not part of our live tracking system)
+
+We calculate unit price for every product we track:
+
+`Unit Price = Shelf Price ÷ Package Size`
+
+When a brand reduces package size — or a store changes its price — we catch it.
+
+---
+
+## What Is Shrinkflation Detection?
+
+Shrinkflation happens when a brand reduces the size of a product without lowering the price. The shelf price stays the same. The unit price goes up.
+
+**Example:**
+- 2021: Cereal at $4.99 for 18 oz → $0.277 per oz
+- 2024: Same cereal at $4.99 for 15.5 oz → $0.322 per oz
+
+Same price. 16% more per ounce. That's shrinkflation.
+
+CartSnitch monitors unit prices over time. When we detect a statistically significant unit price increase — whether from a size reduction, a price increase, or both — we flag it.
+
+---
+
+## How Price Alerts Work
+
+1. **You add a product** — Search for any product you buy regularly and add it to your tracked list.
+2. **We monitor unit prices** — Every time we detect a price or size change, we recalculate the unit price.
+3. **You get an alert** — If the unit price increases beyond a threshold, we notify you — so you can decide whether to switch products, switch stores, or just be aware.
+
+You choose what counts as significant. Some users set alerts for any change. Others only want to know about large unit price jumps.
+
+---
+
+## Store Comparison
+
+CartSnitch compares your total grocery basket across stores.
+
+When you connect your store accounts, we can see what you bought and where. We calculate the total cost of your typical basket at each store we support — so you know where you're getting the best overall deal.
+
+This is different from just comparing the price of one item. Some stores are cheaper on produce, others on pantry staples. CartSnitch shows you the full picture.
+
+---
+
+## What We Don't Do
+
+- **We don't collect receipts** — Store account connections give us enough data to track prices and compare baskets. Receipt-based tracking is being evaluated.
+- **We don't have every product** — Beta is limited to supported stores and categories. We're adding more every week.
+- **We don't affect shelf prices** — We show you the data. What you do with it is up to you.
+
+---
+
+## How We Protect Your Data
+
+- We read price data from your connected store accounts — we never see your login credentials
+- We store only the minimum data needed to calculate unit prices and compare baskets
+- We don't sell your data to third parties
+- You can disconnect your store account at any time and delete your data
+
+---
+
+## Ready to Start?
+
+[Sign up for beta →]

content/marketing/methodology.md

@@ -0,0 +1,102 @@
+# How We Calculate Shrinkflation: Our Methodology
+
+We believe consumers deserve to verify our work. Here's exactly how we calculate shrinkflation percentages and where our data comes from.
+
+---
+
+## The Core Formula
+
+For every product we track, we calculate:
+
+**Unit Price = Shelf Price ÷ Package Size**
+
+Then we calculate the shrinkflation percentage:
+
+**Shrinkflation % = (New Unit Price ÷ Old Unit Price) − 1**
+
+This gives us the effective price increase — accounting for both size changes and price changes.
+
+**Example:**
+- 2021: Cereal at $4.99 for 18 oz → Unit price: $4.99 ÷ 18 oz = $0.277/oz
+- 2024: Same cereal at $4.99 for 15.5 oz → Unit price: $4.99 ÷ 15.5 oz = $0.322/oz
+
+Shrinkflation % = ($4.99 ÷ 15.5) ÷ ($4.99 ÷ 18) − 1 = 16.1%
+
+The shelf price is the same. The unit price went up 16.1%.
+
+---
+
+## Data Sources
+
+We use multiple data sources to build our shrinkflation rankings:
+
+### 1. Manufacturer Packaging Data
+We track documented changes in product sizes as reported by manufacturers. This includes:
+- Net weight changes on packaging
+- Count-per-package changes (e.g., 4 rolls → 3 rolls)
+- Volume changes in liquid products
+
+### 2. USDA FoodData Central
+The USDA FoodData Central database provides reference data on product sizes and nutrition, which we use as baselines for historical comparison.
+
+**URL:** https://fdc.nal.usda.gov/
+
+### 3. Public Retail Data
+When available, we cross-reference shelf prices from public retailer sources to validate price continuity.
+
+---
+
+## How We Rank Shrinkflation Offenders
+
+Our top shrinkflation offenders rankings are based on the calculated shrinkflation percentage for each product. We rank products by:
+
+1. **Highest shrinkflation percentage** — the largest effective unit price increase
+2. **Across consistent time periods** — comparing current sizes/prices to documented baselines from 2020–2024
+3. **By product category** — cereals, snacks, dairy, household goods, etc.
+
+We only include products where we have documented evidence of a size or price change. We do not estimate shrinkflation for products we cannot verify.
+
+---
+
+## Shrinkflation vs Regular Price Increases
+
+We distinguish between:
+
+- **Shrinkflation** — Package size decreases while shelf price stays the same or increases. Unit price goes up.
+- **Regular price increase** — Package size stays the same, shelf price goes up. Unit price goes up.
+- **Combined shrinkflation + price increase** — Package size decreases AND shelf price increases. Unit price goes up significantly.
+
+All three result in a higher unit price. Our percentages capture the total effective increase.
+
+---
+
+## What We Don't Do
+
+- We don't estimate shrinkflation without documented evidence
+- We don't include products we cannot verify
+- We don't adjust our calculations based on brand or retailer pressure
+- We don't publish specific rankings until we can verify the underlying data
+
+---
+
+## Production Data vs Estimates
+
+**Before launch (current):** Our shrinkflation percentages are based on publicly available manufacturer packaging data. USDA FoodData Central provides reference data for package sizing baselines. These are directional estimates — they tell you the pattern is real.
+
+**After production deployment:** Once we have a live product with real transaction data, we'll be able to run the numbers against actual purchase data. This will validate and refine our estimates.
+
+We will always note when statistics are directional estimates versus based on production data.
+
+---
+
+## Future: Publishing Our Queries
+
+Once production is live, we plan to publish the SQL queries behind our shrinkflation calculations — so anyone can run them against our data and verify our work.
+
+This is part of our commitment to transparency.
+
+---
+
+## Questions?
+
+If you have questions about our methodology or believe we've made an error, email us: hello@cartsnitch.app

content/marketing/press-kit.md

@@ -0,0 +1,97 @@
+# CartSnitch Press/Media Kit
+
+**Timing:** Ready by April 24, 2026 (beta launch)
+
+---
+
+## About CartSnitch
+
+CartSnitch is a grocery price tracking and shrinkflation detection app that helps consumers see exactly how much they are paying per unit of product — and when brands shrink products without lowering prices.
+
+**Founded:** 2026
+**Mission:** Help consumers understand what they are really paying for at the grocery store, and expose the practices that cost families hundreds of dollars per year.
+
+---
+
+## Product Description
+
+CartSnitch tracks unit prices (price ÷ size) across grocery products. Users can:
+- Set alerts on products they buy regularly
+- See when a product gets smaller or more expensive
+- Compare total grocery costs across stores
+- Access data on which products have experienced the most shrinkflation
+
+**Status:** Beta (April 24, 2026)
+**Availability:** Web app / PWA
+**Supported stores:** Meijer, Kroger, and Target
+
+---
+
+## The Problem: Shrinkflation
+
+Shrinkflation is the practice of reducing product size while keeping prices the same or raising them. The average US family loses an estimated $300–$500 per year to shrinkflation across all grocery categories.
+
+**Examples (2020–2025):**
+- Family cereal boxes: 20 oz → 18 oz → 16 oz, same shelf price
+- Paper towels: 12 rolls → 10 rolls, same price
+- Yogurt cups: 6 oz → 5.3 oz, same price
+- Dish soap: 24 oz → 20 oz, same price
+
+Unlike price gouging, which is illegal during emergencies in many states, shrinkflation is legal year-round. The only defense is tracking unit prices.
+
+---
+
+## Key Messages
+
+1. **Unit prices reveal the truth.** The shelf price is misleading. Price per ounce or per unit is the honest measure of value.
+
+2. **Shrinkflation is real and costly.** Brands reduce product sizes while maintaining or raising prices. The average family loses $300–$500/year.
+
+3. **CartSnitch tracks it automatically.** We monitor unit prices across products and alert users when their regular purchases change.
+
+4. **Consumers deserve transparency.** Price-per-unit should be displayed prominently at shelf level. Until regulation catches up, CartSnitch gives consumers the data directly.
+
+---
+
+## Statistics (Directional — Based on CartSnitch Analysis of Manufacturer Packaging Data)
+
+- Average family loses **$300–$500/year** to shrinkflation across all grocery categories
+- Cereals specifically: **$80–$120/year** per family
+- Family cereal boxes shrank an average of **12–16%** in oz between 2020–2025
+- Top shrinkflation offenders in 2021–2025: Lay's (28%), Yoplait (27.5%), Cocoa Puffs (27%), Ruffles (23.6%), Cheerios (21.5%)
+
+*Note: Dollar figures are based on CartSnitch analysis of publicly available manufacturer packaging data. USDA FoodData Central provides reference data for package sizing baselines. Production data will refine these figures.*
+
+---
+
+## Quotes
+
+**Penny Pincherton, CEO and Co-founder:**
+> "We built CartSnitch because we were tired of going to the store and getting less for the same money. Shrinkflation is a quiet tax on families who don't have time to calculate price-per-ounce on every product, every week. We do that work automatically."
+
+**Savannah Savings, CMO:**
+> "The grocery industry has been shrinking products in plain sight for years because they know most shoppers won't notice. We think noticing should be easy."
+
+---
+
+## Leadership
+
+- **Penny Pincherton** — CEO and Co-founder
+- **Savannah Savings** — CMO
+- **Chip Overstock** — CTO
+
+---
+
+## Media Assets
+
+- **Screenshots:** Available once staging environment is live (CAR-60 in progress)
+- **Logo:** Available in brand assets folder
+- **Product demo:** TBD
+
+---
+
+## Contact
+
+For press inquiries: press@cartsnitch.app
+For partnerships: partners@cartsnitch.app
+Website: cartsnitch.app

content/marketing/privacy.md

@@ -0,0 +1,94 @@
+# Your Data Is Yours. Here's How We Keep It That Way.
+
+We know we're asking you to connect your grocery store account. That means trusting us with your purchase history — and we take that seriously.
+
+Here's exactly what we access, what we store, and what we never do.
+
+---
+
+## What We Access
+
+When you connect your store account, CartSnitch uses an automated scraper to pull your purchase history from the store loyalty portal. This means we can see:
+
+- **What you bought** — product names and quantities
+- **How much you paid** — shelf prices at time of purchase
+- **When you bought it** — purchase dates
+
+We **cannot** see:
+- Your store login credentials
+- Payment method information
+- Your physical location
+
+---
+
+## What We Store
+
+We store only the data we need to calculate unit prices and compare baskets:
+
+- Product identifiers (names, sizes, categories)
+- Shelf prices and unit prices
+- Purchase frequency
+- Your tracked products and alerts
+
+We **do not store**:
+- Your full purchase history indefinitely
+- Payment information
+- Personal identifying information beyond your email
+
+---
+
+## What We Never Do
+
+- **We never sell your data.** Your data is never a product. We don't license it, share it with third parties, or use it for advertising.
+- **We never see your login credentials.** CartSnitch accesses your store loyalty portal through an automated scraper — we never have access to your store password.
+- **We never post to your social accounts or profile.**
+- **We never use your purchase data for anything other than the CartSnitch service.**
+
+---
+
+## How We Use Your Data
+
+We use your purchase data to:
+
+1. **Calculate unit prices** — so you can compare products fairly
+2. **Detect shrinkflation** — by monitoring when products you buy change in size or price
+3. **Compare store prices** — to show you where your total basket costs less
+4. **Send you alerts** — when products you track change in price or size
+
+That's it.
+
+---
+
+## Data Retention
+
+- You can delete your account and all associated data at any time
+- When you disconnect a store account, we remove the connection and stop accessing new data
+- Historical data associated with your account can be deleted on request
+
+---
+
+## Security
+
+- All data is encrypted in transit and at rest
+- CartSnitch accesses store loyalty portals using an automated scraper — we never see your store password
+- Our team follows strict access controls — only the engineers who need your data to build the product can access it
+
+---
+
+## Want to Disconnect?
+
+You can disconnect your store account at any time:
+
+1. Go to Settings
+2. Select "Connected Accounts"
+3. Click "Disconnect" next to the store you want to remove
+
+Disconnecting immediately stops us from accessing new data from that store.
+
+---
+
+## Questions?
+
+We're happy to answer questions about how we handle data. Email us anytime: privacy@cartsnitch.app
+
+See our full [Terms of Service →]

content/marketing/social/launch-day-posts.md

@@ -0,0 +1,129 @@
+# April 24 Beta Launch Day Social Posts
+
+**Publish date:** April 24, 2026
+**Platforms:** Twitter/X, Reddit (r/Frugal, r/personalfinance)
+**Goal:** Announce beta launch, drive signups, first social proof
+
+---
+
+## Twitter/X — Main Launch Announcement
+
+**Tweet 1 (the big one):**
+🎉 CartSnitch is officially in beta.
+
+We built this because you deserve to know when brands shrink their products without lowering prices.
+
+Track unit prices. Catch shrinkflation. Compare stores.
+
+Join us: [link]
+
+**Tweet 2:**
+Grocery brands have been shrinking products in plain sight for years. Cereal boxes, chip bags, detergent bottles — all getting smaller while shelf prices stay the same.
+
+We track the unit price. You see the truth.
+
+[Link]
+
+**Tweet 3 (CTA thread):**
+How it works:
+1️⃣ Connect your store account
+2️⃣ We track unit prices on everything you buy
+3️⃣ Get alerts when products shrink or get more expensive
+4️⃣ Compare your total basket across stores
+
+Free to join: [link]
+
+**Tweet 4 (shrinkflation data hook):**
+We already found the biggest shrinkflation offenders. Lay's, Yoplait, Cocoa Puffs, Ruffles, Cheerios — all cutting sizes while keeping prices flat.
+
+See the full list: [link to top-10 article]
+
+**Tweet 5 (proof/activation):**
+Beta is live. Free to join.
+
+No commitment. No credit card. Just the data you need to stop overpaying at the grocery store.
+
+👉 [link]
+
+**Hashtags:** #Shrinkflation #GrocerySpending #PriceHiking #Frugal #Beta #CartSnitch
+
+---
+
+## Twitter/X — Reply Chain (engagement)
+
+**In reply to someone asking "what is shrinkflation":**
+When a brand reduces the size of a product but keeps the price the same — or raises it. The shelf price looks fine. The unit price goes up.
+
+Example: cereal at $4.99 for 18 oz → $4.99 for 15.5 oz. Same price. 16% more per ounce.
+
+We track it automatically. [link]
+
+**In reply to "why should I care":**
+The average family loses an estimated $300–$500/year to shrinkflation across all grocery categories. It's not dramatic. It happens slowly. But it adds up.
+
+CartSnitch shows you exactly when it happens to the products you buy.
+
+**In reply to "is this free":**
+Yes, beta is free. We're building the product and adding more stores every week.
+
+[link]
+
+---
+
+## Reddit Post — r/Frugal
+
+**Title:** [Launch] CartSnitch — we built a free tool to track shrinkflation and compare grocery prices across stores (beta)
+
+**Body:**
+Hey r/Frugal — been working on this for a while and finally ready to share.
+
+CartSnitch tracks unit prices (price ÷ size) on grocery products and alerts you when products you buy regularly get smaller or more expensive. It also compares your total grocery bill across stores.
+
+**What it does:**
+- Tracks unit prices on grocery products
+- Alerts you when a product you buy shrinks or gets more expensive
+- Compares your total basket cost across Meijer, Kroger, and Target
+- Shows you the biggest shrinkflation offenders we've found
+
+**Why we built it:**
+Shrinkflation costs the average family an estimated $300–$500/year. It's legal, it's common, and most people don't notice because the shelf price doesn't change.
+
+We're in beta — free to join, no credit card. Looking for feedback.
+
+[link]
+
+*(Mods: happy to answer questions. Not selling anything, just built this because we think consumers deserve this data.)*
+
+---
+
+## Reddit Post — r/personalfinance
+
+**Title:** [Launch] We built a free tool to track grocery shrinkflation and price changes — thinking about the data behind your grocery bill
+
+**Body:**
+I've been tracking grocery prices for about a year and the numbers are wild. Brands reduce product sizes constantly while maintaining or raising shelf prices. The average family loses an estimated $300–$500/year to this.
+
+We built CartSnitch to automate the tracking. It's in beta — free to join.
+
+**What it tracks:**
+- Unit prices (price per oz/g/sheet/load)
+- Product size changes (shrinkflation)
+- Price changes over time
+- Total basket comparison across stores
+
+We're not affiliated with any retailers. Just built this because I kept getting annoyed at the cereal aisle.
+
+Happy to answer questions about the data methodology.
+
+[link]
+
+---
+
+## Instagram / LinkedIn (if applicable)
+
+**Carousel idea:**
+Slide 1: "Your cereal box is lying to you."
+Slide 2: "Same price. Less product. Here's the math." [example with unit price calculation]
+Slide 3: "This is shrinkflation — and it's costing you hundreds a year."
+Slide 4: "CartSnitch tracks it automatically." [app screenshot]
+Slide 5: "Free beta — link in bio."

content/marketing/stores.md

@@ -0,0 +1,93 @@
+# Stores Supported by CartSnitch
+
+CartSnitch currently supports the following stores for price tracking, shrinkflation detection, and store comparison.
+
+We're actively expanding coverage. If your store isn't listed, you can request it — we prioritize stores with the highest user demand.
+
+---
+
+## Currently Supported
+
+### Meijer
+**Status:** Full coverage
+**Available data:**
+- Real-time shelf prices
+- Unit prices by product
+- Your purchase history (when connected)
+- Store-specific pricing
+
+**Supported regions:** Midwest (Meijer and Meijer Express)
+
+**Note:** Connect your Meijer account and CartSnitch will pull your purchase history from the Meijer loyalty portal using an automated scraper.
+
+---
+
+### Kroger
+**Status:** Full coverage
+**Available data:**
+- Real-time shelf prices
+- Unit prices by product
+- Your purchase history (when connected)
+- Store-specific pricing
+
+**Supported regions:** Nationwide (Kroger, Kroger Marketplace, Kroger Pickup)
+
+**Note:** Connect your Kroger account and CartSnitch will pull your purchase history from the Kroger loyalty portal using an automated scraper.
+
+---
+
+### Target
+**Status:** Full coverage
+**Available data:**
+- Real-time shelf prices
+- Unit prices by product
+- Your purchase history (when connected)
+- Store-specific pricing
+
+**Supported regions:** Nationwide
+
+**Note:** Connect your Target account and CartSnitch will pull your purchase history from the Target loyalty portal using an automated scraper.
+
+---
+
+## Evaluating Additional Stores
+
+We're always evaluating new retailers based on user demand. We can't commit to specific stores or timelines yet — but if there's a retailer you'd like us to prioritize, let us know.
+
+[Submit a store request →]
+
+---
+
+## How Store Coverage Works
+
+When you connect your store account, CartSnitch reads your purchase history and current pricing data from your loyalty account — without ever seeing your login credentials. We use read-only access to your loyalty account data.
+
+**What you get when your store is supported:**
+- Personalized price alerts on products you buy
+- Accurate basket cost comparison across your stores
+- Shrinkflation detection on your actual purchases
+
+**What this requires:**
+- An active loyalty account with the store
+- Willingness to connect the account (you can disconnect at any time)
+
+---
+
+## Privacy Note
+
+We never store your store login credentials. Our integration uses read-only access to your loyalty account data. We store only the minimum data needed to calculate unit prices and compare baskets.
+
+See our full [privacy policy →]
+
+---
+
+## Don't See Your Store?
+
+We're building CartSnitch's store coverage as fast as we can. The grocery market is fragmented and each integration requires technical work.
+
+**How to request a store:**
+1. Sign up for beta
+2. Go to Settings > Request a Store
+3. Submit your store name and location
+
+We review requests weekly and prioritize stores with the highest demand and broadest geographic coverage.

docs/uat-receipt-submission.md

@@ -0,0 +1,244 @@
+# UAT Receipt Submission Path
+
+**Issue:** [CAR-812](/CAR/issues/CAR-812)
+**Author:** Barcode Betty
+**Date:** 2026-05-04
+
+---
+
+## Overview
+
+The UAT environment supports receipt submission via **inbound email**. This is the only supported submission method in UAT — there is no public REST API surface for receipt ingestion.
+
+---
+
+## How It Works
+
+### Architecture
+
+```
+User composes email
+    ↓
+Email sent to <user_token>@cartsnitch.<env>.farh.net
+    ↓
+Mailgun webhook receives the email
+    ↓
+Email job enqueued to DragonflyDB stream: email:receipts
+    ↓
+email-worker (ReceiptWitness) consumes the job
+    ↓
+Worker resolves user via email_inbound_token lookup in DB
+    ↓
+Retailer detected from email content (meijer / kroger / target)
+    ↓
+Email parsed into Purchase + PurchaseItem records
+    ↓
+receipt.ingested event published to Redis
+    ↓
+MatchResult created with method=upc, confidence=1.0 for known UPCs
+```
+
+### Key Components
+
+| Component | Location | Role |
+|-----------|----------|------|
+| `users.email_inbound_token` | DB (migration `001_add_email_inbound_token`) | 22-char unique token per user; used as email routing identifier |
+| `email:receipts` stream | DragonflyDB | Queue holding pending email jobs |
+| `email-worker` | `receiptwitness/src/receiptwitness/worker/email_worker.py` | Async worker consuming the stream |
+| `BaseEmailParser` | `receiptwitness/src/receiptwitness/parsers/email/base.py` | Abstract parser; subclasses for meijer/kroger/target |
+| Retailer detectors | `receiptwitness/src/receiptwitness/parsers/email/detector.py` | Sifts sender/subject to pick the right parser |
+
+### Email Address Format
+
+Each user is assigned a unique inbound token. The receipt submission email address is shown in **Settings → Receipt Email** on the UI:
+
+**Address:** `receipts+<email_inbound_token>@receipts.cartsnitch.com`
+
+To find a user's token in the UAT database (requires `kubectl` access to `cartsnitch-uat`):
+
+```bash
+kubectl exec -n cartsnitch-uat deployment/cartsnitch-api -- \\
+  python -c "from cartsnitch_common.database import get_sync_session; \\
+  from cartsnitch_common.models.user import User; \\
+  from sqlalchemy import select; \\
+  s = get_sync_session('postgresql://cartsnitch:cartsnitch@cartsnitch-pg-rw:5432/cartsnitch'); \\
+  u = s.execute(select(User).where(User.email=='dottie@example.com')).scalar_one(); \\
+  print(u.email_inbound_token)"
+```
+
+---
+
+## Submitting a Test Receipt (Step-by-Step)
+
+### Prerequisites
+
+- A test user account in UAT with a known `email_inbound_token`
+- A sample receipt email with a **known UPC** from the seeded `normalized_products` table
+
+### Steps
+
+1. **Obtain the test user's inbound token.**
+   Use the UAT Settings → Receipt Email page in the UI to see the full address `receipts+<token>@receipts.cartsnitch.com`, or query the DB directly (see above).
+
+2. **Compose the email.**
+   Send to: the address shown in Settings → Receipt Email
+   Subject: anything
+   Body: plain-text or HTML receipt content
+
+3. **Expected behavior after email is processed:**
+   - A `Receipt` row is created in `purchases`
+   - `PurchaseItem` rows are created with `upc` matching the seeded product UPC
+   - A `MatchResult` is created with `method='upc'` and `confidence=1.0`
+
+---
+
+## Known UPC for Dottie (from UAT seed)
+
+> **NOTE:** `kubectl` is not available in this execution environment. The UAT seed and DB query could not be executed. The sample receipt below uses a plausible placeholder UPC. Before Dottie runs the regression:
+> 1. Run `bash scripts/seed-env.sh uat` from a machine with UAT kubecontext
+> 2. Query: `SELECT id, canonical_name, upc_variants->0->>'upc' AS sample_upc FROM normalized_products WHERE jsonb_array_length(upc_variants) > 0 LIMIT 1;`
+> 3. Replace the placeholder values below with the real captured row
+
+- `id`: **TBD — run seed and query UAT DB**
+- `name`: **TBD — run seed and query UAT DB**
+- `sample UPC`: **TBD — run seed and query UAT DB**
+
+### Meijer Sample Receipt (plain text)
+
+```
+Meijer
+===================================
+Purchase Date: 03/15/2026
+Store: Meijer #127 - Ann Arbor, MI
+-----------------------------------
+ 1 x Organic Whole Milk 1gal      $4.99
+ 1 x Whole Wheat Bread             $3.29
+ 1 x Bananas (2 lb)                $0.67
+ 1 x Chicken Breast (3 lb)        $12.47
+ 1 x Cheddar Cheese Block 8oz      $5.99
+-----------------------------------
+Subtotal:                        $27.41
+Tax:                              $1.93
+Total:                           $29.34
+===================================
+THANK YOU FOR SHOPPING MEIJER
+===================================
+```
+Meijer
+===================================
+Purchase Date: 03/15/2026
+Store: Meijer #127 - Ann Arbor, MI
+-----------------------------------
+ 1 x Organic Whole Milk 1gal      $4.99
+ 1 x Whole Wheat Bread            $3.29
+ 1 x Bananas (2 lb)               $0.67
+ 1 x Chicken Breast (3 lb)       $12.47
+ 1 x Cheddar Cheese Block 8oz     $5.99
+-----------------------------------
+Subtotal:                       $27.41
+Tax:                             $1.93
+Total:                          $29.34
+===================================
+THANK YOU FOR SHOPPING MEIJER
+===================================
+```
+
+> **Note:** The `email-worker` parses the email body and extracts line items by retailer. The exact format and field mapping depends on the retailer parser. For Meijer, the parser looks for item lines matching `(\d+) x (.+?)\s+\$([\d.]+)`. UPCs in the `upc_variants` JSONB of seeded products will be matched during the normalization step.
+
+### Kroger Sample Receipt (plain text)
+
+```
+KROGER
+===================================
+Purchase Date: 03/15/2026
+Store: KROGER #412 - Ann Arbor MI
+-----------------------------------
+ 1 Organic Whole Milk 1gal        $5.29
+ 1 Whole Wheat Bread              $3.49
+ 1 Bananas (2 lb)                 $0.69
+ 1 Chicken Breast (3 lb)         $11.99
+ 1 Sharp Cheddar Cheese 8oz       $4.99
+-----------------------------------
+Subtotal:                       $26.45
+Tax:                             $1.85
+Total:                          $28.30
+===================================
+```
+
+### Target Sample Receipt (plain text)
+
+```
+TARGET
+===================================
+03/15/2026  14:32
+Store: 0874 Ann Arbor, MI
+===================================
+ 1  Organic Whole Milk 1G         $5.49
+ 1  Whole Wheat Bread             $3.29
+ 1  Bananas LB 2                  $0.68
+ 1  Chicken Breast 3#             $12.99
+ 1  Cheddar Cheese 8OZ           $5.79
+-----------------------------------
+Subtotal:                       $28.24
+Tax (6%):                        $1.69
+Total:                          $29.93
+===================================
+```
+
+---
+
+## Troubleshooting
+
+### Email not processed
+
+1. Check the `email:receipts` stream has messages:
+   ```bash
+   kubectl exec -n cartsnitch-uat deploy/email-worker -- python -c \\
+     "import asyncio; from receiptwitness.queue.email import get_redis; \\
+     async def chk(): c = await get_redis(); info = await c.xinfo_stream('email:receipts'); print(info); \\
+     asyncio.run(chk())"
+   ```
+
+2. Check `email-worker` logs for retailer detection failures:
+   ```bash
+   kubectl logs -n cartsnitch-uat deploy/email-worker -f
+   ```
+
+3. Verify the token resolves to a user in the DB:
+   ```bash
+   kubectl exec -n cartsnitch-uat deploy/cartsnitch-api -- \\
+     python -c "from cartsnitch_common.database import get_sync_session; \\
+     from cartsnitch_common.models.user import User; \\
+     from sqlalchemy import select; \\
+     s = get_sync_session('postgresql://...'); \\
+     r = s.execute(select(User.email_inbound_token).limit(5)).all(); \\
+     print(r)"
+   ```
+
+### No MatchResult created
+
+The normalization pipeline requires a `normalized_product` row with the submitted UPC in `upc_variants`. If the seed was run, the product should be found. Check the `match_results` table after submission:
+
+```sql
+SELECT mr.*, np.canonical_name
+FROM match_results mr
+JOIN normalized_products np ON np.id = mr.normalized_product_id
+WHERE mr.match_method = 'upc'
+ORDER BY mr.created_at DESC
+LIMIT 10;
+```
+
+---
+
+## Related Files
+
+| File | Role |
+|------|------|
+| `common/alembic/versions/001_add_email_inbound_token.py` | Adds `email_inbound_token` column |
+| `receiptwitness/src/receiptwitness/worker/email_worker.py` | Consumes email jobs from stream |
+| `receiptwitness/src/receiptwitness/queue/email.py` | DragonflyDB stream consumer group |
+| `receiptwitness/src/receiptwitness/parsers/email/detector.py` | Retailer detection |
+| `receiptwitness/src/receiptwitness/parsers/email/meijer.py` | Meijer email parser |
+| `receiptwitness/src/receiptwitness/parsers/email/kroger.py` | Kroger email parser |
+| `receiptwitness/src/receiptwitness/parsers/email/target.py` | Target email parser |
+| `docs/uat-runbook.md` | UAT runbook (defect classification, entry/exit criteria) |

docs/uat-runbook.md

@@ -0,0 +1,151 @@
+# CartSnitch UAT Runbook v1
+
+**Version:** 1.0
+**Author:** Savannah Savings, CTO
+**Date:** 2026-03-30
+**Effective:** Immediately upon Phase 1 completion
+
+---
+
+## 1. Defect Severity Classification
+
+Every defect discovered during UAT **must** be classified by severity and priority before triage.
+
+### Severity Levels
+
+| Severity | Definition | Examples |
+|----------|-----------|----------|
+| **S1 — Critical** | Blocks all users from completing a core journey. System is down, data is lost, or security is breached. | Login page crashes for all users; purchase data deleted; auth tokens exposed in response |
+| **S2 — High** | Blocks a major user flow for a significant portion of users. Core feature is broken but workarounds may exist. | Registration fails for email addresses with `+` character; price alerts never trigger; store comparison shows wrong prices |
+| **S3 — Medium** | Feature is degraded but usable. User can complete the journey with friction. | Date formatting shows raw ISO string instead of friendly date; slow page load (>5s) on product detail; search results not sorted correctly |
+| **S4 — Low** | Cosmetic issue, minor UI inconsistency, or edge case with minimal user impact. | Button text truncated on narrow screens; extra whitespace in footer; tooltip shows on hover but not on focus |
+
+### Priority Levels
+
+Priority determines **when** the defect must be fixed. Priority is set by the CTO based on severity, business impact, and sprint capacity.
+
+| Priority | SLA | When to Use |
+|----------|-----|------------|
+| **P0 — Fix Now** | Triage within 1 hour, fix deployed within 4 hours | S1 defects, any security vulnerability, data integrity issues |
+| **P1 — Fix This Sprint** | Triage within 4 hours, fix in current sprint | S2 defects blocking upcoming release, S1 defects with viable workaround |
+| **P2 — Fix Next Sprint** | Triage within 24 hours, scheduled for next sprint | S3 defects, S2 defects with easy workarounds |
+| **P3 — Backlog** | Triage within 48 hours, prioritized against backlog | S4 defects, minor improvements, nice-to-haves |
+
+### Defect Report Template
+
+Every defect filed during UAT must include:
+
+```
+**Title:** [Short description]
+**Severity:** S1/S2/S3/S4
+**Priority:** P0/P1/P2/P3 (set by CTO at triage)
+**Journey:** [Which user journey — J1 through J10]
+**Environment:** [Dev / Prod, deployed image tag]
+**Steps to Reproduce:**
+1. Navigate to ...
+2. Click ...
+3. Enter ...
+**Expected Result:** ...
+**Actual Result:** ...
+**Screenshots/Logs:** [Attach or link]
+**Browser/Device:** [e.g., Chromium 124, mobile viewport 390x844]
+```
+
+---
+
+## 2. UAT Entry Criteria
+
+UAT **must not begin** until ALL of the following are satisfied. Checkout Charlie verifies these before opening the UAT gate.
+
+| # | Criterion | Verified By |
+|---|-----------|------------|
+| E1 | CI pipeline passes on the merged commit (lint, type-check, unit tests, build) | GitHub Actions (automated) |
+| E2 | Docker image is built and pushed to GHCR with a CalVer tag | GitHub Actions (automated) |
+| E3 | Dev environment is deployed and accessible at `cartsnitch.dev.farh.net` | Flux reconciliation + health check |
+| E4 | All Playwright E2E tests pass in CI | GitHub Actions (automated) |
+| E5 | No open S1/S2 defects from previous UAT cycle | Checkout Charlie (manual check) |
+| E6 | PR has been reviewed and approved by QA (Checkout Charlie) and CTO (Savannah Savings) | GitHub PR approvals |
+| E7 | PR has been merged to main by CEO (Coupon Carl) | GitHub merge event |
+| E8 | Acceptance criteria for the feature/change are documented in the Paperclip issue | Checkout Charlie (manual check) |
+
+**If any entry criterion is not met**, UAT is blocked. Checkout Charlie must comment on the Paperclip issue specifying which criteria failed and assign back to the responsible party.
+
+---
+
+## 3. UAT Exit Criteria
+
+UAT is **complete** only when ALL of the following are satisfied. Rollback Rhonda verifies these before signing off.
+
+| # | Criterion | Verified By |
+|---|-----------|------------|
+| X1 | All 10 critical user journeys (J1-J10) have been executed | Rollback Rhonda (full regression) |
+| X2 | Zero open S1 (Critical) defects | Defect tracker |
+| X3 | Zero open S2 (High) defects, OR CTO has granted a documented exception | Defect tracker + CTO sign-off |
+| X4 | All S3/S4 defects are logged and triaged (not necessarily fixed) | Defect tracker |
+| X5 | 100% test execution rate -- every test case was run, none skipped | Rollback Rhonda's UAT report |
+| X6 | Accessibility scan (axe-core) reports zero critical violations | Automated in E2E suite |
+| X7 | Lighthouse performance score >= 50, accessibility score >= 90 | Lighthouse CI |
+| X8 | Written sign-off from Rollback Rhonda confirming all criteria met | Paperclip comment on issue |
+
+**If any exit criterion is not met**, the release is blocked. Rollback Rhonda must:
+1. File defects for all failures using the Defect Report Template above.
+2. Comment on the Paperclip issue specifying which exit criteria failed.
+3. Assign back to CTO for triage and redistribution.
+
+---
+
+## 4. UAT Execution Procedure
+
+### 4.1 Pre-UAT (Checkout Charlie)
+
+1. Verify all entry criteria (E1-E8) are met.
+2. Comment on the Paperclip issue: "UAT gate open -- all entry criteria verified."
+3. Assign to Rollback Rhonda with status todo.
+
+### 4.2 UAT Execution (Rollback Rhonda)
+
+1. **Full regression run** -- execute ALL 10 user journeys against cartsnitch.dev.farh.net. No partial runs. No exceptions.
+2. For each journey, verify:
+   - All interactive elements respond correctly (buttons, forms, links, toggles)
+   - State transitions are correct (auth state, data mutations, navigation)
+   - Error states are handled gracefully (invalid input, network failures)
+   - Accessibility scan passes (axe-core integrated in Playwright)
+3. Log results for each journey: PASS / FAIL with details.
+4. File defects immediately for any failures.
+5. Complete the UAT report with execution results.
+
+### 4.3 Post-UAT Sign-Off
+
+1. If all exit criteria (X1-X8) are met:
+   - Rollback Rhonda posts sign-off comment: "UAT PASSED -- all exit criteria met."
+   - Production promotion is automated via Flux on UAT pass.
+2. If any exit criterion fails:
+   - Rollback Rhonda posts failure comment with specific failures.
+   - CTO triages defects and redistributes to engineers.
+   - After fixes are merged, UAT restarts from 4.1 (full cycle).
+
+---
+
+## 5. Critical User Journeys Reference
+
+| ID | Journey | Key Interactions |
+|----|---------|-----------------|
+| J1 | Registration -> Login -> Dashboard | Form submission, auth state, redirect |
+| J2 | Login -> Browse Products -> View Detail -> Price Chart | Search, navigation, data visualization |
+| J3 | Login -> Purchases -> Purchase Detail -> Product Link | List navigation, detail view, cross-linking |
+| J4 | Login -> Connect Store Account -> Verify Connection | OAuth flow, external integration |
+| J5 | Login -> Create Price Alert -> View -> Delete Alert | CRUD operations, confirmation dialogs |
+| J6 | Login -> Browse Coupons -> Copy Code | Clipboard interaction, toast feedback |
+| J7 | Login -> Settings -> Toggle Preferences -> Sign Out | Checkbox toggles, theme switch, session termination |
+| J8 | Login -> Store Comparison -> Compare Prices | Data comparison, sorting, price display |
+| J9 | Forgot Password Flow | Email input, validation, redirect |
+| J10 | Unauth Access -> Redirect to Login | Route protection, redirect behavior |
+
+---
+
+## 6. Revision History
+
+| Version | Date | Author | Changes |
+|---------|------|--------|---------|
+| 1.0 | 2026-03-30 | Savannah Savings | Initial runbook -- defect taxonomy, entry/exit criteria, execution procedure |
+

e2e/fixtures.ts

@@ -0,0 +1,100 @@
+import { test as base, expect, type Page } from "@playwright/test";
+import AxeBuilder from "@axe-core/playwright";
+
+export const test = base.extend<{ axeCheck: void }>({
+  axeCheck: [async ({ page }, use) => {
+    await use();
+    const results = await new AxeBuilder({ page }).analyze();
+    expect(results.violations).toEqual([]);
+  }, { auto: true }],
+});
+
+export { expect } from "@playwright/test";
+
+const MOCK_USER_ID = "mock_user_123";
+const MOCK_SESSION_ID = "mock_session_456";
+
+async function mockAuthRoutes(page: Page, authenticated = false) {
+  await page.route(/.*\/auth\/sign-up\/email.*/, async (route) => {
+    await route.fulfill({
+      status: 200,
+      contentType: "application/json",
+      body: JSON.stringify({
+        token: null,
+        user: {
+          id: MOCK_USER_ID,
+          email: "mock@cartsnitch.test",
+          name: "Mock User",
+          emailVerified: true,
+          createdAt: new Date().toISOString(),
+          updatedAt: new Date().toISOString(),
+        },
+      }),
+    });
+  });
+
+  await page.route(/.*\/auth\/sign-in\/email.*/, async (route) => {
+    await route.fulfill({
+      status: 200,
+      contentType: "application/json",
+      body: JSON.stringify({
+        redirect: false,
+        token: "mock_token_123",
+        user: {
+          id: MOCK_USER_ID,
+          email: "mock@cartsnitch.test",
+          name: "Mock User",
+          emailVerified: true,
+          createdAt: new Date().toISOString(),
+          updatedAt: new Date().toISOString(),
+        },
+      }),
+    });
+  });
+
+  await page.route(/.*\/auth\/get-session.*/, async (route) => {
+    if (authenticated) {
+      await route.fulfill({
+        status: 200,
+        contentType: "application/json",
+        body: JSON.stringify({
+          session: {
+            id: MOCK_SESSION_ID,
+            expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString(),
+            createdAt: new Date().toISOString(),
+            updatedAt: new Date().toISOString(),
+            ipAddress: null,
+            userAgent: null,
+          },
+          user: {
+            id: MOCK_USER_ID,
+            email: "mock@cartsnitch.test",
+            name: "Mock User",
+            emailVerified: true,
+            createdAt: new Date().toISOString(),
+            updatedAt: new Date().toISOString(),
+          },
+        }),
+      });
+    } else {
+      await route.fulfill({
+        status: 401,
+        contentType: "application/json",
+        body: JSON.stringify({ error: "Unauthorized" }),
+      });
+    }
+  });
+}
+
+export async function mockSessionDelayed(page: Page, delayMs = 3000) {
+  await page.route(/.*\/auth\/get-session.*/, async (route) => {
+    await new Promise((r) => setTimeout(r, delayMs));
+    await route.fulfill({
+      status: 401,
+      contentType: "application/json",
+      body: JSON.stringify({ error: "Unauthorized" }),
+    });
+  });
+}
+
+export { mockAuthRoutes };

e2e/journeys/j1-registration-login.spec.ts

@@ -0,0 +1,52 @@
+import { test, expect } from '@playwright/test';
+import { mockAuthRoutes } from '../fixtures';
+
+const uniqueEmail = () => `betty+e2e-${Date.now()}@cartsnitch.test`;
+
+test.describe('J1: Registration and Login', () => {
+  test('shows success message after registration', async ({ page }) => {
+    await mockAuthRoutes(page, false);
+    await page.goto('/register');
+    await page.fill('[placeholder="Full Name"]', 'Betty Tester');
+    await page.fill('[placeholder="Email"]', uniqueEmail());
+    await page.fill('[placeholder="Password (min. 8 characters)"]', 'TestPass123!');
+    await page.click('button[type="submit"]');
+
+    // Registration now shows "Account created! Please sign in." message
+    await expect(page.locator('.bg-red-50')).toContainText('Account created! Please sign in.');
+  });
+
+  test('shows validation error when registration fields are empty', async ({ page }) => {
+    await page.goto('/register');
+    await page.click('button[type="submit"]');
+
+    await expect(page.locator('.bg-red-50')).toContainText('Please fill in all fields');
+  });
+
+  test('can navigate from register to login', async ({ page }) => {
+    await page.goto('/register');
+    await page.getByRole('link', { name: /sign in/i }).click();
+
+    await expect(page).toHaveURL(/\/login/);
+    await expect(page.getByRole('heading', { name: /cartsnitch/i })).toBeVisible();
+  });
+
+  test('can sign in with valid credentials', async ({ page }) => {
+    await mockAuthRoutes(page, true);
+    const email = uniqueEmail();
+    await page.goto('/register');
+    await page.fill('[placeholder="Full Name"]', 'Login Betty');
+    await page.fill('[placeholder="Email"]', email);
+    await page.fill('[placeholder="Password (min. 8 characters)"]', 'TestPass123!');
+    await page.click('button[type="submit"]');
+    await expect(page.locator('.bg-red-50')).toContainText('Account created! Please sign in.');
+
+    await page.goto('/login');
+    await page.fill('[placeholder="Email"]', 'test@cartsnitch.test');
+    await page.fill('[placeholder="Password"]', 'TestPass123!');
+    await page.click('button[type="submit"]');
+
+    await expect(page).toHaveURL('http://localhost:5173/');
+  });
+
+});

e2e/journeys/j8-unauth-access.spec.ts

@@ -0,0 +1,43 @@
+import { test, expect } from '@playwright/test';
+import { mockAuthRoutes, mockSessionDelayed } from '../fixtures';
+
+test.describe('J8: Unauthenticated Access', () => {
+  test('redirects /dashboard (/) to /login when not authenticated', async ({ page }) => {
+    await mockAuthRoutes(page, false);
+    await page.goto('/');
+
+    await expect(page).toHaveURL(/\/login/);
+    await expect(page.getByRole('heading', { name: /cartsnitch/i })).toBeVisible();
+  });
+
+  test('redirects /purchases to /login when not authenticated', async ({ page }) => {
+    await mockAuthRoutes(page, false);
+    await page.goto('/purchases');
+
+    await expect(page).toHaveURL(/\/login/);
+    await expect(page.getByRole('heading', { name: /cartsnitch/i })).toBeVisible();
+  });
+
+  test('redirects /products to /login when not authenticated', async ({ page }) => {
+    await mockAuthRoutes(page, false);
+    await page.goto('/products');
+
+    await expect(page).toHaveURL(/\/login/);
+    await expect(page.getByRole('heading', { name: /cartsnitch/i })).toBeVisible();
+  });
+
+  test('redirects /coupons to /login when not authenticated', async ({ page }) => {
+    await mockAuthRoutes(page, false);
+    await page.goto('/coupons');
+
+    await expect(page).toHaveURL(/\/login/);
+    await expect(page.getByRole('heading', { name: /cartsnitch/i })).toBeVisible();
+  });
+
+  test('shows loading spinner while auth session is pending', async ({ page }) => {
+    await mockSessionDelayed(page, 3000);
+    await page.goto('/purchases');
+    await expect(page.locator('.animate-spin')).toBeVisible({ timeout: 2000 });
+    await expect(page).toHaveURL(/\/login/, { timeout: 10_000 });
+  });
+});

e2e/smoke.spec.ts

@@ -0,0 +1,8 @@
+import { test, expect, mockAuthRoutes } from './fixtures';
+
+test('app loads', async ({ page }) => {
+  await mockAuthRoutes(page, false);
+  await page.goto('/');
+  await expect(page).toHaveURL(/\/login/);
+  await expect(page.getByRole('heading', { name: /CartSnitch/i })).toBeVisible();
+});

lighthouserc.json

@@ -0,0 +1,24 @@
+{
+  "ci": {
+    "collect": {
+      "staticDistDir": "./dist",
+      "url": ["http://localhost:4173/"],
+      "numberOfRuns": 1,
+      "settings": {
+        "chromeFlags": ["--headless=new", "--no-sandbox", "--disable-gpu", "--disable-dev-shm-usage"],
+        "skipAudits": ["bf-cache"],
+        "disableFullPageScreenshot": true
+      }
+    },
+    "assert": {
+      "assertions": {
+        "categories:performance": ["warn", { "minScore": 0.7 }],
+        "categories:accessibility": ["error", { "minScore": 0.9 }],
+        "categories:best-practices": ["warn", { "minScore": 0.8 }]
+      }
+    },
+    "upload": {
+      "target": "temporary-public-storage"
+    }
+  }
+}

nginx.conf

@@ -9,6 +9,12 @@ server {
     gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript image/svg+xml;
     gzip_min_length 256;
 
+    # Security headers
+    add_header X-Frame-Options "SAMEORIGIN" always;
+    add_header X-Content-Type-Options "nosniff" always;
+    add_header Referrer-Policy "strict-origin-when-cross-origin" always;
+    add_header Content-Security-Policy "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self'; connect-src 'self' https://*.cartsnitch.com https://*.farh.net; frame-ancestors 'self'" always;
+
     # Health endpoint for K8s probes
     location /health {
         access_log off;

package.json

@@ -9,11 +9,13 @@
     "lint": "eslint .",
     "preview": "vite preview",
     "test": "NODE_ENV=test vitest run",
-    "test:watch": "NODE_ENV=test vitest"
+    "test:watch": "NODE_ENV=test vitest",
+    "test:e2e": "npx playwright test"
   },
   "dependencies": {
     "@tanstack/react-query": "^5.0.0",
     "better-auth": "^1.2.0",
+    "picomatch": "4.0.4",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "react-router-dom": "^7.0.0",
@@ -21,24 +23,38 @@
     "zustand": "^5.0.0"
   },
   "devDependencies": {
+    "@axe-core/playwright": "^4.10.0",
     "@eslint/js": "^9.39.4",
+    "@playwright/test": "^1.58.2",
     "@tailwindcss/vite": "^4.0.0",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.3.2",
     "@types/node": "^24.12.0",
     "@types/react": "^18.3.28",
     "@types/react-dom": "^18.3.7",
-    "@vitejs/plugin-react": "^4.5.2",
+    "@vitejs/plugin-react": "^4.7.0",
     "eslint": "^9.39.4",
     "eslint-plugin-react-hooks": "^7.0.1",
     "eslint-plugin-react-refresh": "^0.5.2",
     "globals": "^17.4.0",
     "jsdom": "^25.0.1",
+    "msw": "^2.12.14",
+    "playwright": "^1.58.2",
     "tailwindcss": "^4.0.0",
     "typescript": "^5.7.3",
     "typescript-eslint": "^8.56.1",
-    "vite": "^6.3.5",
+    "vite": "^6.4.2",
     "vite-plugin-pwa": "^0.21.2",
-    "vitest": "^3.2.4"
+    "vitest": "^4.1.8"
+  },
+  "overrides": {
+    "@rollup/pluginutils": "5.3.0",
+    "flatted": "^3.4.2",
+    "serialize-javascript": "7.0.5",
+    "brace-expansion": ">=5.0.6",
+    "lodash": ">=4.17.24",
+    "minimatch": "^10.2.4",
+    "@babel/plugin-transform-modules-systemjs": "^7.29.4",
+    "fast-uri": "^3.1.2"
   }
 }

playwright.config.ts

@@ -0,0 +1,19 @@
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './e2e',
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+  ],
+  webServer: {
+    command: 'npm run dev',
+    url: 'http://localhost:5173',
+    reuseExistingServer: !process.env.CI,
+  },
+  use: {
+    baseURL: 'http://localhost:5173',
+  },
+});

public/robots.txt

@@ -0,0 +1,4 @@
+User-agent: *
+Allow: /
+
+Sitemap: https://cartsnitch.com/sitemap.xml

receiptwitness/.github/workflows/ci.yml

@@ -1,168 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-
-concurrency:
-  group: ci-${{ github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: write
-  packages: write
-
-env:
-  REGISTRY: ghcr.io
-  IMAGE_NAME: cartsnitch/receiptwitness
-
-jobs:
-  lint:
-    runs-on: runners-cartsnitch
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-          cache: pip
-      - name: Install cartsnitch-common from GitHub
-        run: pip install "cartsnitch-common @ git+https://github.com/cartsnitch/common.git@76685ed0384103228cd670b477b967e7752ebe6b"
-      - run: pip install ruff
-      - name: Ruff lint
-        run: ruff check .
-      - name: Ruff format check
-        run: ruff format --check .
-
-  typecheck:
-    runs-on: runners-cartsnitch
-    continue-on-error: true
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-          cache: pip
-      - name: Install cartsnitch-common from GitHub
-        run: pip install "cartsnitch-common @ git+https://github.com/cartsnitch/common.git@76685ed0384103228cd670b477b967e7752ebe6b"
-      - run: pip install -e ".[dev]" mypy
-      - name: Type check
-        run: mypy src/receiptwitness
-
-  test:
-    runs-on: runners-cartsnitch
-    services:
-      postgres:
-        image: postgres:15-alpine
-        credentials:
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
-        env:
-          POSTGRES_USER: cartsnitch
-          POSTGRES_PASSWORD: cartsnitch_test
-          POSTGRES_DB: cartsnitch_test
-        ports:
-          - 5432:5432
-        options: >-
-          --health-cmd pg_isready
-          --health-interval 10s
-          --health-timeout 5s
-          --health-retries 5
-      redis:
-        image: redis:7-alpine
-        credentials:
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
-        ports:
-          - 6379:6379
-        options: >-
-          --health-cmd "redis-cli ping"
-          --health-interval 10s
-          --health-timeout 5s
-          --health-retries 5
-    env:
-      DATABASE_URL: postgresql://cartsnitch:cartsnitch_test@localhost:5432/cartsnitch_test
-      REDIS_URL: redis://localhost:6379/0
-      ENCRYPTION_KEY: dGVzdC1lbmNyeXB0aW9uLWtleS0xMjM0NTY3ODk=
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
-          cache: pip
-      - name: Install cartsnitch-common from GitHub
-        run: pip install "cartsnitch-common @ git+https://github.com/cartsnitch/common.git@76685ed0384103228cd670b477b967e7752ebe6b"
-      - run: pip install -e ".[dev]"
-      - name: Install Playwright browsers
-        run: playwright install chromium --with-deps
-      - name: Run tests
-        run: pytest --tb=short -q
-
-  build-and-push:
-    runs-on: runners-cartsnitch
-    needs: [lint, test]
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Generate CalVer tag
-        id: calver
-        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-        run: |
-          DATE_TAG=$(date -u +%Y.%m.%d)
-          EXISTING=$(git tag -l "v${DATE_TAG}*" | sort -V | tail -1)
-          if [ -z "$EXISTING" ]; then
-            VERSION="$DATE_TAG"
-          elif [ "$EXISTING" = "v${DATE_TAG}" ]; then
-            VERSION="${DATE_TAG}.2"
-          else
-            BUILD_NUM=$(echo "$EXISTING" | sed "s/v${DATE_TAG}\.//")
-            VERSION="${DATE_TAG}.$((BUILD_NUM + 1))"
-          fi
-          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
-          echo "CalVer tag: $VERSION"
-
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
-
-      - name: Log in to Docker Hub
-        uses: docker/login-action@v3
-        with:
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
-
-      - name: Log in to GHCR
-        uses: docker/login-action@v3
-        with:
-          registry: ${{ env.REGISTRY }}
-          username: ${{ github.actor }}
-          password: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Extract metadata
-        id: meta
-        uses: docker/metadata-action@v5
-        with:
-          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
-          tags: |
-            type=sha,prefix=sha-
-            type=raw,value=${{ steps.calver.outputs.version }},enable=${{ github.ref == 'refs/heads/main' }}
-            type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' }}
-
-      - name: Build and push Docker image
-        uses: docker/build-push-action@v6
-        with:
-          context: .
-          push: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
-          tags: ${{ steps.meta.outputs.tags }}
-          labels: ${{ steps.meta.outputs.labels }}
-          target: prod
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
-
-      - name: Create git tag
-        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-        run: |
-          git tag "v${{ steps.calver.outputs.version }}"
-          git push origin "v${{ steps.calver.outputs.version }}"

receiptwitness/Dockerfile

@@ -3,24 +3,22 @@ FROM python:3.12-slim AS build
 
 WORKDIR /app
 
-# git is required to install cartsnitch-common from GitHub; build-essential and
-# libpq-dev are needed to compile any C-extension wheels (e.g. psycopg2 fallback)
-RUN apt-get update && apt-get install -y --no-install-recommends \
-    git \
+# build-essential and libpq-dev are needed to compile any C-extension wheels
+# (e.g. psycopg2 fallback).  No git needed — common/ is copied from the repo root.
+ARG APT_CACHE_BUST=1
+RUN apt-get update && apt-get upgrade -y && apt-get install -y --no-install-recommends \
     libpq-dev \
     build-essential \
     && rm -rf /var/lib/apt/lists/*
 
-COPY pyproject.toml ./
-COPY src/ ./src/
+# Build context is the repo root.  These paths are relative to the root.
+COPY receiptwitness/pyproject.toml ./
+COPY receiptwitness/src/ ./src/
+COPY common/ ./common/
 
-# cartsnitch-common is not on PyPI — install it directly from GitHub, then
-# install the rest of the package dependencies in a single resolver pass so
-# pip can satisfy the cartsnitch-common>=0.1.0 constraint declared in
-# pyproject.toml without hitting PyPI for it.
-RUN pip install --no-cache-dir --prefix=/install \
-    "cartsnitch-common @ git+https://github.com/cartsnitch/common.git@76685ed0384103228cd670b477b967e7752ebe6b" \
-    .
+# Install from the local common/ (cartsnitch-common>=0.1.0 in pyproject.toml
+# will be satisfied by the local package) then install receiptwitness itself.
+RUN pip install --no-cache-dir --prefix=/install ./common/ .
 
 # Stage 2: Production image with Playwright + Chromium
 FROM python:3.12-slim AS prod
@@ -28,7 +26,8 @@ FROM python:3.12-slim AS prod
 WORKDIR /app
 
 # Install Playwright system dependencies for Chromium
-RUN apt-get update && apt-get install -y --no-install-recommends \
+ARG APT_CACHE_BUST=1
+RUN apt-get update && apt-get upgrade -y && apt-get install -y --no-install-recommends \
     libnss3 \
     libatk1.0-0 \
     libatk-bridge2.0-0 \
@@ -51,7 +50,7 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
 RUN adduser --system --group --uid 1000 app
 
 COPY --from=build /install /usr/local
-COPY src/ ./src/
+COPY receiptwitness/src/ ./src/
 
 # Install Playwright Chromium browser (runs as root; /opt/playwright is world-readable)
 RUN PLAYWRIGHT_BROWSERS_PATH=/opt/playwright playwright install chromium

receiptwitness/pyproject.toml

@@ -11,14 +11,16 @@ dependencies = [
     "cartsnitch-common>=0.1.0",
     "playwright>=1.49,<2.0",
     "playwright-stealth>=1.0,<2.0",
-    "cryptography>=42.0,<44.0",
+    "cryptography>=46.0,<47.0",
     "fastapi>=0.115,<1.0",
     "uvicorn[standard]>=0.30,<1.0",
+    "beautifulsoup4>=4.12,<5.0",
     "redis>=5.0,<6.0",
     "pydantic>=2.0,<3.0",
     "pydantic-settings>=2.0,<3.0",
     "sqlalchemy[asyncio]>=2.0,<3.0",
     "asyncpg>=0.29,<1.0",
+    "resend>=2.0",
 ]
 
 [project.optional-dependencies]
@@ -27,6 +29,9 @@ dev = [
     "pytest-asyncio>=0.23",
     "ruff>=0.3",
     "pytest-cov>=5.0",
+    "fakeredis[aioredis]>=2.20",
+    "httpx>=0.27",
+    "python-multipart>=0.0.9",
 ]
 
 [tool.hatch.build.targets.wheel]

receiptwitness/src/receiptwitness/api/routes.py

@@ -1,9 +1,65 @@
 """Internal API routes for triggering scrapes and checking status."""
 
-from fastapi import APIRouter
+import hashlib
+import hmac
+import re
+import time
+
+from fastapi import APIRouter, HTTPException, Request
+
+from receiptwitness.config import settings
+from receiptwitness.queue.email import EmailJob, enqueue_email, get_redis
 
 router = APIRouter()
 
+TOKEN_PATTERN = re.compile(r"receipts\+([A-Za-z0-9_-]+)@")
+
+
+def verify_mailgun_signature(token: str, timestamp: str, signature: str) -> bool:
+    """Verify Mailgun webhook signature."""
+    try:
+        ts = int(timestamp)
+    except (ValueError, TypeError):
+        return False
+    if abs(time.time() - ts) > 300:  # 5 min freshness
+        return False
+    key = settings.mailgun_webhook_signing_key.encode()
+    hmac_digest = hmac.new(key, f"{timestamp}{token}".encode(), hashlib.sha256).hexdigest()
+    return hmac.compare_digest(signature, hmac_digest)
+
+
+@router.post("/inbound/email")
+async def receive_inbound_email(request: Request):
+    form = await request.form()
+    # 1. Verify Mailgun signature
+    token = str(form.get("token", ""))
+    timestamp = str(form.get("timestamp", ""))
+    signature = str(form.get("signature", ""))
+    if not verify_mailgun_signature(token, timestamp, signature):
+        raise HTTPException(status_code=406, detail="Invalid signature")
+    # 2. Extract account token from recipient
+    recipient = str(form.get("recipient", ""))
+    match = TOKEN_PATTERN.search(recipient)
+    if not match:
+        raise HTTPException(status_code=406, detail="Invalid recipient")
+    account_token = match.group(1)
+    # 3. Enqueue — worker resolves token -> user_id
+    body_html_val = form.get("body-html")
+    body_plain_val = form.get("body-plain")
+    job = EmailJob(
+        user_id=account_token,
+        sender=str(form.get("sender", "")),
+        recipient=recipient,
+        subject=str(form.get("subject", "")),
+        body_html=str(body_html_val) if body_html_val is not None else None,
+        body_plain=str(body_plain_val) if body_plain_val is not None else None,
+        received_at=str(form.get("timestamp", "")),
+        message_id=str(form.get("Message-Id", "")),
+    )
+    client = await get_redis()
+    await enqueue_email(client, job)
+    return {"status": "queued"}
+
 
 @router.get("/health")
 async def health():

receiptwitness/src/receiptwitness/config.py

@@ -1,8 +1,12 @@
 """Service-specific configuration for ReceiptWitness."""
 
+from pydantic import model_validator
 from pydantic_settings import BaseSettings
 
 
+_PLACEHOLDER_VALUES = {"change-me-in-production"}
+
+
 class ReceiptWitnessSettings(BaseSettings):
     model_config = {"env_prefix": "RW_"}
 
@@ -22,5 +26,42 @@ class ReceiptWitnessSettings(BaseSettings):
     headless: bool = True
     browser_timeout_ms: int = 60000
 
+    # Email notifications (Resend)
+    resend_api_key: str = ""
+    notification_email_from: str = "notifications@cartsnitch.com"
+    notifications_enabled: bool = False
 
-settings = ReceiptWitnessSettings()
+    # Mailgun inbound email webhook
+    mailgun_webhook_signing_key: str = ""
+
+    @model_validator(mode="after")
+    def validate_required_vars(self):
+        errors = []
+        if not self.session_encryption_key or self.session_encryption_key in _PLACEHOLDER_VALUES:
+            errors.append(
+                "RW_SESSION_ENCRYPTION_KEY must be set to a secure value. "
+                'Generate one with: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"'
+            )
+        if self.notifications_enabled and not self.resend_api_key:
+            errors.append(
+                "RW_RESEND_API_KEY must be set when RW_NOTIFICATIONS_ENABLED=true. "
+                "Get an API key from https://resend.com/api-keys"
+            )
+        if errors:
+            raise ValueError(
+                "ReceiptWitness startup failed — missing required config:\n"
+                + "\n".join(f"  - {e}" for e in errors)
+            )
+        return self
+
+
+class _LazySettings:
+    _instance: ReceiptWitnessSettings | None = None
+
+    def __getattr__(self, name: str):
+        if _LazySettings._instance is None:
+            _LazySettings._instance = ReceiptWitnessSettings()
+        return getattr(_LazySettings._instance, name)
+
+
+settings = _LazySettings()

receiptwitness/src/receiptwitness/events.py

@@ -2,12 +2,17 @@
 
 import json
 import logging
+import uuid
 from datetime import UTC, datetime
 from decimal import Decimal
 
 import redis.asyncio as aioredis
+from cartsnitch_common.database import get_async_session_factory
+from cartsnitch_common.models.user import User
+from sqlalchemy import select
 
 from receiptwitness.config import settings
+from receiptwitness.notifications.email import send_receipt_notification
 
 logger = logging.getLogger(__name__)
 
@@ -39,6 +44,36 @@ async def get_redis_client() -> aioredis.Redis:
     return aioredis.Redis(connection_pool=_get_pool())
 
 
+async def _send_notification_for_event(payload: dict) -> None:
+    """Look up user email and send receipt notification. Silently skips on error."""
+    try:
+        user_uuid = uuid.UUID(payload["user_id"])
+    except (ValueError, KeyError):
+        logger.warning("Invalid user_id in event payload: %s", payload.get("user_id"))
+        return
+
+    try:
+        session_factory = get_async_session_factory(settings.database_url)
+        async with session_factory() as session:
+            result = await session.execute(select(User.email).where(User.id == user_uuid))
+            row = result.scalar_one_or_none()
+            if not row:
+                logger.warning("User %s not found for notification", user_uuid)
+                return
+            user_email = row
+    except Exception:
+        logger.exception("Failed to look up user email for notification")
+        return
+
+    await send_receipt_notification(
+        user_email=user_email,
+        store_name=payload["store_slug"],
+        item_count=payload["item_count"],
+        total=payload["total"],
+        purchase_date=payload["purchase_date"],
+    )
+
+
 async def publish_receipt_ingested(
     user_id: str,
     store_slug: str,
@@ -48,18 +83,19 @@ async def publish_receipt_ingested(
     total: Decimal | float,
 ) -> None:
     """Publish a cartsnitch.receipts.ingested event after successful ingestion."""
+    payload = {
+        "user_id": user_id,
+        "store_slug": store_slug,
+        "purchase_id": purchase_id,
+        "purchase_date": purchase_date,
+        "item_count": item_count,
+        "total": float(total) if isinstance(total, Decimal) else total,
+    }
     event = {
         "event_type": CHANNEL_RECEIPTS_INGESTED,
         "timestamp": datetime.now(UTC).isoformat(),
         "service": "receiptwitness",
-        "payload": {
-            "user_id": user_id,
-            "store_slug": store_slug,
-            "purchase_id": purchase_id,
-            "purchase_date": purchase_date,
-            "item_count": item_count,
-            "total": float(total) if isinstance(total, Decimal) else total,
-        },
+        "payload": payload,
     }
 
     try:
@@ -73,3 +109,5 @@ async def publish_receipt_ingested(
     except aioredis.ConnectionError:
         logger.error("Failed to publish event — Redis/DragonflyDB connection error")
         raise
+    else:
+        await _send_notification_for_event(payload)

receiptwitness/src/receiptwitness/notifications/email.py

@@ -0,0 +1,45 @@
+"""Email notifications via Resend."""
+
+import asyncio
+import html
+import logging
+
+import resend
+
+from receiptwitness.config import settings
+
+logger = logging.getLogger(__name__)
+
+
+async def send_receipt_notification(
+    user_email: str,
+    store_name: str,
+    item_count: int,
+    total: float,
+    purchase_date: str,
+) -> None:
+    """Send receipt ingestion confirmation email via Resend."""
+    if not settings.notifications_enabled or not settings.resend_api_key:
+        logger.debug("Notifications disabled — skipping email send")
+        return
+
+    resend.api_key = settings.resend_api_key
+    store_name_safe = html.escape(store_name)
+    purchase_date_safe = html.escape(purchase_date)
+    try:
+        await asyncio.to_thread(
+            resend.Emails.send,
+            {
+                "from": settings.notification_email_from,
+                "to": [user_email],
+                "subject": f"Receipt processed: {store_name} - ${total:.2f}",
+                "html": (
+                    f"<p>Your receipt from <strong>{store_name_safe}</strong> on "
+                    f"{purchase_date_safe} has been processed.</p>"
+                    f"<p>{item_count} items, total: ${total:.2f}</p>"
+                ),
+            },
+        )
+        logger.info("Receipt notification sent to %s", user_email)
+    except Exception:
+        logger.exception("Failed to send receipt notification to %s", user_email)

receiptwitness/src/receiptwitness/parsers/email/__init__.py

@@ -0,0 +1 @@
+"""Email receipt parsers for retailer email receipts."""

receiptwitness/src/receiptwitness/parsers/email/base.py

@@ -0,0 +1,32 @@
+"""Base interface for email receipt parsers."""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+
+
+@dataclass
+class EmailReceipt:
+    """Raw email data before parsing."""
+
+    sender: str
+    recipient: str
+    subject: str
+    body_html: str | None = None
+    body_plain: str | None = None
+    received_at: str | None = None
+    raw_headers: dict = field(default_factory=dict)
+
+
+class BaseEmailParser(ABC):
+    """All retailer email parsers implement this interface."""
+
+    @abstractmethod
+    def can_parse(self, email: EmailReceipt) -> bool:
+        """Return True if this parser handles this email."""
+        ...
+
+    @abstractmethod
+    def parse(self, email: EmailReceipt) -> dict:
+        """Parse email into a dict matching PurchaseCreate schema fields.
+        Must include an items list matching PurchaseItemCreate fields."""
+        ...