ci: Bump version to 0.11.11 [skip ci]

- Introduced ADR-054 detailing the implementation of an automated sync worker to create Gitea issues from unresolved Bugsink errors.
- Documented architecture, queue configuration, Redis schema, and implementation phases for the sync feature.
- Added frontend testing summary for 2026-01-18, covering multiple sessions of API testing, fixes applied, and Bugsink error tracking status.
- Included detailed API reference and common validation errors encountered during testing.

.claude/hooks.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://claude.ai/schemas/hooks.json",
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"const cmd = process.argv[1] || ''; const isTest = /\\b(npm\\s+(run\\s+)?test|vitest|jest)\\b/i.test(cmd); const isWindows = process.platform === 'win32'; const inContainer = process.env.REMOTE_CONTAINERS === 'true' || process.env.DEVCONTAINER === 'true'; if (isTest && isWindows && !inContainer) { console.error('BLOCKED: Tests must run on Linux. Use Dev Container (Reopen in Container) or WSL.'); process.exit(1); }\" -- \"$CLAUDE_TOOL_INPUT\""
+          }
+        ]
+      }
+    ]
+  }
+}

.claude/settings.local.json

@@ -0,0 +1,105 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm test:*)",
+      "Bash(podman --version:*)",
+      "Bash(podman ps:*)",
+      "Bash(podman machine start:*)",
+      "Bash(podman compose:*)",
+      "Bash(podman pull:*)",
+      "Bash(podman images:*)",
+      "Bash(podman stop:*)",
+      "Bash(echo:*)",
+      "Bash(podman rm:*)",
+      "Bash(podman run:*)",
+      "Bash(podman start:*)",
+      "Bash(podman exec:*)",
+      "Bash(cat:*)",
+      "Bash(PGPASSWORD=postgres psql:*)",
+      "Bash(npm search:*)",
+      "Bash(npx:*)",
+      "Bash(curl:*)",
+      "Bash(powershell:*)",
+      "Bash(cmd.exe:*)",
+      "Bash(npm run test:integration:*)",
+      "Bash(grep:*)",
+      "Bash(done)",
+      "Bash(podman info:*)",
+      "Bash(podman machine:*)",
+      "Bash(podman system connection:*)",
+      "Bash(podman inspect:*)",
+      "Bash(python -m json.tool:*)",
+      "Bash(claude mcp status)",
+      "Bash(powershell.exe -Command \"claude mcp status\")",
+      "Bash(powershell.exe -Command \"claude mcp\")",
+      "Bash(powershell.exe -Command \"claude mcp list\")",
+      "Bash(powershell.exe -Command \"claude --version\")",
+      "Bash(powershell.exe -Command \"claude config\")",
+      "Bash(powershell.exe -Command \"claude mcp get gitea-projectium\")",
+      "Bash(powershell.exe -Command \"claude mcp add --help\")",
+      "Bash(powershell.exe -Command \"claude mcp add -t stdio -s user filesystem -- D:\\\\nodejs\\\\npx.cmd -y @modelcontextprotocol/server-filesystem D:\\\\gitea\\\\flyer-crawler.projectium.com\\\\flyer-crawler.projectium.com\")",
+      "Bash(powershell.exe -Command \"claude mcp add -t stdio -s user fetch -- D:\\\\nodejs\\\\npx.cmd -y @modelcontextprotocol/server-fetch\")",
+      "Bash(powershell.exe -Command \"echo ''List files in src/hooks using filesystem MCP'' | claude --print\")",
+      "Bash(powershell.exe -Command \"echo ''List all podman containers'' | claude --print\")",
+      "Bash(powershell.exe -Command \"echo ''List my repositories on gitea.projectium.com using gitea-projectium MCP'' | claude --print\")",
+      "Bash(powershell.exe -Command \"echo ''List my repositories on gitea.projectium.com using gitea-projectium MCP'' | claude --print --allowedTools ''mcp__gitea-projectium__*''\")",
+      "Bash(powershell.exe -Command \"echo ''Fetch the homepage of https://gitea.projectium.com and summarize it'' | claude --print --allowedTools ''mcp__fetch__*''\")",
+      "Bash(dir \"C:\\\\Users\\\\games3\\\\.claude\")",
+      "Bash(dir:*)",
+      "Bash(D:nodejsnpx.cmd -y @modelcontextprotocol/server-fetch --help)",
+      "Bash(cmd /c \"dir /o-d C:\\\\Users\\\\games3\\\\.claude\\\\debug 2>nul | head -10\")",
+      "mcp__memory__read_graph",
+      "mcp__memory__create_entities",
+      "mcp__memory__search_nodes",
+      "mcp__memory__delete_entities",
+      "mcp__sequential-thinking__sequentialthinking",
+      "mcp__filesystem__list_directory",
+      "mcp__filesystem__read_multiple_files",
+      "mcp__filesystem__directory_tree",
+      "mcp__filesystem__read_text_file",
+      "Bash(wc:*)",
+      "Bash(npm install:*)",
+      "Bash(git grep:*)",
+      "Bash(findstr:*)",
+      "Bash(git add:*)",
+      "mcp__filesystem__write_file",
+      "mcp__podman__container_list",
+      "Bash(podman cp:*)",
+      "mcp__podman__container_inspect",
+      "mcp__podman__network_list",
+      "Bash(podman network connect:*)",
+      "Bash(npm run build:*)",
+      "Bash(set NODE_ENV=test)",
+      "Bash(podman-compose:*)",
+      "Bash(timeout 60 podman machine start:*)",
+      "Bash(podman build:*)",
+      "Bash(podman network rm:*)",
+      "Bash(npm run lint)",
+      "Bash(npm run typecheck:*)",
+      "Bash(npm run type-check:*)",
+      "Bash(npm run test:unit:*)",
+      "mcp__filesystem__move_file",
+      "Bash(git checkout:*)",
+      "Bash(podman image inspect:*)",
+      "Bash(node -e:*)",
+      "Bash(xargs -I {} sh -c 'if ! grep -q \"\"vi.mock.*apiClient\"\" \"\"{}\"\"; then echo \"\"{}\"\"; fi')",
+      "Bash(MSYS_NO_PATHCONV=1 podman exec:*)",
+      "Bash(docker ps:*)",
+      "Bash(find:*)",
+      "Bash(\"/c/Users/games3/.local/bin/uvx.exe\" markitdown-mcp --help)",
+      "Bash(git stash:*)",
+      "Bash(ping:*)",
+      "Bash(tee:*)",
+      "Bash(timeout 1800 podman exec flyer-crawler-dev npm run test:unit:*)",
+      "mcp__filesystem__edit_file",
+      "Bash(timeout 300 tail:*)",
+      "mcp__filesystem__list_allowed_directories",
+      "mcp__memory__add_observations",
+      "Bash(ssh:*)",
+      "mcp__redis__list",
+      "Read(//d/gitea/bugsink-mcp/**)",
+      "Bash(d:/nodejs/npm.cmd install)",
+      "Bash(node node_modules/vitest/vitest.mjs run:*)"
+    ]
+  }
+}

.devcontainer/devcontainer.json

@@ -0,0 +1,96 @@
+{
+  // ============================================================================
+  // VS CODE DEV CONTAINER CONFIGURATION
+  // ============================================================================
+  // This file configures VS Code's Dev Containers extension to provide a
+  // consistent, fully-configured development environment.
+  //
+  // Features:
+  //   - Automatic PostgreSQL + Redis startup with healthchecks
+  //   - Automatic npm install
+  //   - Automatic database schema initialization and seeding
+  //   - Pre-configured VS Code extensions (ESLint, Prettier)
+  //   - Podman support for Windows users
+  //
+  // Usage:
+  //   1. Install the "Dev Containers" extension in VS Code
+  //   2. Open this project folder
+  //   3. Click "Reopen in Container" when prompted (or use Command Palette)
+  //   4. Wait for container build and initialization
+  //   5. Development server starts automatically
+  // ============================================================================
+
+  "name": "Flyer Crawler Dev (Ubuntu 22.04)",
+
+  // Use Docker Compose for multi-container setup
+  "dockerComposeFile": ["../compose.dev.yml"],
+  "service": "app",
+  "workspaceFolder": "/app",
+
+  // VS Code customizations
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        // Code quality
+        "dbaeumer.vscode-eslint",
+        "esbenp.prettier-vscode",
+        // TypeScript
+        "ms-vscode.vscode-typescript-next",
+        // Database
+        "mtxr.sqltools",
+        "mtxr.sqltools-driver-pg",
+        // Utilities
+        "eamodio.gitlens",
+        "streetsidesoftware.code-spell-checker"
+      ],
+      "settings": {
+        "editor.formatOnSave": true,
+        "editor.defaultFormatter": "esbenp.prettier-vscode",
+        "typescript.preferences.importModuleSpecifier": "relative"
+      }
+    }
+  },
+
+  // Run as root (required for npm global installs)
+  "remoteUser": "root",
+
+  // ============================================================================
+  // Lifecycle Commands
+  // ============================================================================
+
+  // initializeCommand: Runs on the HOST before the container is created.
+  // Starts Podman machine on Windows (no-op if already running or using Docker).
+  "initializeCommand": "powershell -Command \"podman machine start; exit 0\"",
+
+  // postCreateCommand: Runs ONCE when the container is first created.
+  // This is where we do full initialization: npm install + database setup.
+  "postCreateCommand": "chmod +x scripts/docker-init.sh && ./scripts/docker-init.sh",
+
+  // postAttachCommand: Runs EVERY TIME VS Code attaches to the container.
+  // Starts the development server automatically.
+  "postAttachCommand": "npm run dev:container",
+
+  // ============================================================================
+  // Port Forwarding
+  // ============================================================================
+  // Automatically forward these ports from the container to the host
+  "forwardPorts": [3000, 3001],
+
+  // Labels for forwarded ports in VS Code's Ports panel
+  "portsAttributes": {
+    "3000": {
+      "label": "Frontend (Vite)",
+      "onAutoForward": "notify"
+    },
+    "3001": {
+      "label": "Backend API",
+      "onAutoForward": "notify"
+    }
+  },
+
+  // ============================================================================
+  // Features
+  // ============================================================================
+  // Additional dev container features (optional)
+  "features": {}
+}

.env.example

@@ -0,0 +1,114 @@
+# .env.example
+# ============================================================================
+# ENVIRONMENT VARIABLES TEMPLATE
+# ============================================================================
+# Copy this file to .env and fill in your values.
+# For local development with Docker/Podman, these defaults should work out of the box.
+#
+# IMPORTANT: Never commit .env files with real credentials to version control!
+# ============================================================================
+
+# ===================
+# Database Configuration
+# ===================
+# PostgreSQL connection settings
+# For container development, use the service name "postgres"
+DB_HOST=postgres
+DB_PORT=5432
+DB_USER=postgres
+DB_PASSWORD=postgres
+DB_NAME=flyer_crawler_dev
+
+# ===================
+# Redis Configuration
+# ===================
+# Redis URL for caching and job queues
+# For container development, use the service name "redis"
+REDIS_URL=redis://redis:6379
+# Optional: Redis password (leave empty if not required)
+REDIS_PASSWORD=
+
+# ===================
+# Application Settings
+# ===================
+NODE_ENV=development
+# Frontend URL for CORS and email links
+FRONTEND_URL=http://localhost:3000
+
+# ===================
+# Authentication
+# ===================
+# REQUIRED: Secret key for signing JWT tokens (generate a random 64+ character string)
+JWT_SECRET=your-super-secret-jwt-key-change-this-in-production
+
+# OAuth Providers (Optional - enable social login)
+# Google OAuth - https://console.cloud.google.com/apis/credentials
+GOOGLE_CLIENT_ID=
+GOOGLE_CLIENT_SECRET=
+# GitHub OAuth - https://github.com/settings/developers
+GITHUB_CLIENT_ID=
+GITHUB_CLIENT_SECRET=
+
+# ===================
+# AI/ML Services
+# ===================
+# REQUIRED: Google Gemini API key for flyer OCR processing
+GEMINI_API_KEY=your-gemini-api-key
+
+# ===================
+# External APIs
+# ===================
+# Optional: Google Maps API key for geocoding store addresses
+GOOGLE_MAPS_API_KEY=
+
+# ===================
+# Email Configuration (Optional)
+# ===================
+# SMTP settings for sending emails (deal notifications, password reset)
+SMTP_HOST=
+SMTP_PORT=587
+SMTP_SECURE=false
+SMTP_USER=
+SMTP_PASS=
+SMTP_FROM_EMAIL=noreply@example.com
+
+# ===================
+# Worker Configuration (Optional)
+# ===================
+# Concurrency settings for background job workers
+WORKER_CONCURRENCY=1
+EMAIL_WORKER_CONCURRENCY=10
+ANALYTICS_WORKER_CONCURRENCY=1
+CLEANUP_WORKER_CONCURRENCY=10
+
+# Worker lock duration in milliseconds (default: 2 minutes)
+WORKER_LOCK_DURATION=120000
+
+# ===================
+# Error Tracking (ADR-015)
+# ===================
+# Sentry-compatible error tracking via Bugsink (self-hosted)
+# DSNs are created in Bugsink UI at http://localhost:8000 (dev) or your production URL
+# Backend DSN - for Express/Node.js errors
+SENTRY_DSN=
+# Frontend DSN - for React/browser errors (uses VITE_ prefix)
+VITE_SENTRY_DSN=
+# Environment name for error grouping (defaults to NODE_ENV)
+SENTRY_ENVIRONMENT=development
+VITE_SENTRY_ENVIRONMENT=development
+# Enable/disable error tracking (default: true)
+SENTRY_ENABLED=true
+VITE_SENTRY_ENABLED=true
+# Enable debug mode for SDK troubleshooting (default: false)
+SENTRY_DEBUG=false
+VITE_SENTRY_DEBUG=false
+
+# ===================
+# Source Maps Upload (ADR-015)
+# ===================
+# Auth token for uploading source maps to Bugsink
+# Create at: https://bugsink.projectium.com (Settings > API Keys)
+# Required for de-minified stack traces in error reports
+SENTRY_AUTH_TOKEN=
+# URL of your Bugsink instance (for source map uploads)
+SENTRY_URL=https://bugsink.projectium.com

.env.test

@@ -0,0 +1,6 @@
+DB_HOST=10.89.0.4
+DB_USER=flyer
+DB_PASSWORD=flyer
+DB_NAME=flyer_crawler_test
+REDIS_URL=redis://redis:6379
+NODE_ENV=test

.gitea/workflows/deploy-to-prod.yml

@@ -47,11 +47,24 @@ jobs:
       - name: Install Dependencies
         run: npm ci
 
+      - name: Bump Minor Version and Push
+        run: |
+          # Configure git for the commit.
+          git config --global user.name 'Gitea Actions'
+          git config --global user.email 'actions@gitea.projectium.com'
+
+          # Bump the minor version number. This creates a new commit and a new tag.
+          # The commit message includes [skip ci] to prevent this push from triggering another workflow run.
+          npm version minor -m "ci: Bump version to %s for production release [skip ci]"
+
+          # Push the new commit and the new tag back to the main branch.
+          git push --follow-tags
+
       - name: Check for Production Database Schema Changes
         env:
           DB_HOST: ${{ secrets.DB_HOST }}
-          DB_USER: ${{ secrets.DB_USER }}
-          DB_PASSWORD: ${{ secrets.DB_PASSWORD }}
+          DB_USER: ${{ secrets.DB_USER_PROD }}
+          DB_PASSWORD: ${{ secrets.DB_PASSWORD_PROD }}
           DB_NAME: ${{ secrets.DB_DATABASE_PROD }}
         run: |
           if [ -z "$DB_HOST" ] || [ -z "$DB_USER" ] || [ -z "$DB_PASSWORD" ] || [ -z "$DB_NAME" ]; then
@@ -61,9 +74,10 @@ jobs:
           echo "--- Checking for production schema changes ---"
           CURRENT_HASH=$(cat sql/master_schema_rollup.sql | dos2unix | sha256sum | awk '{ print $1 }')
           echo "Current Git Schema Hash: $CURRENT_HASH"
-          DEPLOYED_HASH=$(PGPASSWORD="$DB_PASSWORD" psql -v ON_ERROR_STOP=1 -h "$DB_HOST" -p 5432 -U "$DB_USER" -d "$DB_NAME" -c "SELECT schema_hash FROM public.schema_info WHERE environment = 'production';" -t -A || echo "none")
+          # The psql command will now fail the step if the query errors (e.g., column missing), preventing deployment on a bad schema.
+          DEPLOYED_HASH=$(PGPASSWORD="$DB_PASSWORD" psql -v ON_ERROR_STOP=1 -h "$DB_HOST" -p 5432 -U "$DB_USER" -d "$DB_NAME" -c "SELECT schema_hash FROM public.schema_info WHERE environment = 'production';" -t -A)
           echo "Deployed DB Schema Hash: $DEPLOYED_HASH"
-          if [ "$DEPLOYED_HASH" = "none" ] || [ -z "$DEPLOYED_HASH" ]; then
+          if [ -z "$DEPLOYED_HASH" ]; then
             echo "WARNING: No schema hash found in the production database. This is expected for a first-time deployment."
           elif [ "$CURRENT_HASH" != "$DEPLOYED_HASH" ]; then
             echo "ERROR: Database schema mismatch detected! A manual database migration is required."
@@ -73,16 +87,33 @@ jobs:
           fi
 
       - name: Build React Application for Production
+        # Source Maps (ADR-015): If SENTRY_AUTH_TOKEN is set, the @sentry/vite-plugin will:
+        # 1. Generate hidden source maps during build
+        # 2. Upload them to Bugsink for error de-minification
+        # 3. Delete the .map files after upload (so they're not publicly accessible)
         run: |
           if [ -z "${{ secrets.VITE_GOOGLE_GENAI_API_KEY }}" ]; then
             echo "ERROR: The VITE_GOOGLE_GENAI_API_KEY secret is not set."
             exit 1
           fi
+
+          # Source map upload is optional - warn if not configured
+          if [ -z "${{ secrets.SENTRY_AUTH_TOKEN }}" ]; then
+            echo "WARNING: SENTRY_AUTH_TOKEN not set. Source maps will NOT be uploaded to Bugsink."
+            echo "         Errors will show minified stack traces. To fix, add SENTRY_AUTH_TOKEN to Gitea secrets."
+          fi
+
           GITEA_SERVER_URL="https://gitea.projectium.com"
-          COMMIT_MESSAGE=$(git log -1 --pretty=%s)
-          VITE_APP_VERSION="$(date +'%Y%m%d-%H%M'):$(git rev-parse --short HEAD)" \
+          COMMIT_MESSAGE=$(git log -1 --grep="\[skip ci\]" --invert-grep --pretty=%s)
+          PACKAGE_VERSION=$(node -p "require('./package.json').version")
+          VITE_APP_VERSION="$(date +'%Y%m%d-%H%M'):$(git rev-parse --short HEAD):$PACKAGE_VERSION" \
           VITE_APP_COMMIT_URL="$GITEA_SERVER_URL/${{ gitea.repository }}/commit/${{ gitea.sha }}" \
           VITE_APP_COMMIT_MESSAGE="$COMMIT_MESSAGE" \
+          VITE_SENTRY_DSN="${{ secrets.VITE_SENTRY_DSN }}" \
+          VITE_SENTRY_ENVIRONMENT="production" \
+          VITE_SENTRY_ENABLED="true" \
+          SENTRY_AUTH_TOKEN="${{ secrets.SENTRY_AUTH_TOKEN }}" \
+          SENTRY_URL="https://bugsink.projectium.com" \
           VITE_API_BASE_URL=/api VITE_API_KEY=${{ secrets.VITE_GOOGLE_GENAI_API_KEY }} npm run build
 
       - name: Deploy Application to Production Server
@@ -99,10 +130,11 @@ jobs:
         env:
           # --- Production Secrets Injection ---
           DB_HOST: ${{ secrets.DB_HOST }}
-          DB_USER: ${{ secrets.DB_USER }}
-          DB_PASSWORD: ${{ secrets.DB_PASSWORD }}
+          DB_USER: ${{ secrets.DB_USER_PROD }}
+          DB_PASSWORD: ${{ secrets.DB_PASSWORD_PROD }}
           DB_NAME: ${{ secrets.DB_DATABASE_PROD }}
-          REDIS_URL: 'redis://localhost:6379'
+          # Explicitly use database 0 for production (test uses database 1)
+          REDIS_URL: 'redis://localhost:6379/0'
           REDIS_PASSWORD: ${{ secrets.REDIS_PASSWORD_PROD }}
           FRONTEND_URL: 'https://flyer-crawler.projectium.com'
           JWT_SECRET: ${{ secrets.JWT_SECRET }}
@@ -114,6 +146,15 @@ jobs:
           SMTP_USER: ''
           SMTP_PASS: ''
           SMTP_FROM_EMAIL: 'noreply@flyer-crawler.projectium.com'
+          # OAuth Providers
+          GOOGLE_CLIENT_ID: ${{ secrets.GOOGLE_CLIENT_ID }}
+          GOOGLE_CLIENT_SECRET: ${{ secrets.GOOGLE_CLIENT_SECRET }}
+          GITHUB_CLIENT_ID: ${{ secrets.GH_CLIENT_ID }}
+          GITHUB_CLIENT_SECRET: ${{ secrets.GH_CLIENT_SECRET }}
+          # Sentry/Bugsink Error Tracking (ADR-015)
+          SENTRY_DSN: ${{ secrets.SENTRY_DSN }}
+          SENTRY_ENVIRONMENT: 'production'
+          SENTRY_ENABLED: 'true'
         run: |
           if [ -z "$DB_HOST" ] || [ -z "$DB_USER" ] || [ -z "$DB_PASSWORD" ] || [ -z "$DB_NAME" ]; then
             echo "ERROR: One or more production database secrets (DB_HOST, DB_USER, DB_PASSWORD, DB_DATABASE_PROD) are not set."
@@ -123,6 +164,10 @@ jobs:
           cd /var/www/flyer-crawler.projectium.com
           npm install --omit=dev
 
+          # --- Cleanup Errored Processes ---
+          echo "Cleaning up errored or stopped PM2 processes..."
+          node -e "const exec = require('child_process').execSync; try { const list = JSON.parse(exec('pm2 jlist').toString()); list.forEach(p => { if (p.pm2_env.status === 'errored' || p.pm2_env.status === 'stopped') { console.log('Deleting ' + p.pm2_env.status + ' process: ' + p.name + ' (' + p.pm2_env.pm_id + ')'); try { exec('pm2 delete ' + p.pm2_env.pm_id); } catch(e) { console.error('Failed to delete ' + p.pm2_env.pm_id); } } }); } catch (e) { console.error('Error cleaning up processes:', e); }"
+
           # --- Version Check Logic ---
           # Get the version from the newly deployed package.json
           NEW_VERSION=$(node -p "require('./package.json').version")
@@ -139,7 +184,7 @@ jobs:
             else
               echo "Version mismatch (Running: $RUNNING_VERSION -> Deployed: $NEW_VERSION) or app not running. Reloading PM2..."
             fi
-            pm2 startOrReload ecosystem.config.cjs --env production && pm2 save
+            pm2 startOrReload ecosystem.config.cjs --update-env && pm2 save
             echo "Production backend server reloaded successfully."
           else
             echo "Version $NEW_VERSION is already running. Skipping PM2 reload."
@@ -148,7 +193,12 @@ jobs:
           echo "Updating schema hash in production database..."
           CURRENT_HASH=$(cat sql/master_schema_rollup.sql | dos2unix | sha256sum | awk '{ print $1 }')
           PGPASSWORD="$DB_PASSWORD" psql -v ON_ERROR_STOP=1 -h "$DB_HOST" -p 5432 -U "$DB_USER" -d "$DB_NAME" -c \
-          "INSERT INTO public.schema_info (environment, schema_hash, deployed_at) VALUES ('production', '$CURRENT_HASH', NOW())
+          "CREATE TABLE IF NOT EXISTS public.schema_info (
+            environment VARCHAR(50) PRIMARY KEY,
+            schema_hash VARCHAR(64) NOT NULL,
+            deployed_at TIMESTAMP DEFAULT NOW()
+          );
+          INSERT INTO public.schema_info (environment, schema_hash, deployed_at) VALUES ('production', '$CURRENT_HASH', NOW())
            ON CONFLICT (environment) DO UPDATE SET schema_hash = EXCLUDED.schema_hash, deployed_at = NOW();"
 
           UPDATED_HASH=$(PGPASSWORD="$DB_PASSWORD" psql -v ON_ERROR_STOP=1 -h "$DB_HOST" -p 5432 -U "$DB_USER" -d "$DB_NAME" -c "SELECT schema_hash FROM public.schema_info WHERE environment = 'production';" -t -A)
@@ -161,7 +211,17 @@ jobs:
       - name: Show PM2 Environment for Production
         run: |
           echo "--- Displaying recent PM2 logs for flyer-crawler-api ---"
-          sleep 5
-          pm2 describe flyer-crawler-api || echo "Could not find production pm2 process."
-          pm2 logs flyer-crawler-api --lines 20 --nostream || echo "Could not find production pm2 process."
-          pm2 env flyer-crawler-api || echo "Could not find production pm2 process."
+          sleep 5 # Wait a few seconds for the app to start and log its output.
+
+          # Resolve the PM2 ID dynamically to ensure we target the correct process
+          PM2_ID=$(pm2 jlist | node -e "try { const list = JSON.parse(require('fs').readFileSync(0, 'utf-8')); const app = list.find(p => p.name === 'flyer-crawler-api'); console.log(app ? app.pm2_env.pm_id : ''); } catch(e) { console.log(''); }")
+
+          if [ -n "$PM2_ID" ]; then
+            echo "Found process ID: $PM2_ID"
+            pm2 describe "$PM2_ID" || echo "Failed to describe process $PM2_ID"
+            pm2 logs "$PM2_ID" --lines 20 --nostream || echo "Failed to get logs for $PM2_ID"
+            pm2 env "$PM2_ID" || echo "Failed to get env for $PM2_ID"
+          else
+            echo "Could not find process 'flyer-crawler-api' in pm2 list."
+            pm2 list # Fallback to listing everything to help debug
+          fi

.gitea/workflows/deploy-to-test.yml

@@ -51,7 +51,14 @@ jobs:
 
           # Bump the patch version number. This creates a new commit and a new tag.
           # The commit message includes [skip ci] to prevent this push from triggering another workflow run.
-          npm version patch -m "ci: Bump version to %s [skip ci]"
+          # If the tag already exists (e.g. re-running a failed job), we skip the conflicting version.
+          if ! npm version patch -m "ci: Bump version to %s [skip ci]"; then
+            echo "⚠️ Version bump failed (likely tag exists). Attempting to skip to next version..."
+            # Bump package.json to the conflicting version without git tagging
+            npm version patch --no-git-tag-version > /dev/null
+            # Bump again to the next version, forcing it because the directory is now dirty
+            npm version patch -m "ci: Bump version to %s [skip ci]" --force
+          fi
 
           # Push the new commit and the new tag back to the main branch.
           git push --follow-tags
@@ -83,10 +90,29 @@ jobs:
         # integration test suite can launch its own, fresh server instance.
         # '|| true' ensures the workflow doesn't fail if the process isn't running.
         run: |
-          pm2 stop flyer-crawler-api-test || true
-          pm2 stop flyer-crawler-worker-test || true
-          pm2 delete flyer-crawler-api-test || true
-          pm2 delete flyer-crawler-worker-test || true
+          echo "--- Stopping and deleting all test processes ---"
+          # Use a script to parse pm2's JSON output and delete any process whose name ends with '-test'.
+          # This is safer than 'pm2 delete all' and more robust than naming each process individually.
+          # It prevents the accumulation of duplicate processes from previous test runs.
+          node -e "const exec = require('child_process').execSync; try { const list = JSON.parse(exec('pm2 jlist').toString()); list.forEach(p => { if (p.name && p.name.endsWith('-test')) { console.log('Deleting test process: ' + p.name + ' (' + p.pm2_env.pm_id + ')'); try { exec('pm2 delete ' + p.pm2_env.pm_id); } catch(e) { console.error('Failed to delete ' + p.pm2_env.pm_id, e.message); } } }); console.log('✅ Test process cleanup complete.'); } catch (e) { if (e.stdout.toString().includes('No process found')) { console.log('No PM2 processes running, cleanup not needed.'); } else { console.error('Error cleaning up test processes:', e.message); } }" || true
+
+      - name: Flush Redis Test Database Before Tests
+        # CRITICAL: Clear Redis database 1 (test database) to remove stale BullMQ jobs.
+        # This prevents old jobs with outdated error messages from polluting test results.
+        # NOTE: We use database 1 for tests to isolate from production (database 0).
+        env:
+          REDIS_PASSWORD: ${{ secrets.REDIS_PASSWORD_TEST }}
+        run: |
+          echo "--- Flushing Redis database 1 (test database) to remove stale jobs ---"
+          if [ -z "$REDIS_PASSWORD" ]; then
+            echo "⚠️ REDIS_PASSWORD_TEST not set, attempting flush without password..."
+            redis-cli -n 1 FLUSHDB || echo "Redis flush failed (no password)"
+          else
+            redis-cli -a "$REDIS_PASSWORD" -n 1 FLUSHDB 2>/dev/null && echo "✅ Redis database 1 (test) flushed successfully." || echo "⚠️ Redis flush failed"
+          fi
+          # Verify the flush worked by checking key count on database 1
+          KEY_COUNT=$(redis-cli -a "$REDIS_PASSWORD" -n 1 DBSIZE 2>/dev/null | grep -oE '[0-9]+' || echo "unknown")
+          echo "Redis database 1 key count after flush: $KEY_COUNT"
 
       - name: Run All Tests and Generate Merged Coverage Report
         # This single step runs both unit and integration tests, then merges their
@@ -95,26 +121,41 @@ jobs:
         env:
           # --- Database credentials for the test suite ---
           # These are injected from Gitea secrets into the runner's environment.
+          # CRITICAL: Use TEST-specific credentials that have CREATE privileges on the public schema.
           DB_HOST: ${{ secrets.DB_HOST }}
-          DB_USER: ${{ secrets.DB_USER }}
-          DB_PASSWORD: ${{ secrets.DB_PASSWORD }}
-          DB_NAME: 'flyer-crawler-test' # Explicitly set for tests
+          DB_USER: ${{ secrets.DB_USER_TEST }}
+          DB_PASSWORD: ${{ secrets.DB_PASSWORD_TEST }}
+          DB_NAME: ${{ secrets.DB_DATABASE_TEST }}
 
           # --- Redis credentials for the test suite ---
-          REDIS_URL: 'redis://localhost:6379'
+          # CRITICAL: Use Redis database 1 to isolate tests from production (which uses db 0).
+          # This prevents the production worker from picking up test jobs.
+          REDIS_URL: 'redis://localhost:6379/1'
           REDIS_PASSWORD: ${{ secrets.REDIS_PASSWORD_TEST }}
 
           # --- Integration test specific variables ---
-          FRONTEND_URL: 'http://localhost:3000'
+          FRONTEND_URL: 'https://example.com'
           VITE_API_BASE_URL: 'http://localhost:3001/api'
           GEMINI_API_KEY: ${{ secrets.VITE_GOOGLE_GENAI_API_KEY }}
 
+          # --- Storage path for flyer images ---
+          # CRITICAL: Use an absolute path in the test runner's working directory for file storage.
+          # This ensures tests can read processed files to verify their contents (e.g., EXIF stripping).
+          # Without this, multer and flyerProcessingService default to /var/www/.../flyer-images.
+          # NOTE: We use ${{ github.workspace }} which resolves to the checkout directory.
+          STORAGE_PATH: '${{ github.workspace }}/flyer-images'
+
           # --- JWT Secret for Passport authentication in tests ---
           JWT_SECRET: ${{ secrets.JWT_SECRET }}
 
+          # --- V8 Coverage for Server Process ---
+          # This variable tells the Node.js process (our server, started by globalSetup)
+          # where to output its raw V8 coverage data.
+          NODE_V8_COVERAGE: '.coverage/tmp/integration-server'
+
           # --- Increase Node.js memory limit to prevent heap out of memory errors ---
           # This is crucial for memory-intensive tasks like running tests and coverage.
-          NODE_OPTIONS: '--max-old-space-size=8192'
+          NODE_OPTIONS: '--max-old-space-size=8192 --trace-warnings --unhandled-rejections=strict'
 
         run: |
           # Fail-fast check to ensure secrets are configured in Gitea for testing.
@@ -129,10 +170,49 @@ jobs:
           # Run unit and integration tests as separate steps.
           # The `|| true` ensures the workflow continues even if tests fail, allowing coverage to run.
           echo "--- Running Unit Tests ---"
-          npm run test:unit -- --coverage --reporter=verbose --includeTaskLocation --testTimeout=10000 --silent=passed-only || true
+          # npm run test:unit -- --coverage --reporter=verbose --includeTaskLocation --testTimeout=10000 --silent=passed-only || true
+          npm run test:unit -- --coverage \
+            --coverage.exclude='**/*.test.ts' \
+            --coverage.exclude='**/tests/**' \
+            --coverage.exclude='**/mocks/**' \
+            --coverage.exclude='src/components/icons/**' \
+            --coverage.exclude='src/db/**' \
+            --coverage.exclude='src/lib/**' \
+            --coverage.exclude='src/types/**' \
+            --coverage.exclude='**/index.tsx' \
+            --coverage.exclude='**/vite-env.d.ts' \
+            --coverage.exclude='**/vitest.setup.ts' \
+            --reporter=verbose --includeTaskLocation --testTimeout=10000 --silent=passed-only --no-file-parallelism || true
 
           echo "--- Running Integration Tests ---"
-          npm run test:integration -- --coverage --reporter=verbose --includeTaskLocation --testTimeout=10000 --silent=passed-only || true
+          npm run test:integration -- --coverage \
+            --coverage.exclude='**/*.test.ts' \
+            --coverage.exclude='**/tests/**' \
+            --coverage.exclude='**/mocks/**' \
+            --coverage.exclude='src/components/icons/**' \
+            --coverage.exclude='src/db/**' \
+            --coverage.exclude='src/lib/**' \
+            --coverage.exclude='src/types/**' \
+            --coverage.exclude='**/index.tsx' \
+            --coverage.exclude='**/vite-env.d.ts' \
+            --coverage.exclude='**/vitest.setup.ts' \
+            --reporter=verbose --includeTaskLocation --testTimeout=10000 --silent=passed-only || true
+
+          echo "--- Running E2E Tests ---"
+          # Run E2E tests using the dedicated E2E config.
+          # E2E uses port 3098, integration uses 3099 to avoid conflicts.
+          npx vitest run --config vitest.config.e2e.ts --coverage \
+            --coverage.exclude='**/*.test.ts' \
+            --coverage.exclude='**/tests/**' \
+            --coverage.exclude='**/mocks/**' \
+            --coverage.exclude='src/components/icons/**' \
+            --coverage.exclude='src/db/**' \
+            --coverage.exclude='src/lib/**' \
+            --coverage.exclude='src/types/**' \
+            --coverage.exclude='**/index.tsx' \
+            --coverage.exclude='**/vite-env.d.ts' \
+            --coverage.exclude='**/vitest.setup.ts' \
+            --reporter=verbose --no-file-parallelism || true
 
           # Re-enable secret masking for subsequent steps.
           echo "::secret-masking::"
@@ -148,6 +228,7 @@ jobs:
           echo "Checking for source coverage files..."
           ls -l .coverage/unit/coverage-final.json
           ls -l .coverage/integration/coverage-final.json
+          ls -l .coverage/e2e/coverage-final.json || echo "E2E coverage file not found"
 
           # --- V8 Coverage Processing for Backend Server ---
           # The integration tests start the server, which generates raw V8 coverage data.
@@ -160,7 +241,19 @@ jobs:
           # Run c8: read raw files from the temp dir, and output an Istanbul JSON report.
           # We only generate the 'json' report here because it's all nyc needs for merging.
           echo "Server coverage report about to be generated..."
-          npx c8 report --reporter=json --temp-directory .coverage/tmp/integration-server --reports-dir .coverage/integration-server
+          npx c8 report \
+            --include='src/**' \
+            --exclude='**/*.test.ts' \
+            --exclude='**/*.test.tsx' \
+            --exclude='**/tests/**' \
+            --exclude='**/mocks/**' \
+            --exclude='hostexecutor/**' \
+            --exclude='scripts/**' \
+            --exclude='*.config.js' \
+            --exclude='*.config.ts' \
+            --reporter=json \
+            --temp-directory .coverage/tmp/integration-server \
+            --reports-dir .coverage/integration-server
           echo "Server coverage report generated. Verifying existence:"
           ls -l .coverage/integration-server/coverage-final.json
 
@@ -179,6 +272,7 @@ jobs:
           # We give them unique names to be safe, though it's not strictly necessary.
           cp .coverage/unit/coverage-final.json "$NYC_SOURCE_DIR/unit-coverage.json"
           cp .coverage/integration/coverage-final.json "$NYC_SOURCE_DIR/integration-coverage.json"
+          cp .coverage/e2e/coverage-final.json "$NYC_SOURCE_DIR/e2e-coverage.json" || echo "E2E coverage file not found, skipping."
           # This file might not exist if integration tests fail early, so we add `|| true`
           cp .coverage/integration-server/coverage-final.json "$NYC_SOURCE_DIR/integration-server-coverage.json" || echo "Server coverage file not found, skipping."
           echo "Copied coverage files to source directory. Contents:"
@@ -198,7 +292,19 @@ jobs:
             --reporter=text \
             --reporter=html \
             --report-dir .coverage/ \
-            --temp-dir "$NYC_SOURCE_DIR"
+            --temp-dir "$NYC_SOURCE_DIR" \
+            --include "src/**" \
+            --exclude "**/*.test.ts" \
+            --exclude "**/*.test.tsx" \
+            --exclude "**/tests/**" \
+            --exclude "**/mocks/**" \
+            --exclude "**/index.tsx" \
+            --exclude "**/vite-env.d.ts" \
+            --exclude "**/vitest.setup.ts" \
+            --exclude "hostexecutor/**" \
+            --exclude "scripts/**" \
+            --exclude "*.config.js" \
+            --exclude "*.config.ts"
 
           # Re-enable secret masking for subsequent steps.
           echo "::secret-masking::"
@@ -211,16 +317,6 @@ jobs:
         if: always() # This step runs even if the previous test or coverage steps failed.
         run: echo "Skipping test artifact cleanup on runner; this is handled on the server."
 
-      - name: Deploy Coverage Report to Public URL
-        if: always()
-        run: |
-          TARGET_DIR="/var/www/flyer-crawler-test.projectium.com/coverage"
-          echo "Deploying HTML coverage report to $TARGET_DIR..."
-          mkdir -p "$TARGET_DIR"
-          rm -rf "$TARGET_DIR"/*
-          cp -r .coverage/* "$TARGET_DIR/"
-          echo "✅ Coverage report deployed to https://flyer-crawler-test.projectium.com/coverage"
-
       - name: Archive Code Coverage Report
         # This action saves the generated HTML coverage report as a downloadable artifact.
         uses: actions/upload-artifact@v3
@@ -233,10 +329,11 @@ jobs:
       - name: Check for Test Database Schema Changes
         env:
           # Use test database credentials for this check.
+          # CRITICAL: Use TEST-specific credentials that have CREATE privileges on the public schema.
           DB_HOST: ${{ secrets.DB_HOST }}
-          DB_USER: ${{ secrets.DB_USER }}
-          DB_PASSWORD: ${{ secrets.DB_PASSWORD }} # This is used by psql
-          DB_NAME: ${{ secrets.DB_DATABASE_TEST }} # This is used by the application
+          DB_USER: ${{ secrets.DB_USER_TEST }}
+          DB_PASSWORD: ${{ secrets.DB_PASSWORD_TEST }}
+          DB_NAME: ${{ secrets.DB_DATABASE_TEST }}
         run: |
           # Fail-fast check to ensure secrets are configured in Gitea.
           if [ -z "$DB_HOST" ] || [ -z "$DB_USER" ] || [ -z "$DB_PASSWORD" ] || [ -z "$DB_NAME" ]; then
@@ -249,18 +346,19 @@ jobs:
           # We normalize line endings to ensure the hash is consistent across different OS environments.
           CURRENT_HASH=$(cat sql/master_schema_rollup.sql | dos2unix | sha256sum | awk '{ print $1 }')
           echo "Current Git Schema Hash: $CURRENT_HASH"
-
           # Query the production database to get the hash of the deployed schema.
           # The `psql` command requires PGPASSWORD to be set.
           # `\t` sets tuples-only mode and `\A` unaligns output to get just the raw value.
-          # The `|| echo "none"` ensures the command doesn't fail if the table or row doesn't exist yet.          
-          DEPLOYED_HASH=$(PGPASSWORD="$DB_PASSWORD" psql -v ON_ERROR_STOP=1 -h "$DB_HOST" -p 5432 -U "$DB_USER" -d "$DB_NAME" -c "SELECT schema_hash FROM public.schema_info WHERE environment = 'test';" -t -A || echo "none")
+          # The psql command will now fail the step if the query errors (e.g., column missing), preventing deployment on a bad schema.
+          DEPLOYED_HASH=$(PGPASSWORD="$DB_PASSWORD" psql -v ON_ERROR_STOP=1 -h "$DB_HOST" -p 5432 -U "$DB_USER" -d "$DB_NAME" -c "SELECT schema_hash FROM public.schema_info WHERE environment = 'test';" -t -A)
           echo "Deployed DB Schema Hash: $DEPLOYED_HASH"
-
           # Check if the hash is "none" (command failed) OR if it's an empty string (table exists but is empty).
-          if [ "$DEPLOYED_HASH" = "none" ] || [ -z "$DEPLOYED_HASH" ]; then
+          if [ -z "$DEPLOYED_HASH" ]; then
             echo "WARNING: No schema hash found in the test database."
             echo "This is expected for a first-time deployment. The hash will be set after a successful deployment."
+            echo "--- Debug: Dumping schema_info table ---"
+            PGPASSWORD="$DB_PASSWORD" psql -v ON_ERROR_STOP=0 -h "$DB_HOST" -p 5432 -U "$DB_USER" -d "$DB_NAME" -P pager=off -c "SELECT * FROM public.schema_info;" || true
+            echo "----------------------------------------"
             # We allow the deployment to continue, but a manual schema update is required.
             # You could choose to fail here by adding `exit 1`.
           elif [ "$CURRENT_HASH" != "$DEPLOYED_HASH" ]; then
@@ -276,6 +374,11 @@ jobs:
         # We set the environment variable directly in the command line for this step.
         # This maps the Gitea secret to the environment variable the application expects.
         # We also generate and inject the application version, commit URL, and commit message.
+        #
+        # Source Maps (ADR-015): If SENTRY_AUTH_TOKEN is set, the @sentry/vite-plugin will:
+        # 1. Generate hidden source maps during build
+        # 2. Upload them to Bugsink for error de-minification
+        # 3. Delete the .map files after upload (so they're not publicly accessible)
         run: |
           # Fail-fast check for the build-time secret.
           if [ -z "${{ secrets.VITE_GOOGLE_GENAI_API_KEY }}" ]; then
@@ -283,11 +386,24 @@ jobs:
             exit 1
           fi
 
+          # Source map upload is optional - warn if not configured
+          if [ -z "${{ secrets.SENTRY_AUTH_TOKEN }}" ]; then
+            echo "WARNING: SENTRY_AUTH_TOKEN not set. Source maps will NOT be uploaded to Bugsink."
+            echo "         Errors will show minified stack traces. To fix, add SENTRY_AUTH_TOKEN to Gitea secrets."
+          fi
+
           GITEA_SERVER_URL="https://gitea.projectium.com" # Your Gitea instance URL
-          COMMIT_MESSAGE=$(git log -1 --pretty=%s)
-          VITE_APP_VERSION="$(date +'%Y%m%d-%H%M'):$(git rev-parse --short HEAD)" \
+          # Sanitize commit message to prevent shell injection or build breaks (removes quotes, backticks, backslashes, $)
+          COMMIT_MESSAGE=$(git log -1 --grep="\[skip ci\]" --invert-grep --pretty=%s | tr -d '"`\\$')
+          PACKAGE_VERSION=$(node -p "require('./package.json').version")
+          VITE_APP_VERSION="$(date +'%Y%m%d-%H%M'):$(git rev-parse --short HEAD):$PACKAGE_VERSION" \
           VITE_APP_COMMIT_URL="$GITEA_SERVER_URL/${{ gitea.repository }}/commit/${{ gitea.sha }}" \
           VITE_APP_COMMIT_MESSAGE="$COMMIT_MESSAGE" \
+          VITE_SENTRY_DSN="${{ secrets.VITE_SENTRY_DSN_TEST }}" \
+          VITE_SENTRY_ENVIRONMENT="test" \
+          VITE_SENTRY_ENABLED="true" \
+          SENTRY_AUTH_TOKEN="${{ secrets.SENTRY_AUTH_TOKEN }}" \
+          SENTRY_URL="https://bugsink.projectium.com" \
           VITE_API_BASE_URL="https://flyer-crawler-test.projectium.com/api" VITE_API_KEY=${{ secrets.VITE_GOOGLE_GENAI_API_KEY_TEST }} npm run build
 
       - name: Deploy Application to Test Server
@@ -308,6 +424,17 @@ jobs:
           rsync -avz dist/ "$APP_PATH"
           echo "Application deployment complete."
 
+      - name: Deploy Coverage Report to Public URL
+        if: always()
+        run: |
+          TARGET_DIR="/var/www/flyer-crawler-test.projectium.com/coverage"
+          echo "Deploying HTML coverage report to $TARGET_DIR..."
+          mkdir -p "$TARGET_DIR"
+          rm -rf "$TARGET_DIR"/*
+          # The merged nyc report is generated in the .coverage directory. We copy its contents.
+          cp -r .coverage/* "$TARGET_DIR/"
+          echo "✅ Coverage report deployed to https://flyer-crawler-test.projectium.com/coverage"
+
       - name: Install Backend Dependencies and Restart Test Server
         env:
           # --- Test Secrets Injection ---
@@ -315,18 +442,19 @@ jobs:
           # Your Node.js application will read these directly from `process.env`.
 
           # Database Credentials
+          # CRITICAL: Use TEST-specific credentials that have CREATE privileges on the public schema.
           DB_HOST: ${{ secrets.DB_HOST }}
-          DB_USER: ${{ secrets.DB_USER }}
-          DB_PASSWORD: ${{ secrets.DB_PASSWORD }}
+          DB_USER: ${{ secrets.DB_USER_TEST }}
+          DB_PASSWORD: ${{ secrets.DB_PASSWORD_TEST }}
           DB_NAME: ${{ secrets.DB_DATABASE_TEST }}
 
-          # Redis Credentials
-          REDIS_URL: 'redis://localhost:6379'
+          # Redis Credentials (use database 1 to isolate from production)
+          REDIS_URL: 'redis://localhost:6379/1'
           REDIS_PASSWORD: ${{ secrets.REDIS_PASSWORD_TEST }}
 
           # Application Secrets
-          FRONTEND_URL: 'https://flyer-crawler-test.projectium.com'
-          JWT_SECRET: ${{ secrets.JWT_SECRET_TEST }}
+          FRONTEND_URL: 'https://example.com'
+          JWT_SECRET: ${{ secrets.JWT_SECRET }}
           GEMINI_API_KEY: ${{ secrets.VITE_GOOGLE_GENAI_API_KEY_TEST }}
           GOOGLE_MAPS_API_KEY: ${{ secrets.GOOGLE_MAPS_API_KEY }}
 
@@ -337,21 +465,38 @@ jobs:
           SMTP_USER: '' # Using MailHog, no auth needed
           SMTP_PASS: '' # Using MailHog, no auth needed
           SMTP_FROM_EMAIL: 'noreply@flyer-crawler-test.projectium.com'
+          # Sentry/Bugsink Error Tracking (ADR-015)
+          SENTRY_DSN: ${{ secrets.SENTRY_DSN_TEST }}
+          SENTRY_ENVIRONMENT: 'test'
+          SENTRY_ENABLED: 'true'
 
         run: |
           # Fail-fast check to ensure secrets are configured in Gitea.
-          if [ -z "$DB_HOST" ] || [ -z "$DB_USER" ] || [ -z "$DB_PASSWORD" ] || [ -z "$DB_NAME" ]; then
-            echo "ERROR: One or more test database secrets (DB_HOST, DB_USER, DB_PASSWORD, DB_DATABASE_TEST) are not set in Gitea repository settings."
+          MISSING_SECRETS=""
+          if [ -z "$DB_HOST" ]; then MISSING_SECRETS="${MISSING_SECRETS} DB_HOST"; fi
+          if [ -z "$DB_USER" ]; then MISSING_SECRETS="${MISSING_SECRETS} DB_USER"; fi
+          if [ -z "$DB_PASSWORD" ]; then MISSING_SECRETS="${MISSING_SECRETS} DB_PASSWORD"; fi
+          if [ -z "$DB_NAME" ]; then MISSING_SECRETS="${MISSING_SECRETS} DB_NAME"; fi
+          if [ -z "$JWT_SECRET" ]; then MISSING_SECRETS="${MISSING_SECRETS} JWT_SECRET"; fi
+
+          if [ ! -z "$MISSING_SECRETS" ]; then
+            echo "ERROR: The following required secrets are missing in Gitea:${MISSING_SECRETS}"
             exit 1
           fi
 
           echo "Installing production dependencies and restarting test server..."
           cd /var/www/flyer-crawler-test.projectium.com
-          npm install --omit=dev # Install only production dependencies
-          # Use `startOrReload` with the ecosystem file. This is the standard, idempotent way to deploy.
-          # It will START the process if it's not running, or RELOAD it if it is.
+          npm install --omit=dev
+
+          # --- Cleanup Errored Processes ---
+          echo "Cleaning up errored or stopped PM2 processes..."
+          node -e "const exec = require('child_process').execSync; try { const list = JSON.parse(exec('pm2 jlist').toString()); list.forEach(p => { if (p.pm2_env.status === 'errored' || p.pm2_env.status === 'stopped') { console.log('Deleting ' + p.pm2_env.status + ' process: ' + p.name + ' (' + p.pm2_env.pm_id + ')'); try { exec('pm2 delete ' + p.pm2_env.pm_id); } catch(e) { console.error('Failed to delete ' + p.pm2_env.pm_id); } } }); } catch (e) { console.error('Error cleaning up processes:', e); }"
+
+          # Use `startOrReload` with the TEST ecosystem file. This starts test-specific processes
+          # (flyer-crawler-api-test, flyer-crawler-worker-test, flyer-crawler-analytics-worker-test)
+          # that run separately from production processes.
           # We also add `&& pm2 save` to persist the process list across server reboots.
-          pm2 startOrReload ecosystem.config.cjs --env test && pm2 save
+          pm2 startOrReload ecosystem-test.config.cjs --update-env && pm2 save
           echo "Test backend server reloaded successfully."
 
           # After a successful deployment, update the schema hash in the database.
@@ -359,7 +504,12 @@ jobs:
           echo "Updating schema hash in test database..."
           CURRENT_HASH=$(cat sql/master_schema_rollup.sql | dos2unix | sha256sum | awk '{ print $1 }')
           PGPASSWORD="$DB_PASSWORD" psql -v ON_ERROR_STOP=1 -h "$DB_HOST" -p 5432 -U "$DB_USER" -d "$DB_NAME" -c \
-          "INSERT INTO public.schema_info (environment, schema_hash, deployed_at) VALUES ('test', '$CURRENT_HASH', NOW())
+          "CREATE TABLE IF NOT EXISTS public.schema_info (
+            environment VARCHAR(50) PRIMARY KEY,
+            schema_hash VARCHAR(64) NOT NULL,
+            deployed_at TIMESTAMP DEFAULT NOW()
+          );
+          INSERT INTO public.schema_info (environment, schema_hash, deployed_at) VALUES ('test', '$CURRENT_HASH', NOW())
            ON CONFLICT (environment) DO UPDATE SET schema_hash = EXCLUDED.schema_hash, deployed_at = NOW();"
 
           # Verify the hash was updated
@@ -381,7 +531,17 @@ jobs:
         run: |
           echo "--- Displaying recent PM2 logs for flyer-crawler-api-test ---"
           # After a reload, the server restarts. We'll show the last 20 lines of the log to see the startup messages.
-          sleep 5 # Wait a few seconds for the app to start and log its output.
-          pm2 describe flyer-crawler-api-test || echo "Could not find test pm2 process."
-          pm2 logs flyer-crawler-api-test --lines 20 --nostream || echo "Could not find test pm2 process."
-          pm2 env flyer-crawler-api-test || echo "Could not find test pm2 process."
+          sleep 5
+
+          # Resolve the PM2 ID dynamically to ensure we target the correct process
+          PM2_ID=$(pm2 jlist | node -e "try { const list = JSON.parse(require('fs').readFileSync(0, 'utf-8')); const app = list.find(p => p.name === 'flyer-crawler-api-test'); console.log(app ? app.pm2_env.pm_id : ''); } catch(e) { console.log(''); }")
+
+          if [ -n "$PM2_ID" ]; then
+            echo "Found process ID: $PM2_ID"
+            pm2 describe "$PM2_ID" || echo "Failed to describe process $PM2_ID"
+            pm2 logs "$PM2_ID" --lines 20 --nostream || echo "Failed to get logs for $PM2_ID"
+            pm2 env "$PM2_ID" || echo "Failed to get env for $PM2_ID"
+          else
+            echo "Could not find process 'flyer-crawler-api-test' in pm2 list."
+            pm2 list # Fallback to listing everything to help debug
+          fi

.gitea/workflows/manual-db-backup.yml

@@ -20,9 +20,9 @@ jobs:
       # Use production database credentials for this entire job.
       DB_HOST: ${{ secrets.DB_HOST }}
       DB_PORT: ${{ secrets.DB_PORT }}
-      DB_USER: ${{ secrets.DB_USER }}
-      DB_PASSWORD: ${{ secrets.DB_PASSWORD }}
-      DB_NAME: ${{ secrets.DB_NAME_PROD }}
+      DB_USER: ${{ secrets.DB_USER_PROD }}
+      DB_PASSWORD: ${{ secrets.DB_PASSWORD_PROD }}
+      DB_NAME: ${{ secrets.DB_DATABASE_PROD }}
 
     steps:
       - name: Validate Secrets
@@ -60,4 +60,4 @@ jobs:
         uses: actions/upload-artifact@v3
         with:
           name: database-backup
-          path: ${{ env.backup_filename }}
+          path: ${{ env.backup_filename }}

.gitea/workflows/manual-db-reset-prod.yml

@@ -23,9 +23,9 @@ jobs:
     env:
       # Use production database credentials for this entire job.
       DB_HOST: ${{ secrets.DB_HOST }}
-      DB_USER: ${{ secrets.DB_USER }}
-      DB_PASSWORD: ${{ secrets.DB_PASSWORD }} # Used by psql
-      DB_NAME: ${{ secrets.DB_DATABASE_PROD }} # Used by the application
+      DB_USER: ${{ secrets.DB_USER_PROD }}
+      DB_PASSWORD: ${{ secrets.DB_PASSWORD_PROD }}
+      DB_NAME: ${{ secrets.DB_DATABASE_PROD }}
 
     steps:
       - name: Checkout Code
@@ -144,4 +144,4 @@ jobs:
           find "$APP_PATH/flyer-images" -type f -name '*-test-flyer-image.*' -delete
           find "$APP_PATH/flyer-images/icons" -type f -name '*-test-flyer-image.*' -delete
           find "$APP_PATH/flyer-images/archive" -mindepth 1 -maxdepth 1 -type f -delete || echo "Archive directory not found, skipping."
-          echo "✅ Flyer asset directories cleared."
+          echo "✅ Flyer asset directories cleared."

.gitea/workflows/manual-db-reset-test.yml

@@ -23,9 +23,9 @@ jobs:
     env:
       # Use test database credentials for this entire job.
       DB_HOST: ${{ secrets.DB_HOST }}
-      DB_USER: ${{ secrets.DB_USER }}
-      DB_PASSWORD: ${{ secrets.DB_PASSWORD }} # Used by psql
-      DB_NAME: ${{ secrets.DB_DATABASE_TEST }} # Used by the application
+      DB_USER: ${{ secrets.DB_USER_TEST }}
+      DB_PASSWORD: ${{ secrets.DB_PASSWORD_TEST }}
+      DB_NAME: ${{ secrets.DB_DATABASE_TEST }}
 
     steps:
       - name: Checkout Code
@@ -130,4 +130,4 @@ jobs:
           find "$APP_PATH/flyer-images" -mindepth 1 -type f -delete
           find "$APP_PATH/flyer-images/icons" -mindepth 1 -type f -delete
           find "$APP_PATH/flyer-images/archive" -mindepth 1 -type f -delete || echo "Archive directory not found, skipping."
-          echo "✅ Test flyer asset directories cleared."
+          echo "✅ Test flyer asset directories cleared."

.gitea/workflows/manual-db-restore.yml

@@ -22,10 +22,10 @@ jobs:
     env:
       # Use production database credentials for this entire job.
       DB_HOST: ${{ secrets.DB_HOST }}
-      DB_USER: ${{ secrets.DB_USER }}
-      DB_PASSWORD: ${{ secrets.DB_PASSWORD }}
+      DB_USER: ${{ secrets.DB_USER_PROD }}
+      DB_PASSWORD: ${{ secrets.DB_PASSWORD_PROD }}
       DB_NAME: ${{ secrets.DB_DATABASE_PROD }}
-      BACKUP_DIR: "/var/www/backups" # Define a dedicated directory for backups
+      BACKUP_DIR: '/var/www/backups' # Define a dedicated directory for backups
 
     steps:
       - name: Validate Secrets and Inputs
@@ -92,4 +92,4 @@ jobs:
           echo "Restarting application server..."
           cd /var/www/flyer-crawler.projectium.com
           pm2 startOrReload ecosystem.config.cjs --env production && pm2 save
-          echo "✅ Application server restarted."
+          echo "✅ Application server restarted."

.gitea/workflows/manual-deploy-major.yml

@@ -0,0 +1,186 @@
+# .gitea/workflows/manual-deploy-major.yml
+#
+# This workflow provides a MANUAL trigger to perform a MAJOR version bump
+# and deploy the application to the PRODUCTION environment.
+name: Manual - Deploy Major Version to Production
+
+on:
+  workflow_dispatch:
+    inputs:
+      confirmation:
+        description: 'Type "deploy-major-to-prod" to confirm you want to deploy a new major version.'
+        required: true
+        default: 'do-not-run'
+      force_reload:
+        description: 'Force PM2 reload even if version matches (true/false).'
+        required: false
+        type: boolean
+        default: false
+
+jobs:
+  deploy-production-major:
+    runs-on: projectium.com
+
+    steps:
+      - name: Verify Confirmation Phrase
+        run: |
+          if [ "${{ gitea.event.inputs.confirmation }}" != "deploy-major-to-prod" ]; then
+            echo "ERROR: Confirmation phrase did not match. Aborting deployment."
+            exit 1
+          fi
+          echo "✅ Confirmation accepted. Proceeding with major version production deployment."
+
+      - name: Checkout Code from 'main' branch
+        uses: actions/checkout@v3
+        with:
+          ref: 'main' # Explicitly check out the main branch for production deployment
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: '**/package-lock.json'
+
+      - name: Install Dependencies
+        run: npm ci
+
+      - name: Bump Major Version and Push
+        run: |
+          # Configure git for the commit.
+          git config --global user.name 'Gitea Actions'
+          git config --global user.email 'actions@gitea.projectium.com'
+
+          # Bump the major version number. This creates a new commit and a new tag.
+          # The commit message includes [skip ci] to prevent this push from triggering another workflow run.
+          npm version major -m "ci: Bump version to %s for major release [skip ci]"
+
+          # Push the new commit and the new tag back to the main branch.
+          git push --follow-tags
+
+      - name: Check for Production Database Schema Changes
+        env:
+          DB_HOST: ${{ secrets.DB_HOST }}
+          DB_USER: ${{ secrets.DB_USER_PROD }}
+          DB_PASSWORD: ${{ secrets.DB_PASSWORD_PROD }}
+          DB_NAME: ${{ secrets.DB_DATABASE_PROD }}
+        run: |
+          if [ -z "$DB_HOST" ] || [ -z "$DB_USER" ] || [ -z "$DB_PASSWORD" ] || [ -z "$DB_NAME" ]; then
+            echo "ERROR: One or more production database secrets (DB_HOST, DB_USER, DB_PASSWORD, DB_DATABASE_PROD) are not set."
+            exit 1
+          fi
+          echo "--- Checking for production schema changes ---"
+          CURRENT_HASH=$(cat sql/master_schema_rollup.sql | dos2unix | sha256sum | awk '{ print $1 }')
+          echo "Current Git Schema Hash: $CURRENT_HASH"
+          # The psql command will now fail the step if the query errors (e.g., column missing), preventing deployment on a bad schema.
+          DEPLOYED_HASH=$(PGPASSWORD="$DB_PASSWORD" psql -v ON_ERROR_STOP=1 -h "$DB_HOST" -p 5432 -U "$DB_USER" -d "$DB_NAME" -c "SELECT schema_hash FROM public.schema_info WHERE environment = 'production';" -t -A)
+          echo "Deployed DB Schema Hash: $DEPLOYED_HASH"
+          if [ -z "$DEPLOYED_HASH" ]; then
+            echo "WARNING: No schema hash found in the production database. This is expected for a first-time deployment."
+          elif [ "$CURRENT_HASH" != "$DEPLOYED_HASH" ]; then
+            echo "ERROR: Database schema mismatch detected! A manual database migration is required."
+            exit 1
+          else
+            echo "✅ Schema is up to date. No changes detected."
+          fi
+
+      - name: Build React Application for Production
+        run: |
+          if [ -z "${{ secrets.VITE_GOOGLE_GENAI_API_KEY }}" ]; then
+            echo "ERROR: The VITE_GOOGLE_GENAI_API_KEY secret is not set."
+            exit 1
+          fi
+          GITEA_SERVER_URL="https://gitea.projectium.com"
+          COMMIT_MESSAGE=$(git log -1 --grep="\[skip ci\]" --invert-grep --pretty=%s)
+          PACKAGE_VERSION=$(node -p "require('./package.json').version")
+          VITE_APP_VERSION="$(date +'%Y%m%d-%H%M'):$(git rev-parse --short HEAD):$PACKAGE_VERSION" \
+          VITE_APP_COMMIT_URL="$GITEA_SERVER_URL/${{ gitea.repository }}/commit/${{ gitea.sha }}" \
+          VITE_APP_COMMIT_MESSAGE="$COMMIT_MESSAGE" \
+          VITE_API_BASE_URL=/api VITE_API_KEY=${{ secrets.VITE_GOOGLE_GENAI_API_KEY }} npm run build
+
+      - name: Deploy Application to Production Server
+        run: |
+          echo "Deploying application files to /var/www/flyer-crawler.projectium.com..."
+          APP_PATH="/var/www/flyer-crawler.projectium.com"
+          mkdir -p "$APP_PATH"
+          mkdir -p "$APP_PATH/flyer-images/icons" "$APP_PATH/flyer-images/archive"
+          rsync -avz --delete --exclude 'node_modules' --exclude '.git' --exclude 'dist' --exclude 'flyer-images' ./ "$APP_PATH/"
+          rsync -avz dist/ "$APP_PATH"
+          echo "Application deployment complete."
+
+      - name: Install Backend Dependencies and Restart Production Server
+        env:
+          # --- Production Secrets Injection ---
+          DB_HOST: ${{ secrets.DB_HOST }}
+          DB_USER: ${{ secrets.DB_USER_PROD }}
+          DB_PASSWORD: ${{ secrets.DB_PASSWORD_PROD }}
+          DB_NAME: ${{ secrets.DB_DATABASE_PROD }}
+          # Explicitly use database 0 for production (test uses database 1)
+          REDIS_URL: 'redis://localhost:6379/0'
+          REDIS_PASSWORD: ${{ secrets.REDIS_PASSWORD_PROD }}
+          FRONTEND_URL: 'https://flyer-crawler.projectium.com'
+          JWT_SECRET: ${{ secrets.JWT_SECRET }}
+          GEMINI_API_KEY: ${{ secrets.VITE_GOOGLE_GENAI_API_KEY }}
+          GOOGLE_MAPS_API_KEY: ${{ secrets.GOOGLE_MAPS_API_KEY }}
+          SMTP_HOST: 'localhost'
+          SMTP_PORT: '1025'
+          SMTP_SECURE: 'false'
+          SMTP_USER: ''
+          SMTP_PASS: ''
+          SMTP_FROM_EMAIL: 'noreply@flyer-crawler.projectium.com'
+        run: |
+          if [ -z "$DB_HOST" ] || [ -z "$DB_USER" ] || [ -z "$DB_PASSWORD" ] || [ -z "$DB_NAME" ]; then
+            echo "ERROR: One or more production database secrets (DB_HOST, DB_USER, DB_PASSWORD, DB_DATABASE_PROD) are not set."
+            exit 1
+          fi
+          echo "Installing production dependencies and restarting server..."
+          cd /var/www/flyer-crawler.projectium.com
+          npm install --omit=dev
+
+          # --- Cleanup Errored Processes ---
+          echo "Cleaning up errored or stopped PM2 processes..."
+          node -e "const exec = require('child_process').execSync; try { const list = JSON.parse(exec('pm2 jlist').toString()); list.forEach(p => { if (p.pm2_env.status === 'errored' || p.pm2_env.status === 'stopped') { console.log('Deleting ' + p.pm2_env.status + ' process: ' + p.name + ' (' + p.pm2_env.pm_id + ')'); try { exec('pm2 delete ' + p.pm2_env.pm_id); } catch(e) { console.error('Failed to delete ' + p.pm2_env.pm_id); } } }); } catch (e) { console.error('Error cleaning up processes:', e); }"
+
+          # --- Version Check Logic ---
+          # Get the version from the newly deployed package.json
+          NEW_VERSION=$(node -p "require('./package.json').version")
+          echo "Deployed Package Version: $NEW_VERSION"
+
+          # Get the running version from PM2 for the main API process
+          # We use a small node script to parse the JSON output from pm2 jlist
+          RUNNING_VERSION=$(pm2 jlist | node -e "try { const list = JSON.parse(require('fs').readFileSync(0, 'utf-8')); const app = list.find(p => p.name === 'flyer-crawler-api'); console.log(app ? app.pm2_env.version : ''); } catch(e) { console.log(''); }")
+          echo "Running PM2 Version: $RUNNING_VERSION"
+
+          if [ "${{ gitea.event.inputs.force_reload }}" == "true" ] || [ "$NEW_VERSION" != "$RUNNING_VERSION" ] || [ -z "$RUNNING_VERSION" ]; then
+            if [ "${{ gitea.event.inputs.force_reload }}" == "true" ]; then
+              echo "Force reload triggered by manual input. Reloading PM2..."
+            else
+              echo "Version mismatch (Running: $RUNNING_VERSION -> Deployed: $NEW_VERSION) or app not running. Reloading PM2..."
+            fi
+            pm2 startOrReload ecosystem.config.cjs --env production --update-env && pm2 save
+            echo "Production backend server reloaded successfully."
+          else
+            echo "Version $NEW_VERSION is already running. Skipping PM2 reload."
+          fi
+
+          echo "Updating schema hash in production database..."
+          CURRENT_HASH=$(cat sql/master_schema_rollup.sql | dos2unix | sha256sum | awk '{ print $1 }')
+          PGPASSWORD="$DB_PASSWORD" psql -v ON_ERROR_STOP=1 -h "$DB_HOST" -p 5432 -U "$DB_USER" -d "$DB_NAME" -c \
+          "INSERT INTO public.schema_info (environment, schema_hash, deployed_at) VALUES ('production', '$CURRENT_HASH', NOW())
+           ON CONFLICT (environment) DO UPDATE SET schema_hash = EXCLUDED.schema_hash, deployed_at = NOW();"
+
+          UPDATED_HASH=$(PGPASSWORD="$DB_PASSWORD" psql -v ON_ERROR_STOP=1 -h "$DB_HOST" -p 5432 -U "$DB_USER" -d "$DB_NAME" -c "SELECT schema_hash FROM public.schema_info WHERE environment = 'production';" -t -A)
+          if [ "$CURRENT_HASH" = "$UPDATED_HASH" ]; then
+            echo "✅ Schema hash successfully updated in the database to: $UPDATED_HASH"
+          else
+            echo "ERROR: Failed to update schema hash in the database."
+          fi
+
+      - name: Show PM2 Environment for Production
+        run: |
+          echo "--- Displaying recent PM2 logs for flyer-crawler-api ---"
+          sleep 5
+          pm2 describe flyer-crawler-api || echo "Could not find production pm2 process."
+          pm2 logs flyer-crawler-api --lines 20 --nostream || echo "Could not find production pm2 process."
+          pm2 env flyer-crawler-api || echo "Could not find production pm2 process."

.gitea/workflows/manual-redis-flush-prod.yml

@@ -0,0 +1,167 @@
+# .gitea/workflows/manual-redis-flush-prod.yml
+#
+# DANGER: This workflow is DESTRUCTIVE and intended for manual execution only.
+# It will completely FLUSH the PRODUCTION Redis database (db 0).
+# This will clear all BullMQ queues, sessions, caches, and any other Redis data.
+#
+name: Manual - Flush Production Redis
+
+on:
+  workflow_dispatch:
+    inputs:
+      confirmation:
+        description: 'DANGER: This will FLUSH production Redis. Type "flush-production-redis" to confirm.'
+        required: true
+        default: 'do-not-run'
+      flush_type:
+        description: 'What to flush?'
+        required: true
+        type: choice
+        options:
+          - 'queues-only'
+          - 'entire-database'
+        default: 'queues-only'
+
+jobs:
+  flush-redis:
+    runs-on: projectium.com # This job runs on your self-hosted Gitea runner.
+
+    env:
+      REDIS_PASSWORD: ${{ secrets.REDIS_PASSWORD_PROD }}
+
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v3
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: '**/package-lock.json'
+
+      - name: Install Dependencies
+        run: npm ci
+
+      - name: Validate Secrets
+        run: |
+          if [ -z "$REDIS_PASSWORD" ]; then
+            echo "ERROR: REDIS_PASSWORD_PROD secret is not set in Gitea repository settings."
+            exit 1
+          fi
+          echo "✅ Redis password secret is present."
+
+      - name: Verify Confirmation Phrase
+        run: |
+          if [ "${{ gitea.event.inputs.confirmation }}" != "flush-production-redis" ]; then
+            echo "ERROR: Confirmation phrase did not match. Aborting Redis flush."
+            exit 1
+          fi
+          echo "✅ Confirmation accepted. Proceeding with Redis flush."
+
+      - name: Show Current Redis State
+        run: |
+          echo "--- Current Redis Database 0 (Production) State ---"
+          redis-cli -a "$REDIS_PASSWORD" -n 0 INFO keyspace 2>/dev/null || echo "Could not get keyspace info"
+          echo ""
+          echo "--- Key Count ---"
+          KEY_COUNT=$(redis-cli -a "$REDIS_PASSWORD" -n 0 DBSIZE 2>/dev/null | grep -oE '[0-9]+' || echo "unknown")
+          echo "Production Redis (db 0) key count: $KEY_COUNT"
+          echo ""
+          echo "--- BullMQ Queue Keys ---"
+          redis-cli -a "$REDIS_PASSWORD" -n 0 KEYS "bull:*" 2>/dev/null | head -20 || echo "No BullMQ keys found"
+
+      - name: 🚨 FINAL WARNING & PAUSE 🚨
+        run: |
+          echo "*********************************************************************"
+          echo "WARNING: YOU ARE ABOUT TO FLUSH PRODUCTION REDIS DATA."
+          echo "Flush type: ${{ gitea.event.inputs.flush_type }}"
+          echo ""
+          if [ "${{ gitea.event.inputs.flush_type }}" = "entire-database" ]; then
+            echo "This will DELETE ALL Redis data including sessions, caches, and queues!"
+          else
+            echo "This will DELETE ALL BullMQ queue data (pending jobs, failed jobs, etc.)"
+          fi
+          echo ""
+          echo "This action is IRREVERSIBLE. Press Ctrl+C in the runner terminal NOW to cancel."
+          echo "Sleeping for 10 seconds..."
+          echo "*********************************************************************"
+          sleep 10
+
+      - name: Flush BullMQ Queues Only
+        if: ${{ gitea.event.inputs.flush_type == 'queues-only' }}
+        env:
+          REDIS_URL: 'redis://localhost:6379/0'
+        run: |
+          echo "--- Obliterating BullMQ queues using Node.js ---"
+          node -e "
+            const { Queue } = require('bullmq');
+            const IORedis = require('ioredis');
+
+            const connection = new IORedis(process.env.REDIS_URL, {
+              maxRetriesPerRequest: null,
+              password: process.env.REDIS_PASSWORD,
+            });
+
+            const queueNames = [
+              'flyer-processing',
+              'email-sending',
+              'analytics-reporting',
+              'weekly-analytics-reporting',
+              'file-cleanup',
+              'token-cleanup'
+            ];
+
+            (async () => {
+              for (const name of queueNames) {
+                try {
+                  const queue = new Queue(name, { connection });
+                  const counts = await queue.getJobCounts();
+                  console.log('Queue \"' + name + '\" before obliterate:', JSON.stringify(counts));
+                  await queue.obliterate({ force: true });
+                  console.log('✅ Obliterated queue: ' + name);
+                  await queue.close();
+                } catch (err) {
+                  console.error('⚠️ Failed to obliterate queue ' + name + ':', err.message);
+                }
+              }
+              await connection.quit();
+              console.log('✅ All BullMQ queues obliterated.');
+            })();
+          "
+
+      - name: Flush Entire Redis Database
+        if: ${{ gitea.event.inputs.flush_type == 'entire-database' }}
+        run: |
+          echo "--- Flushing entire Redis database 0 (production) ---"
+          redis-cli -a "$REDIS_PASSWORD" -n 0 FLUSHDB 2>/dev/null && echo "✅ Redis database 0 flushed successfully." || echo "❌ Redis flush failed"
+
+      - name: Verify Flush Results
+        run: |
+          echo "--- Redis Database 0 (Production) State After Flush ---"
+          KEY_COUNT=$(redis-cli -a "$REDIS_PASSWORD" -n 0 DBSIZE 2>/dev/null | grep -oE '[0-9]+' || echo "unknown")
+          echo "Production Redis (db 0) key count after flush: $KEY_COUNT"
+          echo ""
+          echo "--- Remaining BullMQ Queue Keys ---"
+          BULL_KEYS=$(redis-cli -a "$REDIS_PASSWORD" -n 0 KEYS "bull:*" 2>/dev/null | wc -l || echo "0")
+          echo "BullMQ key count: $BULL_KEYS"
+
+          if [ "${{ gitea.event.inputs.flush_type }}" = "queues-only" ] && [ "$BULL_KEYS" -gt 0 ]; then
+            echo "⚠️ Warning: Some BullMQ keys may still exist. This can happen if new jobs were added during the flush."
+          fi
+
+      - name: Summary
+        run: |
+          echo ""
+          echo "=========================================="
+          echo "PRODUCTION REDIS FLUSH COMPLETE"
+          echo "=========================================="
+          echo "Flush type: ${{ gitea.event.inputs.flush_type }}"
+          echo "Timestamp: $(date -u '+%Y-%m-%d %H:%M:%S UTC')"
+          echo ""
+          echo "NOTE: If you flushed queues, any pending jobs (flyer processing,"
+          echo "emails, analytics, etc.) have been permanently deleted."
+          echo ""
+          echo "The production workers will automatically start processing"
+          echo "new jobs as they are added to the queues."
+          echo "=========================================="

.gitignore

@@ -11,6 +11,18 @@ node_modules
 dist
 dist-ssr
 *.local
+.env
+*.tsbuildinfo
+
+# Test coverage
+coverage
+.nyc_output
+.coverage
+
+# Test artifacts - flyer-images/ is a runtime directory
+# Test fixtures are stored in src/tests/assets/ instead
+flyer-images/
+test-output.txt
 
 # Editor directories and files
 .vscode/*
@@ -22,3 +34,7 @@ dist-ssr
 *.njsproj
 *.sln
 *.sw?
+Thumbs.db
+.claude
+nul
+tmpclaude*

.husky/pre-commit

@@ -0,0 +1 @@
+npx lint-staged

.lintstagedrc.json

@@ -0,0 +1,4 @@
+{
+  "*.{js,jsx,ts,tsx}": ["eslint --fix", "prettier --write"],
+  "*.{json,md,css,html,yml,yaml}": ["prettier --write"]
+}

.nycrc.json

@@ -0,0 +1,5 @@
+{
+  "text": {
+    "maxCols": 200
+  }
+}

.prettierignore

@@ -0,0 +1,41 @@
+# Dependencies
+node_modules/
+
+# Build output
+dist/
+build/
+.cache/
+
+# Coverage reports
+coverage/
+.coverage/
+
+# IDE and editor configs
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Logs
+*.log
+logs/
+
+# Environment files (may contain secrets)
+.env*
+!.env.example
+
+# Lock files (managed by package managers)
+package-lock.json
+pnpm-lock.yaml
+yarn.lock
+
+# Generated files
+*.min.js
+*.min.css
+
+# Git directory
+.git/
+.gitea/
+
+# Test artifacts
+__snapshots__/

.prettierrc

@@ -6,4 +6,4 @@
   "tabWidth": 2,
   "useTabs": false,
   "endOfLine": "auto"
-}
+}

AUTHENTICATION.md

@@ -0,0 +1,110 @@
+# Authentication Setup
+
+Flyer Crawler supports OAuth authentication via Google and GitHub. This guide walks through configuring both providers.
+
+---
+
+## Google OAuth
+
+### Step 1: Create OAuth Credentials
+
+1. Go to the [Google Cloud Console](https://console.cloud.google.com/)
+2. Create a new project (or select an existing one)
+3. Navigate to **APIs & Services > Credentials**
+4. Click **Create Credentials > OAuth client ID**
+5. Select **Web application** as the application type
+
+### Step 2: Configure Authorized Redirect URIs
+
+Add the callback URL where Google will redirect users after authentication:
+
+| Environment | Redirect URI                                       |
+| ----------- | -------------------------------------------------- |
+| Development | `http://localhost:3001/api/auth/google/callback`   |
+| Production  | `https://your-domain.com/api/auth/google/callback` |
+
+### Step 3: Save Credentials
+
+After clicking **Create**, you'll receive:
+
+- **Client ID**
+- **Client Secret**
+
+Store these securely as environment variables:
+
+- `GOOGLE_CLIENT_ID`
+- `GOOGLE_CLIENT_SECRET`
+
+---
+
+## GitHub OAuth
+
+### Step 1: Create OAuth App
+
+1. Go to your [GitHub Developer Settings](https://github.com/settings/developers)
+2. Navigate to **OAuth Apps**
+3. Click **New OAuth App**
+
+### Step 2: Fill in Application Details
+
+| Field                      | Value                                                |
+| -------------------------- | ---------------------------------------------------- |
+| Application name           | Flyer Crawler (or your preferred name)               |
+| Homepage URL               | `http://localhost:5173` (dev) or your production URL |
+| Authorization callback URL | `http://localhost:3001/api/auth/github/callback`     |
+
+### Step 3: Save GitHub Credentials
+
+After clicking **Register application**, you'll receive:
+
+- **Client ID**
+- **Client Secret**
+
+Store these securely as environment variables:
+
+- `GITHUB_CLIENT_ID`
+- `GITHUB_CLIENT_SECRET`
+
+---
+
+## Environment Variables Summary
+
+| Variable               | Description                              |
+| ---------------------- | ---------------------------------------- |
+| `GOOGLE_CLIENT_ID`     | Google OAuth client ID                   |
+| `GOOGLE_CLIENT_SECRET` | Google OAuth client secret               |
+| `GITHUB_CLIENT_ID`     | GitHub OAuth client ID                   |
+| `GITHUB_CLIENT_SECRET` | GitHub OAuth client secret               |
+| `JWT_SECRET`           | Secret for signing authentication tokens |
+
+---
+
+## Production Considerations
+
+When deploying to production:
+
+1. **Update redirect URIs** in both Google Cloud Console and GitHub OAuth settings to use your production domain
+2. **Use HTTPS** for all callback URLs in production
+3. **Store secrets securely** using your CI/CD platform's secrets management (e.g., Gitea repository secrets)
+
+---
+
+## Troubleshooting
+
+### "redirect_uri_mismatch" Error
+
+The callback URL in your OAuth provider settings doesn't match what the application is sending. Verify:
+
+- The URL is exactly correct (no trailing slashes, correct port)
+- You're using the right environment (dev vs production URLs)
+
+### "invalid_client" Error
+
+The Client ID or Client Secret is incorrect. Double-check your environment variables.
+
+---
+
+## Related Documentation
+
+- [Installation Guide](INSTALL.md) - Local development setup
+- [Deployment Guide](DEPLOYMENT.md) - Production deployment