ci: Bump version to 0.9.18 [skip ci]

test fixes
ci: Bump version to 0.9.17 [skip ci]
2026-01-04 15:22:37 +05:00 · 2026-01-04 02:21:08 -08:00 · 2026-01-04 09:02:18 +05:00 · 2026-01-03 20:01:10 -08:00 · 2026-01-04 05:05:33 +05:00 · 2026-01-03 16:04:04 -08:00
146 changed files with 7750 additions and 2906 deletions
--- a/ecosystem.config.cjs
+++ b/ecosystem.config.cjs
@@ -52,6 +52,7 @@ module.exports = {
        SMTP_USER: process.env.SMTP_USER,
        SMTP_PASS: process.env.SMTP_PASS,
        SMTP_FROM_EMAIL: process.env.SMTP_FROM_EMAIL,
        WORKER_LOCK_DURATION: '120000',
      },
      // Test Environment Settings
      env_test: {
@@ -74,6 +75,7 @@ module.exports = {
        SMTP_USER: process.env.SMTP_USER,
        SMTP_PASS: process.env.SMTP_PASS,
        SMTP_FROM_EMAIL: process.env.SMTP_FROM_EMAIL,
        WORKER_LOCK_DURATION: '120000',
      },
      // Development Environment Settings
      env_development: {
@@ -97,6 +99,7 @@ module.exports = {
        SMTP_USER: process.env.SMTP_USER,
        SMTP_PASS: process.env.SMTP_PASS,
        SMTP_FROM_EMAIL: process.env.SMTP_FROM_EMAIL,
        WORKER_LOCK_DURATION: '120000',
      },
    },
    {
--- a/notes-to-ai4.txt
+++ b/notes-to-ai4.txt
@@ -13,6 +13,15 @@ RULES:
 latest refacter
 Refactor `RecipeSuggester.test.tsx` to use `renderWithProviders`.
 Create a new test file for `StatCard.tsx` to verify its props and rendering.
 while assuming that master_schema_rollup.sql is the "ultimate source of truth", issues can happen and it may not have been properly 
 updated - look for differences between these files
 UPC SCANNING !
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
  "name": "flyer-crawler",
-  "version": "0.7.1",
+  "version": "0.9.18",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "flyer-crawler",
-      "version": "0.7.1",
+      "version": "0.9.18",
      "dependencies": {
        "@bull-board/api": "^6.14.2",
        "@bull-board/express": "^6.14.2",
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
 {
  "name": "flyer-crawler",
  "private": true,
-  "version": "0.7.1",
+  "version": "0.9.18",
  "type": "module",
  "scripts": {
    "dev": "concurrently \"npm:start:dev\" \"vite\"",
--- a/sql/Initial_triggers_and_functions.sql
+++ b/sql/Initial_triggers_and_functions.sql
@@ -1,477 +1,8 @@
 -- sql/Initial_triggers_and_functions.sql
 -- This file contains all trigger functions and trigger definitions for the database.
 -- 1. Set up the trigger to automatically create a profile when a new user signs up.
 -- This function is called by a trigger on the `public.users` table.
 DROP FUNCTION IF EXISTS public.handle_new_user();
 -- It creates a corresponding profile and a default shopping list for the new user.
 -- It now accepts full_name and avatar_url from the user's metadata.
 CREATE OR REPLACE FUNCTION public.handle_new_user()
 RETURNS TRIGGER AS $$
 DECLARE
  new_profile_id UUID;
  user_meta_data JSONB;
 BEGIN
  -- The user's metadata (full_name, avatar_url) is passed via a temporary session variable.
  user_meta_data := current_setting('my_app.user_metadata', true)::JSONB;
  INSERT INTO public.profiles (user_id, role, full_name, avatar_url)
  VALUES (new.user_id, 'user', user_meta_data->>'full_name', user_meta_data->>'avatar_url')
  RETURNING user_id INTO new_profile_id;
  -- Also create a default shopping list for the new user.
  INSERT INTO public.shopping_lists (user_id, name)
  VALUES (new.user_id, 'Main Shopping List');
  -- Log the new user event
  INSERT INTO public.activity_log (user_id, action, display_text, icon, details)
  VALUES (new.user_id, 'user_registered', 
          COALESCE(user_meta_data->>'full_name', new.email) || ' has registered.',
          'user-plus', 
          jsonb_build_object('email', new.email)
  );
  RETURN new;
 END;
 $$ LANGUAGE plpgsql;
 -- This trigger calls the function after a new user is created.
 DROP TRIGGER IF EXISTS on_auth_user_created ON public.users;
 CREATE TRIGGER on_auth_user_created
  AFTER INSERT ON public.users
  FOR EACH ROW EXECUTE FUNCTION public.handle_new_user();
 -- 2. Create a reusable function to automatically update 'updated_at' columns.
 DROP FUNCTION IF EXISTS public.handle_updated_at();
 CREATE OR REPLACE FUNCTION public.handle_updated_at()
 RETURNS TRIGGER AS $$
 BEGIN
  NEW.updated_at = now();
  RETURN NEW;
 END;
 $$ LANGUAGE plpgsql;
 -- Dynamically apply the 'handle_updated_at' trigger to all tables in the public schema
 -- that have an 'updated_at' column. This is more maintainable than creating a separate
 -- trigger for each table.
 DO $$
 DECLARE
    t_name TEXT;
 BEGIN
    FOR t_name IN
        SELECT table_name
        FROM information_schema.columns
        WHERE table_schema = 'public' AND column_name = 'updated_at'
    LOOP
        EXECUTE format('DROP TRIGGER IF EXISTS on_%s_updated ON public.%I;
                        CREATE TRIGGER on_%s_updated
                        BEFORE UPDATE ON public.%I
                        FOR EACH ROW EXECUTE FUNCTION public.handle_updated_at();',
                        t_name, t_name, t_name, t_name);
    END LOOP;
 END;
 $$;
 -- 3. Create a trigger function to populate the item_price_history table on insert.
 DROP FUNCTION IF EXISTS public.update_price_history_on_flyer_item_insert();
 CREATE OR REPLACE FUNCTION public.update_price_history_on_flyer_item_insert()
 RETURNS TRIGGER AS $$
 DECLARE
    flyer_valid_from DATE;
    flyer_valid_to DATE;
    current_summary_date DATE;
    flyer_location_id BIGINT;
 BEGIN
    -- If the item could not be matched, add it to the unmatched queue for review.
    IF NEW.master_item_id IS NULL THEN
        INSERT INTO public.unmatched_flyer_items (flyer_item_id)
        VALUES (NEW.flyer_item_id)
        ON CONFLICT (flyer_item_id) DO NOTHING;
    END IF;
    -- Only run if the new flyer item is linked to a master item and has a price.
    IF NEW.master_item_id IS NULL OR NEW.price_in_cents IS NULL THEN
        RETURN NEW;
    END IF;
    -- Get the validity dates of the flyer and the store_id.
    SELECT valid_from, valid_to INTO flyer_valid_from, flyer_valid_to
    FROM public.flyers
    WHERE flyer_id = NEW.flyer_id;
    -- This single, set-based query is much more performant than looping.
    -- It generates all date/location pairs and inserts/updates them in one operation.
    INSERT INTO public.item_price_history (master_item_id, summary_date, store_location_id, min_price_in_cents, max_price_in_cents, avg_price_in_cents, data_points_count)
    SELECT
        NEW.master_item_id,
        d.day,
        fl.store_location_id,
        NEW.price_in_cents,
        NEW.price_in_cents,
        NEW.price_in_cents,
        1
    FROM public.flyer_locations fl
    CROSS JOIN generate_series(flyer_valid_from, flyer_valid_to, '1 day'::interval) AS d(day)
    WHERE fl.flyer_id = NEW.flyer_id
    ON CONFLICT (master_item_id, summary_date, store_location_id)
    DO UPDATE SET
        min_price_in_cents = LEAST(item_price_history.min_price_in_cents, EXCLUDED.min_price_in_cents),
        max_price_in_cents = GREATEST(item_price_history.max_price_in_cents, EXCLUDED.max_price_in_cents),
        avg_price_in_cents = ROUND(((item_price_history.avg_price_in_cents * item_price_history.data_points_count) + EXCLUDED.avg_price_in_cents) / (item_price_history.data_points_count + 1.0)),
        data_points_count = item_price_history.data_points_count + 1;
    RETURN NEW;
 END;
 $$ LANGUAGE plpgsql;
 -- Create the trigger on the flyer_items table for insert.
 DROP TRIGGER IF EXISTS trigger_update_price_history ON public.flyer_items;
 CREATE TRIGGER trigger_update_price_history
  AFTER INSERT ON public.flyer_items
  FOR EACH ROW EXECUTE FUNCTION public.update_price_history_on_flyer_item_insert();
 -- 4. Create a trigger function to recalculate price history when a flyer item is deleted.
 DROP FUNCTION IF EXISTS public.recalculate_price_history_on_flyer_item_delete();
 CREATE OR REPLACE FUNCTION public.recalculate_price_history_on_flyer_item_delete()
 RETURNS TRIGGER AS $$
 DECLARE
    affected_dates RECORD;
 BEGIN
    -- Only run if the deleted item was linked to a master item and had a price.
    IF OLD.master_item_id IS NULL OR OLD.price_in_cents IS NULL THEN
        RETURN OLD;
    END IF;
    -- This single, set-based query is much more performant than looping.
    -- It recalculates aggregates for all affected dates and locations at once.
    WITH affected_days_and_locations AS (
        -- 1. Get all date/location pairs affected by the deleted item's flyer.
        SELECT DISTINCT
            generate_series(f.valid_from, f.valid_to, '1 day'::interval)::date AS summary_date,
            fl.store_location_id
        FROM public.flyers f
        JOIN public.flyer_locations fl ON f.flyer_id = fl.flyer_id
        WHERE f.flyer_id = OLD.flyer_id
    ),
    new_aggregates AS (
        -- 2. For each affected date/location, recalculate the aggregates from all other relevant flyer items.
        SELECT
            adl.summary_date,
            adl.store_location_id,
            MIN(fi.price_in_cents) AS min_price,
            MAX(fi.price_in_cents) AS max_price,
            ROUND(AVG(fi.price_in_cents))::int AS avg_price,
            COUNT(fi.flyer_item_id)::int AS data_points
        FROM affected_days_and_locations adl
        LEFT JOIN public.flyer_items fi ON fi.master_item_id = OLD.master_item_id AND fi.price_in_cents IS NOT NULL
        LEFT JOIN public.flyers f ON fi.flyer_id = f.flyer_id AND adl.summary_date BETWEEN f.valid_from AND f.valid_to
        LEFT JOIN public.flyer_locations fl ON fi.flyer_id = fl.flyer_id AND adl.store_location_id = fl.store_location_id
        WHERE fl.flyer_id IS NOT NULL -- Ensure the join was successful
        GROUP BY adl.summary_date, adl.store_location_id
    )
    -- 3. Update the history table with the new aggregates.
    UPDATE public.item_price_history iph
    SET
        min_price_in_cents = na.min_price,
        max_price_in_cents = na.max_price,
        avg_price_in_cents = na.avg_price,
        data_points_count = na.data_points
    FROM new_aggregates na
    WHERE iph.master_item_id = OLD.master_item_id
      AND iph.summary_date = na.summary_date
      AND iph.store_location_id = na.store_location_id;
    -- 4. Delete any history records that no longer have any data points.
    DELETE FROM public.item_price_history iph
    WHERE iph.master_item_id = OLD.master_item_id
      AND NOT EXISTS (
          SELECT 1 FROM new_aggregates na
          WHERE na.summary_date = iph.summary_date AND na.store_location_id = iph.store_location_id
      );
    RETURN OLD;
 END;
 $$ LANGUAGE plpgsql;
 -- Create the trigger on the flyer_items table for DELETE operations.
 DROP TRIGGER IF EXISTS trigger_recalculate_price_history_on_delete ON public.flyer_items;
 CREATE TRIGGER trigger_recalculate_price_history_on_delete
  AFTER DELETE ON public.flyer_items
  FOR EACH ROW EXECUTE FUNCTION public.recalculate_price_history_on_flyer_item_delete();
 -- 5. Trigger function to update the average rating on the recipes table.
 DROP FUNCTION IF EXISTS public.update_recipe_rating_aggregates();
 CREATE OR REPLACE FUNCTION public.update_recipe_rating_aggregates()
 RETURNS TRIGGER AS $$
 BEGIN
    UPDATE public.recipes
    SET
        avg_rating = (
            SELECT AVG(rating)
            FROM public.recipe_ratings
            WHERE recipe_id = COALESCE(NEW.recipe_id, OLD.recipe_id) -- This is correct, no change needed
        ),
        rating_count = (
            SELECT COUNT(*)
            FROM public.recipe_ratings
            WHERE recipe_id = COALESCE(NEW.recipe_id, OLD.recipe_id) -- This is correct, no change needed
        )
    WHERE recipe_id = COALESCE(NEW.recipe_id, OLD.recipe_id);
    RETURN NULL; -- The result is ignored since this is an AFTER trigger.
 END;
 $$ LANGUAGE plpgsql;
 -- Trigger to call the function after any change to recipe_ratings.
 DROP TRIGGER IF EXISTS on_recipe_rating_change ON public.recipe_ratings;
 CREATE TRIGGER on_recipe_rating_change
  AFTER INSERT OR UPDATE OR DELETE ON public.recipe_ratings
  FOR EACH ROW EXECUTE FUNCTION public.update_recipe_rating_aggregates();
 -- 6. Trigger function to log the creation of a new recipe.
 DROP FUNCTION IF EXISTS public.log_new_recipe();
 CREATE OR REPLACE FUNCTION public.log_new_recipe()
 RETURNS TRIGGER AS $$
 BEGIN
    INSERT INTO public.activity_log (user_id, action, display_text, icon, details)
    VALUES (
        NEW.user_id,
        'recipe_created',
        (SELECT full_name FROM public.profiles WHERE user_id = NEW.user_id) || ' created a new recipe: ' || NEW.name,
        'chef-hat',
        jsonb_build_object('recipe_id', NEW.recipe_id, 'recipe_name', NEW.name)
    );
    -- Award 'First Recipe' achievement if it's their first one.
    PERFORM public.award_achievement(NEW.user_id, 'First Recipe');
    RETURN NEW;
 END;
 $$ LANGUAGE plpgsql;
 -- Trigger to call the function after a new recipe is inserted.
 DROP TRIGGER IF EXISTS on_new_recipe_created ON public.recipes;
 CREATE TRIGGER on_new_recipe_created
  AFTER INSERT ON public.recipes
  FOR EACH ROW
  WHEN (NEW.user_id IS NOT NULL) -- Only log activity for user-created recipes.
  EXECUTE FUNCTION public.log_new_recipe();
 -- 7a. Trigger function to update the item_count on the flyers table.
 DROP FUNCTION IF EXISTS public.update_flyer_item_count();
 CREATE OR REPLACE FUNCTION public.update_flyer_item_count()
 RETURNS TRIGGER AS $$
 BEGIN
    IF (TG_OP = 'INSERT') THEN
        UPDATE public.flyers SET item_count = item_count + 1 WHERE flyer_id = NEW.flyer_id;
    ELSIF (TG_OP = 'DELETE') THEN
        UPDATE public.flyers SET item_count = item_count - 1 WHERE flyer_id = OLD.flyer_id;
    END IF;
    RETURN NULL; -- The result is ignored since this is an AFTER trigger.
 END;
 $$ LANGUAGE plpgsql;
 -- Trigger to call the function after any change to flyer_items.
 -- This ensures the item_count on the parent flyer is always accurate.
 DROP TRIGGER IF EXISTS on_flyer_item_change ON public.flyer_items;
 CREATE TRIGGER on_flyer_item_change
  AFTER INSERT OR DELETE ON public.flyer_items
  FOR EACH ROW EXECUTE FUNCTION public.update_flyer_item_count();
 -- 7. Trigger function to log the creation of a new flyer.
 DROP FUNCTION IF EXISTS public.log_new_flyer();
 CREATE OR REPLACE FUNCTION public.log_new_flyer()
 RETURNS TRIGGER AS $$
 BEGIN
    INSERT INTO public.activity_log (action, display_text, icon, details)
    VALUES (
        'flyer_uploaded',
        'A new flyer for ' || (SELECT name FROM public.stores WHERE store_id = NEW.store_id) || ' has been uploaded.',
        'file-text',
        jsonb_build_object(
            'flyer_id', NEW.flyer_id,
            'store_name', (SELECT name FROM public.stores WHERE store_id = NEW.store_id),
            'valid_from', to_char(NEW.valid_from, 'YYYY-MM-DD'),
            'valid_to', to_char(NEW.valid_to, 'YYYY-MM-DD')
        )
    );
    RETURN NEW;
 END;
 $$ LANGUAGE plpgsql;
 -- Trigger to call the function after a new flyer is inserted.
 DROP TRIGGER IF EXISTS on_new_flyer_created ON public.flyers;
 CREATE TRIGGER on_new_flyer_created
  AFTER INSERT ON public.flyers
  FOR EACH ROW EXECUTE FUNCTION public.log_new_flyer();
 -- 8. Trigger function to log when a user favorites a recipe.
 DROP FUNCTION IF EXISTS public.log_new_favorite_recipe();
 CREATE OR REPLACE FUNCTION public.log_new_favorite_recipe()
 RETURNS TRIGGER AS $$
 BEGIN
    INSERT INTO public.activity_log (user_id, action, display_text, icon, details)
    VALUES (
        NEW.user_id,
        'recipe_favorited',
        (SELECT full_name FROM public.profiles WHERE user_id = NEW.user_id) || ' favorited the recipe: ' || (SELECT name FROM public.recipes WHERE recipe_id = NEW.recipe_id),
        'heart',
        jsonb_build_object(            
            'recipe_id', NEW.recipe_id
        )
    );
    -- Award 'First Favorite' achievement.
    PERFORM public.award_achievement(NEW.user_id, 'First Favorite');
    RETURN NEW;
 END;
 $$ LANGUAGE plpgsql;
 -- Trigger to call the function after a recipe is favorited.
 DROP TRIGGER IF EXISTS on_new_favorite_recipe ON public.favorite_recipes;
 CREATE TRIGGER on_new_favorite_recipe
  AFTER INSERT ON public.favorite_recipes
  FOR EACH ROW EXECUTE FUNCTION public.log_new_favorite_recipe();
 -- 9. Trigger function to log when a user shares a shopping list.
 DROP FUNCTION IF EXISTS public.log_new_list_share();
 CREATE OR REPLACE FUNCTION public.log_new_list_share()
 RETURNS TRIGGER AS $$
 BEGIN
    INSERT INTO public.activity_log (user_id, action, display_text, icon, details)
    VALUES (
        NEW.shared_by_user_id,
        'list_shared',
        (SELECT full_name FROM public.profiles WHERE user_id = NEW.shared_by_user_id) || ' shared a shopping list.',
        'share-2',
        jsonb_build_object(
            'shopping_list_id', NEW.shopping_list_id,
            'list_name', (SELECT name FROM public.shopping_lists WHERE shopping_list_id = NEW.shopping_list_id),
            'shared_with_user_id', NEW.shared_with_user_id
        )
    );
    -- Award 'List Sharer' achievement.
    PERFORM public.award_achievement(NEW.shared_by_user_id, 'List Sharer');
    RETURN NEW;
 END;
 $$ LANGUAGE plpgsql;
 -- Trigger to call the function after a shopping list is shared.
 DROP TRIGGER IF EXISTS on_new_list_share ON public.shared_shopping_lists;
 CREATE TRIGGER on_new_list_share
  AFTER INSERT ON public.shared_shopping_lists
  FOR EACH ROW EXECUTE FUNCTION public.log_new_list_share();
 -- 9a. Trigger function to log when a user shares a recipe collection.
 DROP FUNCTION IF EXISTS public.log_new_recipe_collection_share();
 CREATE OR REPLACE FUNCTION public.log_new_recipe_collection_share()
 RETURNS TRIGGER AS $$
 BEGIN
    -- Log the activity
    INSERT INTO public.activity_log (user_id, action, display_text, icon, details)
    VALUES (
        NEW.shared_by_user_id, 'recipe_collection_shared',
        (SELECT full_name FROM public.profiles WHERE user_id = NEW.shared_by_user_id) || ' shared a recipe collection.',
        'book',
        jsonb_build_object('collection_id', NEW.recipe_collection_id, 'shared_with_user_id', NEW.shared_with_user_id)
    );
    -- Award 'Recipe Sharer' achievement.
    PERFORM public.award_achievement(NEW.shared_by_user_id, 'Recipe Sharer');
    RETURN NEW;
 END;
 $$ LANGUAGE plpgsql;
 DROP TRIGGER IF EXISTS on_new_recipe_collection_share ON public.shared_recipe_collections;
 CREATE TRIGGER on_new_recipe_collection_share
  AFTER INSERT ON public.shared_recipe_collections
  FOR EACH ROW EXECUTE FUNCTION public.log_new_recipe_collection_share();
 -- 10. Trigger function to geocode a store location's address.
 -- This function is designed to be extensible. In a production environment,
 -- you would replace the placeholder with a call to an external geocoding service
 -- (e.g., using the `http` extension or a `plpythonu` function) to convert
 -- the address into geographic coordinates.
 DROP FUNCTION IF EXISTS public.geocode_store_location();
 CREATE OR REPLACE FUNCTION public.geocode_store_location()
 RETURNS TRIGGER AS $$
 DECLARE
    full_address TEXT;
 BEGIN
    -- Only proceed if the address has actually changed.
    IF TG_OP = 'INSERT' OR (TG_OP = 'UPDATE' AND NEW.address IS DISTINCT FROM OLD.address) THEN
        -- Concatenate address parts into a single string for the geocoder.
        full_address := CONCAT_WS(', ', NEW.address, NEW.city, NEW.province_state, NEW.postal_code);
        -- ======================================================================
        -- Placeholder for Geocoding API Call
        -- ======================================================================
        -- In a real application, you would call a geocoding service here.
        -- For example, using the `http` extension:
        --
        -- DECLARE
        --   response http_get;
        --   lat NUMERIC;
        --   lon NUMERIC;
        -- BEGIN
        --   SELECT * INTO response FROM http_get('https://api.geocodingservice.com/geocode?address=' || url_encode(full_address));
        --   lat := (response.content::jsonb)->'results'->0->'geometry'->'location'->'lat';
        --   lon := (response.content::jsonb)->'results'->0->'geometry'->'location'->'lng';
        --   NEW.location := ST_SetSRID(ST_MakePoint(lon, lat), 4326)::geography;
        -- END;
        --
        -- For now, this function does nothing, but the trigger is in place.
        -- If you manually provide lat/lon, you could parse them here.
        -- For this example, we will assume the `location` might be set manually
        -- or by a separate batch process.
        -- ======================================================================
    END IF;
    RETURN NEW;
 END;
 $$ LANGUAGE plpgsql;
 -- Trigger to call the geocoding function.
 DROP TRIGGER IF EXISTS on_store_location_address_change ON public.store_locations;
 CREATE TRIGGER on_store_location_address_change
  BEFORE INSERT OR UPDATE ON public.store_locations
  FOR EACH ROW EXECUTE FUNCTION public.geocode_store_location();
 -- 11. Trigger function to increment the fork_count on the original recipe.
 DROP FUNCTION IF EXISTS public.increment_recipe_fork_count();
 CREATE OR REPLACE FUNCTION public.increment_recipe_fork_count()
 RETURNS TRIGGER AS $$
 BEGIN
    -- Only run if the recipe is a fork (original_recipe_id is not null).
    IF NEW.original_recipe_id IS NOT NULL THEN
        UPDATE public.recipes SET fork_count = fork_count + 1 WHERE recipe_id = NEW.original_recipe_id;
        -- Award 'First Fork' achievement.
        PERFORM public.award_achievement(NEW.user_id, 'First Fork');
    END IF;
    RETURN NEW;
 END;
 $$ LANGUAGE plpgsql;
 DROP TRIGGER IF EXISTS on_recipe_fork ON public.recipes;
 CREATE TRIGGER on_recipe_fork
  AFTER INSERT ON public.recipes
  FOR EACH ROW EXECUTE FUNCTION public.increment_recipe_fork_count();
 -- ============================================================================
-- PART 6: DATABASE FUNCTIONS
+-- PART 3: DATABASE FUNCTIONS
 -- ============================================================================
  -- Function to find the best current sale price for a user's watched items.
 DROP FUNCTION IF EXISTS public.get_best_sale_prices_for_user(UUID);
@@ -1336,8 +867,7 @@ AS $$
        'list_shared'
        -- 'new_recipe_rating' could be added here later
    )
-  ORDER BY
+  ORDER BY al.created_at DESC, al.display_text, al.icon
    al.created_at DESC
  LIMIT p_limit
  OFFSET p_offset;
 $$;
@@ -1549,16 +1079,18 @@ $$;
 -- It replaces the need to call get_best_sale_prices_for_user for each user individually.
 -- Returns: TABLE(...) - A set of records including user details and deal information.
 -- =================================================================
 DROP FUNCTION IF EXISTS public.get_best_sale_prices_for_all_users();
 CREATE OR REPLACE FUNCTION public.get_best_sale_prices_for_all_users()
 RETURNS TABLE(
    user_id uuid,
    email text,
    full_name text,
-    master_item_id integer,
+    master_item_id bigint,
    item_name text,
    best_price_in_cents integer,
    store_name text,
-    flyer_id integer,
+    flyer_id bigint,
    valid_to date
 ) AS $$
 BEGIN
@@ -1569,11 +1101,12 @@ BEGIN
        SELECT
            fi.master_item_id,
            fi.price_in_cents,
-            f.store_name,
+            s.name as store_name,
            f.flyer_id,
            f.valid_to
        FROM public.flyer_items fi
        JOIN public.flyers f ON fi.flyer_id = f.flyer_id
        JOIN public.stores s ON f.store_id = s.store_id
        WHERE
            fi.master_item_id IS NOT NULL
            AND fi.price_in_cents IS NOT NULL
@@ -1616,3 +1149,472 @@ BEGIN
        bp.price_rank = 1;
 END;
 $$ LANGUAGE plpgsql;
 -- ============================================================================
 -- PART 4: TRIGGERS
 -- ============================================================================
 -- 1. Trigger to automatically create a profile when a new user signs up.
 -- This function is called by a trigger on the `public.users` table.
 DROP FUNCTION IF EXISTS public.handle_new_user();
 -- It creates a corresponding profile and a default shopping list for the new user.
 -- It now accepts full_name and avatar_url from the user's metadata.
 CREATE OR REPLACE FUNCTION public.handle_new_user()
 RETURNS TRIGGER AS $$
 DECLARE
  new_profile_id UUID;
  user_meta_data JSONB;
 BEGIN
  -- The user's metadata (full_name, avatar_url) is passed via a temporary session variable.
  user_meta_data := current_setting('my_app.user_metadata', true)::JSONB;
  INSERT INTO public.profiles (user_id, role, full_name, avatar_url)
  VALUES (new.user_id, 'user', user_meta_data->>'full_name', user_meta_data->>'avatar_url')
  RETURNING user_id INTO new_profile_id;
  -- Also create a default shopping list for the new user.
  INSERT INTO public.shopping_lists (user_id, name)
  VALUES (new.user_id, 'Main Shopping List');
  -- Log the new user event
  INSERT INTO public.activity_log (user_id, action, display_text, icon, details)
  VALUES (new.user_id, 'user_registered', 
          COALESCE(user_meta_data->>'full_name', new.email) || ' has registered.',
          'user-plus', 
          jsonb_build_object('email', new.email)
  );
  RETURN new;
 END;
 $$ LANGUAGE plpgsql;
 -- This trigger calls the function after a new user is created.
 DROP TRIGGER IF EXISTS on_auth_user_created ON public.users;
 CREATE TRIGGER on_auth_user_created
  AFTER INSERT ON public.users
  FOR EACH ROW EXECUTE FUNCTION public.handle_new_user();
 -- 2. Create a reusable function to automatically update 'updated_at' columns.
 DROP FUNCTION IF EXISTS public.handle_updated_at();
 CREATE OR REPLACE FUNCTION public.handle_updated_at()
 RETURNS TRIGGER AS $$
 BEGIN
  NEW.updated_at = now();
  RETURN NEW;
 END;
 $$ LANGUAGE plpgsql;
 -- Dynamically apply the 'handle_updated_at' trigger to all tables in the public schema
 -- that have an 'updated_at' column. This is more maintainable than creating a separate
 -- trigger for each table.
 DO $$
 DECLARE
    t_name TEXT;
 BEGIN
    FOR t_name IN
        SELECT table_name
        FROM information_schema.columns
        WHERE table_schema = 'public' AND column_name = 'updated_at'
    LOOP
        EXECUTE format('DROP TRIGGER IF EXISTS on_%s_updated ON public.%I;
                        CREATE TRIGGER on_%s_updated
                        BEFORE UPDATE ON public.%I
                        FOR EACH ROW EXECUTE FUNCTION public.handle_updated_at();',
                        t_name, t_name, t_name, t_name);
    END LOOP;
 END;
 $$;
 -- 3. Create a trigger function to populate the item_price_history table on insert.
 DROP FUNCTION IF EXISTS public.update_price_history_on_flyer_item_insert();
 CREATE OR REPLACE FUNCTION public.update_price_history_on_flyer_item_insert()
 RETURNS TRIGGER AS $$
 DECLARE
    flyer_valid_from DATE;
    flyer_valid_to DATE;
    current_summary_date DATE;
    flyer_location_id BIGINT;
 BEGIN
    -- If the item could not be matched, add it to the unmatched queue for review.
    IF NEW.master_item_id IS NULL THEN
        INSERT INTO public.unmatched_flyer_items (flyer_item_id)
        VALUES (NEW.flyer_item_id)
        ON CONFLICT (flyer_item_id) DO NOTHING;
    END IF;
    -- Only run if the new flyer item is linked to a master item and has a price.
    IF NEW.master_item_id IS NULL OR NEW.price_in_cents IS NULL THEN
        RETURN NEW;
    END IF;
    -- Get the validity dates of the flyer and the store_id.
    SELECT valid_from, valid_to INTO flyer_valid_from, flyer_valid_to
    FROM public.flyers
    WHERE flyer_id = NEW.flyer_id;
    -- This single, set-based query is much more performant than looping.
    -- It generates all date/location pairs and inserts/updates them in one operation.
    INSERT INTO public.item_price_history (master_item_id, summary_date, store_location_id, min_price_in_cents, max_price_in_cents, avg_price_in_cents, data_points_count)
    SELECT
        NEW.master_item_id,
        d.day,
        fl.store_location_id,
        NEW.price_in_cents,
        NEW.price_in_cents,
        NEW.price_in_cents,
        1
    FROM public.flyer_locations fl
    CROSS JOIN generate_series(flyer_valid_from, flyer_valid_to, '1 day'::interval) AS d(day)
    WHERE fl.flyer_id = NEW.flyer_id
    ON CONFLICT (master_item_id, summary_date, store_location_id)
    DO UPDATE SET
        min_price_in_cents = LEAST(item_price_history.min_price_in_cents, EXCLUDED.min_price_in_cents),
        max_price_in_cents = GREATEST(item_price_history.max_price_in_cents, EXCLUDED.max_price_in_cents),
        avg_price_in_cents = ROUND(((item_price_history.avg_price_in_cents * item_price_history.data_points_count) + EXCLUDED.avg_price_in_cents) / (item_price_history.data_points_count + 1.0)),
        data_points_count = item_price_history.data_points_count + 1;
    RETURN NEW;
 END;
 $$ LANGUAGE plpgsql;
 -- Create the trigger on the flyer_items table for insert.
 DROP TRIGGER IF EXISTS trigger_update_price_history ON public.flyer_items;
 CREATE TRIGGER trigger_update_price_history
  AFTER INSERT ON public.flyer_items
  FOR EACH ROW EXECUTE FUNCTION public.update_price_history_on_flyer_item_insert();
 -- 4. Create a trigger function to recalculate price history when a flyer item is deleted.
 DROP FUNCTION IF EXISTS public.recalculate_price_history_on_flyer_item_delete();
 CREATE OR REPLACE FUNCTION public.recalculate_price_history_on_flyer_item_delete()
 RETURNS TRIGGER AS $$
 DECLARE
    affected_dates RECORD;
 BEGIN
    -- Only run if the deleted item was linked to a master item and had a price.
    IF OLD.master_item_id IS NULL OR OLD.price_in_cents IS NULL THEN
        RETURN OLD;
    END IF;
    -- This single, set-based query is much more performant than looping.
    -- It recalculates aggregates for all affected dates and locations at once.
    WITH affected_days_and_locations AS (
        -- 1. Get all date/location pairs affected by the deleted item's flyer.
        SELECT DISTINCT
            generate_series(f.valid_from, f.valid_to, '1 day'::interval)::date AS summary_date,
            fl.store_location_id
        FROM public.flyers f
        JOIN public.flyer_locations fl ON f.flyer_id = fl.flyer_id
        WHERE f.flyer_id = OLD.flyer_id
    ),
    new_aggregates AS (
        -- 2. For each affected date/location, recalculate the aggregates from all other relevant flyer items.
        SELECT
            adl.summary_date,
            adl.store_location_id,
            MIN(fi.price_in_cents) AS min_price,
            MAX(fi.price_in_cents) AS max_price,
            ROUND(AVG(fi.price_in_cents))::int AS avg_price,
            COUNT(fi.flyer_item_id)::int AS data_points
        FROM affected_days_and_locations adl
        LEFT JOIN public.flyer_items fi ON fi.master_item_id = OLD.master_item_id AND fi.price_in_cents IS NOT NULL
        LEFT JOIN public.flyers f ON fi.flyer_id = f.flyer_id AND adl.summary_date BETWEEN f.valid_from AND f.valid_to
        LEFT JOIN public.flyer_locations fl ON fi.flyer_id = fl.flyer_id AND adl.store_location_id = fl.store_location_id
        WHERE fl.flyer_id IS NOT NULL -- Ensure the join was successful
        GROUP BY adl.summary_date, adl.store_location_id
    )
    -- 3. Update the history table with the new aggregates.
    UPDATE public.item_price_history iph
    SET
        min_price_in_cents = na.min_price,
        max_price_in_cents = na.max_price,
        avg_price_in_cents = na.avg_price,
        data_points_count = na.data_points
    FROM new_aggregates na
    WHERE iph.master_item_id = OLD.master_item_id
      AND iph.summary_date = na.summary_date
      AND iph.store_location_id = na.store_location_id;
    -- 4. Delete any history records that no longer have any data points.
    DELETE FROM public.item_price_history iph
    WHERE iph.master_item_id = OLD.master_item_id
      AND NOT EXISTS (
          SELECT 1 FROM new_aggregates na
          WHERE na.summary_date = iph.summary_date AND na.store_location_id = iph.store_location_id
      );
    RETURN OLD;
 END;
 $$ LANGUAGE plpgsql;
 -- Create the trigger on the flyer_items table for DELETE operations.
 DROP TRIGGER IF EXISTS trigger_recalculate_price_history_on_delete ON public.flyer_items;
 CREATE TRIGGER trigger_recalculate_price_history_on_delete
  AFTER DELETE ON public.flyer_items
  FOR EACH ROW EXECUTE FUNCTION public.recalculate_price_history_on_flyer_item_delete();
 -- 5. Trigger function to update the average rating on the recipes table.
 DROP FUNCTION IF EXISTS public.update_recipe_rating_aggregates();
 CREATE OR REPLACE FUNCTION public.update_recipe_rating_aggregates()
 RETURNS TRIGGER AS $$
 BEGIN
    UPDATE public.recipes
    SET
        avg_rating = (
            SELECT AVG(rating)
            FROM public.recipe_ratings
            WHERE recipe_id = COALESCE(NEW.recipe_id, OLD.recipe_id) -- This is correct, no change needed
        ),
        rating_count = (
            SELECT COUNT(*)
            FROM public.recipe_ratings
            WHERE recipe_id = COALESCE(NEW.recipe_id, OLD.recipe_id) -- This is correct, no change needed
        )
    WHERE recipe_id = COALESCE(NEW.recipe_id, OLD.recipe_id);
    RETURN NULL; -- The result is ignored since this is an AFTER trigger.
 END;
 $$ LANGUAGE plpgsql;
 -- Trigger to call the function after any change to recipe_ratings.
 DROP TRIGGER IF EXISTS on_recipe_rating_change ON public.recipe_ratings;
 CREATE TRIGGER on_recipe_rating_change
  AFTER INSERT OR UPDATE OR DELETE ON public.recipe_ratings
  FOR EACH ROW EXECUTE FUNCTION public.update_recipe_rating_aggregates();
 -- 6. Trigger function to log the creation of a new recipe.
 DROP FUNCTION IF EXISTS public.log_new_recipe();
 CREATE OR REPLACE FUNCTION public.log_new_recipe()
 RETURNS TRIGGER AS $$
 BEGIN
    INSERT INTO public.activity_log (user_id, action, display_text, icon, details)
    VALUES (
        NEW.user_id,
        'recipe_created',
        (SELECT full_name FROM public.profiles WHERE user_id = NEW.user_id) || ' created a new recipe: ' || NEW.name,
        'chef-hat',
        jsonb_build_object('recipe_id', NEW.recipe_id, 'recipe_name', NEW.name)
    );
    -- Award 'First Recipe' achievement if it's their first one.
    PERFORM public.award_achievement(NEW.user_id, 'First Recipe');
    RETURN NEW;
 END;
 $$ LANGUAGE plpgsql;
 -- Trigger to call the function after a new recipe is inserted.
 DROP TRIGGER IF EXISTS on_new_recipe_created ON public.recipes;
 CREATE TRIGGER on_new_recipe_created
  AFTER INSERT ON public.recipes
  FOR EACH ROW
  WHEN (NEW.user_id IS NOT NULL) -- Only log activity for user-created recipes.
  EXECUTE FUNCTION public.log_new_recipe();
 -- 7a. Trigger function to update the item_count on the flyers table.
 DROP FUNCTION IF EXISTS public.update_flyer_item_count();
 CREATE OR REPLACE FUNCTION public.update_flyer_item_count()
 RETURNS TRIGGER AS $$
 BEGIN
    IF (TG_OP = 'INSERT') THEN
        UPDATE public.flyers SET item_count = item_count + 1 WHERE flyer_id = NEW.flyer_id;
    ELSIF (TG_OP = 'DELETE') THEN
        UPDATE public.flyers SET item_count = item_count - 1 WHERE flyer_id = OLD.flyer_id;
    END IF;
    RETURN NULL; -- The result is ignored since this is an AFTER trigger.
 END;
 $$ LANGUAGE plpgsql;
 -- Trigger to call the function after any change to flyer_items.
 -- This ensures the item_count on the parent flyer is always accurate.
 DROP TRIGGER IF EXISTS on_flyer_item_change ON public.flyer_items;
 CREATE TRIGGER on_flyer_item_change
  AFTER INSERT OR DELETE ON public.flyer_items
  FOR EACH ROW EXECUTE FUNCTION public.update_flyer_item_count();
 -- 7. Trigger function to log the creation of a new flyer.
 DROP FUNCTION IF EXISTS public.log_new_flyer();
 CREATE OR REPLACE FUNCTION public.log_new_flyer()
 RETURNS TRIGGER AS $$
 BEGIN
    -- If the flyer was uploaded by a registered user, award the 'First-Upload' achievement.
    -- The award_achievement function handles checking if the user already has it.
    IF NEW.uploaded_by IS NOT NULL THEN
        PERFORM public.award_achievement(NEW.uploaded_by, 'First-Upload');
    END IF;
    INSERT INTO public.activity_log (user_id, action, display_text, icon, details)
    VALUES (
        NEW.uploaded_by, -- Log the user who uploaded it
        'flyer_uploaded',
        'A new flyer for ' || (SELECT name FROM public.stores WHERE store_id = NEW.store_id) || ' has been uploaded.',
        'file-text',
        jsonb_build_object(
            'flyer_id', NEW.flyer_id,
            'store_name', (SELECT name FROM public.stores WHERE store_id = NEW.store_id),
            'valid_from', to_char(NEW.valid_from, 'YYYY-MM-DD'),
            'valid_to', to_char(NEW.valid_to, 'YYYY-MM-DD')
        )
    );
    RETURN NEW;
 END;
 $$ LANGUAGE plpgsql;
 -- Trigger to call the function after a new flyer is inserted.
 DROP TRIGGER IF EXISTS on_new_flyer_created ON public.flyers;
 CREATE TRIGGER on_new_flyer_created
  AFTER INSERT ON public.flyers
  FOR EACH ROW EXECUTE FUNCTION public.log_new_flyer();
 -- 8. Trigger function to log when a user favorites a recipe.
 DROP FUNCTION IF EXISTS public.log_new_favorite_recipe();
 CREATE OR REPLACE FUNCTION public.log_new_favorite_recipe()
 RETURNS TRIGGER AS $$
 BEGIN
    INSERT INTO public.activity_log (user_id, action, display_text, icon, details)
    VALUES (
        NEW.user_id,
        'recipe_favorited',
        (SELECT full_name FROM public.profiles WHERE user_id = NEW.user_id) || ' favorited the recipe: ' || (SELECT name FROM public.recipes WHERE recipe_id = NEW.recipe_id),
        'heart',
        jsonb_build_object(            
            'recipe_id', NEW.recipe_id
        )
    );
    -- Award 'First Favorite' achievement.
    PERFORM public.award_achievement(NEW.user_id, 'First Favorite');
    RETURN NEW;
 END;
 $$ LANGUAGE plpgsql;
 -- Trigger to call the function after a recipe is favorited.
 DROP TRIGGER IF EXISTS on_new_favorite_recipe ON public.favorite_recipes;
 CREATE TRIGGER on_new_favorite_recipe
  AFTER INSERT ON public.favorite_recipes
  FOR EACH ROW EXECUTE FUNCTION public.log_new_favorite_recipe();
 -- 9. Trigger function to log when a user shares a shopping list.
 DROP FUNCTION IF EXISTS public.log_new_list_share();
 CREATE OR REPLACE FUNCTION public.log_new_list_share()
 RETURNS TRIGGER AS $$
 BEGIN
    INSERT INTO public.activity_log (user_id, action, display_text, icon, details)
    VALUES (
        NEW.shared_by_user_id,
        'list_shared',
        (SELECT full_name FROM public.profiles WHERE user_id = NEW.shared_by_user_id) || ' shared a shopping list.',
        'share-2',
        jsonb_build_object(
            'shopping_list_id', NEW.shopping_list_id,
            'list_name', (SELECT name FROM public.shopping_lists WHERE shopping_list_id = NEW.shopping_list_id),
            'shared_with_user_id', NEW.shared_with_user_id
        )
    );
    -- Award 'List Sharer' achievement.
    PERFORM public.award_achievement(NEW.shared_by_user_id, 'List Sharer');
    RETURN NEW;
 END;
 $$ LANGUAGE plpgsql;
 -- Trigger to call the function after a shopping list is shared.
 DROP TRIGGER IF EXISTS on_new_list_share ON public.shared_shopping_lists;
 CREATE TRIGGER on_new_list_share
  AFTER INSERT ON public.shared_shopping_lists
  FOR EACH ROW EXECUTE FUNCTION public.log_new_list_share();
 -- 9a. Trigger function to log when a user shares a recipe collection.
 DROP FUNCTION IF EXISTS public.log_new_recipe_collection_share();
 CREATE OR REPLACE FUNCTION public.log_new_recipe_collection_share()
 RETURNS TRIGGER AS $$
 BEGIN
    -- Log the activity
    INSERT INTO public.activity_log (user_id, action, display_text, icon, details)
    VALUES (
        NEW.shared_by_user_id, 'recipe_collection_shared',
        (SELECT full_name FROM public.profiles WHERE user_id = NEW.shared_by_user_id) || ' shared a recipe collection.',
        'book',
        jsonb_build_object('collection_id', NEW.recipe_collection_id, 'shared_with_user_id', NEW.shared_with_user_id)
    );
    -- Award 'Recipe Sharer' achievement.
    PERFORM public.award_achievement(NEW.shared_by_user_id, 'Recipe Sharer');
    RETURN NEW;
 END;
 $$ LANGUAGE plpgsql;
 DROP TRIGGER IF EXISTS on_new_recipe_collection_share ON public.shared_recipe_collections;
 CREATE TRIGGER on_new_recipe_collection_share
  AFTER INSERT ON public.shared_recipe_collections
  FOR EACH ROW EXECUTE FUNCTION public.log_new_recipe_collection_share();
 -- 10. Trigger function to geocode a store location's address.
 -- This function is triggered when an address is inserted or updated, and is
 -- designed to be extensible for external geocoding services to populate the
 -- latitude, longitude, and location fields.
 DROP FUNCTION IF EXISTS public.geocode_address();
 CREATE OR REPLACE FUNCTION public.geocode_address()
 RETURNS TRIGGER AS $$
 DECLARE
    full_address TEXT;
 BEGIN
    -- Only proceed if an address component has actually changed.
    IF TG_OP = 'INSERT' OR (TG_OP = 'UPDATE' AND (
        NEW.address_line_1 IS DISTINCT FROM OLD.address_line_1 OR
        NEW.address_line_2 IS DISTINCT FROM OLD.address_line_2 OR
        NEW.city IS DISTINCT FROM OLD.city OR
        NEW.province_state IS DISTINCT FROM OLD.province_state OR
        NEW.postal_code IS DISTINCT FROM OLD.postal_code OR
        NEW.country IS DISTINCT FROM OLD.country
    )) THEN
        -- Concatenate address parts into a single string for the geocoder.
        full_address := CONCAT_WS(', ', NEW.address_line_1, NEW.address_line_2, NEW.city, NEW.province_state, NEW.postal_code, NEW.country);
        -- Placeholder for Geocoding API Call
        -- In a real application, you would call a service here and update NEW.latitude, NEW.longitude, and NEW.location.
        -- e.g., NEW.latitude := result.lat; NEW.longitude := result.lon;
        -- NEW.location := ST_SetSRID(ST_MakePoint(NEW.longitude, NEW.latitude), 4326);
    END IF;
    RETURN NEW;
 END;
 $$ LANGUAGE plpgsql;
 -- This trigger calls the geocoding function when an address changes.
 DROP TRIGGER IF EXISTS on_address_change_geocode ON public.addresses;
 CREATE TRIGGER on_address_change_geocode
  BEFORE INSERT OR UPDATE ON public.addresses
  FOR EACH ROW EXECUTE FUNCTION public.geocode_address();
 -- 11. Trigger function to increment the fork_count on the original recipe.
 DROP FUNCTION IF EXISTS public.increment_recipe_fork_count();
 CREATE OR REPLACE FUNCTION public.increment_recipe_fork_count()
 RETURNS TRIGGER AS $$
 BEGIN
    -- Only run if the recipe is a fork (original_recipe_id is not null).
    IF NEW.original_recipe_id IS NOT NULL THEN
        UPDATE public.recipes SET fork_count = fork_count + 1 WHERE recipe_id = NEW.original_recipe_id;
        -- Award 'First Fork' achievement.
        PERFORM public.award_achievement(NEW.user_id, 'First Fork');
    END IF;
    RETURN NEW;
 END;
 $$ LANGUAGE plpgsql;
 DROP TRIGGER IF EXISTS on_recipe_fork ON public.recipes;
 CREATE TRIGGER on_recipe_fork
  AFTER INSERT ON public.recipes
  FOR EACH ROW EXECUTE FUNCTION public.increment_recipe_fork_count();
--- a/sql/initial_data.sql
+++ b/sql/initial_data.sql
@@ -265,5 +265,6 @@ INSERT INTO public.achievements (name, description, icon, points_value) VALUES
 ('List Sharer', 'Share a shopping list with another user for the first time.', 'list', 20),
 ('First Favorite', 'Mark a recipe as one of your favorites.', 'heart', 5),
 ('First Fork', 'Make a personal copy of a public recipe.', 'git-fork', 10),
-('First Budget Created', 'Create your first budget to track spending.', 'piggy-bank', 15)
+('First Budget Created', 'Create your first budget to track spending.', 'piggy-bank', 15),
 ('First-Upload', 'Upload your first flyer.', 'upload-cloud', 25)
 ON CONFLICT (name) DO NOTHING;
--- a/sql/initial_schema.sql
+++ b/sql/initial_schema.sql
@@ -8,16 +8,23 @@
 CREATE TABLE IF NOT EXISTS public.addresses (
    address_id BIGINT PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
    address_line_1 TEXT NOT NULL UNIQUE,
    address_line_2 TEXT,
    city TEXT NOT NULL,
    province_state TEXT NOT NULL,
    postal_code TEXT NOT NULL,
    country TEXT NOT NULL,
    address_line_2 TEXT,
    latitude NUMERIC(9, 6),
    longitude NUMERIC(9, 6),
    location GEOGRAPHY(Point, 4326),
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT addresses_address_line_1_check CHECK (TRIM(address_line_1) <> ''),
    CONSTRAINT addresses_city_check CHECK (TRIM(city) <> ''),
    CONSTRAINT addresses_province_state_check CHECK (TRIM(province_state) <> ''),
    CONSTRAINT addresses_postal_code_check CHECK (TRIM(postal_code) <> ''),
    CONSTRAINT addresses_country_check CHECK (TRIM(country) <> ''),
    CONSTRAINT addresses_latitude_check CHECK (latitude >= -90 AND latitude <= 90),
    CONSTRAINT addresses_longitude_check CHECK (longitude >= -180 AND longitude <= 180)
 );
 COMMENT ON TABLE public.addresses IS 'A centralized table for storing all physical addresses for users and stores.';
 COMMENT ON COLUMN public.addresses.latitude IS 'The geographic latitude.';
@@ -31,12 +38,14 @@ CREATE TABLE IF NOT EXISTS public.users (
    email TEXT NOT NULL UNIQUE,
    password_hash TEXT,
    refresh_token TEXT,
-    failed_login_attempts INTEGER DEFAULT 0,
+    failed_login_attempts INTEGER DEFAULT 0 CHECK (failed_login_attempts >= 0),
    last_failed_login TIMESTAMPTZ,
    last_login_at TIMESTAMPTZ,
    last_login_ip TEXT,
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT users_email_check CHECK (email ~* '^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$'),
    CONSTRAINT users_password_hash_check CHECK (password_hash IS NULL OR TRIM(password_hash) <> '')
 );
 COMMENT ON TABLE public.users IS 'Stores user authentication information.';
 COMMENT ON COLUMN public.users.refresh_token IS 'Stores the long-lived refresh token for re-authentication.';
@@ -59,10 +68,13 @@ CREATE TABLE IF NOT EXISTS public.activity_log (
    icon TEXT,
    details JSONB,
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT activity_log_action_check CHECK (TRIM(action) <> ''),
    CONSTRAINT activity_log_display_text_check CHECK (TRIM(display_text) <> '')
 );
 COMMENT ON TABLE public.activity_log IS 'Logs key user and system actions for auditing and display in an activity feed.';
-CREATE INDEX IF NOT EXISTS idx_activity_log_user_id ON public.activity_log(user_id);
+-- This composite index is more efficient for user-specific activity feeds ordered by date.
 CREATE INDEX IF NOT EXISTS idx_activity_log_user_id_created_at ON public.activity_log(user_id, created_at DESC);
 -- 3. for public user profiles.
 -- This table is linked to the users table and stores non-sensitive user data.
@@ -72,16 +84,20 @@ CREATE TABLE IF NOT EXISTS public.profiles (
  full_name TEXT,
  avatar_url TEXT,
  address_id BIGINT REFERENCES public.addresses(address_id) ON DELETE SET NULL,
  points INTEGER DEFAULT 0 NOT NULL CHECK (points >= 0),
  preferences JSONB,
  role TEXT CHECK (role IN ('admin', 'user')),
  points INTEGER DEFAULT 0 NOT NULL,
  created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
  updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
  CONSTRAINT profiles_full_name_check CHECK (full_name IS NULL OR TRIM(full_name) <> ''),
  CONSTRAINT profiles_avatar_url_check CHECK (avatar_url IS NULL OR avatar_url ~* '^https://?.*'),
  created_by UUID REFERENCES public.users(user_id) ON DELETE SET NULL,
  updated_by UUID REFERENCES public.users(user_id) ON DELETE SET NULL
 );
 COMMENT ON TABLE public.profiles IS 'Stores public-facing user data, linked to the public.users table.';
 COMMENT ON COLUMN public.profiles.address_id IS 'A foreign key to the user''s primary address in the `addresses` table.';
 -- This index is crucial for the gamification leaderboard feature.
 CREATE INDEX IF NOT EXISTS idx_profiles_points_leaderboard ON public.profiles (points DESC, full_name ASC);
 COMMENT ON COLUMN public.profiles.points IS 'A simple integer column to store a user''s total accumulated points from achievements.';
 -- 4. The 'stores' table for normalized store data.
@@ -91,6 +107,8 @@ CREATE TABLE IF NOT EXISTS public.stores (
  logo_url TEXT,
  created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
  updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
  CONSTRAINT stores_name_check CHECK (TRIM(name) <> ''),
  CONSTRAINT stores_logo_url_check CHECK (logo_url IS NULL OR logo_url ~* '^https://?.*'),
  created_by UUID REFERENCES public.users(user_id) ON DELETE SET NULL
 );
 COMMENT ON TABLE public.stores IS 'Stores metadata for grocery store chains (e.g., Safeway, Kroger).';
@@ -100,7 +118,8 @@ CREATE TABLE IF NOT EXISTS public.categories (
  category_id BIGINT PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
  name TEXT NOT NULL UNIQUE,
  created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-  updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+  updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
  CONSTRAINT categories_name_check CHECK (TRIM(name) <> '')
 );
 COMMENT ON TABLE public.categories IS 'Stores a predefined list of grocery item categories (e.g., ''Fruits & Vegetables'', ''Dairy & Eggs'').';
@@ -116,10 +135,15 @@ CREATE TABLE IF NOT EXISTS public.flyers (
  valid_to DATE,
  store_address TEXT,
  status TEXT DEFAULT 'processed' NOT NULL CHECK (status IN ('processed', 'needs_review', 'archived')),
-  item_count INTEGER DEFAULT 0 NOT NULL,
+  item_count INTEGER DEFAULT 0 NOT NULL CHECK (item_count >= 0),
  uploaded_by UUID REFERENCES public.users(user_id) ON DELETE SET NULL,
  created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-  updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+  updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
  CONSTRAINT flyers_valid_dates_check CHECK (valid_to >= valid_from),
  CONSTRAINT flyers_file_name_check CHECK (TRIM(file_name) <> ''),
  CONSTRAINT flyers_image_url_check CHECK (image_url ~* '^https://?.*'),
  CONSTRAINT flyers_icon_url_check CHECK (icon_url IS NULL OR icon_url ~* '^https://?.*'),
  CONSTRAINT flyers_checksum_check CHECK (checksum IS NULL OR length(checksum) = 64)
 );
 COMMENT ON TABLE public.flyers IS 'Stores metadata for each processed flyer, linking it to a store and its validity period.';
 CREATE INDEX IF NOT EXISTS idx_flyers_store_id ON public.flyers(store_id);
@@ -135,9 +159,9 @@ COMMENT ON COLUMN public.flyers.status IS 'The processing status of the flyer, e
 COMMENT ON COLUMN public.flyers.item_count IS 'A cached count of the number of items in this flyer, maintained by a trigger.';
 COMMENT ON COLUMN public.flyers.uploaded_by IS 'The user who uploaded the flyer. Can be null for anonymous or system uploads.';
 CREATE INDEX IF NOT EXISTS idx_flyers_status ON public.flyers(status);
 CREATE INDEX IF NOT EXISTS idx_flyers_created_at ON public.flyers (created_at DESC);
 CREATE INDEX IF NOT EXISTS idx_flyers_valid_to_file_name ON public.flyers (valid_to DESC, file_name ASC);
 CREATE INDEX IF NOT EXISTS idx_flyers_status ON public.flyers(status);
 -- 7. The 'master_grocery_items' table. This is the master dictionary.
 CREATE TABLE IF NOT EXISTS public.master_grocery_items (
    master_grocery_item_id BIGINT PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
@@ -147,7 +171,8 @@ CREATE TABLE IF NOT EXISTS public.master_grocery_items (
    allergy_info JSONB,
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    created_by UUID REFERENCES public.users(user_id) ON DELETE SET NULL
+    created_by UUID REFERENCES public.users(user_id) ON DELETE SET NULL,
    CONSTRAINT master_grocery_items_name_check CHECK (TRIM(name) <> '')
 );
 COMMENT ON TABLE public.master_grocery_items IS 'The master dictionary of canonical grocery items. Each item has a unique name and is linked to a category.';
 CREATE INDEX IF NOT EXISTS idx_master_grocery_items_category_id ON public.master_grocery_items(category_id);
@@ -172,7 +197,9 @@ CREATE TABLE IF NOT EXISTS public.brands (
    logo_url TEXT,
    store_id BIGINT REFERENCES public.stores(store_id) ON DELETE SET NULL,
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT brands_name_check CHECK (TRIM(name) <> ''),
    CONSTRAINT brands_logo_url_check CHECK (logo_url IS NULL OR logo_url ~* '^https://?.*')
 );
 COMMENT ON TABLE public.brands IS 'Stores brand names like "Coca-Cola", "Maple Leaf", or "Kraft".';
 COMMENT ON COLUMN public.brands.store_id IS 'If this is a store-specific brand (e.g., President''s Choice), this links to the parent store.';
@@ -187,7 +214,9 @@ CREATE TABLE IF NOT EXISTS public.products (
    size TEXT,
    upc_code TEXT UNIQUE,
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT products_name_check CHECK (TRIM(name) <> ''),
    CONSTRAINT products_upc_code_check CHECK (upc_code IS NULL OR upc_code ~ '^[0-9]{8,14}$')
 );
 COMMENT ON TABLE public.products IS 'Represents a specific, sellable product, combining a generic item with a brand and size.';
 COMMENT ON COLUMN public.products.upc_code IS 'Universal Product Code, if available, for exact product matching.';
@@ -203,18 +232,22 @@ CREATE TABLE IF NOT EXISTS public.flyer_items (
  flyer_id BIGINT REFERENCES public.flyers(flyer_id) ON DELETE CASCADE,
  item TEXT NOT NULL,
  price_display TEXT NOT NULL,
-  price_in_cents INTEGER,
+  price_in_cents INTEGER CHECK (price_in_cents IS NULL OR price_in_cents >= 0),
  quantity_num NUMERIC,
  quantity TEXT NOT NULL,
  category_id BIGINT REFERENCES public.categories(category_id) ON DELETE SET NULL,  
  category_name TEXT,
  unit_price JSONB,
-  view_count INTEGER DEFAULT 0 NOT NULL,
+  view_count INTEGER DEFAULT 0 NOT NULL CHECK (view_count >= 0),
-  click_count INTEGER DEFAULT 0 NOT NULL,
+  click_count INTEGER DEFAULT 0 NOT NULL CHECK (click_count >= 0),
  master_item_id BIGINT REFERENCES public.master_grocery_items(master_grocery_item_id) ON DELETE SET NULL,
  product_id BIGINT REFERENCES public.products(product_id) ON DELETE SET NULL,
  created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-  updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+  updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
  CONSTRAINT flyer_items_item_check CHECK (TRIM(item) <> ''),
  CONSTRAINT flyer_items_price_display_check CHECK (TRIM(price_display) <> ''),
  CONSTRAINT flyer_items_quantity_check CHECK (TRIM(quantity) <> ''),
  CONSTRAINT flyer_items_category_name_check CHECK (category_name IS NULL OR TRIM(category_name) <> '')
 );
 COMMENT ON TABLE public.flyer_items IS 'Stores individual items extracted from a specific flyer.';
 COMMENT ON COLUMN public.flyer_items.flyer_id IS 'Foreign key linking this item to its parent flyer in the `flyers` table.';
@@ -233,6 +266,8 @@ CREATE INDEX IF NOT EXISTS idx_flyer_items_master_item_id ON public.flyer_items(
 CREATE INDEX IF NOT EXISTS idx_flyer_items_category_id ON public.flyer_items(category_id);
 CREATE INDEX IF NOT EXISTS idx_flyer_items_product_id ON public.flyer_items(product_id);
 -- Add a GIN index to the 'item' column for fast fuzzy text searching.
 -- This partial index is optimized for queries that find the best price for an item.
 CREATE INDEX IF NOT EXISTS idx_flyer_items_master_item_price ON public.flyer_items (master_item_id, price_in_cents ASC) WHERE price_in_cents IS NOT NULL;
 -- This requires the pg_trgm extension.
 CREATE INDEX IF NOT EXISTS flyer_items_item_trgm_idx ON public.flyer_items USING GIN (item gin_trgm_ops);
@@ -241,7 +276,7 @@ CREATE TABLE IF NOT EXISTS public.user_alerts (
    user_alert_id BIGINT PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
    user_watched_item_id BIGINT NOT NULL REFERENCES public.user_watched_items(user_watched_item_id) ON DELETE CASCADE,
    alert_type TEXT NOT NULL CHECK (alert_type IN ('PRICE_BELOW', 'PERCENT_OFF_AVERAGE')),
-    threshold_value NUMERIC NOT NULL,
+    threshold_value NUMERIC NOT NULL CHECK (threshold_value > 0),
    is_active BOOLEAN DEFAULT true NOT NULL,
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
@@ -259,7 +294,8 @@ CREATE TABLE IF NOT EXISTS public.notifications (
    link_url TEXT,
    is_read BOOLEAN DEFAULT false NOT NULL,
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT notifications_content_check CHECK (TRIM(content) <> '')
 );
 COMMENT ON TABLE public.notifications IS 'A central log of notifications generated for users, such as price alerts.';
 COMMENT ON COLUMN public.notifications.content IS 'The notification message displayed to the user.';
@@ -272,8 +308,8 @@ CREATE TABLE IF NOT EXISTS public.store_locations (
    store_location_id BIGINT PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
    store_id BIGINT REFERENCES public.stores(store_id) ON DELETE CASCADE,
    address_id BIGINT NOT NULL REFERENCES public.addresses(address_id) ON DELETE CASCADE,
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    UNIQUE(store_id, address_id),
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
 );
 COMMENT ON TABLE public.store_locations IS 'Stores physical locations of stores with geographic data for proximity searches.';
@@ -285,13 +321,14 @@ CREATE TABLE IF NOT EXISTS public.item_price_history (
    master_item_id BIGINT NOT NULL REFERENCES public.master_grocery_items(master_grocery_item_id) ON DELETE CASCADE,
    summary_date DATE NOT NULL,
    store_location_id BIGINT REFERENCES public.store_locations(store_location_id) ON DELETE CASCADE,
-    min_price_in_cents INTEGER,
+    min_price_in_cents INTEGER CHECK (min_price_in_cents IS NULL OR min_price_in_cents >= 0),
-    max_price_in_cents INTEGER,
+    max_price_in_cents INTEGER CHECK (max_price_in_cents IS NULL OR max_price_in_cents >= 0),
-    avg_price_in_cents INTEGER,
+    avg_price_in_cents INTEGER CHECK (avg_price_in_cents IS NULL OR avg_price_in_cents >= 0),
-    data_points_count INTEGER DEFAULT 0 NOT NULL,
+    data_points_count INTEGER DEFAULT 0 NOT NULL CHECK (data_points_count >= 0),
    UNIQUE(master_item_id, summary_date, store_location_id),
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT item_price_history_price_order_check CHECK (min_price_in_cents <= max_price_in_cents)
 );
 COMMENT ON TABLE public.item_price_history IS 'Serves as a summary table to speed up charting and analytics.';
 COMMENT ON COLUMN public.item_price_history.summary_date IS 'The date for which the price data is summarized.';
@@ -308,7 +345,8 @@ CREATE TABLE IF NOT EXISTS public.master_item_aliases (
    master_item_id BIGINT NOT NULL REFERENCES public.master_grocery_items(master_grocery_item_id) ON DELETE CASCADE,
    alias TEXT NOT NULL UNIQUE,
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT master_item_aliases_alias_check CHECK (TRIM(alias) <> '')
 );
 COMMENT ON TABLE public.master_item_aliases IS 'Stores synonyms or alternative names for master items to improve matching.';
 COMMENT ON COLUMN public.master_item_aliases.alias IS 'An alternative name, e.g., "Ground Chuck" for the master item "Ground Beef".';
@@ -320,7 +358,8 @@ CREATE TABLE IF NOT EXISTS public.shopping_lists (
    user_id UUID NOT NULL REFERENCES public.users(user_id) ON DELETE CASCADE,
    name TEXT NOT NULL,
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT shopping_lists_name_check CHECK (TRIM(name) <> '')
 );
 COMMENT ON TABLE public.shopping_lists IS 'Stores user-created shopping lists, e.g., "Weekly Groceries".';
 CREATE INDEX IF NOT EXISTS idx_shopping_lists_user_id ON public.shopping_lists(user_id);
@@ -331,12 +370,13 @@ CREATE TABLE IF NOT EXISTS public.shopping_list_items (
    shopping_list_id BIGINT NOT NULL REFERENCES public.shopping_lists(shopping_list_id) ON DELETE CASCADE,
    master_item_id BIGINT REFERENCES public.master_grocery_items(master_grocery_item_id) ON DELETE CASCADE,
    custom_item_name TEXT,
-    quantity NUMERIC DEFAULT 1 NOT NULL,
+    quantity NUMERIC DEFAULT 1 NOT NULL CHECK (quantity > 0),
    is_purchased BOOLEAN DEFAULT false NOT NULL,
    notes TEXT,
    added_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    CONSTRAINT must_have_item_identifier CHECK (master_item_id IS NOT NULL OR custom_item_name IS NOT NULL)
+    CONSTRAINT must_have_item_identifier CHECK (master_item_id IS NOT NULL OR custom_item_name IS NOT NULL),
    CONSTRAINT shopping_list_items_custom_item_name_check CHECK (custom_item_name IS NULL OR TRIM(custom_item_name) <> '')
 );
 COMMENT ON TABLE public.shopping_list_items IS 'Contains individual items for a specific shopping list.';
 COMMENT ON COLUMN public.shopping_list_items.custom_item_name IS 'For items not in the master list, e.g., "Grandma''s special spice mix".';
@@ -344,7 +384,6 @@ COMMENT ON COLUMN public.shopping_list_items.is_purchased IS 'Lets users check i
 CREATE INDEX IF NOT EXISTS idx_shopping_list_items_shopping_list_id ON public.shopping_list_items(shopping_list_id);
 CREATE INDEX IF NOT EXISTS idx_shopping_list_items_master_item_id ON public.shopping_list_items(master_item_id);
 -- 17. Manage shared access to shopping lists.
 CREATE TABLE IF NOT EXISTS public.shared_shopping_lists (
    shared_shopping_list_id BIGINT PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
    shopping_list_id BIGINT NOT NULL REFERENCES public.shopping_lists(shopping_list_id) ON DELETE CASCADE,
@@ -369,6 +408,7 @@ CREATE TABLE IF NOT EXISTS public.menu_plans (
    end_date DATE NOT NULL,
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,    
    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT menu_plans_name_check CHECK (TRIM(name) <> ''),
    CONSTRAINT date_range_check CHECK (end_date >= start_date)
 );
 COMMENT ON TABLE public.menu_plans IS 'Represents a user''s meal plan for a specific period, e.g., "Week of Oct 23".';
@@ -397,11 +437,13 @@ CREATE TABLE IF NOT EXISTS public.suggested_corrections (
    user_id UUID NOT NULL REFERENCES public.users(user_id) ON DELETE CASCADE,
    correction_type TEXT NOT NULL,
    suggested_value TEXT NOT NULL,
-    status TEXT DEFAULT 'pending' NOT NULL,
+    status TEXT DEFAULT 'pending' NOT NULL CHECK (status IN ('pending', 'approved', 'rejected')),
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    reviewed_notes TEXT,
    reviewed_at TIMESTAMPTZ,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT suggested_corrections_correction_type_check CHECK (TRIM(correction_type) <> ''),
    CONSTRAINT suggested_corrections_suggested_value_check CHECK (TRIM(suggested_value) <> '')
 );
 COMMENT ON TABLE public.suggested_corrections IS 'A queue for user-submitted data corrections, enabling crowdsourced data quality improvements.';
 COMMENT ON COLUMN public.suggested_corrections.correction_type IS 'The type of error the user is reporting.';
@@ -417,12 +459,13 @@ CREATE TABLE IF NOT EXISTS public.user_submitted_prices (
    user_id UUID NOT NULL REFERENCES public.users(user_id) ON DELETE CASCADE,
    master_item_id BIGINT NOT NULL REFERENCES public.master_grocery_items(master_grocery_item_id) ON DELETE CASCADE,
    store_id BIGINT NOT NULL REFERENCES public.stores(store_id) ON DELETE CASCADE,
-    price_in_cents INTEGER NOT NULL,
+    price_in_cents INTEGER NOT NULL CHECK (price_in_cents > 0),
    photo_url TEXT,
-    upvotes INTEGER DEFAULT 0 NOT NULL,
+    upvotes INTEGER DEFAULT 0 NOT NULL CHECK (upvotes >= 0),
-    downvotes INTEGER DEFAULT 0 NOT NULL,
+    downvotes INTEGER DEFAULT 0 NOT NULL CHECK (downvotes >= 0),
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT user_submitted_prices_photo_url_check CHECK (photo_url IS NULL OR photo_url ~* '^https://?.*')
 );
 COMMENT ON TABLE public.user_submitted_prices IS 'Stores item prices submitted by users directly from physical stores.';
 COMMENT ON COLUMN public.user_submitted_prices.photo_url IS 'URL to user-submitted photo evidence of the price.';
@@ -464,20 +507,22 @@ CREATE TABLE IF NOT EXISTS public.recipes (
    name TEXT NOT NULL,
    description TEXT,
    instructions TEXT,
-    prep_time_minutes INTEGER,
+    prep_time_minutes INTEGER CHECK (prep_time_minutes IS NULL OR prep_time_minutes >= 0),
-    cook_time_minutes INTEGER,
+    cook_time_minutes INTEGER CHECK (cook_time_minutes IS NULL OR cook_time_minutes >= 0),
-    servings INTEGER,
+    servings INTEGER CHECK (servings IS NULL OR servings > 0),
    photo_url TEXT,
    calories_per_serving INTEGER,
    protein_grams NUMERIC,
    fat_grams NUMERIC,
    carb_grams NUMERIC,
-    avg_rating NUMERIC(2,1) DEFAULT 0.0 NOT NULL,
+    avg_rating NUMERIC(2,1) DEFAULT 0.0 NOT NULL CHECK (avg_rating >= 0.0 AND avg_rating <= 5.0),
-    status TEXT DEFAULT 'private' NOT NULL CHECK (status IN ('private', 'pending_review', 'public', 'rejected')),
+    status TEXT DEFAULT 'private' NOT NULL CHECK (status IN ('private', 'pending_review', 'public', 'rejected')),    
-    rating_count INTEGER DEFAULT 0 NOT NULL,
+    rating_count INTEGER DEFAULT 0 NOT NULL CHECK (rating_count >= 0),
-    fork_count INTEGER DEFAULT 0 NOT NULL,
+    fork_count INTEGER DEFAULT 0 NOT NULL CHECK (fork_count >= 0),
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT recipes_name_check CHECK (TRIM(name) <> ''),
    CONSTRAINT recipes_photo_url_check CHECK (photo_url IS NULL OR photo_url ~* '^https://?.*')
 );
 COMMENT ON TABLE public.recipes IS 'Stores recipes that can be used to generate shopping lists.';
 COMMENT ON COLUMN public.recipes.servings IS 'The number of servings this recipe yields.';
@@ -488,11 +533,11 @@ COMMENT ON COLUMN public.recipes.calories_per_serving IS 'Optional nutritional i
 COMMENT ON COLUMN public.recipes.protein_grams IS 'Optional nutritional information.';
 COMMENT ON COLUMN public.recipes.fat_grams IS 'Optional nutritional information.';
 COMMENT ON COLUMN public.recipes.carb_grams IS 'Optional nutritional information.';
 COMMENT ON COLUMN public.recipes.fork_count IS 'To track how many times a public recipe has been "forked" or copied by other users.';
 CREATE INDEX IF NOT EXISTS idx_recipes_user_id ON public.recipes(user_id);
 CREATE INDEX IF NOT EXISTS idx_recipes_original_recipe_id ON public.recipes(original_recipe_id);
 -- Add a partial unique index to ensure system-wide recipes (user_id IS NULL) have unique names.
-- This allows different users to have recipes with the same name.
+-- This index helps speed up sorting for recipe recommendations.
 CREATE INDEX IF NOT EXISTS idx_recipes_rating_sort ON public.recipes (avg_rating DESC, rating_count DESC);
 CREATE UNIQUE INDEX IF NOT EXISTS idx_recipes_unique_system_recipe_name ON public.recipes(name) WHERE user_id IS NULL;
 -- 27. For ingredients required for each recipe.
@@ -500,10 +545,11 @@ CREATE TABLE IF NOT EXISTS public.recipe_ingredients (
    recipe_ingredient_id BIGINT PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
    recipe_id BIGINT NOT NULL REFERENCES public.recipes(recipe_id) ON DELETE CASCADE,
    master_item_id BIGINT NOT NULL REFERENCES public.master_grocery_items(master_grocery_item_id) ON DELETE CASCADE,
-    quantity NUMERIC NOT NULL,
+    quantity NUMERIC NOT NULL CHECK (quantity > 0),
    unit TEXT NOT NULL,
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT recipe_ingredients_unit_check CHECK (TRIM(unit) <> '')
 );
 COMMENT ON TABLE public.recipe_ingredients IS 'Defines the ingredients and quantities needed for a recipe.';
 COMMENT ON COLUMN public.recipe_ingredients.unit IS 'e.g., "cups", "tbsp", "g", "each".';
@@ -529,7 +575,8 @@ CREATE TABLE IF NOT EXISTS public.tags (
    tag_id BIGINT PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
    name TEXT NOT NULL UNIQUE,
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT tags_name_check CHECK (TRIM(name) <> '')
 );
 COMMENT ON TABLE public.tags IS 'Stores tags for categorizing recipes, e.g., "Vegetarian", "Quick & Easy".';
@@ -543,6 +590,7 @@ CREATE TABLE IF NOT EXISTS public.recipe_tags (
 );
 COMMENT ON TABLE public.recipe_tags IS 'A linking table to associate multiple tags with a single recipe.';
 CREATE INDEX IF NOT EXISTS idx_recipe_tags_recipe_id ON public.recipe_tags(recipe_id);
 -- This index is crucial for functions that find recipes based on tags.
 CREATE INDEX IF NOT EXISTS idx_recipe_tags_tag_id ON public.recipe_tags(tag_id);
 -- 31. Store a predefined list of kitchen appliances.
@@ -550,7 +598,8 @@ CREATE TABLE IF NOT EXISTS public.appliances (
    appliance_id BIGINT PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
    name TEXT NOT NULL UNIQUE,
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT appliances_name_check CHECK (TRIM(name) <> '')
 );
 COMMENT ON TABLE public.appliances IS 'A predefined list of kitchen appliances (e.g., Air Fryer, Instant Pot).';
@@ -590,7 +639,8 @@ CREATE TABLE IF NOT EXISTS public.recipe_comments (
    content TEXT NOT NULL,
    status TEXT DEFAULT 'visible' NOT NULL CHECK (status IN ('visible', 'hidden', 'reported')),
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT recipe_comments_content_check CHECK (TRIM(content) <> '')
 );
 COMMENT ON TABLE public.recipe_comments IS 'Allows for threaded discussions and comments on recipes.';
 COMMENT ON COLUMN public.recipe_comments.parent_comment_id IS 'For threaded comments.';
@@ -605,6 +655,7 @@ CREATE TABLE IF NOT EXISTS public.pantry_locations (
    name TEXT NOT NULL,    
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT pantry_locations_name_check CHECK (TRIM(name) <> ''),
    UNIQUE(user_id, name)
 );
 COMMENT ON TABLE public.pantry_locations IS 'User-defined locations for organizing pantry items (e.g., "Fridge", "Freezer", "Spice Rack").';
@@ -618,8 +669,9 @@ CREATE TABLE IF NOT EXISTS public.planned_meals (
    plan_date DATE NOT NULL,
    meal_type TEXT NOT NULL,
    servings_to_cook INTEGER,
-    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
+    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,    
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT planned_meals_meal_type_check CHECK (TRIM(meal_type) <> '')
 );
 COMMENT ON TABLE public.planned_meals IS 'Assigns a recipe to a specific day and meal type within a user''s menu plan.';
 COMMENT ON COLUMN public.planned_meals.meal_type IS 'The designated meal for the recipe, e.g., ''Breakfast'', ''Lunch'', ''Dinner''.';
@@ -631,7 +683,7 @@ CREATE TABLE IF NOT EXISTS public.pantry_items (
    pantry_item_id BIGINT PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
    user_id UUID NOT NULL REFERENCES public.users(user_id) ON DELETE CASCADE,
    master_item_id BIGINT NOT NULL REFERENCES public.master_grocery_items(master_grocery_item_id) ON DELETE CASCADE,
-    quantity NUMERIC NOT NULL,
+    quantity NUMERIC NOT NULL CHECK (quantity >= 0),
    unit TEXT,
    best_before_date DATE,
    pantry_location_id BIGINT REFERENCES public.pantry_locations(pantry_location_id) ON DELETE SET NULL,
@@ -640,7 +692,6 @@ CREATE TABLE IF NOT EXISTS public.pantry_items (
    UNIQUE(user_id, master_item_id, unit)
 );
 COMMENT ON TABLE public.pantry_items IS 'Tracks a user''s personal inventory of grocery items to enable smart shopping lists.';
 COMMENT ON COLUMN public.pantry_items.quantity IS 'The current amount of the item. Convention: use grams for weight, mL for volume where applicable.';
 COMMENT ON COLUMN public.pantry_items.pantry_location_id IS 'Links the item to a user-defined location like "Fridge" or "Freezer".';
 COMMENT ON COLUMN public.pantry_items.unit IS 'e.g., ''g'', ''ml'', ''items''. Should align with recipe_ingredients.unit and quantity convention.';
 CREATE INDEX IF NOT EXISTS idx_pantry_items_user_id ON public.pantry_items(user_id);
@@ -654,7 +705,8 @@ CREATE TABLE IF NOT EXISTS public.password_reset_tokens (
    token_hash TEXT NOT NULL UNIQUE,
    expires_at TIMESTAMPTZ NOT NULL,
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT password_reset_tokens_token_hash_check CHECK (TRIM(token_hash) <> '')
 );
 COMMENT ON TABLE public.password_reset_tokens IS 'Stores secure, single-use tokens for password reset requests.';
 COMMENT ON COLUMN public.password_reset_tokens.token_hash IS 'A bcrypt hash of the reset token sent to the user.';
@@ -669,10 +721,13 @@ CREATE TABLE IF NOT EXISTS public.unit_conversions (
    master_item_id BIGINT NOT NULL REFERENCES public.master_grocery_items(master_grocery_item_id) ON DELETE CASCADE,
    from_unit TEXT NOT NULL,
    to_unit TEXT NOT NULL,
-    factor NUMERIC NOT NULL,
+    factor NUMERIC NOT NULL CHECK (factor > 0),
    UNIQUE(master_item_id, from_unit, to_unit),
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT unit_conversions_from_unit_check CHECK (TRIM(from_unit) <> ''),
    CONSTRAINT unit_conversions_to_unit_check CHECK (TRIM(to_unit) <> ''),
    CONSTRAINT unit_conversions_units_check CHECK (from_unit <> to_unit)
 );
 COMMENT ON TABLE public.unit_conversions IS 'Stores item-specific unit conversion factors (e.g., grams of flour to cups).';
 COMMENT ON COLUMN public.unit_conversions.factor IS 'The multiplication factor to convert from_unit to to_unit.';
@@ -686,7 +741,8 @@ CREATE TABLE IF NOT EXISTS public.user_item_aliases (
    alias TEXT NOT NULL,
    UNIQUE(user_id, alias),
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT user_item_aliases_alias_check CHECK (TRIM(alias) <> '')
 );
 COMMENT ON TABLE public.user_item_aliases IS 'Allows users to create personal aliases for grocery items (e.g., "Dad''s Cereal").';
 CREATE INDEX IF NOT EXISTS idx_user_item_aliases_user_id ON public.user_item_aliases(user_id);
@@ -723,7 +779,8 @@ CREATE TABLE IF NOT EXISTS public.recipe_collections (
    name TEXT NOT NULL,
    description TEXT,
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT recipe_collections_name_check CHECK (TRIM(name) <> '')
 );
 COMMENT ON TABLE public.recipe_collections IS 'Allows users to create personal collections of recipes (e.g., "Holiday Baking").';
 CREATE INDEX IF NOT EXISTS idx_recipe_collections_user_id ON public.recipe_collections(user_id);
@@ -748,8 +805,11 @@ CREATE TABLE IF NOT EXISTS public.shared_recipe_collections (
    shared_with_user_id UUID NOT NULL REFERENCES public.users(user_id) ON DELETE CASCADE,
    permission_level TEXT NOT NULL CHECK (permission_level IN ('view', 'edit')),
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    UNIQUE(recipe_collection_id, shared_with_user_id)
 );
 -- This index is crucial for efficiently finding all collections shared with a specific user.
 CREATE INDEX IF NOT EXISTS idx_shared_recipe_collections_shared_with ON public.shared_recipe_collections(shared_with_user_id);
 -- 45. Log user search queries for analysis.
 CREATE TABLE IF NOT EXISTS public.search_queries (
@@ -759,7 +819,8 @@ CREATE TABLE IF NOT EXISTS public.search_queries (
    result_count INTEGER,
    was_successful BOOLEAN,
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT search_queries_query_text_check CHECK (TRIM(query_text) <> '')
 );
 COMMENT ON TABLE public.search_queries IS 'Logs user search queries to analyze search effectiveness and identify gaps in data.';
 COMMENT ON COLUMN public.search_queries.was_successful IS 'Indicates if the user interacted with a search result.';
@@ -785,10 +846,11 @@ CREATE TABLE IF NOT EXISTS public.shopping_trip_items (
    shopping_trip_id BIGINT NOT NULL REFERENCES public.shopping_trips(shopping_trip_id) ON DELETE CASCADE,
    master_item_id BIGINT REFERENCES public.master_grocery_items(master_grocery_item_id) ON DELETE SET NULL,
    custom_item_name TEXT,
-    quantity NUMERIC NOT NULL,
+    quantity NUMERIC NOT NULL CHECK (quantity > 0),
    price_paid_cents INTEGER,    
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT shopping_trip_items_custom_item_name_check CHECK (custom_item_name IS NULL OR TRIM(custom_item_name) <> ''),
    CONSTRAINT trip_must_have_item_identifier CHECK (master_item_id IS NOT NULL OR custom_item_name IS NOT NULL)
 );
 COMMENT ON TABLE public.shopping_trip_items IS 'A historical log of items purchased during a shopping trip.';
@@ -802,7 +864,8 @@ CREATE TABLE IF NOT EXISTS public.dietary_restrictions (
    name TEXT NOT NULL UNIQUE,
    type TEXT NOT NULL CHECK (type IN ('diet', 'allergy')),
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT dietary_restrictions_name_check CHECK (TRIM(name) <> '')
 );
 COMMENT ON TABLE public.dietary_restrictions IS 'A predefined list of common diets (e.g., Vegan) and allergies (e.g., Nut Allergy).';
@@ -815,6 +878,7 @@ CREATE TABLE IF NOT EXISTS public.user_dietary_restrictions (
    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
 );
 COMMENT ON TABLE public.user_dietary_restrictions IS 'Connects users to their selected dietary needs and allergies.';
 -- This index is crucial for functions that filter recipes based on user diets/allergies.
 CREATE INDEX IF NOT EXISTS idx_user_dietary_restrictions_user_id ON public.user_dietary_restrictions(user_id);
 CREATE INDEX IF NOT EXISTS idx_user_dietary_restrictions_restriction_id ON public.user_dietary_restrictions(restriction_id);
@@ -840,6 +904,7 @@ CREATE TABLE IF NOT EXISTS public.user_follows (
    CONSTRAINT cant_follow_self CHECK (follower_id <> following_id)
 );
 COMMENT ON TABLE public.user_follows IS 'Stores user following relationships to build a social graph.';
 -- This index is crucial for efficiently generating a user's activity feed.
 CREATE INDEX IF NOT EXISTS idx_user_follows_follower_id ON public.user_follows(follower_id);
 CREATE INDEX IF NOT EXISTS idx_user_follows_following_id ON public.user_follows(following_id);
@@ -850,12 +915,13 @@ CREATE TABLE IF NOT EXISTS public.receipts (
    store_id BIGINT REFERENCES public.stores(store_id) ON DELETE CASCADE,
    receipt_image_url TEXT NOT NULL,
    transaction_date TIMESTAMPTZ,
-    total_amount_cents INTEGER,
+    total_amount_cents INTEGER CHECK (total_amount_cents IS NULL OR total_amount_cents >= 0),
    status TEXT DEFAULT 'pending' NOT NULL CHECK (status IN ('pending', 'processing', 'completed', 'failed')),
    raw_text TEXT,
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    processed_at TIMESTAMPTZ,
+    processed_at TIMESTAMPTZ,    
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT receipts_receipt_image_url_check CHECK (receipt_image_url ~* '^https://?.*')
 );
 COMMENT ON TABLE public.receipts IS 'Stores uploaded user receipts for purchase tracking and analysis.';
 CREATE INDEX IF NOT EXISTS idx_receipts_user_id ON public.receipts(user_id);
@@ -866,13 +932,14 @@ CREATE TABLE IF NOT EXISTS public.receipt_items (
    receipt_item_id BIGINT PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
    receipt_id BIGINT NOT NULL REFERENCES public.receipts(receipt_id) ON DELETE CASCADE,
    raw_item_description TEXT NOT NULL,
-    quantity NUMERIC DEFAULT 1 NOT NULL,
+    quantity NUMERIC DEFAULT 1 NOT NULL CHECK (quantity > 0),
-    price_paid_cents INTEGER NOT NULL,
+    price_paid_cents INTEGER NOT NULL CHECK (price_paid_cents >= 0),
    master_item_id BIGINT REFERENCES public.master_grocery_items(master_grocery_item_id) ON DELETE SET NULL,
    product_id BIGINT REFERENCES public.products(product_id) ON DELETE SET NULL,
    status TEXT DEFAULT 'unmatched' NOT NULL CHECK (status IN ('unmatched', 'matched', 'needs_review', 'ignored')),
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT receipt_items_raw_item_description_check CHECK (TRIM(raw_item_description) <> '')
 );
 COMMENT ON TABLE public.receipt_items IS 'Stores individual line items extracted from a user receipt.';
 CREATE INDEX IF NOT EXISTS idx_receipt_items_receipt_id ON public.receipt_items(receipt_id);
@@ -885,7 +952,6 @@ CREATE TABLE IF NOT EXISTS public.schema_info (
    deployed_at TIMESTAMPTZ DEFAULT now() NOT NULL
 );
 COMMENT ON TABLE public.schema_info IS 'Stores metadata about the deployed schema, such as a hash of the schema file, to detect changes.';
 COMMENT ON COLUMN public.schema_info.environment IS 'The deployment environment (e.g., ''development'', ''test'', ''production'').';
 COMMENT ON COLUMN public.schema_info.schema_hash IS 'A SHA-256 hash of the master_schema_rollup.sql file at the time of deployment.';
 -- 55. Store user reactions to various entities (e.g., recipes, comments).
@@ -906,14 +972,31 @@ COMMENT ON COLUMN public.user_reactions.reaction_type IS 'The type of reaction (
 CREATE INDEX IF NOT EXISTS idx_user_reactions_user_id ON public.user_reactions(user_id);
 CREATE INDEX IF NOT EXISTS idx_user_reactions_entity ON public.user_reactions(entity_type, entity_id);
 -- 56. Store user-defined budgets for spending analysis.
 CREATE TABLE IF NOT EXISTS public.budgets (
    budget_id BIGINT PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
    user_id UUID NOT NULL REFERENCES public.users(user_id) ON DELETE CASCADE,
    name TEXT NOT NULL,
    amount_cents INTEGER NOT NULL CHECK (amount_cents > 0),
    period TEXT NOT NULL CHECK (period IN ('weekly', 'monthly')),
    start_date DATE NOT NULL,
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,    
    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT budgets_name_check CHECK (TRIM(name) <> '')
 );
 COMMENT ON TABLE public.budgets IS 'Allows users to set weekly or monthly grocery budgets for spending tracking.';
 CREATE INDEX IF NOT EXISTS idx_budgets_user_id ON public.budgets(user_id);
 -- 57. Static table defining available achievements for gamification.
 CREATE TABLE IF NOT EXISTS public.achievements (
    achievement_id BIGINT PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
    name TEXT NOT NULL UNIQUE,
    description TEXT NOT NULL,
    icon TEXT,
-    points_value INTEGER NOT NULL DEFAULT 0,
+    points_value INTEGER NOT NULL DEFAULT 0 CHECK (points_value >= 0),    
-    created_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT achievements_name_check CHECK (TRIM(name) <> ''),
    CONSTRAINT achievements_description_check CHECK (TRIM(description) <> '')
 );
 COMMENT ON TABLE public.achievements IS 'A static table defining the available achievements users can earn.';
@@ -929,16 +1012,3 @@ CREATE INDEX IF NOT EXISTS idx_user_achievements_user_id ON public.user_achievem
 CREATE INDEX IF NOT EXISTS idx_user_achievements_achievement_id ON public.user_achievements(achievement_id);
 -- 56. Store user-defined budgets for spending analysis.
 CREATE TABLE IF NOT EXISTS public.budgets (
    budget_id BIGINT PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
    user_id UUID NOT NULL REFERENCES public.users(user_id) ON DELETE CASCADE,
    name TEXT NOT NULL,
    amount_cents INTEGER NOT NULL,
    period TEXT NOT NULL CHECK (period IN ('weekly', 'monthly')),
    start_date DATE NOT NULL,
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
 );
 COMMENT ON TABLE public.budgets IS 'Allows users to set weekly or monthly grocery budgets for spending tracking.';
 CREATE INDEX IF NOT EXISTS idx_budgets_user_id ON public.budgets(user_id);
--- a/sql/master_schema_rollup.sql
+++ b/sql/master_schema_rollup.sql
@@ -23,16 +23,23 @@
 CREATE TABLE IF NOT EXISTS public.addresses (
    address_id BIGINT PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
    address_line_1 TEXT NOT NULL UNIQUE,
    address_line_2 TEXT,
    city TEXT NOT NULL,
    province_state TEXT NOT NULL,
    postal_code TEXT NOT NULL,
    country TEXT NOT NULL,
    address_line_2 TEXT,
    latitude NUMERIC(9, 6),
    longitude NUMERIC(9, 6),
    location GEOGRAPHY(Point, 4326),
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT addresses_address_line_1_check CHECK (TRIM(address_line_1) <> ''),
    CONSTRAINT addresses_city_check CHECK (TRIM(city) <> ''),
    CONSTRAINT addresses_province_state_check CHECK (TRIM(province_state) <> ''),
    CONSTRAINT addresses_postal_code_check CHECK (TRIM(postal_code) <> ''),
    CONSTRAINT addresses_country_check CHECK (TRIM(country) <> ''),
    CONSTRAINT addresses_latitude_check CHECK (latitude >= -90 AND latitude <= 90),
    CONSTRAINT addresses_longitude_check CHECK (longitude >= -180 AND longitude <= 180)
 );
 COMMENT ON TABLE public.addresses IS 'A centralized table for storing all physical addresses for users and stores.';
 COMMENT ON COLUMN public.addresses.latitude IS 'The geographic latitude.';
@@ -45,14 +52,16 @@ CREATE INDEX IF NOT EXISTS addresses_location_idx ON public.addresses USING GIST
 CREATE TABLE IF NOT EXISTS public.users (
    user_id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    email TEXT NOT NULL UNIQUE,
-    password_hash TEXT,
+    password_hash TEXT,    
    refresh_token TEXT,
-    failed_login_attempts INTEGER DEFAULT 0,
+    failed_login_attempts INTEGER DEFAULT 0 CHECK (failed_login_attempts >= 0),
    last_failed_login TIMESTAMPTZ,
    last_login_at TIMESTAMPTZ,
    last_login_ip TEXT,
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT users_email_check CHECK (email ~* '^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$'),
    CONSTRAINT users_password_hash_check CHECK (password_hash IS NULL OR TRIM(password_hash) <> '')
 );
 COMMENT ON TABLE public.users IS 'Stores user authentication information.';
 COMMENT ON COLUMN public.users.refresh_token IS 'Stores the long-lived refresh token for re-authentication.';
@@ -74,11 +83,14 @@ CREATE TABLE IF NOT EXISTS public.activity_log (
    display_text TEXT NOT NULL,
    icon TEXT,
    details JSONB,
-    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
+    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,    
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT activity_log_action_check CHECK (TRIM(action) <> ''),
    CONSTRAINT activity_log_display_text_check CHECK (TRIM(display_text) <> '')
 );
 COMMENT ON TABLE public.activity_log IS 'Logs key user and system actions for auditing and display in an activity feed.';
-CREATE INDEX IF NOT EXISTS idx_activity_log_user_id ON public.activity_log(user_id);
+-- This composite index is more efficient for user-specific activity feeds ordered by date.
 CREATE INDEX IF NOT EXISTS idx_activity_log_user_id_created_at ON public.activity_log(user_id, created_at DESC);
 -- 3. for public user profiles.
 -- This table is linked to the users table and stores non-sensitive user data.
@@ -88,16 +100,20 @@ CREATE TABLE IF NOT EXISTS public.profiles (
    full_name TEXT,
    avatar_url TEXT,
    address_id BIGINT REFERENCES public.addresses(address_id) ON DELETE SET NULL,
-    points INTEGER DEFAULT 0 NOT NULL,
+    points INTEGER DEFAULT 0 NOT NULL CHECK (points >= 0),
    preferences JSONB,
-    role TEXT CHECK (role IN ('admin', 'user')),
+    role TEXT NOT NULL CHECK (role IN ('admin', 'user')),
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    created_by UUID REFERENCES public.users(user_id) ON DELETE SET NULL,
+    CONSTRAINT profiles_full_name_check CHECK (full_name IS NULL OR TRIM(full_name) <> ''),
    CONSTRAINT profiles_avatar_url_check CHECK (avatar_url IS NULL OR avatar_url ~* '^https?://.*'),
    created_by UUID REFERENCES public.users(user_id) ON DELETE SET NULL,    
    updated_by UUID REFERENCES public.users(user_id) ON DELETE SET NULL
 );
 COMMENT ON TABLE public.profiles IS 'Stores public-facing user data, linked to the public.users table.';
 COMMENT ON COLUMN public.profiles.address_id IS 'A foreign key to the user''s primary address in the `addresses` table.';
 -- This index is crucial for the gamification leaderboard feature.
 CREATE INDEX IF NOT EXISTS idx_profiles_points_leaderboard ON public.profiles (points DESC, full_name ASC);
 COMMENT ON COLUMN public.profiles.points IS 'A simple integer column to store a user''s total accumulated points from achievements.';
 -- 4. The 'stores' table for normalized store data.
@@ -107,7 +123,9 @@ CREATE TABLE IF NOT EXISTS public.stores (
    logo_url TEXT,
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    created_by UUID REFERENCES public.users(user_id) ON DELETE SET NULL
+    CONSTRAINT stores_name_check CHECK (TRIM(name) <> ''),
    CONSTRAINT stores_logo_url_check CHECK (logo_url IS NULL OR logo_url ~* '^https?://.*'),
    created_by UUID REFERENCES public.users(user_id) ON DELETE SET NULL    
 );
 COMMENT ON TABLE public.stores IS 'Stores metadata for grocery store chains (e.g., Safeway, Kroger).';
@@ -116,7 +134,8 @@ CREATE TABLE IF NOT EXISTS public.categories (
    category_id BIGINT PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
    name TEXT NOT NULL UNIQUE,
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT categories_name_check CHECK (TRIM(name) <> '')
 );
 COMMENT ON TABLE public.categories IS 'Stores a predefined list of grocery item categories (e.g., ''Fruits & Vegetables'', ''Dairy & Eggs'').';
@@ -125,17 +144,22 @@ CREATE TABLE IF NOT EXISTS public.flyers (
    flyer_id BIGINT PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
    file_name TEXT NOT NULL,
    image_url TEXT NOT NULL,
-    icon_url TEXT,
+    icon_url TEXT NOT NULL,
-  checksum TEXT UNIQUE,  
+    checksum TEXT UNIQUE,  
-  store_id BIGINT REFERENCES public.stores(store_id) ON DELETE CASCADE,
+    store_id BIGINT REFERENCES public.stores(store_id) ON DELETE CASCADE,
    valid_from DATE,
    valid_to DATE,
    store_address TEXT,
-  status TEXT DEFAULT 'processed' NOT NULL CHECK (status IN ('processed', 'needs_review', 'archived')),
+    status TEXT DEFAULT 'processed' NOT NULL CHECK (status IN ('processed', 'needs_review', 'archived')),
-    item_count INTEGER DEFAULT 0 NOT NULL,
+    item_count INTEGER DEFAULT 0 NOT NULL CHECK (item_count >= 0),
    uploaded_by UUID REFERENCES public.users(user_id) ON DELETE SET NULL,
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT flyers_valid_dates_check CHECK (valid_to >= valid_from),
    CONSTRAINT flyers_file_name_check CHECK (TRIM(file_name) <> ''),
    CONSTRAINT flyers_image_url_check CHECK (image_url ~* '^https?://.*'),
    CONSTRAINT flyers_icon_url_check CHECK (icon_url ~* '^https?://.*'),
    CONSTRAINT flyers_checksum_check CHECK (checksum IS NULL OR length(checksum) = 64)
 );
 COMMENT ON TABLE public.flyers IS 'Stores metadata for each processed flyer, linking it to a store and its validity period.';
 CREATE INDEX IF NOT EXISTS idx_flyers_store_id ON public.flyers(store_id);
@@ -151,9 +175,9 @@ COMMENT ON COLUMN public.flyers.status IS 'The processing status of the flyer, e
 COMMENT ON COLUMN public.flyers.item_count IS 'A cached count of the number of items in this flyer, maintained by a trigger.';
 COMMENT ON COLUMN public.flyers.uploaded_by IS 'The user who uploaded the flyer. Can be null for anonymous or system uploads.';
 CREATE INDEX IF NOT EXISTS idx_flyers_status ON public.flyers(status);
 CREATE INDEX IF NOT EXISTS idx_flyers_created_at ON public.flyers (created_at DESC);
 CREATE INDEX IF NOT EXISTS idx_flyers_valid_to_file_name ON public.flyers (valid_to DESC, file_name ASC);
 CREATE INDEX IF NOT EXISTS idx_flyers_status ON public.flyers(status);
 -- 7. The 'master_grocery_items' table. This is the master dictionary.
 CREATE TABLE IF NOT EXISTS public.master_grocery_items (
    master_grocery_item_id BIGINT PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
@@ -163,7 +187,8 @@ CREATE TABLE IF NOT EXISTS public.master_grocery_items (
    allergy_info JSONB,
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    created_by UUID REFERENCES public.users(user_id) ON DELETE SET NULL
+    created_by UUID REFERENCES public.users(user_id) ON DELETE SET NULL,
    CONSTRAINT master_grocery_items_name_check CHECK (TRIM(name) <> '')
 );
 COMMENT ON TABLE public.master_grocery_items IS 'The master dictionary of canonical grocery items. Each item has a unique name and is linked to a category.';
 CREATE INDEX IF NOT EXISTS idx_master_grocery_items_category_id ON public.master_grocery_items(category_id);
@@ -188,7 +213,9 @@ CREATE TABLE IF NOT EXISTS public.brands (
    logo_url TEXT,
    store_id BIGINT REFERENCES public.stores(store_id) ON DELETE SET NULL,
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT brands_name_check CHECK (TRIM(name) <> ''),
    CONSTRAINT brands_logo_url_check CHECK (logo_url IS NULL OR logo_url ~* '^https?://.*')
 );
 COMMENT ON TABLE public.brands IS 'Stores brand names like "Coca-Cola", "Maple Leaf", or "Kraft".';
 COMMENT ON COLUMN public.brands.store_id IS 'If this is a store-specific brand (e.g., President''s Choice), this links to the parent store.';
@@ -203,7 +230,9 @@ CREATE TABLE IF NOT EXISTS public.products (
    size TEXT,
    upc_code TEXT UNIQUE,
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT products_name_check CHECK (TRIM(name) <> ''),
    CONSTRAINT products_upc_code_check CHECK (upc_code IS NULL OR upc_code ~ '^[0-9]{8,14}$')
 );
 COMMENT ON TABLE public.products IS 'Represents a specific, sellable product, combining a generic item with a brand and size.';
 COMMENT ON COLUMN public.products.upc_code IS 'Universal Product Code, if available, for exact product matching.';
@@ -219,18 +248,22 @@ CREATE TABLE IF NOT EXISTS public.flyer_items (
  flyer_id BIGINT REFERENCES public.flyers(flyer_id) ON DELETE CASCADE,
  item TEXT NOT NULL,
  price_display TEXT NOT NULL,
-  price_in_cents INTEGER,
+  price_in_cents INTEGER CHECK (price_in_cents IS NULL OR price_in_cents >= 0),
  quantity_num NUMERIC,
  quantity TEXT NOT NULL,
  category_id BIGINT REFERENCES public.categories(category_id) ON DELETE SET NULL,  
  category_name TEXT,
  unit_price JSONB,
-  view_count INTEGER DEFAULT 0 NOT NULL,
+  view_count INTEGER DEFAULT 0 NOT NULL CHECK (view_count >= 0),
-  click_count INTEGER DEFAULT 0 NOT NULL,
+  click_count INTEGER DEFAULT 0 NOT NULL CHECK (click_count >= 0),
  master_item_id BIGINT REFERENCES public.master_grocery_items(master_grocery_item_id) ON DELETE SET NULL,
  product_id BIGINT REFERENCES public.products(product_id) ON DELETE SET NULL,
  created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-  updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+  updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
  CONSTRAINT flyer_items_item_check CHECK (TRIM(item) <> ''),
  CONSTRAINT flyer_items_price_display_check CHECK (TRIM(price_display) <> ''),
  CONSTRAINT flyer_items_quantity_check CHECK (TRIM(quantity) <> ''),
  CONSTRAINT flyer_items_category_name_check CHECK (category_name IS NULL OR TRIM(category_name) <> '')
 );
 COMMENT ON TABLE public.flyer_items IS 'Stores individual items extracted from a specific flyer.';
 COMMENT ON COLUMN public.flyer_items.flyer_id IS 'Foreign key linking this item to its parent flyer in the `flyers` table.';
@@ -249,6 +282,8 @@ CREATE INDEX IF NOT EXISTS idx_flyer_items_master_item_id ON public.flyer_items(
 CREATE INDEX IF NOT EXISTS idx_flyer_items_category_id ON public.flyer_items(category_id);
 CREATE INDEX IF NOT EXISTS idx_flyer_items_product_id ON public.flyer_items(product_id);
 -- Add a GIN index to the 'item' column for fast fuzzy text searching.
 -- This partial index is optimized for queries that find the best price for an item.
 CREATE INDEX IF NOT EXISTS idx_flyer_items_master_item_price ON public.flyer_items (master_item_id, price_in_cents ASC) WHERE price_in_cents IS NOT NULL;
 -- This requires the pg_trgm extension.
 CREATE INDEX IF NOT EXISTS flyer_items_item_trgm_idx ON public.flyer_items USING GIN (item gin_trgm_ops);
@@ -257,7 +292,7 @@ CREATE TABLE IF NOT EXISTS public.user_alerts (
    user_alert_id BIGINT PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
    user_watched_item_id BIGINT NOT NULL REFERENCES public.user_watched_items(user_watched_item_id) ON DELETE CASCADE,
    alert_type TEXT NOT NULL CHECK (alert_type IN ('PRICE_BELOW', 'PERCENT_OFF_AVERAGE')),
-    threshold_value NUMERIC NOT NULL,
+    threshold_value NUMERIC NOT NULL CHECK (threshold_value > 0),
    is_active BOOLEAN DEFAULT true NOT NULL,
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
@@ -275,7 +310,8 @@ CREATE TABLE IF NOT EXISTS public.notifications (
    link_url TEXT,
    is_read BOOLEAN DEFAULT false NOT NULL,
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT notifications_content_check CHECK (TRIM(content) <> '')
 );
 COMMENT ON TABLE public.notifications IS 'A central log of notifications generated for users, such as price alerts.';
 COMMENT ON COLUMN public.notifications.content IS 'The notification message displayed to the user.';
@@ -301,13 +337,14 @@ CREATE TABLE IF NOT EXISTS public.item_price_history (
    master_item_id BIGINT NOT NULL REFERENCES public.master_grocery_items(master_grocery_item_id) ON DELETE CASCADE,
    summary_date DATE NOT NULL,
    store_location_id BIGINT REFERENCES public.store_locations(store_location_id) ON DELETE CASCADE,
-    min_price_in_cents INTEGER,
+    min_price_in_cents INTEGER CHECK (min_price_in_cents IS NULL OR min_price_in_cents >= 0),
-    max_price_in_cents INTEGER,
+    max_price_in_cents INTEGER CHECK (max_price_in_cents IS NULL OR max_price_in_cents >= 0),
-    avg_price_in_cents INTEGER,
+    avg_price_in_cents INTEGER CHECK (avg_price_in_cents IS NULL OR avg_price_in_cents >= 0),
-    data_points_count INTEGER DEFAULT 0 NOT NULL,
+    data_points_count INTEGER DEFAULT 0 NOT NULL CHECK (data_points_count >= 0),
    UNIQUE(master_item_id, summary_date, store_location_id),
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT item_price_history_price_order_check CHECK (min_price_in_cents <= max_price_in_cents)
 );
 COMMENT ON TABLE public.item_price_history IS 'Serves as a summary table to speed up charting and analytics.';
 COMMENT ON COLUMN public.item_price_history.summary_date IS 'The date for which the price data is summarized.';
@@ -324,7 +361,8 @@ CREATE TABLE IF NOT EXISTS public.master_item_aliases (
    master_item_id BIGINT NOT NULL REFERENCES public.master_grocery_items(master_grocery_item_id) ON DELETE CASCADE,
    alias TEXT NOT NULL UNIQUE,
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT master_item_aliases_alias_check CHECK (TRIM(alias) <> '')
 );
 COMMENT ON TABLE public.master_item_aliases IS 'Stores synonyms or alternative names for master items to improve matching.';
 COMMENT ON COLUMN public.master_item_aliases.alias IS 'An alternative name, e.g., "Ground Chuck" for the master item "Ground Beef".';
@@ -336,7 +374,8 @@ CREATE TABLE IF NOT EXISTS public.shopping_lists (
    user_id UUID NOT NULL REFERENCES public.users(user_id) ON DELETE CASCADE,
    name TEXT NOT NULL,
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT shopping_lists_name_check CHECK (TRIM(name) <> '')
 );
 COMMENT ON TABLE public.shopping_lists IS 'Stores user-created shopping lists, e.g., "Weekly Groceries".';
 CREATE INDEX IF NOT EXISTS idx_shopping_lists_user_id ON public.shopping_lists(user_id);
@@ -347,12 +386,13 @@ CREATE TABLE IF NOT EXISTS public.shopping_list_items (
    shopping_list_id BIGINT NOT NULL REFERENCES public.shopping_lists(shopping_list_id) ON DELETE CASCADE,
    master_item_id BIGINT REFERENCES public.master_grocery_items(master_grocery_item_id) ON DELETE CASCADE,
    custom_item_name TEXT,
-    quantity NUMERIC DEFAULT 1 NOT NULL,
+    quantity NUMERIC DEFAULT 1 NOT NULL CHECK (quantity > 0),
    is_purchased BOOLEAN DEFAULT false NOT NULL,
    notes TEXT,
    added_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    CONSTRAINT must_have_item_identifier CHECK (master_item_id IS NOT NULL OR custom_item_name IS NOT NULL)
+    CONSTRAINT must_have_item_identifier CHECK (master_item_id IS NOT NULL OR custom_item_name IS NOT NULL),
    CONSTRAINT shopping_list_items_custom_item_name_check CHECK (custom_item_name IS NULL OR TRIM(custom_item_name) <> '')
 );
 COMMENT ON TABLE public.shopping_list_items IS 'Contains individual items for a specific shopping list.';
 COMMENT ON COLUMN public.shopping_list_items.custom_item_name IS 'For items not in the master list, e.g., "Grandma''s special spice mix".';
@@ -384,7 +424,8 @@ CREATE TABLE IF NOT EXISTS public.menu_plans (
    start_date DATE NOT NULL,
    end_date DATE NOT NULL,
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,    
    CONSTRAINT menu_plans_name_check CHECK (TRIM(name) <> ''),
    CONSTRAINT date_range_check CHECK (end_date >= start_date)
 );
 COMMENT ON TABLE public.menu_plans IS 'Represents a user''s meal plan for a specific period, e.g., "Week of Oct 23".';
@@ -413,11 +454,13 @@ CREATE TABLE IF NOT EXISTS public.suggested_corrections (
    user_id UUID NOT NULL REFERENCES public.users(user_id) ON DELETE CASCADE,
    correction_type TEXT NOT NULL,
    suggested_value TEXT NOT NULL,
-    status TEXT DEFAULT 'pending' NOT NULL,
+    status TEXT DEFAULT 'pending' NOT NULL CHECK (status IN ('pending', 'approved', 'rejected')),
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    reviewed_notes TEXT,
    reviewed_at TIMESTAMPTZ,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT suggested_corrections_correction_type_check CHECK (TRIM(correction_type) <> ''),
    CONSTRAINT suggested_corrections_suggested_value_check CHECK (TRIM(suggested_value) <> '')
 );
 COMMENT ON TABLE public.suggested_corrections IS 'A queue for user-submitted data corrections, enabling crowdsourced data quality improvements.';
 COMMENT ON COLUMN public.suggested_corrections.correction_type IS 'The type of error the user is reporting.';
@@ -433,12 +476,13 @@ CREATE TABLE IF NOT EXISTS public.user_submitted_prices (
    user_id UUID NOT NULL REFERENCES public.users(user_id) ON DELETE CASCADE,
    master_item_id BIGINT NOT NULL REFERENCES public.master_grocery_items(master_grocery_item_id) ON DELETE CASCADE,
    store_id BIGINT NOT NULL REFERENCES public.stores(store_id) ON DELETE CASCADE,
-    price_in_cents INTEGER NOT NULL,
+    price_in_cents INTEGER NOT NULL CHECK (price_in_cents > 0),
    photo_url TEXT,
-    upvotes INTEGER DEFAULT 0 NOT NULL,
+    upvotes INTEGER DEFAULT 0 NOT NULL CHECK (upvotes >= 0),
-    downvotes INTEGER DEFAULT 0 NOT NULL,
+    downvotes INTEGER DEFAULT 0 NOT NULL CHECK (downvotes >= 0),
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT user_submitted_prices_photo_url_check CHECK (photo_url IS NULL OR photo_url ~* '^https?://.*')
 );
 COMMENT ON TABLE public.user_submitted_prices IS 'Stores item prices submitted by users directly from physical stores.';
 COMMENT ON COLUMN public.user_submitted_prices.photo_url IS 'URL to user-submitted photo evidence of the price.';
@@ -449,7 +493,8 @@ CREATE INDEX IF NOT EXISTS idx_user_submitted_prices_master_item_id ON public.us
 -- 22. Log flyer items that could not be automatically matched to a master item.
 CREATE TABLE IF NOT EXISTS public.unmatched_flyer_items (
    unmatched_flyer_item_id BIGINT PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
-    flyer_item_id BIGINT NOT NULL REFERENCES public.flyer_items(flyer_item_id) ON DELETE CASCADE,    status TEXT DEFAULT 'pending' NOT NULL CHECK (status IN ('pending', 'resolved', 'ignored')),
+    flyer_item_id BIGINT NOT NULL REFERENCES public.flyer_items(flyer_item_id) ON DELETE CASCADE,    
    status TEXT DEFAULT 'pending' NOT NULL CHECK (status IN ('pending', 'resolved', 'ignored')),
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    reviewed_at TIMESTAMPTZ,
    UNIQUE(flyer_item_id),
@@ -479,20 +524,22 @@ CREATE TABLE IF NOT EXISTS public.recipes (
    name TEXT NOT NULL,
    description TEXT,
    instructions TEXT,
-    prep_time_minutes INTEGER,
+    prep_time_minutes INTEGER CHECK (prep_time_minutes IS NULL OR prep_time_minutes >= 0),
-    cook_time_minutes INTEGER,
+    cook_time_minutes INTEGER CHECK (cook_time_minutes IS NULL OR cook_time_minutes >= 0),
-    servings INTEGER,
+    servings INTEGER CHECK (servings IS NULL OR servings > 0),
    photo_url TEXT,
    calories_per_serving INTEGER,
    protein_grams NUMERIC,
    fat_grams NUMERIC,
    carb_grams NUMERIC,
-    avg_rating NUMERIC(2,1) DEFAULT 0.0 NOT NULL,
+    avg_rating NUMERIC(2,1) DEFAULT 0.0 NOT NULL CHECK (avg_rating >= 0.0 AND avg_rating <= 5.0),    
    status TEXT DEFAULT 'private' NOT NULL CHECK (status IN ('private', 'pending_review', 'public', 'rejected')),
-    rating_count INTEGER DEFAULT 0 NOT NULL,
+    rating_count INTEGER DEFAULT 0 NOT NULL CHECK (rating_count >= 0),
-    fork_count INTEGER DEFAULT 0 NOT NULL,
+    fork_count INTEGER DEFAULT 0 NOT NULL CHECK (fork_count >= 0),
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT recipes_name_check CHECK (TRIM(name) <> ''),
    CONSTRAINT recipes_photo_url_check CHECK (photo_url IS NULL OR photo_url ~* '^https?://.*')
 );
 COMMENT ON TABLE public.recipes IS 'Stores recipes that can be used to generate shopping lists.';
 COMMENT ON COLUMN public.recipes.servings IS 'The number of servings this recipe yields.';
@@ -507,6 +554,8 @@ CREATE INDEX IF NOT EXISTS idx_recipes_user_id ON public.recipes(user_id);
 CREATE INDEX IF NOT EXISTS idx_recipes_original_recipe_id ON public.recipes(original_recipe_id);
 -- Add a partial unique index to ensure system-wide recipes (user_id IS NULL) have unique names.
 -- This allows different users to have recipes with the same name.
 -- This index helps speed up sorting for recipe recommendations.
 CREATE INDEX IF NOT EXISTS idx_recipes_rating_sort ON public.recipes (avg_rating DESC, rating_count DESC);
 CREATE UNIQUE INDEX IF NOT EXISTS idx_recipes_unique_system_recipe_name ON public.recipes(name) WHERE user_id IS NULL;
 -- 27. For ingredients required for each recipe.
@@ -514,10 +563,11 @@ CREATE TABLE IF NOT EXISTS public.recipe_ingredients (
    recipe_ingredient_id BIGINT PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
    recipe_id BIGINT NOT NULL REFERENCES public.recipes(recipe_id) ON DELETE CASCADE,
    master_item_id BIGINT NOT NULL REFERENCES public.master_grocery_items(master_grocery_item_id) ON DELETE CASCADE,
-    quantity NUMERIC NOT NULL,
+    quantity NUMERIC NOT NULL CHECK (quantity > 0),
    unit TEXT NOT NULL,
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT recipe_ingredients_unit_check CHECK (TRIM(unit) <> '')
 );
 COMMENT ON TABLE public.recipe_ingredients IS 'Defines the ingredients and quantities needed for a recipe.';
 COMMENT ON COLUMN public.recipe_ingredients.unit IS 'e.g., "cups", "tbsp", "g", "each".';
@@ -544,7 +594,8 @@ CREATE TABLE IF NOT EXISTS public.tags (
    tag_id BIGINT PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
    name TEXT NOT NULL UNIQUE,
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT tags_name_check CHECK (TRIM(name) <> '')
 );
 COMMENT ON TABLE public.tags IS 'Stores tags for categorizing recipes, e.g., "Vegetarian", "Quick & Easy".';
@@ -566,7 +617,8 @@ CREATE TABLE IF NOT EXISTS public.appliances (
    appliance_id BIGINT PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
    name TEXT NOT NULL UNIQUE,
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT appliances_name_check CHECK (TRIM(name) <> '')
 );
 COMMENT ON TABLE public.appliances IS 'A predefined list of kitchen appliances (e.g., Air Fryer, Instant Pot).';
@@ -606,7 +658,8 @@ CREATE TABLE IF NOT EXISTS public.recipe_comments (
    content TEXT NOT NULL,
    status TEXT DEFAULT 'visible' NOT NULL CHECK (status IN ('visible', 'hidden', 'reported')),
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT recipe_comments_content_check CHECK (TRIM(content) <> '')
 );
 COMMENT ON TABLE public.recipe_comments IS 'Allows for threaded discussions and comments on recipes.';
 COMMENT ON COLUMN public.recipe_comments.parent_comment_id IS 'For threaded comments.';
@@ -620,7 +673,8 @@ CREATE TABLE IF NOT EXISTS public.pantry_locations (
    user_id UUID NOT NULL REFERENCES public.users(user_id) ON DELETE CASCADE,
    name TEXT NOT NULL,    
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,    
    CONSTRAINT pantry_locations_name_check CHECK (TRIM(name) <> ''),
    UNIQUE(user_id, name)
 );
 COMMENT ON TABLE public.pantry_locations IS 'User-defined locations for organizing pantry items (e.g., "Fridge", "Freezer", "Spice Rack").';
@@ -634,8 +688,9 @@ CREATE TABLE IF NOT EXISTS public.planned_meals (
    plan_date DATE NOT NULL,    
    meal_type TEXT NOT NULL,
    servings_to_cook INTEGER,
-    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
+    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,    
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT planned_meals_meal_type_check CHECK (TRIM(meal_type) <> '')
 );
 COMMENT ON TABLE public.planned_meals IS 'Assigns a recipe to a specific day and meal type within a user''s menu plan.';
 COMMENT ON COLUMN public.planned_meals.meal_type IS 'The designated meal for the recipe, e.g., ''Breakfast'', ''Lunch'', ''Dinner''.';
@@ -647,7 +702,7 @@ CREATE TABLE IF NOT EXISTS public.pantry_items (
    pantry_item_id BIGINT PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
    user_id UUID NOT NULL REFERENCES public.users(user_id) ON DELETE CASCADE,
    master_item_id BIGINT NOT NULL REFERENCES public.master_grocery_items(master_grocery_item_id) ON DELETE CASCADE,
-    quantity NUMERIC NOT NULL,
+    quantity NUMERIC NOT NULL CHECK (quantity >= 0),
    unit TEXT,
    best_before_date DATE,
    pantry_location_id BIGINT REFERENCES public.pantry_locations(pantry_location_id) ON DELETE SET NULL,
@@ -670,7 +725,8 @@ CREATE TABLE IF NOT EXISTS public.password_reset_tokens (
    token_hash TEXT NOT NULL UNIQUE,
    expires_at TIMESTAMPTZ NOT NULL,
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT password_reset_tokens_token_hash_check CHECK (TRIM(token_hash) <> '')
 );
 COMMENT ON TABLE public.password_reset_tokens IS 'Stores secure, single-use tokens for password reset requests.';
 COMMENT ON COLUMN public.password_reset_tokens.token_hash IS 'A bcrypt hash of the reset token sent to the user.';
@@ -685,10 +741,13 @@ CREATE TABLE IF NOT EXISTS public.unit_conversions (
    master_item_id BIGINT NOT NULL REFERENCES public.master_grocery_items(master_grocery_item_id) ON DELETE CASCADE,
    from_unit TEXT NOT NULL,
    to_unit TEXT NOT NULL,
-    factor NUMERIC NOT NULL,
+    factor NUMERIC NOT NULL CHECK (factor > 0),
    UNIQUE(master_item_id, from_unit, to_unit),
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    UNIQUE(master_item_id, from_unit, to_unit),
    CONSTRAINT unit_conversions_from_unit_check CHECK (TRIM(from_unit) <> ''),
    CONSTRAINT unit_conversions_to_unit_check CHECK (TRIM(to_unit) <> ''),
    CONSTRAINT unit_conversions_units_check CHECK (from_unit <> to_unit)
 );
 COMMENT ON TABLE public.unit_conversions IS 'Stores item-specific unit conversion factors (e.g., grams of flour to cups).';
 COMMENT ON COLUMN public.unit_conversions.factor IS 'The multiplication factor to convert from_unit to to_unit.';
@@ -700,9 +759,10 @@ CREATE TABLE IF NOT EXISTS public.user_item_aliases (
    user_id UUID NOT NULL REFERENCES public.users(user_id) ON DELETE CASCADE,
    master_item_id BIGINT NOT NULL REFERENCES public.master_grocery_items(master_grocery_item_id) ON DELETE CASCADE,
    alias TEXT NOT NULL,
    UNIQUE(user_id, alias),
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    UNIQUE(user_id, alias),
    CONSTRAINT user_item_aliases_alias_check CHECK (TRIM(alias) <> '')
 );
 COMMENT ON TABLE public.user_item_aliases IS 'Allows users to create personal aliases for grocery items (e.g., "Dad''s Cereal").';
 CREATE INDEX IF NOT EXISTS idx_user_item_aliases_user_id ON public.user_item_aliases(user_id);
@@ -739,7 +799,8 @@ CREATE TABLE IF NOT EXISTS public.recipe_collections (
    name TEXT NOT NULL,
    description TEXT,
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT recipe_collections_name_check CHECK (TRIM(name) <> '')
 );
 COMMENT ON TABLE public.recipe_collections IS 'Allows users to create personal collections of recipes (e.g., "Holiday Baking").';
 CREATE INDEX IF NOT EXISTS idx_recipe_collections_user_id ON public.recipe_collections(user_id);
@@ -764,8 +825,11 @@ CREATE TABLE IF NOT EXISTS public.shared_recipe_collections (
    shared_with_user_id UUID NOT NULL REFERENCES public.users(user_id) ON DELETE CASCADE,
    permission_level TEXT NOT NULL CHECK (permission_level IN ('view', 'edit')),
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    UNIQUE(recipe_collection_id, shared_with_user_id)
 );
 -- This index is crucial for efficiently finding all collections shared with a specific user.
 CREATE INDEX IF NOT EXISTS idx_shared_recipe_collections_shared_with ON public.shared_recipe_collections(shared_with_user_id);
 -- 45. Log user search queries for analysis.
 CREATE TABLE IF NOT EXISTS public.search_queries (
@@ -775,7 +839,8 @@ CREATE TABLE IF NOT EXISTS public.search_queries (
    result_count INTEGER,
    was_successful BOOLEAN,
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT search_queries_query_text_check CHECK (TRIM(query_text) <> '')
 );
 COMMENT ON TABLE public.search_queries IS 'Logs user search queries to analyze search effectiveness and identify gaps in data.';
 COMMENT ON COLUMN public.search_queries.was_successful IS 'Indicates if the user interacted with a search result.';
@@ -801,10 +866,11 @@ CREATE TABLE IF NOT EXISTS public.shopping_trip_items (
    shopping_trip_id BIGINT NOT NULL REFERENCES public.shopping_trips(shopping_trip_id) ON DELETE CASCADE,
    master_item_id BIGINT REFERENCES public.master_grocery_items(master_grocery_item_id) ON DELETE SET NULL,
    custom_item_name TEXT,
-    quantity NUMERIC NOT NULL,
+    quantity NUMERIC NOT NULL CHECK (quantity > 0),
    price_paid_cents INTEGER,    
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT shopping_trip_items_custom_item_name_check CHECK (custom_item_name IS NULL OR TRIM(custom_item_name) <> ''),
    CONSTRAINT trip_must_have_item_identifier CHECK (master_item_id IS NOT NULL OR custom_item_name IS NOT NULL)
 );
 COMMENT ON TABLE public.shopping_trip_items IS 'A historical log of items purchased during a shopping trip.';
@@ -818,7 +884,8 @@ CREATE TABLE IF NOT EXISTS public.dietary_restrictions (
    name TEXT NOT NULL UNIQUE,
    type TEXT NOT NULL CHECK (type IN ('diet', 'allergy')),
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT dietary_restrictions_name_check CHECK (TRIM(name) <> '')
 );
 COMMENT ON TABLE public.dietary_restrictions IS 'A predefined list of common diets (e.g., Vegan) and allergies (e.g., Nut Allergy).';
@@ -868,11 +935,12 @@ CREATE TABLE IF NOT EXISTS public.receipts (
    store_id BIGINT REFERENCES public.stores(store_id) ON DELETE CASCADE,
    receipt_image_url TEXT NOT NULL,
    transaction_date TIMESTAMPTZ,
-    total_amount_cents INTEGER,
+    total_amount_cents INTEGER CHECK (total_amount_cents IS NULL OR total_amount_cents >= 0),
    status TEXT DEFAULT 'pending' NOT NULL CHECK (status IN ('pending', 'processing', 'completed', 'failed')),
    raw_text TEXT,
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    processed_at TIMESTAMPTZ,
+    processed_at TIMESTAMPTZ,    
    CONSTRAINT receipts_receipt_image_url_check CHECK (receipt_image_url ~* '^https?://.*'),
    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
 );
 COMMENT ON TABLE public.receipts IS 'Stores uploaded user receipts for purchase tracking and analysis.';
@@ -884,13 +952,14 @@ CREATE TABLE IF NOT EXISTS public.receipt_items (
    receipt_item_id BIGINT PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
    receipt_id BIGINT NOT NULL REFERENCES public.receipts(receipt_id) ON DELETE CASCADE,
    raw_item_description TEXT NOT NULL,
-    quantity NUMERIC DEFAULT 1 NOT NULL,
+    quantity NUMERIC DEFAULT 1 NOT NULL CHECK (quantity > 0),
-    price_paid_cents INTEGER NOT NULL,
+    price_paid_cents INTEGER NOT NULL CHECK (price_paid_cents >= 0),
    master_item_id BIGINT REFERENCES public.master_grocery_items(master_grocery_item_id) ON DELETE SET NULL,
    product_id BIGINT REFERENCES public.products(product_id) ON DELETE SET NULL,
    status TEXT DEFAULT 'unmatched' NOT NULL CHECK (status IN ('unmatched', 'matched', 'needs_review', 'ignored')),
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT receipt_items_raw_item_description_check CHECK (TRIM(raw_item_description) <> '')
 );
 COMMENT ON TABLE public.receipt_items IS 'Stores individual line items extracted from a user receipt.';
 CREATE INDEX IF NOT EXISTS idx_receipt_items_receipt_id ON public.receipt_items(receipt_id);
@@ -929,11 +998,12 @@ CREATE TABLE IF NOT EXISTS public.budgets (
    budget_id BIGINT PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
    user_id UUID NOT NULL REFERENCES public.users(user_id) ON DELETE CASCADE,
    name TEXT NOT NULL,
-    amount_cents INTEGER NOT NULL,
+    amount_cents INTEGER NOT NULL CHECK (amount_cents > 0),
    period TEXT NOT NULL CHECK (period IN ('weekly', 'monthly')),
    start_date DATE NOT NULL,
    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
-    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    updated_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT budgets_name_check CHECK (TRIM(name) <> '')
 );
 COMMENT ON TABLE public.budgets IS 'Allows users to set weekly or monthly grocery budgets for spending tracking.';
 CREATE INDEX IF NOT EXISTS idx_budgets_user_id ON public.budgets(user_id);
@@ -944,8 +1014,10 @@ CREATE TABLE IF NOT EXISTS public.achievements (
    name TEXT NOT NULL UNIQUE,
    description TEXT NOT NULL,
    icon TEXT,
-    points_value INTEGER NOT NULL DEFAULT 0,
+    points_value INTEGER NOT NULL DEFAULT 0 CHECK (points_value >= 0),
-    created_at TIMESTAMPTZ DEFAULT now() NOT NULL
+    created_at TIMESTAMPTZ DEFAULT now() NOT NULL,
    CONSTRAINT achievements_name_check CHECK (TRIM(name) <> ''),
    CONSTRAINT achievements_description_check CHECK (TRIM(description) <> '')
 );
 COMMENT ON TABLE public.achievements IS 'A static table defining the available achievements users can earn.';
@@ -1041,6 +1113,7 @@ DECLARE
    ground_beef_id BIGINT; pasta_item_id BIGINT; tomatoes_id BIGINT; onions_id BIGINT; garlic_id BIGINT;
    bell_peppers_id BIGINT; carrots_id BIGINT; soy_sauce_id BIGINT;
    soda_item_id BIGINT; turkey_item_id BIGINT; bread_item_id BIGINT; cheese_item_id BIGINT;
    chicken_thighs_id BIGINT; paper_towels_id BIGINT; toilet_paper_id BIGINT;
    -- Tag IDs
    quick_easy_tag BIGINT; healthy_tag BIGINT; chicken_tag BIGINT;
@@ -1092,6 +1165,9 @@ BEGIN
    SELECT mgi.master_grocery_item_id INTO turkey_item_id FROM public.master_grocery_items mgi WHERE mgi.name = 'turkey';
    SELECT mgi.master_grocery_item_id INTO bread_item_id FROM public.master_grocery_items mgi WHERE mgi.name = 'bread';
    SELECT mgi.master_grocery_item_id INTO cheese_item_id FROM public.master_grocery_items mgi WHERE mgi.name = 'cheese';
    SELECT mgi.master_grocery_item_id INTO chicken_thighs_id FROM public.master_grocery_items mgi WHERE mgi.name = 'chicken thighs';
    SELECT mgi.master_grocery_item_id INTO paper_towels_id FROM public.master_grocery_items mgi WHERE mgi.name = 'paper towels';
    SELECT mgi.master_grocery_item_id INTO toilet_paper_id FROM public.master_grocery_items mgi WHERE mgi.name = 'toilet paper';
    -- Insert ingredients for each recipe
    INSERT INTO public.recipe_ingredients (recipe_id, master_item_id, quantity, unit) VALUES
@@ -1128,6 +1204,17 @@ BEGIN
    (bolognese_recipe_id, family_tag), (bolognese_recipe_id, beef_tag), (bolognese_recipe_id, weeknight_tag),
    (stir_fry_recipe_id, quick_easy_tag), (stir_fry_recipe_id, healthy_tag), (stir_fry_recipe_id, vegetarian_tag)
    ON CONFLICT (recipe_id, tag_id) DO NOTHING;
    INSERT INTO public.master_item_aliases (master_item_id, alias) VALUES
    (ground_beef_id, 'ground chuck'), (ground_beef_id, 'lean ground beef'), 
    (ground_beef_id, 'extra lean ground beef'), (ground_beef_id, 'hamburger meat'),
    (chicken_breast_id, 'boneless skinless chicken breast'), (chicken_breast_id, 'chicken cutlets'),
    (chicken_thighs_id, 'boneless skinless chicken thighs'), (chicken_thighs_id, 'bone-in chicken thighs'),
    (bell_peppers_id, 'red pepper'), (bell_peppers_id, 'green pepper'), (bell_peppers_id, 'yellow pepper'), (bell_peppers_id, 'orange pepper'),
    (soda_item_id, 'pop'), (soda_item_id, 'soft drink'), (soda_item_id, 'coke'), (soda_item_id, 'pepsi'),
    (paper_towels_id, 'paper towel'),
    (toilet_paper_id, 'bathroom tissue'), (toilet_paper_id, 'toilet tissue')
    ON CONFLICT (alias) DO NOTHING;
 END $$;
 -- Pre-populate the unit_conversions table with common cooking conversions.
@@ -1176,7 +1263,8 @@ INSERT INTO public.achievements (name, description, icon, points_value) VALUES
 ('List Sharer', 'Share a shopping list with another user for the first time.', 'list', 20),
 ('First Favorite', 'Mark a recipe as one of your favorites.', 'heart', 5),
 ('First Fork', 'Make a personal copy of a public recipe.', 'git-fork', 10),
-('First Budget Created', 'Create your first budget to track spending.', 'piggy-bank', 15)
+('First Budget Created', 'Create your first budget to track spending.', 'piggy-bank', 15),
 ('First-Upload', 'Upload your first flyer.', 'upload-cloud', 25)
 ON CONFLICT (name) DO NOTHING;
 -- ============================================================================
@@ -2042,6 +2130,61 @@ AS $$
  ORDER BY potential_savings_cents DESC;
 $$;
 -- Function to get a user's spending breakdown by category for a given date range.
 DROP FUNCTION IF EXISTS public.get_spending_by_category(UUID, DATE, DATE);
 CREATE OR REPLACE FUNCTION public.get_spending_by_category(p_user_id UUID, p_start_date DATE, p_end_date DATE)
 RETURNS TABLE (
    category_id BIGINT,
    category_name TEXT,
    total_spent_cents BIGINT
 )
 LANGUAGE sql
 STABLE
 SECURITY INVOKER
 AS $$
  WITH all_purchases AS (
    -- CTE 1: Combine purchases from completed shopping trips.
    -- We only consider items that have a price paid.
    SELECT
      sti.master_item_id,
      sti.price_paid_cents
    FROM public.shopping_trip_items sti
    JOIN public.shopping_trips st ON sti.shopping_trip_id = st.shopping_trip_id
    WHERE st.user_id = p_user_id
      AND st.completed_at::date BETWEEN p_start_date AND p_end_date
      AND sti.price_paid_cents IS NOT NULL
    UNION ALL
    -- CTE 2: Combine purchases from processed receipts.
    SELECT
      ri.master_item_id,
      ri.price_paid_cents
    FROM public.receipt_items ri
    JOIN public.receipts r ON ri.receipt_id = r.receipt_id
    WHERE r.user_id = p_user_id
      AND r.transaction_date::date BETWEEN p_start_date AND p_end_date
      AND ri.master_item_id IS NOT NULL -- Only include items matched to a master item
  )
  -- Final Aggregation: Group all combined purchases by category and sum the spending.
  SELECT
    c.category_id,
    c.name AS category_name,
    SUM(ap.price_paid_cents)::BIGINT AS total_spent_cents
  FROM all_purchases ap
  -- Join with master_grocery_items to get the category_id for each purchase.
  JOIN public.master_grocery_items mgi ON ap.master_item_id = mgi.master_grocery_item_id
  -- Join with categories to get the category name for display.
  JOIN public.categories c ON mgi.category_id = c.category_id
  GROUP BY
    c.category_id, c.name
  HAVING
    SUM(ap.price_paid_cents) > 0
  ORDER BY
    total_spent_cents DESC;
 $$;
 -- Function to approve a suggested correction and apply it.
 DROP FUNCTION IF EXISTS public.approve_correction(BIGINT);
@@ -2485,8 +2628,15 @@ DROP FUNCTION IF EXISTS public.log_new_flyer();
 CREATE OR REPLACE FUNCTION public.log_new_flyer()
 RETURNS TRIGGER AS $$
 BEGIN
-    INSERT INTO public.activity_log (action, display_text, icon, details)
+    -- If the flyer was uploaded by a registered user, award the 'First-Upload' achievement.
    -- The award_achievement function handles checking if the user already has it.
    IF NEW.uploaded_by IS NOT NULL THEN
        PERFORM public.award_achievement(NEW.uploaded_by, 'First-Upload');
    END IF;
    INSERT INTO public.activity_log (user_id, action, display_text, icon, details)
    VALUES (
        NEW.uploaded_by, -- Log the user who uploaded it
        'flyer_uploaded',
        'A new flyer for ' || (SELECT name FROM public.stores WHERE store_id = NEW.store_id) || ' has been uploaded.',
        'file-text',
@@ -2544,6 +2694,7 @@ BEGIN
        (SELECT full_name FROM public.profiles WHERE user_id = NEW.shared_by_user_id) || ' shared a shopping list.',
        'share-2',
        jsonb_build_object(
            'shopping_list_id', NEW.shopping_list_id,
            'list_name', (SELECT name FROM public.shopping_lists WHERE shopping_list_id = NEW.shopping_list_id),
            'shared_with_user_id', NEW.shared_with_user_id
        )
@@ -2591,6 +2742,66 @@ CREATE TRIGGER on_new_recipe_collection_share
  AFTER INSERT ON public.shared_recipe_collections
  FOR EACH ROW EXECUTE FUNCTION public.log_new_recipe_collection_share();
 -- 10. Trigger function to geocode a store location's address.
 -- This function is triggered when an address is inserted or updated, and is
 -- designed to be extensible for external geocoding services to populate the
 -- latitude, longitude, and location fields.
 DROP FUNCTION IF EXISTS public.geocode_address();
 CREATE OR REPLACE FUNCTION public.geocode_address()
 RETURNS TRIGGER AS $$
 DECLARE
    full_address TEXT;
 BEGIN
    -- Only proceed if an address component has actually changed.
    IF TG_OP = 'INSERT' OR (TG_OP = 'UPDATE' AND (
        NEW.address_line_1 IS DISTINCT FROM OLD.address_line_1 OR
        NEW.address_line_2 IS DISTINCT FROM OLD.address_line_2 OR
        NEW.city IS DISTINCT FROM OLD.city OR
        NEW.province_state IS DISTINCT FROM OLD.province_state OR
        NEW.postal_code IS DISTINCT FROM OLD.postal_code OR
        NEW.country IS DISTINCT FROM OLD.country
    )) THEN
        -- Concatenate address parts into a single string for the geocoder.
        full_address := CONCAT_WS(', ', NEW.address_line_1, NEW.address_line_2, NEW.city, NEW.province_state, NEW.postal_code, NEW.country);
        -- Placeholder for Geocoding API Call.
        -- In a real application, you would call a service here and update NEW.latitude, NEW.longitude, and NEW.location.
        -- e.g., NEW.latitude := result.lat; NEW.longitude := result.lon;
        -- NEW.location := ST_SetSRID(ST_MakePoint(NEW.longitude, NEW.latitude), 4326);
    END IF;
    RETURN NEW;
 END;
 $$ LANGUAGE plpgsql;
 -- This trigger calls the geocoding function when an address changes.
 DROP TRIGGER IF EXISTS on_address_change_geocode ON public.addresses;
 CREATE TRIGGER on_address_change_geocode
  BEFORE INSERT OR UPDATE ON public.addresses
  FOR EACH ROW EXECUTE FUNCTION public.geocode_address();
 -- 11. Trigger function to increment the fork_count on the original recipe.
 DROP FUNCTION IF EXISTS public.increment_recipe_fork_count();
 CREATE OR REPLACE FUNCTION public.increment_recipe_fork_count()
 RETURNS TRIGGER AS $$
 BEGIN
    -- Only run if the recipe is a fork (original_recipe_id is not null).
    IF NEW.original_recipe_id IS NOT NULL THEN
        UPDATE public.recipes SET fork_count = fork_count + 1 WHERE recipe_id = NEW.original_recipe_id;
        -- Award 'First Fork' achievement.
        PERFORM public.award_achievement(NEW.user_id, 'First Fork');
    END IF;
    RETURN NEW;
 END;
 $$ LANGUAGE plpgsql;
 DROP TRIGGER IF EXISTS on_recipe_fork ON public.recipes;
 CREATE TRIGGER on_recipe_fork
  AFTER INSERT ON public.recipes
  FOR EACH ROW EXECUTE FUNCTION public.increment_recipe_fork_count();
 -- =================================================================
 -- Function: get_best_sale_prices_for_all_users()
 -- Description: Retrieves the best sale price for every item on every user's watchlist.
@@ -2598,16 +2809,19 @@ CREATE TRIGGER on_new_recipe_collection_share
 -- It replaces the need to call get_best_sale_prices_for_user for each user individually.
 -- Returns: TABLE(...) - A set of records including user details and deal information.
 -- =================================================================
 DROP FUNCTION IF EXISTS public.get_best_sale_prices_for_all_users();
 CREATE OR REPLACE FUNCTION public.get_best_sale_prices_for_all_users()
 RETURNS TABLE(
    user_id uuid,
    email text,
    full_name text,
-    master_item_id integer,
+    master_item_id bigint,
    item_name text,
    best_price_in_cents integer,
    store_name text,
-    flyer_id integer,
+    flyer_id bigint,
    valid_to date
 ) AS $$
 BEGIN
@@ -2615,22 +2829,27 @@ BEGIN
    WITH
    -- Step 1: Find all flyer items that are currently on sale and have a valid price.
    current_sales AS (
        SELECT
            fi.master_item_id,
            fi.price_in_cents,
-            f.store_name,
+            s.name as store_name,
            f.flyer_id,
            f.valid_to
        FROM public.flyer_items fi
        JOIN public.flyers f ON fi.flyer_id = f.flyer_id
        JOIN public.stores s ON f.store_id = s.store_id
        WHERE
            fi.master_item_id IS NOT NULL
            AND fi.price_in_cents IS NOT NULL
            AND f.valid_to >= CURRENT_DATE
    ),
    -- Step 2: For each master item, find its absolute best (lowest) price across all current sales.
    -- We use a window function to rank the sales for each item by price.
    best_prices AS (
        SELECT
            cs.master_item_id,
            cs.price_in_cents AS best_price_in_cents,
@@ -2643,6 +2862,7 @@ BEGIN
    )
    -- Step 3: Join the best-priced items with the user watchlist and user details.
    SELECT
        u.user_id,
        u.email,
        p.full_name,
@@ -2662,6 +2882,7 @@ BEGIN
    JOIN public.master_grocery_items mgi ON bp.master_item_id = mgi.master_grocery_item_id
    WHERE
        -- Only include the items that are at their absolute best price (rank = 1).
        bp.price_rank = 1;
 END;
 $$ LANGUAGE plpgsql;
--- a/src/components/AchievementsList.test.tsx
+++ b/src/components/AchievementsList.test.tsx
@@ -1,9 +1,10 @@
 // src/components/AchievementsList.test.tsx
 import React from 'react';
-import { render, screen } from '@testing-library/react';
+import { screen } from '@testing-library/react';
 import { describe, it, expect } from 'vitest';
 import { AchievementsList } from './AchievementsList';
 import { createMockUserAchievement } from '../tests/utils/mockFactories';
 import { renderWithProviders } from '../tests/utils/renderWithProviders';
 describe('AchievementsList', () => {
  it('should render the list of achievements with correct details', () => {
@@ -24,7 +25,7 @@ describe('AchievementsList', () => {
      createMockUserAchievement({ achievement_id: 3, name: 'Unknown Achievement', icon: 'star' }), // This icon is not in the component's map
    ];
-    render(<AchievementsList achievements={mockAchievements} />);
+    renderWithProviders(<AchievementsList achievements={mockAchievements} />);
    expect(screen.getByRole('heading', { name: /achievements/i })).toBeInTheDocument();
@@ -44,7 +45,7 @@ describe('AchievementsList', () => {
  });
  it('should render a message when there are no achievements', () => {
-    render(<AchievementsList achievements={[]} />);
+    renderWithProviders(<AchievementsList achievements={[]} />);
    expect(
      screen.getByText('No achievements earned yet. Keep exploring to unlock them!'),
    ).toBeInTheDocument();
--- a/src/components/AdminRoute.test.tsx
+++ b/src/components/AdminRoute.test.tsx
@@ -1,11 +1,12 @@
 // src/components/AdminRoute.test.tsx
 import React from 'react';
-import { render, screen } from '@testing-library/react';
+import { screen } from '@testing-library/react';
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, vi } from 'vitest';
-import { MemoryRouter, Routes, Route } from 'react-router-dom';
+import { Routes, Route } from 'react-router-dom';
 import { AdminRoute } from './AdminRoute';
 import type { Profile } from '../types';
 import { createMockProfile } from '../tests/utils/mockFactories';
 import { renderWithProviders } from '../tests/utils/renderWithProviders';
 // Unmock the component to test the real implementation
 vi.unmock('./AdminRoute');
@@ -14,15 +15,14 @@ const AdminContent = () => <div>Admin Page Content</div>;
 const HomePage = () => <div>Home Page</div>;
 const renderWithRouter = (profile: Profile | null, initialPath: string) => {
-  render(
+  renderWithProviders(
-    <MemoryRouter initialEntries={[initialPath]}>
+    <Routes>
-      <Routes>
+      <Route path="/" element={<HomePage />} />
-        <Route path="/" element={<HomePage />} />
+      <Route path="/admin" element={<AdminRoute profile={profile} />}>
-        <Route path="/admin" element={<AdminRoute profile={profile} />}>
+        <Route index element={<AdminContent />} />
-          <Route index element={<AdminContent />} />
+      </Route>
-        </Route>
+    </Routes>,
-      </Routes>
+    { initialEntries: [initialPath] },
    </MemoryRouter>,
  );
 };
--- a/src/components/AnonymousUserBanner.test.tsx
+++ b/src/components/AnonymousUserBanner.test.tsx
@@ -1,8 +1,9 @@
 // src/components/AnonymousUserBanner.test.tsx
 import React from 'react';
-import { render, screen, fireEvent } from '@testing-library/react';
+import { screen, fireEvent } from '@testing-library/react';
 import { describe, it, expect, vi } from 'vitest';
 import { AnonymousUserBanner } from './AnonymousUserBanner';
 import { renderWithProviders } from '../tests/utils/renderWithProviders';
 // Mock the icon to ensure it is rendered correctly
 vi.mock('./icons/InformationCircleIcon', () => ({
@@ -14,7 +15,7 @@ vi.mock('./icons/InformationCircleIcon', () => ({
 describe('AnonymousUserBanner', () => {
  it('should render the banner with the correct text content and accessibility role', () => {
    const mockOnOpenProfile = vi.fn();
-    render(<AnonymousUserBanner onOpenProfile={mockOnOpenProfile} />);
+    renderWithProviders(<AnonymousUserBanner onOpenProfile={mockOnOpenProfile} />);
    // Check for accessibility role
    expect(screen.getByRole('alert')).toBeInTheDocument();
@@ -30,7 +31,7 @@ describe('AnonymousUserBanner', () => {
  it('should call onOpenProfile when the "sign up or log in" button is clicked', () => {
    const mockOnOpenProfile = vi.fn();
-    render(<AnonymousUserBanner onOpenProfile={mockOnOpenProfile} />);
+    renderWithProviders(<AnonymousUserBanner onOpenProfile={mockOnOpenProfile} />);
    const loginButton = screen.getByRole('button', { name: /sign up or log in/i });
    fireEvent.click(loginButton);
--- a/src/components/AppGuard.test.tsx
+++ b/src/components/AppGuard.test.tsx
@@ -1,12 +1,15 @@
 // src/components/AppGuard.test.tsx
 import React from 'react';
-import { render, screen, waitFor } from '@testing-library/react';
+import { screen, waitFor } from '@testing-library/react';
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { AppGuard } from './AppGuard';
 import { useAppInitialization } from '../hooks/useAppInitialization';
 import * as apiClient from '../services/apiClient';
 import { useModal } from '../hooks/useModal';
 import { renderWithProviders } from '../tests/utils/renderWithProviders';
 // Mock dependencies
 // The apiClient is mocked globally in `src/tests/setup/globalApiMock.ts`.
 vi.mock('../hooks/useAppInitialization');
 vi.mock('../hooks/useModal');
 vi.mock('./WhatsNewModal', () => ({
@@ -19,6 +22,7 @@ vi.mock('../config', () => ({
  },
 }));
 const mockedApiClient = vi.mocked(apiClient);
 const mockedUseAppInitialization = vi.mocked(useAppInitialization);
 const mockedUseModal = vi.mocked(useModal);
@@ -38,7 +42,7 @@ describe('AppGuard', () => {
  });
  it('should render children', () => {
-    render(
+    renderWithProviders(
      <AppGuard>
        <div>Child Content</div>
      </AppGuard>,
@@ -51,7 +55,7 @@ describe('AppGuard', () => {
      ...mockedUseModal(),
      isModalOpen: (modalId) => modalId === 'whatsNew',
    });
-    render(
+    renderWithProviders(
      <AppGuard>
        <div>Child</div>
      </AppGuard>,
@@ -64,7 +68,7 @@ describe('AppGuard', () => {
      isDarkMode: true,
      unitSystem: 'imperial',
    });
-    render(
+    renderWithProviders(
      <AppGuard>
        <div>Child</div>
      </AppGuard>,
@@ -78,7 +82,7 @@ describe('AppGuard', () => {
  });
  it('should set light mode styles for toaster', async () => {
-    render(
+    renderWithProviders(
      <AppGuard>
        <div>Child</div>
      </AppGuard>,
--- a/src/components/ConfirmationModal.test.tsx
+++ b/src/components/ConfirmationModal.test.tsx
@@ -1,8 +1,9 @@
 // src/components/ConfirmationModal.test.tsx
 import React from 'react';
-import { render, screen, fireEvent } from '@testing-library/react';
+import { screen, fireEvent } from '@testing-library/react';
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { ConfirmationModal } from './ConfirmationModal';
 import { renderWithProviders } from '../tests/utils/renderWithProviders';
 describe('ConfirmationModal (in components)', () => {
  const mockOnClose = vi.fn();
@@ -21,12 +22,12 @@ describe('ConfirmationModal (in components)', () => {
  });
  it('should not render when isOpen is false', () => {
-    const { container } = render(<ConfirmationModal {...defaultProps} isOpen={false} />);
+    const { container } = renderWithProviders(<ConfirmationModal {...defaultProps} isOpen={false} />);
    expect(container.firstChild).toBeNull();
  });
  it('should render correctly when isOpen is true', () => {
-    render(<ConfirmationModal {...defaultProps} />);
+    renderWithProviders(<ConfirmationModal {...defaultProps} />);
    expect(screen.getByRole('heading', { name: 'Confirm Action' })).toBeInTheDocument();
    expect(screen.getByText('Are you sure you want to do this?')).toBeInTheDocument();
    expect(screen.getByRole('button', { name: 'Confirm' })).toBeInTheDocument();
@@ -34,38 +35,38 @@ describe('ConfirmationModal (in components)', () => {
  });
  it('should call onConfirm when the confirm button is clicked', () => {
-    render(<ConfirmationModal {...defaultProps} />);
+    renderWithProviders(<ConfirmationModal {...defaultProps} />);
    fireEvent.click(screen.getByRole('button', { name: 'Confirm' }));
    expect(mockOnConfirm).toHaveBeenCalledTimes(1);
  });
  it('should call onClose when the cancel button is clicked', () => {
-    render(<ConfirmationModal {...defaultProps} />);
+    renderWithProviders(<ConfirmationModal {...defaultProps} />);
    fireEvent.click(screen.getByRole('button', { name: 'Cancel' }));
    expect(mockOnClose).toHaveBeenCalledTimes(1);
  });
  it('should call onClose when the close icon is clicked', () => {
-    render(<ConfirmationModal {...defaultProps} />);
+    renderWithProviders(<ConfirmationModal {...defaultProps} />);
    fireEvent.click(screen.getByLabelText('Close confirmation modal'));
    expect(mockOnClose).toHaveBeenCalledTimes(1);
  });
  it('should call onClose when the overlay is clicked', () => {
-    render(<ConfirmationModal {...defaultProps} />);
+    renderWithProviders(<ConfirmationModal {...defaultProps} />);
    // The overlay is the parent of the modal content div
    fireEvent.click(screen.getByRole('dialog'));
    expect(mockOnClose).toHaveBeenCalledTimes(1);
  });
  it('should not call onClose when clicking inside the modal content', () => {
-    render(<ConfirmationModal {...defaultProps} />);
+    renderWithProviders(<ConfirmationModal {...defaultProps} />);
    fireEvent.click(screen.getByText('Are you sure you want to do this?'));
    expect(mockOnClose).not.toHaveBeenCalled();
  });
  it('should render custom button text and classes', () => {
-    render(
+    renderWithProviders(
      <ConfirmationModal
        {...defaultProps}
        confirmButtonText="Yes, Delete"
--- a/src/components/DarkModeToggle.test.tsx
+++ b/src/components/DarkModeToggle.test.tsx
@@ -1,8 +1,9 @@
 // src/components/DarkModeToggle.test.tsx
 import React from 'react';
-import { render, screen, fireEvent } from '@testing-library/react';
+import { screen, fireEvent } from '@testing-library/react';
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { DarkModeToggle } from './DarkModeToggle';
 import { renderWithProviders } from '../tests/utils/renderWithProviders';
 // Mock the icon components to isolate the toggle's logic
 vi.mock('./icons/SunIcon', () => ({
@@ -20,7 +21,7 @@ describe('DarkModeToggle', () => {
  });
  it('should render in light mode state', () => {
-    render(<DarkModeToggle isDarkMode={false} onToggle={mockOnToggle} />);
+    renderWithProviders(<DarkModeToggle isDarkMode={false} onToggle={mockOnToggle} />);
    const checkbox = screen.getByRole('checkbox');
    expect(checkbox).not.toBeChecked();
@@ -29,7 +30,7 @@ describe('DarkModeToggle', () => {
  });
  it('should render in dark mode state', () => {
-    render(<DarkModeToggle isDarkMode={true} onToggle={mockOnToggle} />);
+    renderWithProviders(<DarkModeToggle isDarkMode={true} onToggle={mockOnToggle} />);
    const checkbox = screen.getByRole('checkbox');
    expect(checkbox).toBeChecked();
@@ -38,7 +39,7 @@ describe('DarkModeToggle', () => {
  });
  it('should call onToggle when the label is clicked', () => {
-    render(<DarkModeToggle isDarkMode={false} onToggle={mockOnToggle} />);
+    renderWithProviders(<DarkModeToggle isDarkMode={false} onToggle={mockOnToggle} />);
    // Clicking the label triggers the checkbox change
    const label = screen.getByTitle('Switch to Dark Mode');
--- a/src/components/Dashboard.test.tsx
+++ b/src/components/Dashboard.test.tsx
@@ -0,0 +1,67 @@
 // src/components/Dashboard.test.tsx
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { screen } from '@testing-library/react';
 import { Dashboard } from './Dashboard';
 import { renderWithProviders } from '../tests/utils/renderWithProviders';
 // Mock child components to isolate Dashboard logic
 // Note: The Dashboard component imports these using '../components/RecipeSuggester'
 // which resolves to the same file as './RecipeSuggester' when inside src/components.
 vi.mock('./RecipeSuggester', () => ({
  RecipeSuggester: () => <div data-testid="recipe-suggester-mock">Recipe Suggester</div>,
 }));
 vi.mock('./FlyerCountDisplay', () => ({
  FlyerCountDisplay: () => <div data-testid="flyer-count-display-mock">Flyer Count Display</div>,
 }));
 vi.mock('./Leaderboard', () => ({
  Leaderboard: () => <div data-testid="leaderboard-mock">Leaderboard</div>,
 }));
 describe('Dashboard Component', () => {
  beforeEach(() => {
    vi.clearAllMocks();
  });
  it('renders the dashboard title', () => {
    console.log('TEST: Verifying dashboard title render');
    renderWithProviders(<Dashboard />);
    expect(screen.getByRole('heading', { name: /dashboard/i, level: 1 })).toBeInTheDocument();
  });
  it('renders the RecipeSuggester widget', () => {
    console.log('TEST: Verifying RecipeSuggester presence');
    renderWithProviders(<Dashboard />);
    expect(screen.getByTestId('recipe-suggester-mock')).toBeInTheDocument();
  });
  it('renders the FlyerCountDisplay widget within the "Your Flyers" section', () => {
    console.log('TEST: Verifying FlyerCountDisplay presence and section title');
    renderWithProviders(<Dashboard />);
    // Check for the section heading
    expect(screen.getByRole('heading', { name: /your flyers/i, level: 2 })).toBeInTheDocument();
    // Check for the component
    expect(screen.getByTestId('flyer-count-display-mock')).toBeInTheDocument();
  });
  it('renders the Leaderboard widget in the sidebar area', () => {
    console.log('TEST: Verifying Leaderboard presence');
    renderWithProviders(<Dashboard />);
    expect(screen.getByTestId('leaderboard-mock')).toBeInTheDocument();
  });
  it('renders with the correct grid layout classes', () => {
    console.log('TEST: Verifying layout classes');
    const { container } = renderWithProviders(<Dashboard />);
    // The main grid container
    const gridContainer = container.querySelector('.grid');
    expect(gridContainer).toBeInTheDocument();
    expect(gridContainer).toHaveClass('grid-cols-1');
    expect(gridContainer).toHaveClass('lg:grid-cols-3');
    expect(gridContainer).toHaveClass('gap-6');
  });
 });
--- a/src/components/Dashboard.tsx
+++ b/src/components/Dashboard.tsx
@@ -0,0 +1,33 @@
 import React from 'react';
 import { RecipeSuggester } from '../components/RecipeSuggester';
 import { FlyerCountDisplay } from '../components/FlyerCountDisplay';
 import { Leaderboard } from '../components/Leaderboard';
 export const Dashboard: React.FC = () => {
  return (
    <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8 py-8">
      <h1 className="text-2xl font-bold text-gray-900 dark:text-white mb-6">Dashboard</h1>
      <div className="grid grid-cols-1 lg:grid-cols-3 gap-6">
        {/* Main Content Area */}
        <div className="lg:col-span-2 space-y-6">
          {/* Recipe Suggester Section */}
          <RecipeSuggester />
          {/* Other Dashboard Widgets */}
          <div className="bg-white dark:bg-gray-800 shadow rounded-lg p-6">
            <h2 className="text-lg font-medium text-gray-900 dark:text-white mb-4">Your Flyers</h2>
            <FlyerCountDisplay />
          </div>
        </div>
        {/* Sidebar Area */}
        <div className="space-y-6">
          <Leaderboard />
        </div>
      </div>
    </div>
  );
 };
 export default Dashboard;
--- a/src/components/ErrorDisplay.test.tsx
+++ b/src/components/ErrorDisplay.test.tsx
@@ -1,24 +1,25 @@
 // src/components/ErrorDisplay.test.tsx
 import React from 'react';
-import { render, screen } from '@testing-library/react';
+import { screen } from '@testing-library/react';
 import { describe, it, expect } from 'vitest';
 import { ErrorDisplay } from './ErrorDisplay';
 import { renderWithProviders } from '../tests/utils/renderWithProviders';
 describe('ErrorDisplay (in components)', () => {
  it('should not render when the message is empty', () => {
-    const { container } = render(<ErrorDisplay message="" />);
+    const { container } = renderWithProviders(<ErrorDisplay message="" />);
    expect(container.firstChild).toBeNull();
  });
  it('should not render when the message is null', () => {
    // The component expects a string, but we test for nullish values as a safeguard.
-    const { container } = render(<ErrorDisplay message={null as unknown as string} />);
+    const { container } = renderWithProviders(<ErrorDisplay message={null as unknown as string} />);
    expect(container.firstChild).toBeNull();
  });
  it('should render the error message when provided', () => {
    const errorMessage = 'Something went terribly wrong.';
-    render(<ErrorDisplay message={errorMessage} />);
+    renderWithProviders(<ErrorDisplay message={errorMessage} />);
    const alert = screen.getByRole('alert');
    expect(alert).toBeInTheDocument();
--- a/src/components/FlyerCorrectionTool.test.tsx
+++ b/src/components/FlyerCorrectionTool.test.tsx
@@ -1,24 +1,18 @@
 // src/components/FlyerCorrectionTool.test.tsx
 import React from 'react';
-import { render, screen, fireEvent, waitFor, act } from '@testing-library/react';
+import { screen, fireEvent, waitFor, act } from '@testing-library/react';
 import { describe, it, expect, vi, beforeEach, type Mocked } from 'vitest';
 import { FlyerCorrectionTool } from './FlyerCorrectionTool';
 import * as aiApiClient from '../services/aiApiClient';
 import { notifyError, notifySuccess } from '../services/notificationService';
 import { renderWithProviders } from '../tests/utils/renderWithProviders';
 // Unmock the component to test the real implementation
 vi.unmock('./FlyerCorrectionTool');
-// Mock dependencies
+// The aiApiClient, notificationService, and logger are mocked globally.
-vi.mock('../services/aiApiClient');
+// We can get a typed reference to the aiApiClient for individual test overrides.
-vi.mock('../services/notificationService');
+const mockedAiApiClient = vi.mocked(aiApiClient);
 vi.mock('../services/logger', () => ({
  logger: {
    error: vi.fn(),
  },
 }));
 const mockedAiApiClient = aiApiClient as Mocked<typeof aiApiClient>;
 const mockedNotifySuccess = notifySuccess as Mocked<typeof notifySuccess>;
 const mockedNotifyError = notifyError as Mocked<typeof notifyError>;
@@ -54,12 +48,12 @@ describe('FlyerCorrectionTool', () => {
  });
  it('should not render when isOpen is false', () => {
-    const { container } = render(<FlyerCorrectionTool {...defaultProps} isOpen={false} />);
+    const { container } = renderWithProviders(<FlyerCorrectionTool {...defaultProps} isOpen={false} />);
    expect(container.firstChild).toBeNull();
  });
  it('should render correctly when isOpen is true', () => {
-    render(<FlyerCorrectionTool {...defaultProps} />);
+    renderWithProviders(<FlyerCorrectionTool {...defaultProps} />);
    expect(screen.getByRole('heading', { name: /flyer correction tool/i })).toBeInTheDocument();
    expect(screen.getByAltText('Flyer for correction')).toBeInTheDocument();
    expect(screen.getByRole('button', { name: /extract store name/i })).toBeInTheDocument();
@@ -67,7 +61,7 @@ describe('FlyerCorrectionTool', () => {
  });
  it('should call onClose when the close button is clicked', () => {
-    render(<FlyerCorrectionTool {...defaultProps} />);
+    renderWithProviders(<FlyerCorrectionTool {...defaultProps} />);
    // Use the specific aria-label defined in the component to find the close button
    const closeButton = screen.getByLabelText(/close correction tool/i);
    fireEvent.click(closeButton);
@@ -75,13 +69,13 @@ describe('FlyerCorrectionTool', () => {
  });
  it('should have disabled extraction buttons initially', () => {
-    render(<FlyerCorrectionTool {...defaultProps} />);
+    renderWithProviders(<FlyerCorrectionTool {...defaultProps} />);
    expect(screen.getByRole('button', { name: /extract store name/i })).toBeDisabled();
    expect(screen.getByRole('button', { name: /extract sale dates/i })).toBeDisabled();
  });
  it('should enable extraction buttons after a selection is made', () => {
-    render(<FlyerCorrectionTool {...defaultProps} />);
+    renderWithProviders(<FlyerCorrectionTool {...defaultProps} />);
    const canvas = screen.getByRole('dialog').querySelector('canvas')!;
    // Simulate drawing a rectangle
@@ -94,7 +88,7 @@ describe('FlyerCorrectionTool', () => {
  });
  it('should stop drawing when the mouse leaves the canvas', () => {
-    render(<FlyerCorrectionTool {...defaultProps} />);
+    renderWithProviders(<FlyerCorrectionTool {...defaultProps} />);
    const canvas = screen.getByRole('dialog').querySelector('canvas')!;
    fireEvent.mouseDown(canvas, { clientX: 10, clientY: 10 });
@@ -114,7 +108,7 @@ describe('FlyerCorrectionTool', () => {
    });
    mockedAiApiClient.rescanImageArea.mockReturnValue(rescanPromise);
-    render(<FlyerCorrectionTool {...defaultProps} />);
+    renderWithProviders(<FlyerCorrectionTool {...defaultProps} />);
    // Wait for the image fetch to complete to ensure 'imageFile' state is populated
    console.log('--- [TEST LOG] ---: Awaiting image fetch inside component...');
@@ -192,7 +186,7 @@ describe('FlyerCorrectionTool', () => {
    // Mock fetch to reject
    global.fetch = vi.fn(() => Promise.reject(new Error('Network error'))) as Mocked<typeof fetch>;
-    render(<FlyerCorrectionTool {...defaultProps} />);
+    renderWithProviders(<FlyerCorrectionTool {...defaultProps} />);
    await waitFor(() => {
      expect(mockedNotifyError).toHaveBeenCalledWith('Could not load the image for correction.');
@@ -211,7 +205,7 @@ describe('FlyerCorrectionTool', () => {
      return new Promise(() => {});
    }) as Mocked<typeof fetch>;
-    render(<FlyerCorrectionTool {...defaultProps} />);
+    renderWithProviders(<FlyerCorrectionTool {...defaultProps} />);
    const canvas = screen.getByRole('dialog').querySelector('canvas')!;
@@ -238,7 +232,7 @@ describe('FlyerCorrectionTool', () => {
  it('should handle non-standard API errors during rescan', async () => {
    console.log('TEST: Starting "should handle non-standard API errors during rescan"');
    mockedAiApiClient.rescanImageArea.mockRejectedValue('A plain string error');
-    render(<FlyerCorrectionTool {...defaultProps} />);
+    renderWithProviders(<FlyerCorrectionTool {...defaultProps} />);
    // Wait for image fetch to ensure imageFile is set before we interact
    await waitFor(() => expect(global.fetch).toHaveBeenCalled());
--- a/src/components/FlyerCountDisplay.test.tsx
+++ b/src/components/FlyerCountDisplay.test.tsx
@@ -1,11 +1,12 @@
 // src/components/FlyerCountDisplay.test.tsx
 import React from 'react';
-import { render, screen } from '@testing-library/react';
+import { screen } from '@testing-library/react';
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { FlyerCountDisplay } from './FlyerCountDisplay';
 import { useFlyers } from '../hooks/useFlyers';
 import type { Flyer } from '../types';
 import { createMockFlyer } from '../tests/utils/mockFactories';
 import { renderWithProviders } from '../tests/utils/renderWithProviders';
 // Mock the dependencies
 vi.mock('../hooks/useFlyers');
@@ -32,7 +33,7 @@ describe('FlyerCountDisplay', () => {
    });
    // Act: Render the component.
-    render(<FlyerCountDisplay />);
+    renderWithProviders(<FlyerCountDisplay />);
    // Assert: Check that the loading spinner is visible.
    expect(screen.getByTestId('loading-spinner')).toBeInTheDocument();
@@ -53,7 +54,7 @@ describe('FlyerCountDisplay', () => {
    });
    // Act
-    render(<FlyerCountDisplay />);
+    renderWithProviders(<FlyerCountDisplay />);
    // Assert: Check that the error message is displayed.
    expect(screen.getByRole('alert')).toHaveTextContent(errorMessage);
@@ -73,7 +74,7 @@ describe('FlyerCountDisplay', () => {
    });
    // Act
-    render(<FlyerCountDisplay />);
+    renderWithProviders(<FlyerCountDisplay />);
    // Assert: Check that the correct count is displayed.
    const countDisplay = screen.getByTestId('flyer-count');
--- a/src/components/Footer.test.tsx
+++ b/src/components/Footer.test.tsx
@@ -1,8 +1,9 @@
 // src/components/Footer.test.tsx
 import React from 'react';
-import { render, screen } from '@testing-library/react';
+import { screen } from '@testing-library/react';
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import { Footer } from './Footer';
 import { renderWithProviders } from '../tests/utils/renderWithProviders';
 describe('Footer', () => {
  beforeEach(() => {
@@ -21,7 +22,7 @@ describe('Footer', () => {
    vi.setSystemTime(mockDate);
    // Act: Render the component
-    render(<Footer />);
+    renderWithProviders(<Footer />);
    // Assert: Check that the rendered text includes the mocked year
    expect(screen.getByText('Copyright 2025-2025')).toBeInTheDocument();
@@ -29,7 +30,7 @@ describe('Footer', () => {
  it('should display the correct year when it changes', () => {
    vi.setSystemTime(new Date('2030-01-01T00:00:00Z'));
-    render(<Footer />);
+    renderWithProviders(<Footer />);
    expect(screen.getByText('Copyright 2025-2030')).toBeInTheDocument();
  });
 });
--- a/src/components/Header.test.tsx
+++ b/src/components/Header.test.tsx
@@ -1,11 +1,11 @@
 // src/components/Header.test.tsx
 import React from 'react';
-import { render, screen, fireEvent } from '@testing-library/react';
+import { screen, fireEvent } from '@testing-library/react';
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { MemoryRouter } from 'react-router-dom';
 import { Header } from './Header';
 import type { UserProfile } from '../types';
 import { createMockUserProfile } from '../tests/utils/mockFactories';
 import { renderWithProviders } from '../tests/utils/renderWithProviders';
 // Unmock the component to test the real implementation
 vi.unmock('./Header');
@@ -34,12 +34,8 @@ const defaultProps = {
 };
 // Helper to render with router context
-const renderWithRouter = (props: Partial<React.ComponentProps<typeof Header>>) => {
+const renderHeader = (props: Partial<React.ComponentProps<typeof Header>>) => {
-  return render(
+  return renderWithProviders(<Header {...defaultProps} {...props} />);
    <MemoryRouter>
      <Header {...defaultProps} {...props} />
    </MemoryRouter>,
  );
 };
 describe('Header', () => {
@@ -48,30 +44,30 @@ describe('Header', () => {
  });
  it('should render the application title', () => {
-    renderWithRouter({});
+    renderHeader({});
    expect(screen.getByRole('heading', { name: /flyer crawler/i })).toBeInTheDocument();
  });
  it('should display unit system and theme mode', () => {
-    renderWithRouter({ isDarkMode: true, unitSystem: 'metric' });
+    renderHeader({ isDarkMode: true, unitSystem: 'metric' });
    expect(screen.getByText(/metric/i)).toBeInTheDocument();
    expect(screen.getByText(/dark mode/i)).toBeInTheDocument();
  });
  describe('When user is logged out', () => {
    it('should show a Login button', () => {
-      renderWithRouter({ userProfile: null, authStatus: 'SIGNED_OUT' });
+      renderHeader({ userProfile: null, authStatus: 'SIGNED_OUT' });
      expect(screen.getByRole('button', { name: /login/i })).toBeInTheDocument();
    });
    it('should call onOpenProfile when Login button is clicked', () => {
-      renderWithRouter({ userProfile: null, authStatus: 'SIGNED_OUT' });
+      renderHeader({ userProfile: null, authStatus: 'SIGNED_OUT' });
      fireEvent.click(screen.getByRole('button', { name: /login/i }));
      expect(mockOnOpenProfile).toHaveBeenCalledTimes(1);
    });
    it('should not show user-specific buttons', () => {
-      renderWithRouter({ userProfile: null, authStatus: 'SIGNED_OUT' });
+      renderHeader({ userProfile: null, authStatus: 'SIGNED_OUT' });
      expect(screen.queryByLabelText(/open voice assistant/i)).not.toBeInTheDocument();
      expect(screen.queryByLabelText(/open my account settings/i)).not.toBeInTheDocument();
      expect(screen.queryByRole('button', { name: /logout/i })).not.toBeInTheDocument();
@@ -80,29 +76,29 @@ describe('Header', () => {
  describe('When user is authenticated', () => {
    it('should display the user email', () => {
-      renderWithRouter({ userProfile: mockUserProfile, authStatus: 'AUTHENTICATED' });
+      renderHeader({ userProfile: mockUserProfile, authStatus: 'AUTHENTICATED' });
      expect(screen.getByText(mockUserProfile.user.email)).toBeInTheDocument();
    });
    it('should display "Guest" for anonymous users', () => {
-      renderWithRouter({ userProfile: mockUserProfile, authStatus: 'SIGNED_OUT' });
+      renderHeader({ userProfile: mockUserProfile, authStatus: 'SIGNED_OUT' });
      expect(screen.getByText(/guest/i)).toBeInTheDocument();
    });
    it('should call onOpenVoiceAssistant when microphone icon is clicked', () => {
-      renderWithRouter({ userProfile: mockUserProfile, authStatus: 'AUTHENTICATED' });
+      renderHeader({ userProfile: mockUserProfile, authStatus: 'AUTHENTICATED' });
      fireEvent.click(screen.getByLabelText(/open voice assistant/i));
      expect(mockOnOpenVoiceAssistant).toHaveBeenCalledTimes(1);
    });
    it('should call onOpenProfile when cog icon is clicked', () => {
-      renderWithRouter({ userProfile: mockUserProfile, authStatus: 'AUTHENTICATED' });
+      renderHeader({ userProfile: mockUserProfile, authStatus: 'AUTHENTICATED' });
      fireEvent.click(screen.getByLabelText(/open my account settings/i));
      expect(mockOnOpenProfile).toHaveBeenCalledTimes(1);
    });
    it('should call onSignOut when Logout button is clicked', () => {
-      renderWithRouter({ userProfile: mockUserProfile, authStatus: 'AUTHENTICATED' });
+      renderHeader({ userProfile: mockUserProfile, authStatus: 'AUTHENTICATED' });
      fireEvent.click(screen.getByRole('button', { name: /logout/i }));
      expect(mockOnSignOut).toHaveBeenCalledTimes(1);
    });
@@ -110,14 +106,14 @@ describe('Header', () => {
  describe('Admin user', () => {
    it('should show the Admin Area link for admin users', () => {
-      renderWithRouter({ userProfile: mockAdminProfile, authStatus: 'AUTHENTICATED' });
+      renderHeader({ userProfile: mockAdminProfile, authStatus: 'AUTHENTICATED' });
      const adminLink = screen.getByTitle(/admin area/i);
      expect(adminLink).toBeInTheDocument();
      expect(adminLink.closest('a')).toHaveAttribute('href', '/admin');
    });
    it('should not show the Admin Area link for non-admin users', () => {
-      renderWithRouter({ userProfile: mockUserProfile, authStatus: 'AUTHENTICATED' });
+      renderHeader({ userProfile: mockUserProfile, authStatus: 'AUTHENTICATED' });
      expect(screen.queryByTitle(/admin area/i)).not.toBeInTheDocument();
    });
  });
--- a/src/components/Leaderboard.test.tsx
+++ b/src/components/Leaderboard.test.tsx
@@ -1,21 +1,17 @@
 // src/components/Leaderboard.test.tsx
 import React from 'react';
-import { render, screen, waitFor } from '@testing-library/react';
+import { screen, waitFor } from '@testing-library/react';
 import { describe, it, expect, vi, beforeEach, type Mocked } from 'vitest';
 import Leaderboard from './Leaderboard';
 import * as apiClient from '../services/apiClient';
 import { LeaderboardUser } from '../types';
 import { createMockLeaderboardUser } from '../tests/utils/mockFactories';
 import { createMockLogger } from '../tests/utils/mockLogger';
 import { renderWithProviders } from '../tests/utils/renderWithProviders';
-// Mock the apiClient
+// The apiClient and logger are mocked globally.
-vi.mock('../services/apiClient'); // This was correct
+// We can get a typed reference to the apiClient for individual test overrides.
-const mockedApiClient = apiClient as Mocked<typeof apiClient>;
+const mockedApiClient = vi.mocked(apiClient);
 // Mock the logger
 vi.mock('../services/logger', () => ({
  logger: createMockLogger(),
 }));
 // Mock lucide-react icons to prevent rendering errors in the test environment
 vi.mock('lucide-react', () => ({
@@ -45,13 +41,13 @@ describe('Leaderboard', () => {
  it('should display a loading message initially', () => {
    // Mock a pending promise that never resolves to keep it in the loading state
    mockedApiClient.fetchLeaderboard.mockReturnValue(new Promise(() => {}));
-    render(<Leaderboard />);
+    renderWithProviders(<Leaderboard />);
    expect(screen.getByText('Loading Leaderboard...')).toBeInTheDocument();
  });
  it('should display an error message if the API call fails', async () => {
    mockedApiClient.fetchLeaderboard.mockResolvedValue(new Response(null, { status: 500 }));
-    render(<Leaderboard />);
+    renderWithProviders(<Leaderboard />);
    await waitFor(() => {
      expect(screen.getByRole('alert')).toBeInTheDocument();
@@ -62,7 +58,7 @@ describe('Leaderboard', () => {
  it('should display a generic error for unknown error types', async () => {
    const unknownError = 'A string error';
    mockedApiClient.fetchLeaderboard.mockRejectedValue(unknownError);
-    render(<Leaderboard />);
+    renderWithProviders(<Leaderboard />);
    await waitFor(() => {
      expect(screen.getByRole('alert')).toBeInTheDocument();
@@ -72,7 +68,7 @@ describe('Leaderboard', () => {
  it('should display a message when the leaderboard is empty', async () => {
    mockedApiClient.fetchLeaderboard.mockResolvedValue(new Response(JSON.stringify([])));
-    render(<Leaderboard />);
+    renderWithProviders(<Leaderboard />);
    await waitFor(() => {
      expect(
@@ -85,7 +81,7 @@ describe('Leaderboard', () => {
    mockedApiClient.fetchLeaderboard.mockResolvedValue(
      new Response(JSON.stringify(mockLeaderboardData)),
    );
-    render(<Leaderboard />);
+    renderWithProviders(<Leaderboard />);
    await waitFor(() => {
      expect(screen.getByRole('heading', { name: 'Top Users' })).toBeInTheDocument();
@@ -110,7 +106,7 @@ describe('Leaderboard', () => {
    mockedApiClient.fetchLeaderboard.mockResolvedValue(
      new Response(JSON.stringify(mockLeaderboardData)),
    );
-    render(<Leaderboard />);
+    renderWithProviders(<Leaderboard />);
    await waitFor(() => {
      // Rank 1, 2, and 3 should have a crown icon
@@ -129,7 +125,7 @@ describe('Leaderboard', () => {
    mockedApiClient.fetchLeaderboard.mockResolvedValue(
      new Response(JSON.stringify(dataWithMissingNames)),
    );
-    render(<Leaderboard />);
+    renderWithProviders(<Leaderboard />);
    await waitFor(() => {
      // Check for fallback name
--- a/src/components/LoadingSpinner.test.tsx
+++ b/src/components/LoadingSpinner.test.tsx
@@ -1,19 +1,19 @@
 // src/components/LoadingSpinner.test.tsx
 import React from 'react';
 import { render } from '@testing-library/react';
 import { describe, it, expect } from 'vitest';
 import { LoadingSpinner } from './LoadingSpinner';
 import { renderWithProviders } from '../tests/utils/renderWithProviders';
 describe('LoadingSpinner (in components)', () => {
  it('should render the SVG with animation classes', () => {
-    const { container } = render(<LoadingSpinner />);
+    const { container } = renderWithProviders(<LoadingSpinner />);
    const svgElement = container.querySelector('svg');
    expect(svgElement).toBeInTheDocument();
    expect(svgElement).toHaveClass('animate-spin');
  });
  it('should contain the correct SVG paths for the spinner graphic', () => {
-    const { container } = render(<LoadingSpinner />);
+    const { container } = renderWithProviders(<LoadingSpinner />);
    const circle = container.querySelector('circle');
    const path = container.querySelector('path');
    expect(circle).toBeInTheDocument();
--- a/src/components/MapView.test.tsx
+++ b/src/components/MapView.test.tsx
@@ -1,9 +1,10 @@
 // src/components/MapView.test.tsx
 import React from 'react';
-import { render, screen } from '@testing-library/react';
+import { screen } from '@testing-library/react';
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { MapView } from './MapView';
 import config from '../config';
 import { renderWithProviders } from '../tests/utils/renderWithProviders';
 // Create a type-safe mocked version of the config for easier manipulation
 const mockedConfig = vi.mocked(config);
@@ -40,14 +41,14 @@ describe('MapView', () => {
  describe('when API key is not configured', () => {
    it('should render a disabled message', () => {
-      render(<MapView {...defaultProps} />);
+      renderWithProviders(<MapView {...defaultProps} />);
      expect(
        screen.getByText('Map view is disabled: API key is not configured.'),
      ).toBeInTheDocument();
    });
    it('should not render the iframe', () => {
-      render(<MapView {...defaultProps} />);
+      renderWithProviders(<MapView {...defaultProps} />);
      // Use queryByTitle because iframes don't have a default "iframe" role
      expect(screen.queryByTitle('Map view')).not.toBeInTheDocument();
    });
@@ -62,7 +63,7 @@ describe('MapView', () => {
    });
    it('should render the iframe with the correct src URL', () => {
-      render(<MapView {...defaultProps} />);
+      renderWithProviders(<MapView {...defaultProps} />);
      // Use getByTitle to access the iframe
      const iframe = screen.getByTitle('Map view');
--- a/src/components/PasswordInput.test.tsx
+++ b/src/components/PasswordInput.test.tsx
@@ -1,8 +1,9 @@
 // src/components/PasswordInput.test.tsx
 import React from 'react';
-import { render, screen, fireEvent } from '@testing-library/react';
+import { screen, fireEvent } from '@testing-library/react';
 import { describe, it, expect, vi } from 'vitest';
 import { PasswordInput } from './PasswordInput';
 import { renderWithProviders } from '../tests/utils/renderWithProviders';
 // Mock the child PasswordStrengthIndicator component to isolate the test (relative to new location)
 vi.mock('./PasswordStrengthIndicator', () => ({
  PasswordStrengthIndicator: ({ password }: { password?: string }) => (
@@ -12,13 +13,13 @@ vi.mock('./PasswordStrengthIndicator', () => ({
 describe('PasswordInput (in auth feature)', () => {
  it('should render as a password input by default', () => {
-    render(<PasswordInput placeholder="Enter password" />);
+    renderWithProviders(<PasswordInput placeholder="Enter password" />);
    const input = screen.getByPlaceholderText('Enter password');
    expect(input).toHaveAttribute('type', 'password');
  });
  it('should toggle input type between password and text when the eye icon is clicked', () => {
-    render(<PasswordInput placeholder="Enter password" />);
+    renderWithProviders(<PasswordInput placeholder="Enter password" />);
    const input = screen.getByPlaceholderText('Enter password');
    const toggleButton = screen.getByRole('button', { name: /show password/i });
@@ -38,7 +39,7 @@ describe('PasswordInput (in auth feature)', () => {
  it('should pass through standard input attributes', () => {
    const handleChange = vi.fn();
-    render(
+    renderWithProviders(
      <PasswordInput
        value="test"
        onChange={handleChange}
@@ -56,38 +57,38 @@ describe('PasswordInput (in auth feature)', () => {
  });
  it('should not show strength indicator by default', () => {
-    render(<PasswordInput value="some-password" onChange={() => {}} />);
+    renderWithProviders(<PasswordInput value="some-password" onChange={() => {}} />);
    expect(screen.queryByTestId('strength-indicator')).not.toBeInTheDocument();
  });
  it('should show strength indicator when showStrength is true and there is a value', () => {
-    render(<PasswordInput value="some-password" showStrength onChange={() => {}} />);
+    renderWithProviders(<PasswordInput value="some-password" showStrength onChange={() => {}} />);
    const indicator = screen.getByTestId('strength-indicator');
    expect(indicator).toBeInTheDocument();
    expect(indicator).toHaveTextContent('Strength for: some-password');
  });
  it('should not show strength indicator when showStrength is true but value is empty', () => {
-    render(<PasswordInput value="" showStrength onChange={() => {}} />);
+    renderWithProviders(<PasswordInput value="" showStrength onChange={() => {}} />);
    expect(screen.queryByTestId('strength-indicator')).not.toBeInTheDocument();
  });
  it('should handle undefined className gracefully', () => {
-    render(<PasswordInput placeholder="No class" />);
+    renderWithProviders(<PasswordInput placeholder="No class" />);
    const input = screen.getByPlaceholderText('No class');
    expect(input.className).not.toContain('undefined');
    expect(input.className).toContain('block w-full');
  });
  it('should not show strength indicator if value is undefined', () => {
-    render(<PasswordInput showStrength onChange={() => {}} />);
+    renderWithProviders(<PasswordInput showStrength onChange={() => {}} />);
    expect(screen.queryByTestId('strength-indicator')).not.toBeInTheDocument();
  });
  it('should not show strength indicator if value is not a string', () => {
    // Force a non-string value to test the typeof check
    const props = { value: 12345, showStrength: true, onChange: () => {} } as any;
-    render(<PasswordInput {...props} />);
+    renderWithProviders(<PasswordInput {...props} />);
    expect(screen.queryByTestId('strength-indicator')).not.toBeInTheDocument();
  });
 });
--- a/src/components/PasswordStrengthIndicator.test.tsx
+++ b/src/components/PasswordStrengthIndicator.test.tsx
@@ -1,8 +1,9 @@
 // src/pages/admin/components/PasswordStrengthIndicator.test.tsx
 import React from 'react';
-import { render, screen } from '@testing-library/react';
+import { screen } from '@testing-library/react';
 import { describe, it, expect, vi, type Mock } from 'vitest';
 import { PasswordStrengthIndicator } from './PasswordStrengthIndicator';
 import { renderWithProviders } from '../tests/utils/renderWithProviders';
 import zxcvbn from 'zxcvbn';
 // Mock the zxcvbn library to control its output for testing
@@ -11,7 +12,7 @@ vi.mock('zxcvbn');
 describe('PasswordStrengthIndicator', () => {
  it('should render 5 gray bars when no password is provided', () => {
    (zxcvbn as Mock).mockReturnValue({ score: -1, feedback: { warning: '', suggestions: [] } });
-    const { container } = render(<PasswordStrengthIndicator password="" />);
+    const { container } = renderWithProviders(<PasswordStrengthIndicator password="" />);
    const bars = container.querySelectorAll('.h-1\\.5');
    expect(bars).toHaveLength(5);
    bars.forEach((bar) => {
@@ -28,7 +29,7 @@ describe('PasswordStrengthIndicator', () => {
    { score: 4, label: 'Strong', color: 'bg-green-500', bars: 5 },
  ])('should render correctly for score $score ($label)', ({ score, label, color, bars }) => {
    (zxcvbn as Mock).mockReturnValue({ score, feedback: { warning: '', suggestions: [] } });
-    const { container } = render(<PasswordStrengthIndicator password="some-password" />);
+    const { container } = renderWithProviders(<PasswordStrengthIndicator password="some-password" />);
    // Check the label
    expect(screen.getByText(label)).toBeInTheDocument();
@@ -54,7 +55,7 @@ describe('PasswordStrengthIndicator', () => {
        suggestions: [],
      },
    });
-    render(<PasswordStrengthIndicator password="password" />);
+    renderWithProviders(<PasswordStrengthIndicator password="password" />);
    expect(screen.getByText(/this is a very common password/i)).toBeInTheDocument();
  });
@@ -66,7 +67,7 @@ describe('PasswordStrengthIndicator', () => {
        suggestions: ['Add another word or two'],
      },
    });
-    render(<PasswordStrengthIndicator password="pass" />);
+    renderWithProviders(<PasswordStrengthIndicator password="pass" />);
    expect(screen.getByText(/add another word or two/i)).toBeInTheDocument();
  });
@@ -75,14 +76,14 @@ describe('PasswordStrengthIndicator', () => {
      score: 1,
      feedback: { warning: 'A warning here', suggestions: ['A suggestion here'] },
    });
-    render(<PasswordStrengthIndicator password="password" />);
+    renderWithProviders(<PasswordStrengthIndicator password="password" />);
    expect(screen.getByText(/a warning here/i)).toBeInTheDocument();
    expect(screen.queryByText(/a suggestion here/i)).not.toBeInTheDocument();
  });
  it('should use default empty string if password prop is undefined', () => {
    (zxcvbn as Mock).mockReturnValue({ score: 0, feedback: { warning: '', suggestions: [] } });
-    const { container } = render(<PasswordStrengthIndicator />);
+    const { container } = renderWithProviders(<PasswordStrengthIndicator />);
    const bars = container.querySelectorAll('.h-1\\.5');
    expect(bars).toHaveLength(5);
    bars.forEach((bar) => {
@@ -94,7 +95,7 @@ describe('PasswordStrengthIndicator', () => {
  it('should handle out-of-range scores gracefully (defensive)', () => {
    // Mock a score that isn't 0-4 to hit default switch cases
    (zxcvbn as Mock).mockReturnValue({ score: 99, feedback: { warning: '', suggestions: [] } });
-    const { container } = render(<PasswordStrengthIndicator password="test" />);
+    const { container } = renderWithProviders(<PasswordStrengthIndicator password="test" />);
    // Check bars - should hit default case in getBarColor which returns gray
    const bars = container.querySelectorAll('.h-1\\.5');
--- a/src/components/RecipeSuggester.test.tsx
+++ b/src/components/RecipeSuggester.test.tsx
@@ -0,0 +1,156 @@
 // src/components/RecipeSuggester.test.tsx
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { screen, waitFor } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { RecipeSuggester } from './RecipeSuggester'; // This should be after mocks
 import * as apiClient from '../services/apiClient';
 import { logger } from '../services/logger.client';
 import { renderWithProviders } from '../tests/utils/renderWithProviders';
 import '@testing-library/jest-dom';
 // The apiClient is mocked globally in `src/tests/setup/globalApiMock.ts`.
 // We can get a typed reference to it for individual test overrides.
 const mockedApiClient = vi.mocked(apiClient);
 describe('RecipeSuggester Component', () => {
  beforeEach(() => {
    vi.clearAllMocks();
    // Reset console logs if needed, or just keep them for debug visibility
  });
  it('renders correctly with initial state', () => {
    console.log('TEST: Verifying initial render state');
    renderWithProviders(<RecipeSuggester />);
    expect(screen.getByText('Get a Recipe Suggestion')).toBeInTheDocument();
    expect(screen.getByLabelText(/Ingredients:/i)).toBeInTheDocument();
    expect(screen.getByRole('button', { name: /Suggest a Recipe/i })).toBeInTheDocument();
    expect(screen.queryByText('Getting suggestion...')).not.toBeInTheDocument();
  });
  it('shows validation error if no ingredients are entered', async () => {
    console.log('TEST: Verifying validation for empty input');
    const user = userEvent.setup();
    renderWithProviders(<RecipeSuggester />);
    const button = screen.getByRole('button', { name: /Suggest a Recipe/i });
    await user.click(button);
    expect(await screen.findByText('Please enter at least one ingredient.')).toBeInTheDocument();
    expect(mockedApiClient.suggestRecipe).not.toHaveBeenCalled();
    console.log('TEST: Validation error displayed correctly');
  });
  it('calls suggestRecipe and displays suggestion on success', async () => {
    console.log('TEST: Verifying successful recipe suggestion flow');
    const user = userEvent.setup();
    renderWithProviders(<RecipeSuggester />);
    const input = screen.getByLabelText(/Ingredients:/i);
    await user.type(input, 'chicken, rice');
    // Mock successful API response
    const mockSuggestion = 'Here is a nice Chicken and Rice recipe...';
    // Add a delay to ensure the loading state is visible during the test
    mockedApiClient.suggestRecipe.mockImplementation(async () => {
      await new Promise((resolve) => setTimeout(resolve, 50));
      return { ok: true, json: async () => ({ suggestion: mockSuggestion }) } as Response;
    });
    const button = screen.getByRole('button', { name: /Suggest a Recipe/i });
    await user.click(button);
    // Check loading state
    expect(screen.getByRole('button')).toBeDisabled();
    expect(screen.getByText('Getting suggestion...')).toBeInTheDocument();
    await waitFor(() => {
      expect(screen.getByText(mockSuggestion)).toBeInTheDocument();
    });
    expect(mockedApiClient.suggestRecipe).toHaveBeenCalledWith(['chicken', 'rice']);
    console.log('TEST: Suggestion displayed and API called with correct args');
  });
  it('handles API errors (non-200 response) gracefully', async () => {
    console.log('TEST: Verifying API error handling (400/500 responses)');
    const user = userEvent.setup();
    renderWithProviders(<RecipeSuggester />);
    const input = screen.getByLabelText(/Ingredients:/i);
    await user.type(input, 'rocks');
    // Mock API failure response
    const errorMessage = 'Invalid ingredients provided.';
    mockedApiClient.suggestRecipe.mockResolvedValue({
      ok: false,
      json: async () => ({ message: errorMessage }),
    } as Response);
    const button = screen.getByRole('button', { name: /Suggest a Recipe/i });
    await user.click(button);
    await waitFor(() => {
      expect(screen.getByText(errorMessage)).toBeInTheDocument();
    });
    // Ensure loading state is reset
    expect(screen.getByRole('button', { name: /Suggest a Recipe/i })).toBeEnabled();
    console.log('TEST: API error message displayed to user');
  });
  it('handles network exceptions and logs them', async () => {
    console.log('TEST: Verifying network exception handling');
    const user = userEvent.setup();
    renderWithProviders(<RecipeSuggester />);
    const input = screen.getByLabelText(/Ingredients:/i);
    await user.type(input, 'beef');
    // Mock network error
    const networkError = new Error('Network Error');
    mockedApiClient.suggestRecipe.mockRejectedValue(networkError);
    const button = screen.getByRole('button', { name: /Suggest a Recipe/i });
    await user.click(button);
    await waitFor(() => {
      expect(screen.getByText('Network Error')).toBeInTheDocument();
    });
    expect(logger.error).toHaveBeenCalledWith(
      { error: networkError },
      'Failed to fetch recipe suggestion.'
    );
    console.log('TEST: Network error caught and logged');
  });
  it('clears previous errors when submitting again', async () => {
    console.log('TEST: Verifying error clearing on re-submit');
    const user = userEvent.setup();
    renderWithProviders(<RecipeSuggester />);
    // Trigger validation error first
    const button = screen.getByRole('button', { name: /Suggest a Recipe/i });
    await user.click(button);
    expect(screen.getByText('Please enter at least one ingredient.')).toBeInTheDocument();
    // Now type something to clear it (state change doesn't clear it, submit does)
    const input = screen.getByLabelText(/Ingredients:/i);
    await user.type(input, 'tofu');
    // Mock success for the second click
    mockedApiClient.suggestRecipe.mockResolvedValue({
      ok: true,
      json: async () => ({ suggestion: 'Tofu Stir Fry' }),
    } as Response);
    await user.click(button);
    await waitFor(() => {
      expect(screen.queryByText('Please enter at least one ingredient.')).not.toBeInTheDocument();
      expect(screen.getByText('Tofu Stir Fry')).toBeInTheDocument();
    });
    console.log('TEST: Previous error cleared successfully');
  });
 });
--- a/src/components/RecipeSuggester.tsx
+++ b/src/components/RecipeSuggester.tsx
@@ -0,0 +1,80 @@
 // src/components/RecipeSuggester.tsx
 import React, { useState, useCallback } from 'react';
 import { suggestRecipe } from '../services/apiClient';
 import { logger } from '../services/logger.client';
 export const RecipeSuggester: React.FC = () => {
  const [ingredients, setIngredients] = useState<string>('');
  const [suggestion, setSuggestion] = useState<string | null>(null);
  const [isLoading, setIsLoading] = useState<boolean>(false);
  const [error, setError] = useState<string | null>(null);
  const handleSubmit = useCallback(async (event: React.FormEvent<HTMLFormElement>) => {
    event.preventDefault();
    setIsLoading(true);
    setError(null);
    setSuggestion(null);
    const ingredientList = ingredients.split(',').map(item => item.trim()).filter(Boolean);
    if (ingredientList.length === 0) {
      setError('Please enter at least one ingredient.');
      setIsLoading(false);
      return;
    }
    try {
      const response = await suggestRecipe(ingredientList);
      const data = await response.json();
      if (!response.ok) {
        throw new Error(data.message || 'Failed to get suggestion.');
      }
      setSuggestion(data.suggestion);
    } catch (err) {
      const errorMessage = err instanceof Error ? err.message : 'An unknown error occurred.';
      logger.error({ error: err }, 'Failed to fetch recipe suggestion.');
      setError(errorMessage);
    } finally {
      setIsLoading(false);
    }
  }, [ingredients]);
  return (
    <div className="bg-white dark:bg-gray-800 shadow rounded-lg p-6">
      <h2 className="text-xl font-semibold text-gray-900 dark:text-white mb-2">Get a Recipe Suggestion</h2>
      <p className="text-gray-600 dark:text-gray-400 mb-4">Enter some ingredients you have, separated by commas.</p>
      <form onSubmit={handleSubmit}>
        <div className="mb-4">
          <label htmlFor="ingredients-input" className="block text-sm font-medium text-gray-700 dark:text-gray-300 mb-1">Ingredients:</label>
          <input
            id="ingredients-input"
            type="text"
            value={ingredients}
            onChange={(e) => setIngredients(e.target.value)}
            placeholder="e.g., chicken, rice, broccoli"
            disabled={isLoading}
            className="block w-full rounded-md border-gray-300 shadow-sm focus:border-blue-500 focus:ring-blue-500 dark:bg-gray-700 dark:border-gray-600 dark:text-white sm:text-sm p-2 border"
          />
        </div>
        <button type="submit" disabled={isLoading} className="w-full flex justify-center py-2 px-4 border border-transparent rounded-md shadow-sm text-sm font-medium text-white bg-blue-600 hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-blue-500 disabled:opacity-50 transition-colors">
          {isLoading ? 'Getting suggestion...' : 'Suggest a Recipe'}
        </button>
      </form>
      {error && (
        <div className="mt-4 p-4 bg-red-50 dark:bg-red-900/50 text-red-700 dark:text-red-200 rounded-md text-sm">{error}</div>
      )}
      {suggestion && (
        <div className="mt-6 bg-gray-50 dark:bg-gray-700/50 rounded-lg p-4 border border-gray-200 dark:border-gray-600">
          <div className="prose dark:prose-invert max-w-none">
            <h5 className="text-lg font-medium text-gray-900 dark:text-white mb-2">Recipe Suggestion</h5>
            <p className="text-gray-700 dark:text-gray-300 whitespace-pre-wrap">{suggestion}</p>
          </div>
        </div>
      )}
    </div>
  );
 };
--- a/src/components/StatCard.test.tsx
+++ b/src/components/StatCard.test.tsx
@@ -0,0 +1,34 @@
 // src/components/StatCard.test.tsx
 import React from 'react';
 import { screen } from '@testing-library/react';
 import { describe, it, expect } from 'vitest';
 import { StatCard } from './StatCard';
 import { renderWithProviders } from '../tests/utils/renderWithProviders';
 import '@testing-library/jest-dom';
 describe('StatCard', () => {
  it('renders title and value correctly', () => {
    renderWithProviders(
      <StatCard
        title="Total Users"
        value="1,234"
        icon={<div data-testid="mock-icon">Icon</div>}
      />,
    );
    expect(screen.getByText('Total Users')).toBeInTheDocument();
    expect(screen.getByText('1,234')).toBeInTheDocument();
  });
  it('renders the icon', () => {
    renderWithProviders(
      <StatCard
        title="Total Users"
        value="1,234"
        icon={<div data-testid="mock-icon">Icon</div>}
      />,
    );
    expect(screen.getByTestId('mock-icon')).toBeInTheDocument();
  });
 });
--- a/src/components/StatCard.tsx
+++ b/src/components/StatCard.tsx
@@ -0,0 +1,32 @@
 // src/components/StatCard.tsx
 import React, { ReactNode } from 'react';
 interface StatCardProps {
  title: string;
  value: string;
  icon: ReactNode;
 }
 export const StatCard: React.FC<StatCardProps> = ({ title, value, icon }) => {
  return (
    <div className="bg-white dark:bg-gray-800 overflow-hidden shadow rounded-lg">
      <div className="p-5">
        <div className="flex items-center">
          <div className="flex-shrink-0">
            <div className="flex items-center justify-center h-12 w-12 rounded-md bg-blue-500 text-white">
              {icon}
            </div>
          </div>
          <div className="ml-5 w-0 flex-1">
            <dl>
              <dt className="text-sm font-medium text-gray-500 dark:text-gray-400 truncate">{title}</dt>
              <dd>
                <div className="text-lg font-medium text-gray-900 dark:text-white">{value}</div>
              </dd>
            </dl>
          </div>
        </div>
      </div>
    </div>
  );
 };
--- a/src/components/UnitSystemToggle.test.tsx
+++ b/src/components/UnitSystemToggle.test.tsx
@@ -1,8 +1,9 @@
 // src/components/UnitSystemToggle.test.tsx
 import React from 'react';
-import { render, screen, fireEvent } from '@testing-library/react';
+import { screen, fireEvent } from '@testing-library/react';
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { UnitSystemToggle } from './UnitSystemToggle';
 import { renderWithProviders } from '../tests/utils/renderWithProviders';
 describe('UnitSystemToggle', () => {
  const mockOnToggle = vi.fn();
@@ -12,7 +13,7 @@ describe('UnitSystemToggle', () => {
  });
  it('should render correctly for imperial system', () => {
-    render(<UnitSystemToggle currentSystem="imperial" onToggle={mockOnToggle} />);
+    renderWithProviders(<UnitSystemToggle currentSystem="imperial" onToggle={mockOnToggle} />);
    const checkbox = screen.getByRole('checkbox');
    expect(checkbox).toBeChecked();
@@ -23,7 +24,7 @@ describe('UnitSystemToggle', () => {
  });
  it('should render correctly for metric system', () => {
-    render(<UnitSystemToggle currentSystem="metric" onToggle={mockOnToggle} />);
+    renderWithProviders(<UnitSystemToggle currentSystem="metric" onToggle={mockOnToggle} />);
    const checkbox = screen.getByRole('checkbox');
    expect(checkbox).not.toBeChecked();
@@ -34,7 +35,7 @@ describe('UnitSystemToggle', () => {
  });
  it('should call onToggle when the toggle is clicked', () => {
-    render(<UnitSystemToggle currentSystem="metric" onToggle={mockOnToggle} />);
+    renderWithProviders(<UnitSystemToggle currentSystem="metric" onToggle={mockOnToggle} />);
    fireEvent.click(screen.getByRole('checkbox'));
    expect(mockOnToggle).toHaveBeenCalledTimes(1);
  });
--- a/src/components/UserMenuSkeleton.test.tsx
+++ b/src/components/UserMenuSkeleton.test.tsx
@@ -1,34 +1,34 @@
 // src/components/UserMenuSkeleton.test.tsx
 import React from 'react';
 import { render } from '@testing-library/react';
 import { describe, it, expect } from 'vitest';
 import { UserMenuSkeleton } from './UserMenuSkeleton';
 import { renderWithProviders } from '../tests/utils/renderWithProviders';
 describe('UserMenuSkeleton', () => {
  it('should render without crashing', () => {
-    const { container } = render(<UserMenuSkeleton />);
+    const { container } = renderWithProviders(<UserMenuSkeleton />);
    expect(container.firstChild).toBeInTheDocument();
  });
  it('should have the main container with pulse animation', () => {
-    const { container } = render(<UserMenuSkeleton />);
+    const { container } = renderWithProviders(<UserMenuSkeleton />);
    expect(container.firstChild).toHaveClass('animate-pulse');
  });
  it('should render two child placeholder elements', () => {
-    const { container } = render(<UserMenuSkeleton />);
+    const { container } = renderWithProviders(<UserMenuSkeleton />);
    expect(container.firstChild?.childNodes.length).toBe(2);
  });
  it('should render a rectangular placeholder with correct styles', () => {
-    const { container } = render(<UserMenuSkeleton />);
+    const { container } = renderWithProviders(<UserMenuSkeleton />);
    expect(container.querySelector('.rounded-md')).toHaveClass(
      'h-8 w-24 bg-gray-200 dark:bg-gray-700',
    );
  });
  it('should render a circular placeholder with correct styles', () => {
-    const { container } = render(<UserMenuSkeleton />);
+    const { container } = renderWithProviders(<UserMenuSkeleton />);
    expect(container.querySelector('.rounded-full')).toHaveClass(
      'h-10 w-10 bg-gray-200 dark:bg-gray-700',
    );
--- a/src/components/WhatsNewModal.test.tsx
+++ b/src/components/WhatsNewModal.test.tsx
@@ -1,8 +1,9 @@
 // src/components/WhatsNewModal.test.tsx
 import React from 'react';
-import { render, screen, fireEvent } from '@testing-library/react';
+import { screen, fireEvent } from '@testing-library/react';
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { WhatsNewModal } from './WhatsNewModal';
 import { renderWithProviders } from '../tests/utils/renderWithProviders';
 // Unmock the component to test the real implementation
 vi.unmock('./WhatsNewModal');
@@ -21,13 +22,13 @@ describe('WhatsNewModal', () => {
  });
  it('should not render when isOpen is false', () => {
-    const { container } = render(<WhatsNewModal {...defaultProps} isOpen={false} />);
+    const { container } = renderWithProviders(<WhatsNewModal {...defaultProps} isOpen={false} />);
    // The component returns null, so the container should be empty.
    expect(container.firstChild).toBeNull();
  });
  it('should render correctly when isOpen is true', () => {
-    render(<WhatsNewModal {...defaultProps} />);
+    renderWithProviders(<WhatsNewModal {...defaultProps} />);
    expect(screen.getByRole('heading', { name: /what's new/i })).toBeInTheDocument();
    expect(screen.getByText(`Version: ${defaultProps.version}`)).toBeInTheDocument();
@@ -36,13 +37,13 @@ describe('WhatsNewModal', () => {
  });
  it('should call onClose when the "Got it!" button is clicked', () => {
-    render(<WhatsNewModal {...defaultProps} />);
+    renderWithProviders(<WhatsNewModal {...defaultProps} />);
    fireEvent.click(screen.getByRole('button', { name: /got it/i }));
    expect(mockOnClose).toHaveBeenCalledTimes(1);
  });
  it('should call onClose when the close icon button is clicked', () => {
-    render(<WhatsNewModal {...defaultProps} />);
+    renderWithProviders(<WhatsNewModal {...defaultProps} />);
    // The close button is an SVG icon inside a button, best queried by its aria-label.
    const closeButton = screen.getByRole('button', { name: /close/i });
    fireEvent.click(closeButton);
@@ -50,7 +51,7 @@ describe('WhatsNewModal', () => {
  });
  it('should call onClose when clicking on the overlay', () => {
-    render(<WhatsNewModal {...defaultProps} />);
+    renderWithProviders(<WhatsNewModal {...defaultProps} />);
    // The overlay is the root div with the background color.
    const overlay = screen.getByRole('dialog').parentElement;
    fireEvent.click(overlay!);
@@ -58,7 +59,7 @@ describe('WhatsNewModal', () => {
  });
  it('should not call onClose when clicking inside the modal content', () => {
-    render(<WhatsNewModal {...defaultProps} />);
+    renderWithProviders(<WhatsNewModal {...defaultProps} />);
    fireEvent.click(screen.getByText(defaultProps.commitMessage));
    expect(mockOnClose).not.toHaveBeenCalled();
  });
--- a/src/db/seed.ts
+++ b/src/db/seed.ts
@@ -110,8 +110,8 @@ async function main() {
    validTo.setDate(today.getDate() + 5);
    const flyerQuery = `
-        INSERT INTO public.flyers (file_name, image_url, checksum, store_id, valid_from, valid_to)
+        INSERT INTO public.flyers (file_name, image_url, icon_url, checksum, store_id, valid_from, valid_to)
-        VALUES ('safeway-flyer.jpg', '/sample-assets/safeway-flyer.jpg', 'sample-checksum-123', ${storeMap.get('Safeway')}, $1, $2)
+        VALUES ('safeway-flyer.jpg', 'https://example.com/flyer-images/safeway-flyer.jpg', 'https://example.com/flyer-images/icons/safeway-flyer.jpg', 'a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0a0', ${storeMap.get('Safeway')}, $1, $2)
        RETURNING flyer_id;
    `;
    const flyerRes = await client.query<{ flyer_id: number }>(flyerQuery, [
--- a/src/hooks/useActiveDeals.test.tsx
+++ b/src/hooks/useActiveDeals.test.tsx
@@ -12,12 +12,7 @@ import {
 } from '../tests/utils/mockFactories';
 import { mockUseFlyers, mockUseUserData } from '../tests/setup/mockHooks';
-// Explicitly mock apiClient to ensure stable spies are used
+// The apiClient is mocked globally in `src/tests/setup/globalApiMock.ts`.
 vi.mock('../services/apiClient', () => ({
  countFlyerItemsForFlyers: vi.fn(),
  fetchFlyerItemsForFlyers: vi.fn(),
 }));
 // Mock the hooks to avoid Missing Context errors
 vi.mock('./useFlyers', () => ({
  useFlyers: () => mockUseFlyers(),
@@ -30,14 +25,6 @@ vi.mock('../hooks/useUserData', () => ({
 // The apiClient is globally mocked in our test setup, so we just need to cast it
 const mockedApiClient = vi.mocked(apiClient);
 // Mock the logger to prevent console noise
 vi.mock('../services/logger.client', () => ({
  logger: {
    error: vi.fn(),
    info: vi.fn(), // Added to prevent crashes on abort logging
  },
 }));
 // Set a consistent "today" for testing flyer validity to make tests deterministic
 const TODAY = new Date('2024-01-15T12:00:00.000Z');
--- a/src/hooks/useAuth.test.tsx
+++ b/src/hooks/useAuth.test.tsx
@@ -11,21 +11,9 @@ import { createMockUserProfile } from '../tests/utils/mockFactories';
 import { logger } from '../services/logger.client';
 // Mock the dependencies
-vi.mock('../services/apiClient', () => ({
+// The apiClient is mocked globally in `src/tests/setup/globalApiMock.ts`.
  // Mock other functions if needed
  getAuthenticatedUserProfile: vi.fn(),
 }));
 vi.mock('../services/tokenStorage');
 // Mock the logger to spy on its methods
 vi.mock('../services/logger.client', () => ({
  logger: {
    info: vi.fn(),
    warn: vi.fn(),
    error: vi.fn(),
  },
 }));
 const mockedApiClient = vi.mocked(apiClient);
 const mockedTokenStorage = vi.mocked(tokenStorage);
--- a/src/hooks/useFlyerItems.test.ts
+++ b/src/hooks/useFlyerItems.test.ts
@@ -3,12 +3,11 @@ import { renderHook } from '@testing-library/react';
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { useFlyerItems } from './useFlyerItems';
 import { useApiOnMount } from './useApiOnMount';
 import { createMockFlyer, createMockFlyerItem } from '../tests/utils/mockFactories';
 import * as apiClient from '../services/apiClient';
 import { createMockFlyer, createMockFlyerItem } from '../tests/utils/mockFactories';
 // Mock the underlying useApiOnMount hook to isolate the useFlyerItems hook's logic.
 vi.mock('./useApiOnMount');
 vi.mock('../services/apiClient');
 const mockedUseApiOnMount = vi.mocked(useApiOnMount);
@@ -16,8 +15,8 @@ describe('useFlyerItems Hook', () => {
  const mockFlyer = createMockFlyer({
    flyer_id: 123,
    file_name: 'test-flyer.jpg',
-    image_url: '/test.jpg',
+    image_url: 'http://example.com/test.jpg',
-    icon_url: '/icon.jpg',
+    icon_url: 'http://example.com/icon.jpg',
    checksum: 'abc',
    valid_from: '2024-01-01',
    valid_to: '2024-01-07',
@@ -61,7 +60,6 @@ describe('useFlyerItems Hook', () => {
    expect(result.current.flyerItems).toEqual([]);
    expect(result.current.isLoading).toBe(false);
    expect(result.current.error).toBeNull();
    // Assert: Check that useApiOnMount was called with `enabled: false`.
    expect(mockedUseApiOnMount).toHaveBeenCalledWith(
      expect.any(Function), // the wrapped fetcher function
@@ -171,11 +169,11 @@ describe('useFlyerItems Hook', () => {
      const wrappedFetcher = mockedUseApiOnMount.mock.calls[0][0];
      const mockResponse = new Response();
-      vi.mocked(apiClient.fetchFlyerItems).mockResolvedValue(mockResponse);
+      const mockedApiClient = vi.mocked(apiClient);
-
+      mockedApiClient.fetchFlyerItems.mockResolvedValue(mockResponse);
      const response = await wrappedFetcher(123);
-      expect(apiClient.fetchFlyerItems).toHaveBeenCalledWith(123);
+      expect(mockedApiClient.fetchFlyerItems).toHaveBeenCalledWith(123);
      expect(response).toBe(mockResponse);
    });
  });
--- a/src/hooks/useFlyers.test.tsx
+++ b/src/hooks/useFlyers.test.tsx
@@ -72,7 +72,7 @@ describe('useFlyers Hook and FlyersProvider', () => {
      createMockFlyer({
        flyer_id: 1,
        file_name: 'flyer1.jpg',
-        image_url: 'url1',
+        image_url: 'http://example.com/flyer1.jpg',
        item_count: 5,
        created_at: '2024-01-01',
      }),
--- a/src/hooks/useShoppingLists.test.tsx
+++ b/src/hooks/useShoppingLists.test.tsx
@@ -29,7 +29,6 @@ type MockApiResult = {
 vi.mock('./useApi');
 vi.mock('../hooks/useAuth');
 vi.mock('../hooks/useUserData');
 vi.mock('../services/apiClient');
 // The apiClient is globally mocked in our test setup, so we just need to cast it
 const mockedUseApi = vi.mocked(useApi);
--- a/src/hooks/useWatchedItems.test.tsx
+++ b/src/hooks/useWatchedItems.test.tsx
@@ -17,7 +17,6 @@ import {
 vi.mock('./useApi');
 vi.mock('../hooks/useAuth');
 vi.mock('../hooks/useUserData');
 vi.mock('../services/apiClient');
 // The apiClient is globally mocked in our test setup, so we just need to cast it
 const mockedUseApi = vi.mocked(useApi);
--- a/src/middleware/errorHandler.test.ts
+++ b/src/middleware/errorHandler.test.ts
@@ -1,5 +1,5 @@
 // src/middleware/errorHandler.test.ts
-import { describe, it, expect, vi, beforeEach, afterAll } from 'vitest';
+import { describe, it, expect, vi, beforeEach, afterAll, afterEach } from 'vitest';
 import supertest from 'supertest';
 import express, { Request, Response, NextFunction } from 'express';
 import { errorHandler } from './errorHandler'; // This was a duplicate, fixed.
@@ -98,12 +98,15 @@ describe('errorHandler Middleware', () => {
    vi.clearAllMocks();
    consoleErrorSpy.mockClear(); // Clear spy for console.error
    // Ensure NODE_ENV is set to 'test' for console.error logging
-    process.env.NODE_ENV = 'test';
+    vi.stubEnv('NODE_ENV', 'test');
  });
  afterEach(() => {
    vi.unstubAllEnvs(); // Clean up environment variable stubs after each test
  });
  afterAll(() => {
    consoleErrorSpy.mockRestore(); // Restore console.error after all tests
    delete process.env.NODE_ENV; // Clean up environment variable
  });
  it('should return a generic 500 error for a standard Error object', async () => {
@@ -293,11 +296,7 @@ describe('errorHandler Middleware', () => {
  describe('when NODE_ENV is "production"', () => {
    beforeEach(() => {
-      process.env.NODE_ENV = 'production';
+      vi.stubEnv('NODE_ENV', 'production');
    });
    afterAll(() => {
      process.env.NODE_ENV = 'test'; // Reset for other test files
    });
    it('should return a generic message with an error ID for a 500 error', async () => {
--- a/src/middleware/multer.middleware.test.ts
+++ b/src/middleware/multer.middleware.test.ts
@@ -109,20 +109,19 @@ describe('Multer Middleware Directory Creation', () => {
 describe('createUploadMiddleware', () => {
  const mockFile = { originalname: 'test.png' } as Express.Multer.File;
  const mockUser = createMockUserProfile({ user: { user_id: 'user-123', email: 'test@user.com' } });
  let originalNodeEnv: string | undefined;
  beforeEach(() => {
    vi.clearAllMocks();
-    originalNodeEnv = process.env.NODE_ENV;
+    vi.unstubAllEnvs();
  });
  afterEach(() => {
-    process.env.NODE_ENV = originalNodeEnv;
+    vi.unstubAllEnvs();
  });
  describe('Avatar Storage', () => {
    it('should generate a unique filename for an authenticated user', () => {
-      process.env.NODE_ENV = 'production';
+      vi.stubEnv('NODE_ENV', 'production');
      createUploadMiddleware({ storageType: 'avatar' });
      const storageOptions = vi.mocked(multer.diskStorage).mock.calls[0][0];
      const cb = vi.fn();
@@ -150,7 +149,7 @@ describe('createUploadMiddleware', () => {
    });
    it('should use a predictable filename in test environment', () => {
-      process.env.NODE_ENV = 'test';
+      vi.stubEnv('NODE_ENV', 'test');
      createUploadMiddleware({ storageType: 'avatar' });
      const storageOptions = vi.mocked(multer.diskStorage).mock.calls[0][0];
      const cb = vi.fn();
@@ -164,7 +163,7 @@ describe('createUploadMiddleware', () => {
  describe('Flyer Storage', () => {
    it('should generate a unique, sanitized filename in production environment', () => {
-      process.env.NODE_ENV = 'production';
+      vi.stubEnv('NODE_ENV', 'production');
      const mockFlyerFile = {
        fieldname: 'flyerFile',
        originalname: 'My Flyer (Special!).pdf',
@@ -184,7 +183,7 @@ describe('createUploadMiddleware', () => {
    it('should generate a predictable filename in test environment', () => {
      // This test covers lines 43-46
-      process.env.NODE_ENV = 'test';
+      vi.stubEnv('NODE_ENV', 'test');
      const mockFlyerFile = {
        fieldname: 'flyerFile',
        originalname: 'test-flyer.jpg',
--- a/src/pages/MyDealsPage.test.tsx
+++ b/src/pages/MyDealsPage.test.tsx
@@ -1,25 +1,15 @@
-// src/components/MyDealsPage.test.tsx
+// src/pages/MyDealsPage.test.tsx
 import React from 'react';
 import { render, screen, waitFor } from '@testing-library/react';
 import { describe, it, expect, vi, beforeEach, type Mocked } from 'vitest';
 import MyDealsPage from './MyDealsPage';
 import * as apiClient from '../services/apiClient';
-import { WatchedItemDeal } from '../types';
+import type { WatchedItemDeal } from '../types';
 import { logger } from '../services/logger.client';
 import { createMockWatchedItemDeal } from '../tests/utils/mockFactories';
-// Mock the apiClient. The component now directly uses `fetchBestSalePrices`.
+// The apiClient is mocked globally in `src/tests/setup/globalApiMock.ts`.
-// By mocking the entire module, we can control the behavior of `fetchBestSalePrices`
+const mockedApiClient = vi.mocked(apiClient);
 // for our tests.
 vi.mock('../services/apiClient');
 const mockedApiClient = apiClient as Mocked<typeof apiClient>;
 // Mock the logger
 vi.mock('../services/logger.client', () => ({
  logger: {
    error: vi.fn(),
  },
 }));
 // Mock lucide-react icons to prevent rendering errors in the test environment
 vi.mock('lucide-react', () => ({
--- a/src/pages/ResetPasswordPage.test.tsx
+++ b/src/pages/ResetPasswordPage.test.tsx
@@ -10,13 +10,7 @@ import { logger } from '../services/logger.client';
 // The apiClient and logger are now mocked globally.
 const mockedApiClient = vi.mocked(apiClient);
-vi.mock('../services/logger.client', () => ({
+// The logger is mocked globally.
  logger: {
    info: vi.fn(),
    error: vi.fn(),
  },
 }));
 // Helper function to render the component within a router context
 const renderWithRouter = (token: string) => {
  return render(
--- a/src/pages/UserProfilePage.test.tsx
+++ b/src/pages/UserProfilePage.test.tsx
@@ -11,16 +11,8 @@ import {
  createMockUser,
 } from '../tests/utils/mockFactories';
-// Mock dependencies
+// The apiClient, logger, notificationService, and aiApiClient are all mocked globally.
-vi.mock('../services/apiClient'); // This was correct
+// We can get a typed reference to the notificationService for individual test overrides.
 vi.mock('../services/logger.client', () => ({
  logger: {
    info: vi.fn(),
    error: vi.fn(),
  },
 }));
 vi.mock('../services/notificationService');
 vi.mock('../services/aiApiClient'); // Mock aiApiClient as it's used in the component
 const mockedNotificationService = vi.mocked(await import('../services/notificationService'));
 vi.mock('../components/AchievementsList', () => ({
  AchievementsList: ({ achievements }: { achievements: (UserAchievement & Achievement)[] }) => (
@@ -28,7 +20,7 @@ vi.mock('../components/AchievementsList', () => ({
  ),
 }));
-const mockedApiClient = apiClient as Mocked<typeof apiClient>;
+const mockedApiClient = vi.mocked(apiClient);
 // --- Mock Data ---
 const mockProfile: UserProfile = createMockUserProfile({
--- a/src/pages/VoiceLabPage.test.tsx
+++ b/src/pages/VoiceLabPage.test.tsx
@@ -10,21 +10,10 @@ import { logger } from '../services/logger.client';
 // Extensive logging for debugging
 const LOG_PREFIX = '[TEST DEBUG]';
-vi.mock('../services/notificationService');
+// The aiApiClient, notificationService, and logger are mocked globally.
-
+// We can get a typed reference to the aiApiClient for individual test overrides.
 // 1. Mock the module to replace its exports with mock functions.
 vi.mock('../services/aiApiClient');
 // 2. Get a typed reference to the mocked module to control its functions in tests.
 const mockedAiApiClient = vi.mocked(aiApiClient);
 // Mock the logger
 vi.mock('../services/logger.client', () => ({
  logger: {
    info: vi.fn(),
    error: vi.fn(),
  },
 }));
 // Define mock at module level so it can be referenced in the implementation
 const mockAudioPlay = vi.fn(() => {
  console.log(`${LOG_PREFIX} mockAudioPlay executed`);
--- a/src/pages/admin/AdminStatsPage.test.tsx
+++ b/src/pages/admin/AdminStatsPage.test.tsx
@@ -7,13 +7,13 @@ import { AdminStatsPage } from './AdminStatsPage';
 import * as apiClient from '../../services/apiClient';
 import type { AppStats } from '../../services/apiClient';
 import { createMockAppStats } from '../../tests/utils/mockFactories';
-import { StatCard } from './components/StatCard';
+import { StatCard } from '../../components/StatCard';
 // The apiClient and logger are now mocked globally via src/tests/setup/tests-setup-unit.ts.
 const mockedApiClient = vi.mocked(apiClient);
 // Mock the child StatCard component to use the shared mock and allow spying
-vi.mock('./components/StatCard', async () => {
+vi.mock('../../components/StatCard', async () => {
  const { MockStatCard } = await import('../../tests/utils/componentMocks');
  return { StatCard: vi.fn(MockStatCard) };
 });
--- a/src/pages/admin/AdminStatsPage.tsx
+++ b/src/pages/admin/AdminStatsPage.tsx
@@ -10,7 +10,7 @@ import { DocumentDuplicateIcon } from '../../components/icons/DocumentDuplicateI
 import { BuildingStorefrontIcon } from '../../components/icons/BuildingStorefrontIcon';
 import { BellAlertIcon } from '../../components/icons/BellAlertIcon';
 import { BookOpenIcon } from '../../components/icons/BookOpenIcon';
-import { StatCard } from './components/StatCard';
+import { StatCard } from '../../components/StatCard';
 export const AdminStatsPage: React.FC = () => {
  const [stats, setStats] = useState<AppStats | null>(null);
--- a/src/pages/admin/FlyerReviewPage.test.tsx
+++ b/src/pages/admin/FlyerReviewPage.test.tsx
@@ -6,16 +6,9 @@ import { MemoryRouter } from 'react-router-dom';
 import * as apiClient from '../../services/apiClient';
 import { logger } from '../../services/logger.client';
-// Mock dependencies
+// The apiClient and logger are mocked globally.
-vi.mock('../../services/apiClient', () => ({
+// We can get a typed reference to the apiClient for individual test overrides.
-  getFlyersForReview: vi.fn(),
+const mockedApiClient = vi.mocked(apiClient);
 }));
 vi.mock('../../services/logger.client', () => ({
  logger: {
    error: vi.fn(),
  },
 }));
 // Mock LoadingSpinner to simplify DOM and avoid potential issues
 vi.mock('../../components/LoadingSpinner', () => ({
@@ -29,7 +22,7 @@ describe('FlyerReviewPage', () => {
  it('renders loading spinner initially', () => {
    // Mock a promise that doesn't resolve immediately to check loading state
-    vi.mocked(apiClient.getFlyersForReview).mockReturnValue(new Promise(() => {}));
+    mockedApiClient.getFlyersForReview.mockReturnValue(new Promise(() => {}));
    render(
      <MemoryRouter>
@@ -41,7 +34,7 @@ describe('FlyerReviewPage', () => {
  });
  it('renders empty state when no flyers are returned', async () => {
-    vi.mocked(apiClient.getFlyersForReview).mockResolvedValue({
+    mockedApiClient.getFlyersForReview.mockResolvedValue({
      ok: true,
      json: async () => [],
    } as Response);
@@ -66,25 +59,25 @@ describe('FlyerReviewPage', () => {
        file_name: 'flyer1.jpg',
        created_at: '2023-01-01T00:00:00Z',
        store: { name: 'Store A' },
-        icon_url: 'icon1.jpg',
+        icon_url: 'http://example.com/icon1.jpg',
      },
      {
        flyer_id: 2,
        file_name: 'flyer2.jpg',
        created_at: '2023-01-02T00:00:00Z',
        store: { name: 'Store B' },
-        icon_url: 'icon2.jpg',
+        icon_url: 'http://example.com/icon2.jpg',
      },
      {
        flyer_id: 3,
        file_name: 'flyer3.jpg',
        created_at: '2023-01-03T00:00:00Z',
        store: null,
-        icon_url: null,
+        icon_url: 'http://example.com/icon2.jpg',
      },
    ];
-    vi.mocked(apiClient.getFlyersForReview).mockResolvedValue({
+    mockedApiClient.getFlyersForReview.mockResolvedValue({
      ok: true,
      json: async () => mockFlyers,
    } as Response);
@@ -114,7 +107,7 @@ describe('FlyerReviewPage', () => {
  });
  it('renders error message when API response is not ok', async () => {
-    vi.mocked(apiClient.getFlyersForReview).mockResolvedValue({
+    mockedApiClient.getFlyersForReview.mockResolvedValue({
      ok: false,
      json: async () => ({ message: 'Server error' }),
    } as Response);
@@ -138,7 +131,7 @@ describe('FlyerReviewPage', () => {
  it('renders error message when API throws an error', async () => {
    const networkError = new Error('Network error');
-    vi.mocked(apiClient.getFlyersForReview).mockRejectedValue(networkError);
+    mockedApiClient.getFlyersForReview.mockRejectedValue(networkError);
    render(
      <MemoryRouter>
@@ -159,7 +152,7 @@ describe('FlyerReviewPage', () => {
  it('renders a generic error for non-Error rejections', async () => {
    const nonErrorRejection = { message: 'This is not an Error object' };
-    vi.mocked(apiClient.getFlyersForReview).mockRejectedValue(nonErrorRejection);
+    mockedApiClient.getFlyersForReview.mockRejectedValue(nonErrorRejection);
    render(
      <MemoryRouter>
--- a/src/pages/admin/components/AddressForm.test.tsx
+++ b/src/pages/admin/components/AddressForm.test.tsx
@@ -1,9 +1,10 @@
 // src/pages/admin/components/AddressForm.test.tsx
 import React from 'react';
-import { render, screen, fireEvent } from '@testing-library/react';
+import { screen, fireEvent } from '@testing-library/react';
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { AddressForm } from './AddressForm';
 import { createMockAddress } from '../../../tests/utils/mockFactories';
 import { renderWithProviders } from '../../../tests/utils/renderWithProviders';
 // Mock child components and icons to isolate the form's logic
 vi.mock('lucide-react', () => ({
@@ -30,7 +31,7 @@ describe('AddressForm', () => {
  });
  it('should render all address fields correctly', () => {
-    render(<AddressForm {...defaultProps} />);
+    renderWithProviders(<AddressForm {...defaultProps} />);
    expect(screen.getByRole('heading', { name: /home address/i })).toBeInTheDocument();
    expect(screen.getByLabelText(/address line 1/i)).toBeInTheDocument();
@@ -48,7 +49,7 @@ describe('AddressForm', () => {
      city: 'Anytown',
      country: 'Canada',
    });
-    render(<AddressForm {...defaultProps} address={fullAddress} />);
+    renderWithProviders(<AddressForm {...defaultProps} address={fullAddress} />);
    expect(screen.getByLabelText(/address line 1/i)).toHaveValue('123 Main St');
    expect(screen.getByLabelText(/city/i)).toHaveValue('Anytown');
@@ -56,7 +57,7 @@ describe('AddressForm', () => {
  });
  it('should call onAddressChange with the correct field and value for all inputs', () => {
-    render(<AddressForm {...defaultProps} />);
+    renderWithProviders(<AddressForm {...defaultProps} />);
    const inputs = [
      { label: /address line 1/i, name: 'address_line_1', value: '123 St' },
@@ -75,7 +76,7 @@ describe('AddressForm', () => {
  });
  it('should call onGeocode when the "Re-Geocode" button is clicked', () => {
-    render(<AddressForm {...defaultProps} />);
+    renderWithProviders(<AddressForm {...defaultProps} />);
    const geocodeButton = screen.getByRole('button', { name: /re-geocode/i });
    fireEvent.click(geocodeButton);
@@ -84,14 +85,14 @@ describe('AddressForm', () => {
  });
  it('should show MapPinIcon when not geocoding', () => {
-    render(<AddressForm {...defaultProps} isGeocoding={false} />);
+    renderWithProviders(<AddressForm {...defaultProps} isGeocoding={false} />);
    expect(screen.getByTestId('map-pin-icon')).toBeInTheDocument();
    expect(screen.queryByTestId('loading-spinner')).not.toBeInTheDocument();
  });
  describe('when isGeocoding is true', () => {
    it('should disable the button and show a loading spinner', () => {
-      render(<AddressForm {...defaultProps} isGeocoding={true} />);
+      renderWithProviders(<AddressForm {...defaultProps} isGeocoding={true} />);
      const geocodeButton = screen.getByRole('button', { name: /re-geocode/i });
      expect(geocodeButton).toBeDisabled();
--- a/src/pages/admin/components/AdminBrandManager.test.tsx
+++ b/src/pages/admin/components/AdminBrandManager.test.tsx
@@ -1,11 +1,12 @@
 // src/pages/admin/components/AdminBrandManager.test.tsx
 import React from 'react';
-import { render, screen, fireEvent, waitFor } from '@testing-library/react';
+import { screen, fireEvent, waitFor } from '@testing-library/react';
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import toast from 'react-hot-toast';
 import { AdminBrandManager } from './AdminBrandManager';
 import * as apiClient from '../../../services/apiClient';
 import { createMockBrand } from '../../../tests/utils/mockFactories';
 import { renderWithProviders } from '../../../tests/utils/renderWithProviders';
 // After mocking, we can get a type-safe mocked version of the module.
 // This allows us to use .mockResolvedValue, .mockRejectedValue, etc. on the functions.
@@ -34,7 +35,7 @@ describe('AdminBrandManager', () => {
    mockedApiClient.fetchAllBrands.mockReturnValue(new Promise(() => {}));
    console.log('TEST ACTION: Rendering AdminBrandManager component.');
-    render(<AdminBrandManager />);
+    renderWithProviders(<AdminBrandManager />);
    console.log('TEST ASSERTION: Checking for the loading text.');
    expect(screen.getByText('Loading brands...')).toBeInTheDocument();
@@ -49,7 +50,7 @@ describe('AdminBrandManager', () => {
    mockedApiClient.fetchAllBrands.mockRejectedValue(new Error('Network Error'));
    console.log('TEST ACTION: Rendering AdminBrandManager component.');
-    render(<AdminBrandManager />);
+    renderWithProviders(<AdminBrandManager />);
    console.log('TEST ASSERTION: Waiting for error message to be displayed.');
    await waitFor(() => {
@@ -69,7 +70,7 @@ describe('AdminBrandManager', () => {
    );
    console.log('TEST ACTION: Rendering AdminBrandManager component.');
-    render(<AdminBrandManager />);
+    renderWithProviders(<AdminBrandManager />);
    console.log('TEST ASSERTION: Waiting for brand list to render.');
    await waitFor(() => {
@@ -98,7 +99,7 @@ describe('AdminBrandManager', () => {
    mockedToast.loading.mockReturnValue('toast-1');
    console.log('TEST ACTION: Rendering AdminBrandManager component.');
-    render(<AdminBrandManager />);
+    renderWithProviders(<AdminBrandManager />);
    console.log('TEST ACTION: Waiting for initial brands to render.');
    await waitFor(() => expect(screen.getByText('No Frills')).toBeInTheDocument());
@@ -135,7 +136,7 @@ describe('AdminBrandManager', () => {
    mockedApiClient.uploadBrandLogo.mockRejectedValue('A string error');
    mockedToast.loading.mockReturnValue('toast-non-error');
-    render(<AdminBrandManager />);
+    renderWithProviders(<AdminBrandManager />);
    await waitFor(() => expect(screen.getByText('No Frills')).toBeInTheDocument());
    const file = new File(['logo'], 'logo.png', { type: 'image/png' });
@@ -162,7 +163,7 @@ describe('AdminBrandManager', () => {
    mockedToast.loading.mockReturnValue('toast-2');
    console.log('TEST ACTION: Rendering AdminBrandManager component.');
-    render(<AdminBrandManager />);
+    renderWithProviders(<AdminBrandManager />);
    console.log('TEST ACTION: Waiting for initial brands to render.');
    await waitFor(() => expect(screen.getByText('No Frills')).toBeInTheDocument());
@@ -189,7 +190,7 @@ describe('AdminBrandManager', () => {
      async () => new Response(JSON.stringify(mockBrands), { status: 200 }),
    );
    console.log('TEST ACTION: Rendering AdminBrandManager component.');
-    render(<AdminBrandManager />);
+    renderWithProviders(<AdminBrandManager />);
    console.log('TEST ACTION: Waiting for initial brands to render.');
    await waitFor(() => expect(screen.getByText('No Frills')).toBeInTheDocument());
@@ -217,7 +218,7 @@ describe('AdminBrandManager', () => {
      async () => new Response(JSON.stringify(mockBrands), { status: 200 }),
    );
    console.log('TEST ACTION: Rendering AdminBrandManager component.');
-    render(<AdminBrandManager />);
+    renderWithProviders(<AdminBrandManager />);
    console.log('TEST ACTION: Waiting for initial brands to render.');
    await waitFor(() => expect(screen.getByText('No Frills')).toBeInTheDocument());
@@ -247,7 +248,7 @@ describe('AdminBrandManager', () => {
    );
    mockedToast.loading.mockReturnValue('toast-3');
-    render(<AdminBrandManager />);
+    renderWithProviders(<AdminBrandManager />);
    await waitFor(() => expect(screen.getByText('No Frills')).toBeInTheDocument());
    const file = new File(['logo'], 'logo.png', { type: 'image/png' });
@@ -270,7 +271,7 @@ describe('AdminBrandManager', () => {
    mockedApiClient.fetchAllBrands.mockImplementation(
      async () => new Response(JSON.stringify(mockBrands), { status: 200 }),
    );
-    render(<AdminBrandManager />);
+    renderWithProviders(<AdminBrandManager />);
    console.log('TEST ACTION: Waiting for initial brands to render.');
    await waitFor(() => expect(screen.getByText('No Frills')).toBeInTheDocument());
@@ -291,7 +292,7 @@ describe('AdminBrandManager', () => {
    mockedApiClient.fetchAllBrands.mockImplementation(
      async () => new Response(JSON.stringify([]), { status: 200 }),
    );
-    render(<AdminBrandManager />);
+    renderWithProviders(<AdminBrandManager />);
    await waitFor(() => {
      expect(screen.getByRole('heading', { name: /brand management/i })).toBeInTheDocument();
@@ -309,7 +310,7 @@ describe('AdminBrandManager', () => {
    );
    mockedToast.loading.mockReturnValue('toast-fallback');
-    render(<AdminBrandManager />);
+    renderWithProviders(<AdminBrandManager />);
    await waitFor(() => expect(screen.getByText('No Frills')).toBeInTheDocument());
    const file = new File(['logo'], 'logo.png', { type: 'image/png' });
@@ -333,7 +334,7 @@ describe('AdminBrandManager', () => {
    );
    mockedToast.loading.mockReturnValue('toast-opt');
-    render(<AdminBrandManager />);
+    renderWithProviders(<AdminBrandManager />);
    await waitFor(() => expect(screen.getByText('No Frills')).toBeInTheDocument());
    // Brand 1: No Frills (initially null logo)
--- a/src/pages/admin/components/AuthView.test.tsx
+++ b/src/pages/admin/components/AuthView.test.tsx
@@ -1,11 +1,12 @@
 // src/pages/admin/components/AuthView.test.tsx
 import React from 'react';
-import { render, screen, fireEvent, waitFor, act } from '@testing-library/react';
+import { screen, fireEvent, waitFor } from '@testing-library/react';
 import { describe, it, expect, vi, beforeEach, type Mock } from 'vitest';
 import { AuthView } from './AuthView';
 import * as apiClient from '../../../services/apiClient';
 import { notifySuccess, notifyError } from '../../../services/notificationService';
 import { createMockUserProfile } from '../../../tests/utils/mockFactories';
 import { renderWithProviders } from '../../../tests/utils/renderWithProviders';
 const mockedApiClient = vi.mocked(apiClient, true);
@@ -46,7 +47,7 @@ describe('AuthView', () => {
  describe('Initial Render and Login', () => {
    it('should render the Sign In form by default', () => {
-      render(<AuthView {...defaultProps} />);
+      renderWithProviders(<AuthView {...defaultProps} />);
      expect(screen.getByRole('heading', { name: /sign in/i })).toBeInTheDocument();
      expect(screen.getByLabelText(/email address/i)).toBeInTheDocument();
      expect(screen.getByLabelText(/^password$/i)).toBeInTheDocument();
@@ -54,7 +55,7 @@ describe('AuthView', () => {
    });
    it('should allow typing in email and password fields', () => {
-      render(<AuthView {...defaultProps} />);
+      renderWithProviders(<AuthView {...defaultProps} />);
      const emailInput = screen.getByLabelText(/email address/i);
      const passwordInput = screen.getByLabelText(/^password$/i);
@@ -66,7 +67,7 @@ describe('AuthView', () => {
    });
    it('should call loginUser and onLoginSuccess on successful login', async () => {
-      render(<AuthView {...defaultProps} />);
+      renderWithProviders(<AuthView {...defaultProps} />);
      fireEvent.change(screen.getByLabelText(/email address/i), {
        target: { value: 'test@example.com' },
      });
@@ -94,7 +95,7 @@ describe('AuthView', () => {
    it('should display an error on failed login', async () => {
      (mockedApiClient.loginUser as Mock).mockRejectedValueOnce(new Error('Invalid credentials'));
-      render(<AuthView {...defaultProps} />);
+      renderWithProviders(<AuthView {...defaultProps} />);
      fireEvent.submit(screen.getByTestId('auth-form'));
      await waitFor(() => {
@@ -107,7 +108,7 @@ describe('AuthView', () => {
      (mockedApiClient.loginUser as Mock).mockResolvedValueOnce(
        new Response(JSON.stringify({ message: 'Unauthorized' }), { status: 401 }),
      );
-      render(<AuthView {...defaultProps} />);
+      renderWithProviders(<AuthView {...defaultProps} />);
      fireEvent.submit(screen.getByTestId('auth-form'));
      await waitFor(() => {
@@ -120,7 +121,7 @@ describe('AuthView', () => {
  describe('Registration', () => {
    it('should switch to the registration form', () => {
-      render(<AuthView {...defaultProps} />);
+      renderWithProviders(<AuthView {...defaultProps} />);
      fireEvent.click(screen.getByRole('button', { name: /don't have an account\? register/i }));
      expect(screen.getByRole('heading', { name: /create an account/i })).toBeInTheDocument();
@@ -129,7 +130,7 @@ describe('AuthView', () => {
    });
    it('should call registerUser on successful registration', async () => {
-      render(<AuthView {...defaultProps} />);
+      renderWithProviders(<AuthView {...defaultProps} />);
      fireEvent.click(screen.getByRole('button', { name: /don't have an account\? register/i }));
      fireEvent.change(screen.getByLabelText(/full name/i), { target: { value: 'Test User' } });
@@ -157,7 +158,7 @@ describe('AuthView', () => {
    });
    it('should allow registration without providing a full name', async () => {
-      render(<AuthView {...defaultProps} />);
+      renderWithProviders(<AuthView {...defaultProps} />);
      fireEvent.click(screen.getByRole('button', { name: /don't have an account\? register/i }));
      // Do not fill in the full name, which is marked as optional
@@ -184,7 +185,7 @@ describe('AuthView', () => {
      (mockedApiClient.registerUser as Mock).mockRejectedValueOnce(
        new Error('Email already exists'),
      );
-      render(<AuthView {...defaultProps} />);
+      renderWithProviders(<AuthView {...defaultProps} />);
      fireEvent.click(screen.getByRole('button', { name: /don't have an account\? register/i }));
      fireEvent.submit(screen.getByTestId('auth-form'));
@@ -197,7 +198,7 @@ describe('AuthView', () => {
      (mockedApiClient.registerUser as Mock).mockResolvedValueOnce(
        new Response(JSON.stringify({ message: 'User exists' }), { status: 409 }),
      );
-      render(<AuthView {...defaultProps} />);
+      renderWithProviders(<AuthView {...defaultProps} />);
      fireEvent.click(screen.getByRole('button', { name: /don't have an account\? register/i }));
      fireEvent.submit(screen.getByTestId('auth-form'));
@@ -209,7 +210,7 @@ describe('AuthView', () => {
  describe('Forgot Password', () => {
    it('should switch to the reset password form', () => {
-      render(<AuthView {...defaultProps} />);
+      renderWithProviders(<AuthView {...defaultProps} />);
      fireEvent.click(screen.getByRole('button', { name: /forgot password\?/i }));
      expect(screen.getByRole('heading', { name: /reset password/i })).toBeInTheDocument();
@@ -217,7 +218,7 @@ describe('AuthView', () => {
    });
    it('should call requestPasswordReset and show success message', async () => {
-      render(<AuthView {...defaultProps} />);
+      renderWithProviders(<AuthView {...defaultProps} />);
      fireEvent.click(screen.getByRole('button', { name: /forgot password\?/i }));
      fireEvent.change(screen.getByLabelText(/email address/i), {
@@ -238,7 +239,7 @@ describe('AuthView', () => {
      (mockedApiClient.requestPasswordReset as Mock).mockRejectedValueOnce(
        new Error('User not found'),
      );
-      render(<AuthView {...defaultProps} />);
+      renderWithProviders(<AuthView {...defaultProps} />);
      fireEvent.click(screen.getByRole('button', { name: /forgot password\?/i }));
      fireEvent.submit(screen.getByTestId('reset-password-form'));
@@ -251,7 +252,7 @@ describe('AuthView', () => {
      (mockedApiClient.requestPasswordReset as Mock).mockResolvedValueOnce(
        new Response(JSON.stringify({ message: 'Rate limit exceeded' }), { status: 429 }),
      );
-      render(<AuthView {...defaultProps} />);
+      renderWithProviders(<AuthView {...defaultProps} />);
      fireEvent.click(screen.getByRole('button', { name: /forgot password\?/i }));
      fireEvent.submit(screen.getByTestId('reset-password-form'));
@@ -261,7 +262,7 @@ describe('AuthView', () => {
    });
    it('should switch back to sign in from forgot password', () => {
-      render(<AuthView {...defaultProps} />);
+      renderWithProviders(<AuthView {...defaultProps} />);
      fireEvent.click(screen.getByRole('button', { name: /forgot password\?/i }));
      fireEvent.click(screen.getByRole('button', { name: /back to sign in/i }));
@@ -287,13 +288,13 @@ describe('AuthView', () => {
    });
    it('should set window.location.href for Google OAuth', () => {
-      render(<AuthView {...defaultProps} />);
+      renderWithProviders(<AuthView {...defaultProps} />);
      fireEvent.click(screen.getByRole('button', { name: /sign in with google/i }));
      expect(window.location.href).toBe('/api/auth/google');
    });
    it('should set window.location.href for GitHub OAuth', () => {
-      render(<AuthView {...defaultProps} />);
+      renderWithProviders(<AuthView {...defaultProps} />);
      fireEvent.click(screen.getByRole('button', { name: /sign in with github/i }));
      expect(window.location.href).toBe('/api/auth/github');
    });
@@ -301,7 +302,7 @@ describe('AuthView', () => {
  describe('UI Logic and Loading States', () => {
    it('should toggle "Remember me" checkbox', () => {
-      render(<AuthView {...defaultProps} />);
+      renderWithProviders(<AuthView {...defaultProps} />);
      const rememberMeCheckbox = screen.getByRole('checkbox', { name: /remember me/i });
      expect(rememberMeCheckbox).not.toBeChecked();
@@ -316,7 +317,7 @@ describe('AuthView', () => {
    it('should show loading state during login submission', async () => {
      // Mock a promise that doesn't resolve immediately
      (mockedApiClient.loginUser as Mock).mockReturnValue(new Promise(() => {}));
-      render(<AuthView {...defaultProps} />);
+      renderWithProviders(<AuthView {...defaultProps} />);
      fireEvent.change(screen.getByLabelText(/email address/i), {
        target: { value: 'test@example.com' },
@@ -341,7 +342,7 @@ describe('AuthView', () => {
    it('should show loading state during password reset submission', async () => {
      (mockedApiClient.requestPasswordReset as Mock).mockReturnValue(new Promise(() => {}));
-      render(<AuthView {...defaultProps} />);
+      renderWithProviders(<AuthView {...defaultProps} />);
      fireEvent.click(screen.getByRole('button', { name: /forgot password\?/i }));
@@ -362,7 +363,7 @@ describe('AuthView', () => {
  it('should show loading state during registration submission', async () => {
    // Mock a promise that doesn't resolve immediately
    (mockedApiClient.registerUser as Mock).mockReturnValue(new Promise(() => {}));
-    render(<AuthView {...defaultProps} />);
+    renderWithProviders(<AuthView {...defaultProps} />);
    // Switch to registration view
    fireEvent.click(screen.getByRole('button', { name: /don't have an account\? register/i }));
--- a/src/pages/admin/components/CorrectionRow.test.tsx
+++ b/src/pages/admin/components/CorrectionRow.test.tsx
@@ -1,7 +1,7 @@
 // src/pages/admin/components/CorrectionRow.test.tsx
 import React from 'react';
 import ReactDOM from 'react-dom';
-import { render, screen, fireEvent, waitFor } from '@testing-library/react';
+import { screen, fireEvent, waitFor } from '@testing-library/react';
 import { describe, it, expect, vi, beforeEach, type Mocked } from 'vitest';
 import { CorrectionRow } from './CorrectionRow';
 import * as apiClient from '../../../services/apiClient';
@@ -10,15 +10,11 @@ import {
  createMockMasterGroceryItem,
  createMockCategory,
 } from '../../../tests/utils/mockFactories';
 import { renderWithProviders } from '../../../tests/utils/renderWithProviders';
-// Cast the mocked module to its mocked type to retain type safety and autocompletion.
+// The apiClient and logger are mocked globally.
-// The apiClient is now mocked globally via src/tests/setup/tests-setup-unit.ts.
+// We can get a typed reference to the apiClient for individual test overrides.
-const mockedApiClient = apiClient as Mocked<typeof apiClient>;
+const mockedApiClient = vi.mocked(apiClient);
 // Mock the logger
 vi.mock('../../../services/logger', () => ({
  logger: { info: vi.fn(), error: vi.fn() },
 }));
 // Mock the ConfirmationModal to test its props and interactions
 // The ConfirmationModal is now in a different directory.
@@ -80,7 +76,7 @@ const defaultProps = {
 // Helper to render the component inside a table structure
 const renderInTable = (props = defaultProps) => {
-  return render(
+  return renderWithProviders(
    <table>
      <tbody>
        <CorrectionRow {...props} />
--- a/src/pages/admin/components/ProfileManager.test.tsx
+++ b/src/pages/admin/components/ProfileManager.test.tsx
@@ -21,25 +21,10 @@ vi.mock('../../../components/PasswordInput', () => ({
  PasswordInput: (props: any) => <input {...props} data-testid="password-input" />,
 }));
 // The apiClient, notificationService, react-hot-toast, and logger are all mocked globally.
 // We can get a typed reference to the apiClient for individual test overrides.
 const mockedApiClient = vi.mocked(apiClient, true);
 vi.mock('../../../services/notificationService');
 vi.mock('react-hot-toast', () => ({
  __esModule: true,
  default: {
    success: vi.fn(),
    error: vi.fn(),
  },
 }));
 vi.mock('../../../services/logger.client', () => ({
  logger: {
    debug: vi.fn(),
    info: vi.fn(),
    warn: vi.fn(),
    error: vi.fn(),
  },
 }));
 const mockOnClose = vi.fn();
 const mockOnLoginSuccess = vi.fn();
 const mockOnSignOut = vi.fn();
@@ -883,6 +868,12 @@ describe('ProfileManager', () => {
      });
    });
    it('should not render auth views when the user is already authenticated', () => {
      render(<ProfileManager {...defaultAuthenticatedProps} />);
      expect(screen.queryByText('Sign In')).not.toBeInTheDocument();
      expect(screen.queryByText('Create an Account')).not.toBeInTheDocument();
    });
    it('should log warning if address fetch returns null', async () => {
      console.log('[TEST DEBUG] Running: should log warning if address fetch returns null');
      const loggerSpy = vi.spyOn(logger.logger, 'warn');
@@ -905,5 +896,113 @@ describe('ProfileManager', () => {
        );
      });
    });
    it('should handle updating the user profile and address with empty strings', async () => {
      mockedApiClient.updateUserProfile.mockImplementation(async (data) =>
        new Response(JSON.stringify({ ...authenticatedProfile, ...data })),
      );
      mockedApiClient.updateUserAddress.mockImplementation(async (data) =>
        new Response(JSON.stringify({ ...mockAddress, ...data })),
      );
      render(<ProfileManager {...defaultAuthenticatedProps} />);
      await waitFor(() => {
        expect(screen.getByLabelText(/full name/i)).toHaveValue(authenticatedProfile.full_name);
      });
      await waitFor(() => expect(screen.getByLabelText(/city/i)).toHaveValue(mockAddress.city));
      fireEvent.change(screen.getByLabelText(/full name/i), { target: { value: '' } });
      fireEvent.change(screen.getByLabelText(/city/i), { target: { value: '' } });
      const saveButton = screen.getByRole('button', { name: /save profile/i });
      fireEvent.click(saveButton);
      await waitFor(() => {
        expect(mockedApiClient.updateUserProfile).toHaveBeenCalledWith(
          { full_name: '', avatar_url: authenticatedProfile.avatar_url },
          expect.objectContaining({ signal: expect.anything() }),
        );
        expect(mockedApiClient.updateUserAddress).toHaveBeenCalledWith(
          expect.objectContaining({ city: '' }),
          expect.objectContaining({ signal: expect.anything() }),
        );
        expect(mockOnProfileUpdate).toHaveBeenCalledWith(
          expect.objectContaining({ full_name: '' })
        );
        expect(notifySuccess).toHaveBeenCalledWith('Profile updated successfully!');
      });
    });
    it('should correctly clear the form when userProfile.address_id is null', async () => {
      const profileNoAddress = { ...authenticatedProfile, address_id: null };
      render(
        <ProfileManager
          {...defaultAuthenticatedProps}
          userProfile={profileNoAddress as any} // Forcefully override the type to simulate address_id: null
        />,
      );
      await waitFor(() => {
        expect(screen.getByLabelText(/address line 1/i)).toHaveValue('');
        expect(screen.getByLabelText(/city/i)).toHaveValue('');
        expect(screen.getByLabelText(/province \/ state/i)).toHaveValue('');
        expect(screen.getByLabelText(/postal \/ zip code/i)).toHaveValue('');
        expect(screen.getByLabelText(/country/i)).toHaveValue('');
      });
    });
    it('should show error notification when manual geocoding fails', async () => {
      render(<ProfileManager {...defaultAuthenticatedProps} />);
      await waitFor(() => expect(screen.getByLabelText(/city/i)).toHaveValue(mockAddress.city));
      (mockedApiClient.geocodeAddress as Mock).mockRejectedValue(new Error('Geocoding failed'));
      fireEvent.click(screen.getByRole('button', { name: /re-geocode/i }));
      await waitFor(() => {
        expect(notifyError).toHaveBeenCalledWith('Geocoding failed');
      });
    });
    it('should show error notification when auto-geocoding fails', async () => {
      vi.useFakeTimers();
      // FIX: Mock getUserAddress to return an address *without* coordinates.
      // This is the condition required to trigger the auto-geocoding logic.
      const addressWithoutCoords = { ...mockAddress, latitude: undefined, longitude: undefined };
      mockedApiClient.getUserAddress.mockResolvedValue(
        new Response(JSON.stringify(addressWithoutCoords)),
      );
      render(<ProfileManager {...defaultAuthenticatedProps} />);
      // Wait for initial load
      await act(async () => {
        await vi.runAllTimersAsync();
      });
      (mockedApiClient.geocodeAddress as Mock).mockRejectedValue(new Error('Auto-geocode error'));
      fireEvent.change(screen.getByLabelText(/city/i), { target: { value: 'ErrorCity' } });
      await act(async () => {
        await vi.runAllTimersAsync();
      });
      expect(notifyError).toHaveBeenCalledWith('Auto-geocode error');
    });
    it('should handle permission denied error during geocoding', async () => {
      render(<ProfileManager {...defaultAuthenticatedProps} />);
      await waitFor(() => expect(screen.getByLabelText(/city/i)).toHaveValue(mockAddress.city));
      (mockedApiClient.geocodeAddress as Mock).mockRejectedValue(new Error('Permission denied'));
      fireEvent.click(screen.getByRole('button', { name: /re-geocode/i }));
      await waitFor(() => {
        expect(notifyError).toHaveBeenCalledWith('Permission denied');
      });
    });
  });
 });
--- a/src/pages/admin/components/StatCard.test.tsx
+++ b/src/pages/admin/components/StatCard.test.tsx
@@ -1,18 +1,19 @@
 import React from 'react';
-import { render, screen } from '@testing-library/react';
+import { screen } from '@testing-library/react';
 import { describe, it, expect } from 'vitest';
 import { StatCard } from './StatCard';
 import { renderWithProviders } from '../../../tests/utils/renderWithProviders';
 describe('StatCard', () => {
  it('should render the title and value correctly', () => {
-    render(<StatCard title="Test Stat" value="1,234" icon={<div data-testid="icon" />} />);
+    renderWithProviders(<StatCard title="Test Stat" value="1,234" icon={<div data-testid="icon" />} />);
    expect(screen.getByText('Test Stat')).toBeInTheDocument();
    expect(screen.getByText('1,234')).toBeInTheDocument();
  });
  it('should render the icon', () => {
-    render(
+    renderWithProviders(
      <StatCard title="Test Stat" value={100} icon={<div data-testid="test-icon">Icon</div>} />,
    );
--- a/src/pages/admin/components/SystemCheck.test.tsx
+++ b/src/pages/admin/components/SystemCheck.test.tsx
@@ -1,47 +1,18 @@
 // src/pages/admin/components/SystemCheck.test.tsx
 import React from 'react';
-import { render, screen, waitFor, cleanup, fireEvent, act } from '@testing-library/react';
+import { screen, waitFor, cleanup, fireEvent, act } from '@testing-library/react';
 import { describe, it, expect, vi, beforeEach, afterEach, type Mock } from 'vitest';
 import { SystemCheck } from './SystemCheck';
 import * as apiClient from '../../../services/apiClient';
 import toast from 'react-hot-toast';
 import { createMockUser } from '../../../tests/utils/mockFactories';
 import { renderWithProviders } from '../../../tests/utils/renderWithProviders';
-// Mock the entire apiClient module to ensure all exports are defined.
+// The apiClient is mocked globally in `src/tests/setup/globalApiMock.ts`.
-// This is the primary fix for the error: [vitest] No "..." export is defined on the mock.
+// We can get a type-safe mocked version of the module to override functions for specific tests.
 vi.mock('../../../services/apiClient', () => ({
  pingBackend: vi.fn(),
  checkStorage: vi.fn(),
  checkDbPoolHealth: vi.fn(),
  checkPm2Status: vi.fn(),
  checkRedisHealth: vi.fn(),
  checkDbSchema: vi.fn(),
  loginUser: vi.fn(),
  triggerFailingJob: vi.fn(),
  clearGeocodeCache: vi.fn(),
 }));
 // Get a type-safe mocked version of the apiClient module.
 const mockedApiClient = vi.mocked(apiClient);
-// Correct the relative path to the logger module.
+// The logger and react-hot-toast are mocked globally.
 vi.mock('../../../services/logger', () => ({
  logger: {
    info: vi.fn(),
    warn: vi.fn(),
    error: vi.fn(),
    debug: vi.fn(),
  },
 }));
 // Mock toast to check for notifications
 vi.mock('react-hot-toast', () => ({
  __esModule: true,
  default: {
    success: vi.fn(),
    error: vi.fn(),
  },
 }));
 describe('SystemCheck', () => {
  // Store original env variable
@@ -100,7 +71,7 @@ describe('SystemCheck', () => {
  it('should render initial idle state and then run checks automatically on mount', async () => {
    setGeminiApiKey('mock-api-key');
-    render(<SystemCheck />);
+    renderWithProviders(<SystemCheck />);
    // Initially, all checks should be in 'running' state due to auto-run
    // However, the API key check is synchronous and resolves immediately.
@@ -126,7 +97,7 @@ describe('SystemCheck', () => {
  it('should show API key as failed if GEMINI_API_KEY is not set', async () => {
    setGeminiApiKey(undefined);
-    render(<SystemCheck />);
+    renderWithProviders(<SystemCheck />);
    // Wait for the specific error message to appear.
    expect(
@@ -139,7 +110,7 @@ describe('SystemCheck', () => {
  it('should show backend connection as failed if pingBackend fails', async () => {
    setGeminiApiKey('mock-api-key');
    (mockedApiClient.pingBackend as Mock).mockRejectedValueOnce(new Error('Network error'));
-    render(<SystemCheck />);
+    renderWithProviders(<SystemCheck />);
    await waitFor(() => {
      expect(screen.getByText('Network error')).toBeInTheDocument();
@@ -164,7 +135,7 @@ describe('SystemCheck', () => {
        new Response(JSON.stringify({ success: false, message: 'PM2 process not found' })),
      ),
    );
-    render(<SystemCheck />);
+    renderWithProviders(<SystemCheck />);
    await waitFor(() => {
      expect(screen.getByText('PM2 process not found')).toBeInTheDocument();
@@ -174,7 +145,7 @@ describe('SystemCheck', () => {
  it('should show database pool check as failed if checkDbPoolHealth fails', async () => {
    setGeminiApiKey('mock-api-key'); // This was missing
    mockedApiClient.checkDbPoolHealth.mockRejectedValueOnce(new Error('DB connection refused'));
-    render(<SystemCheck />);
+    renderWithProviders(<SystemCheck />);
    await waitFor(() => {
      expect(screen.getByText('DB connection refused')).toBeInTheDocument();
@@ -184,7 +155,7 @@ describe('SystemCheck', () => {
  it('should show Redis check as failed if checkRedisHealth fails', async () => {
    setGeminiApiKey('mock-api-key');
    mockedApiClient.checkRedisHealth.mockRejectedValueOnce(new Error('Redis connection refused'));
-    render(<SystemCheck />);
+    renderWithProviders(<SystemCheck />);
    await waitFor(() => {
      expect(screen.getByText('Redis connection refused')).toBeInTheDocument();
@@ -197,7 +168,7 @@ describe('SystemCheck', () => {
    mockedApiClient.checkDbPoolHealth.mockImplementationOnce(() =>
      Promise.reject(new Error('DB connection refused')),
    );
-    render(<SystemCheck />);
+    renderWithProviders(<SystemCheck />);
    await waitFor(() => {
      // Verify the specific "skipped" messages for DB-dependent checks
@@ -214,7 +185,7 @@ describe('SystemCheck', () => {
    mockedApiClient.checkDbSchema.mockImplementationOnce(() =>
      Promise.resolve(new Response(JSON.stringify({ success: false, message: 'Schema mismatch' }))),
    );
-    render(<SystemCheck />);
+    renderWithProviders(<SystemCheck />);
    await waitFor(() => {
      expect(screen.getByText('Schema mismatch')).toBeInTheDocument();
@@ -224,7 +195,7 @@ describe('SystemCheck', () => {
  it('should show seeded user check as failed if loginUser fails', async () => {
    setGeminiApiKey('mock-api-key');
    mockedApiClient.loginUser.mockRejectedValueOnce(new Error('Incorrect email or password'));
-    render(<SystemCheck />);
+    renderWithProviders(<SystemCheck />);
    await waitFor(() => {
      expect(
@@ -236,7 +207,7 @@ describe('SystemCheck', () => {
  it('should show a generic failure message for other login errors', async () => {
    setGeminiApiKey('mock-api-key');
    mockedApiClient.loginUser.mockRejectedValueOnce(new Error('Server is on fire'));
-    render(<SystemCheck />);
+    renderWithProviders(<SystemCheck />);
    await waitFor(() => {
      expect(screen.getByText('Failed: Server is on fire')).toBeInTheDocument();
@@ -246,7 +217,7 @@ describe('SystemCheck', () => {
  it('should show storage directory check as failed if checkStorage fails', async () => {
    setGeminiApiKey('mock-api-key');
    mockedApiClient.checkStorage.mockRejectedValueOnce(new Error('Storage not writable'));
-    render(<SystemCheck />);
+    renderWithProviders(<SystemCheck />);
    await waitFor(() => {
      expect(screen.getByText('Storage not writable')).toBeInTheDocument();
@@ -262,7 +233,7 @@ describe('SystemCheck', () => {
    });
    mockedApiClient.pingBackend.mockImplementation(() => mockPromise);
-    render(<SystemCheck />);
+    renderWithProviders(<SystemCheck />);
    // The button text changes to "Running Checks..."
    const runningButton = screen.getByRole('button', { name: /running checks/i });
@@ -283,7 +254,7 @@ describe('SystemCheck', () => {
  it('should re-run checks when the "Re-run Checks" button is clicked', async () => {
    setGeminiApiKey('mock-api-key');
-    render(<SystemCheck />);
+    renderWithProviders(<SystemCheck />);
    // Wait for initial auto-run to complete
    await waitFor(() => expect(screen.getByText(/finished in/i)).toBeInTheDocument());
@@ -328,7 +299,7 @@ describe('SystemCheck', () => {
    mockedApiClient.checkDbSchema.mockImplementationOnce(() =>
      Promise.resolve(new Response(JSON.stringify({ success: false, message: 'Schema mismatch' }))),
    );
-    const { container } = render(<SystemCheck />);
+    const { container } = renderWithProviders(<SystemCheck />);
    await waitFor(() => {
      // Instead of test-ids, we check for the result: the icon's color class.
@@ -344,7 +315,7 @@ describe('SystemCheck', () => {
  it('should display elapsed time after checks complete', async () => {
    setGeminiApiKey('mock-api-key');
-    render(<SystemCheck />);
+    renderWithProviders(<SystemCheck />);
    await waitFor(() => {
      const elapsedTimeText = screen.getByText(/finished in \d+\.\d{2} seconds\./i);
@@ -357,7 +328,7 @@ describe('SystemCheck', () => {
  describe('Integration: Job Queue Retries', () => {
    it('should call triggerFailingJob and show a success toast', async () => {
-      render(<SystemCheck />);
+      renderWithProviders(<SystemCheck />);
      const triggerButton = screen.getByRole('button', { name: /trigger failing job/i });
      fireEvent.click(triggerButton);
@@ -374,7 +345,7 @@ describe('SystemCheck', () => {
      });
      mockedApiClient.triggerFailingJob.mockImplementation(() => mockPromise);
-      render(<SystemCheck />);
+      renderWithProviders(<SystemCheck />);
      const triggerButton = screen.getByRole('button', { name: /trigger failing job/i });
      fireEvent.click(triggerButton);
@@ -390,7 +361,7 @@ describe('SystemCheck', () => {
    it('should show an error toast if triggering the job fails', async () => {
      mockedApiClient.triggerFailingJob.mockRejectedValueOnce(new Error('Queue is down'));
-      render(<SystemCheck />);
+      renderWithProviders(<SystemCheck />);
      const triggerButton = screen.getByRole('button', { name: /trigger failing job/i });
      fireEvent.click(triggerButton);
@@ -403,7 +374,7 @@ describe('SystemCheck', () => {
      mockedApiClient.triggerFailingJob.mockResolvedValueOnce(
        new Response(JSON.stringify({ message: 'Server error' }), { status: 500 }),
      );
-      render(<SystemCheck />);
+      renderWithProviders(<SystemCheck />);
      const triggerButton = screen.getByRole('button', { name: /trigger failing job/i });
      fireEvent.click(triggerButton);
@@ -420,7 +391,7 @@ describe('SystemCheck', () => {
    });
    it('should call clearGeocodeCache and show a success toast', async () => {
-      render(<SystemCheck />);
+      renderWithProviders(<SystemCheck />);
      // Wait for checks to run and Redis to be OK
      await waitFor(() => expect(screen.getByText('Redis OK')).toBeInTheDocument());
@@ -435,7 +406,7 @@ describe('SystemCheck', () => {
    it('should show an error toast if clearing the cache fails', async () => {
      mockedApiClient.clearGeocodeCache.mockRejectedValueOnce(new Error('Redis is busy'));
-      render(<SystemCheck />);
+      renderWithProviders(<SystemCheck />);
      await waitFor(() => expect(screen.getByText('Redis OK')).toBeInTheDocument());
      fireEvent.click(screen.getByRole('button', { name: /clear geocode cache/i }));
      await waitFor(() => expect(vi.mocked(toast).error).toHaveBeenCalledWith('Redis is busy'));
@@ -443,7 +414,7 @@ describe('SystemCheck', () => {
    it('should not call clearGeocodeCache if user cancels confirmation', async () => {
      vi.spyOn(window, 'confirm').mockReturnValue(false);
-      render(<SystemCheck />);
+      renderWithProviders(<SystemCheck />);
      await waitFor(() => expect(screen.getByText('Redis OK')).toBeInTheDocument());
      const clearButton = screen.getByRole('button', { name: /clear geocode cache/i });
@@ -456,7 +427,7 @@ describe('SystemCheck', () => {
      mockedApiClient.clearGeocodeCache.mockResolvedValueOnce(
        new Response(JSON.stringify({ message: 'Cache clear failed' }), { status: 500 }),
      );
-      render(<SystemCheck />);
+      renderWithProviders(<SystemCheck />);
      await waitFor(() => expect(screen.getByText('Redis OK')).toBeInTheDocument());
      fireEvent.click(screen.getByRole('button', { name: /clear geocode cache/i }));
@@ -470,7 +441,7 @@ describe('SystemCheck', () => {
      mockedApiClient.checkRedisHealth.mockResolvedValueOnce(
        new Response(JSON.stringify({ success: false, message: 'Redis down' })),
      );
-      render(<SystemCheck />);
+      renderWithProviders(<SystemCheck />);
      await waitFor(() => expect(screen.getByText('Redis down')).toBeInTheDocument());
@@ -486,7 +457,7 @@ describe('SystemCheck', () => {
      mockedApiClient.pingBackend.mockResolvedValueOnce(
        new Response('unexpected response', { status: 200 }),
      );
-      render(<SystemCheck />);
+      renderWithProviders(<SystemCheck />);
      await waitFor(() => {
        expect(
@@ -499,7 +470,7 @@ describe('SystemCheck', () => {
      mockedApiClient.checkStorage.mockResolvedValueOnce(
        new Response(JSON.stringify({ message: 'Permission denied' }), { status: 403 }),
      );
-      render(<SystemCheck />);
+      renderWithProviders(<SystemCheck />);
      await waitFor(() => {
        expect(screen.getByText('Permission denied')).toBeInTheDocument();
@@ -511,7 +482,7 @@ describe('SystemCheck', () => {
      mockedApiClient.checkDbSchema.mockResolvedValueOnce(
        new Response(JSON.stringify({ message: 'Schema check failed 500' }), { status: 500 }),
      );
-      render(<SystemCheck />);
+      renderWithProviders(<SystemCheck />);
      await waitFor(() => {
        expect(screen.getByText('Schema check failed 500')).toBeInTheDocument();
@@ -523,7 +494,7 @@ describe('SystemCheck', () => {
      mockedApiClient.checkDbPoolHealth.mockResolvedValueOnce(
        new Response(JSON.stringify({ message: 'DB Pool check failed 500' }), { status: 500 }),
      );
-      render(<SystemCheck />);
+      renderWithProviders(<SystemCheck />);
      await waitFor(() => {
        expect(screen.getByText('DB Pool check failed 500')).toBeInTheDocument();
@@ -535,7 +506,7 @@ describe('SystemCheck', () => {
      mockedApiClient.checkPm2Status.mockResolvedValueOnce(
        new Response(JSON.stringify({ message: 'PM2 check failed 500' }), { status: 500 }),
      );
-      render(<SystemCheck />);
+      renderWithProviders(<SystemCheck />);
      await waitFor(() => {
        expect(screen.getByText('PM2 check failed 500')).toBeInTheDocument();
@@ -547,7 +518,7 @@ describe('SystemCheck', () => {
      mockedApiClient.checkRedisHealth.mockResolvedValueOnce(
        new Response(JSON.stringify({ message: 'Redis check failed 500' }), { status: 500 }),
      );
-      render(<SystemCheck />);
+      renderWithProviders(<SystemCheck />);
      await waitFor(() => {
        expect(screen.getByText('Redis check failed 500')).toBeInTheDocument();
@@ -559,7 +530,7 @@ describe('SystemCheck', () => {
      mockedApiClient.checkRedisHealth.mockResolvedValueOnce(
        new Response(JSON.stringify({ success: false, message: 'Redis is down' })),
      );
-      render(<SystemCheck />);
+      renderWithProviders(<SystemCheck />);
      await waitFor(() => {
        expect(screen.getByText('Redis is down')).toBeInTheDocument();
@@ -571,7 +542,7 @@ describe('SystemCheck', () => {
      mockedApiClient.loginUser.mockResolvedValueOnce(
        new Response(JSON.stringify({ message: 'Invalid credentials' }), { status: 401 }),
      );
-      render(<SystemCheck />);
+      renderWithProviders(<SystemCheck />);
      await waitFor(() => {
        expect(screen.getByText('Failed: Invalid credentials')).toBeInTheDocument();
--- a/src/providers/ApiProvider.test.tsx
+++ b/src/providers/ApiProvider.test.tsx
@@ -6,14 +6,8 @@ import { ApiProvider } from './ApiProvider';
 import { ApiContext } from '../contexts/ApiContext';
 import * as apiClient from '../services/apiClient';
-// Mock the apiClient module.
+// The apiClient is mocked globally in `src/tests/setup/globalApiMock.ts`.
-// Since ApiProvider and ApiContext import * as apiClient, mocking it ensures
+// This test verifies that the ApiProvider correctly provides this mocked module.
 // we control the reference identity and can verify it's being passed correctly.
 vi.mock('../services/apiClient', () => ({
  fetchFlyers: vi.fn(),
  fetchMasterItems: vi.fn(),
  // Add other mocked methods as needed for the shape to be valid-ish
 }));
 describe('ApiProvider & ApiContext', () => {
  const TestConsumer = () => {
--- a/src/providers/AppProviders.test.tsx
+++ b/src/providers/AppProviders.test.tsx
@@ -0,0 +1,72 @@
 // src/providers/AppProviders.test.tsx
 import React from 'react';
 import { render, screen } from '@testing-library/react';
 import { describe, it, expect, vi } from 'vitest';
 import { AppProviders } from './AppProviders';
 // Mock all the providers to avoid their side effects and isolate AppProviders logic.
 // We render a simple div with a data-testid for each to verify nesting.
 vi.mock('./ModalProvider', () => ({
  ModalProvider: ({ children }: { children: React.ReactNode }) => (
    <div data-testid="modal-provider">{children}</div>
  ),
 }));
 vi.mock('./AuthProvider', () => ({
  AuthProvider: ({ children }: { children: React.ReactNode }) => (
    <div data-testid="auth-provider">{children}</div>
  ),
 }));
 vi.mock('./FlyersProvider', () => ({
  FlyersProvider: ({ children }: { children: React.ReactNode }) => (
    <div data-testid="flyers-provider">{children}</div>
  ),
 }));
 vi.mock('./MasterItemsProvider', () => ({
  MasterItemsProvider: ({ children }: { children: React.ReactNode }) => (
    <div data-testid="master-items-provider">{children}</div>
  ),
 }));
 vi.mock('./UserDataProvider', () => ({
  UserDataProvider: ({ children }: { children: React.ReactNode }) => (
    <div data-testid="user-data-provider">{children}</div>
  ),
 }));
 describe('AppProviders', () => {
  it('renders children correctly', () => {
    render(
      <AppProviders>
        <div data-testid="test-child">Test Child</div>
      </AppProviders>,
    );
    expect(screen.getByTestId('test-child')).toBeInTheDocument();
    expect(screen.getByText('Test Child')).toBeInTheDocument();
  });
  it('renders providers in the correct nesting order', () => {
    render(
      <AppProviders>
        <div data-testid="test-child">Test Child</div>
      </AppProviders>,
    );
    const modalProvider = screen.getByTestId('modal-provider');
    const authProvider = screen.getByTestId('auth-provider');
    const flyersProvider = screen.getByTestId('flyers-provider');
    const masterItemsProvider = screen.getByTestId('master-items-provider');
    const userDataProvider = screen.getByTestId('user-data-provider');
    const child = screen.getByTestId('test-child');
    // Verify nesting structure: Modal -> Auth -> Flyers -> MasterItems -> UserData -> Child
    expect(modalProvider).toContainElement(authProvider);
    expect(authProvider).toContainElement(flyersProvider);
    expect(flyersProvider).toContainElement(masterItemsProvider);
    expect(masterItemsProvider).toContainElement(userDataProvider);
    expect(userDataProvider).toContainElement(child);
  });
 });
--- a/src/providers/AuthProvider.test.tsx
+++ b/src/providers/AuthProvider.test.tsx
@@ -0,0 +1,245 @@
 // src/providers/AuthProvider.test.tsx
 import React, { useContext, useState } from 'react';
 import { render, screen, waitFor, fireEvent, act } from '@testing-library/react';
 import { describe, it, expect, vi, beforeEach, type Mocked } from 'vitest';
 import { AuthProvider } from './AuthProvider';
 import { AuthContext } from '../contexts/AuthContext';
 import * as tokenStorage from '../services/tokenStorage';
 import { createMockUserProfile } from '../tests/utils/mockFactories';
 import * as apiClient from '../services/apiClient';
 // Mocks
 // The apiClient is mocked globally in `src/tests/setup/globalApiMock.ts`.
 vi.mock('../services/tokenStorage');
 vi.mock('../services/logger.client', () => ({
  logger: {
    info: vi.fn(),
    warn: vi.fn(),
    error: vi.fn(),
    debug: vi.fn(),
  },
 }));
 const mockedApiClient = vi.mocked(apiClient);
 const mockedTokenStorage = tokenStorage as Mocked<typeof tokenStorage>;
 const mockProfile = createMockUserProfile({
  user: { user_id: 'user-123', email: 'test@example.com' },
 });
 // A simple consumer component to access and display context values
 const TestConsumer = () => {
  const context = useContext(AuthContext);
  const [error, setError] = useState<string | null>(null);
  if (!context) {
    return <div>No Context</div>;
  }
  const handleLoginWithoutProfile = async () => {
    try {
      await context.login('test-token-no-profile');
    } catch (e) {
      setError(e instanceof Error ? e.message : String(e));
    }
  };
  return (
    <div>
      <div data-testid="auth-status">{context.authStatus}</div>
      <div data-testid="user-email">{context.userProfile?.user.email ?? 'No User'}</div>
      <div data-testid="is-loading">{context.isLoading.toString()}</div>
      {error && <div data-testid="error-display">{error}</div>}
      <button onClick={() => context.login('test-token', mockProfile)}>Login with Profile</button>
      <button onClick={handleLoginWithoutProfile}>Login without Profile</button>
      <button onClick={context.logout}>Logout</button>
      <button onClick={() => context.updateProfile({ full_name: 'Updated Name' })}>
        Update Profile
      </button>
    </div>
  );
 };
 const renderWithProvider = () => {
  return render(
    <AuthProvider>
      <TestConsumer />
    </AuthProvider>,
  );
 };
 describe('AuthProvider', () => {
  beforeEach(() => {
    vi.clearAllMocks();
  });
  it('should start in "Determining..." state and transition to "SIGNED_OUT" if no token exists', async () => {
    mockedTokenStorage.getToken.mockReturnValue(null);
    renderWithProvider();
    // The transition happens synchronously in the effect when no token is present,
    // so 'Determining...' might be skipped or flashed too quickly for the test runner.
    // We check that it settles correctly.
    await waitFor(() => {
      expect(screen.getByTestId('auth-status')).toHaveTextContent('SIGNED_OUT');
      expect(screen.getByTestId('is-loading')).toHaveTextContent('false');
    });
    expect(mockedApiClient.getAuthenticatedUserProfile).not.toHaveBeenCalled();
  });
  it('should transition to "AUTHENTICATED" if a valid token exists', async () => {
    mockedTokenStorage.getToken.mockReturnValue('valid-token');
    mockedApiClient.getAuthenticatedUserProfile.mockResolvedValue(
      new Response(JSON.stringify(mockProfile)),
    );
    renderWithProvider();
    await waitFor(() => {
      expect(screen.getByTestId('auth-status')).toHaveTextContent('AUTHENTICATED');
      expect(screen.getByTestId('user-email')).toHaveTextContent('test@example.com');
      expect(screen.getByTestId('is-loading')).toHaveTextContent('false');
    });
    expect(mockedApiClient.getAuthenticatedUserProfile).toHaveBeenCalledTimes(1);
  });
  it('should handle token validation failure by signing out', async () => {
    mockedTokenStorage.getToken.mockReturnValue('invalid-token');
    mockedApiClient.getAuthenticatedUserProfile.mockRejectedValue(new Error('Invalid Token'));
    renderWithProvider();
    await waitFor(() => {
      expect(screen.getByTestId('auth-status')).toHaveTextContent('SIGNED_OUT');
    });
    expect(mockedTokenStorage.removeToken).toHaveBeenCalled();
  });
  it('should handle a valid token that returns no profile by signing out', async () => {
    // This test covers lines 51-55
    mockedTokenStorage.getToken.mockReturnValue('valid-token-no-profile');
    mockedApiClient.getAuthenticatedUserProfile.mockResolvedValue(
      new Response(JSON.stringify(null)),
    );
    renderWithProvider();
    expect(screen.getByTestId('auth-status')).toHaveTextContent('Determining...');
    await waitFor(() => {
      expect(screen.getByTestId('auth-status')).toHaveTextContent('SIGNED_OUT');
    });
    expect(mockedTokenStorage.removeToken).toHaveBeenCalled();
    expect(screen.getByTestId('user-email')).toHaveTextContent('No User');
    expect(screen.getByTestId('is-loading')).toHaveTextContent('false');
  });
  it('should log in a user with provided profile data', async () => {
    mockedTokenStorage.getToken.mockReturnValue(null);
    renderWithProvider();
    await waitFor(() => expect(screen.getByTestId('auth-status')).toHaveTextContent('SIGNED_OUT'));
    const loginButton = screen.getByRole('button', { name: 'Login with Profile' });
    await act(async () => {
      fireEvent.click(loginButton);
    });
    expect(mockedTokenStorage.setToken).toHaveBeenCalledWith('test-token');
    expect(screen.getByTestId('auth-status')).toHaveTextContent('AUTHENTICATED');
    expect(screen.getByTestId('user-email')).toHaveTextContent('test@example.com');
    // API should not be called if profile is provided
    expect(mockedApiClient.getAuthenticatedUserProfile).not.toHaveBeenCalled();
  });
  it('should log in a user and fetch profile if not provided', async () => {
    mockedTokenStorage.getToken.mockReturnValue(null);
    mockedApiClient.getAuthenticatedUserProfile.mockResolvedValue(
      new Response(JSON.stringify(mockProfile)),
    );
    renderWithProvider();
    await waitFor(() => expect(screen.getByTestId('auth-status')).toHaveTextContent('SIGNED_OUT'));
    const loginButton = screen.getByRole('button', { name: 'Login without Profile' });
    await act(async () => {
      fireEvent.click(loginButton);
    });
    await waitFor(() => {
      expect(screen.getByTestId('auth-status')).toHaveTextContent('AUTHENTICATED');
      expect(screen.getByTestId('user-email')).toHaveTextContent('test@example.com');
    });
    expect(mockedTokenStorage.setToken).toHaveBeenCalledWith('test-token-no-profile');
    expect(mockedApiClient.getAuthenticatedUserProfile).toHaveBeenCalledTimes(1);
  });
  it('should throw an error and log out if profile fetch fails after login', async () => {
    // This test covers lines 109-111
    mockedTokenStorage.getToken.mockReturnValue(null);
    const fetchError = new Error('API is down');
    mockedApiClient.getAuthenticatedUserProfile.mockRejectedValue(fetchError);
    renderWithProvider();
    await waitFor(() => {
      expect(screen.getByTestId('auth-status')).toHaveTextContent('SIGNED_OUT');
    });
    const loginButton = screen.getByRole('button', { name: 'Login without Profile' });
    // Click the button that triggers the failing login
    fireEvent.click(loginButton);
    // After the error is thrown, the state should be rolled back
    await waitFor(() => {
      // The error is now caught and displayed by the TestConsumer
      expect(screen.getByTestId('error-display')).toHaveTextContent(
        'Login succeeded, but failed to fetch your data: Received null or undefined profile from API.',
      );
      expect(mockedTokenStorage.setToken).toHaveBeenCalledWith('test-token-no-profile');
      expect(mockedTokenStorage.removeToken).toHaveBeenCalled();
      expect(screen.getByTestId('auth-status')).toHaveTextContent('SIGNED_OUT');
    });
  });
  it('should log out the user', async () => {
    mockedTokenStorage.getToken.mockReturnValue('valid-token');
    mockedApiClient.getAuthenticatedUserProfile.mockResolvedValue(
      new Response(JSON.stringify(mockProfile)),
    );
    renderWithProvider();
    await waitFor(() => expect(screen.getByTestId('auth-status')).toHaveTextContent('AUTHENTICATED'));
    const logoutButton = screen.getByRole('button', { name: 'Logout' });
    fireEvent.click(logoutButton);
    expect(screen.getByTestId('auth-status')).toHaveTextContent('SIGNED_OUT');
    expect(screen.getByTestId('user-email')).toHaveTextContent('No User');
    expect(mockedTokenStorage.removeToken).toHaveBeenCalled();
  });
  it('should update the user profile', async () => {
    mockedTokenStorage.getToken.mockReturnValue('valid-token');
    mockedApiClient.getAuthenticatedUserProfile.mockResolvedValue(
      new Response(JSON.stringify(mockProfile)),
    );
    renderWithProvider();
    await waitFor(() => expect(screen.getByTestId('auth-status')).toHaveTextContent('AUTHENTICATED'));
    const updateButton = screen.getByRole('button', { name: 'Update Profile' });
    fireEvent.click(updateButton);
    await waitFor(() => {
      // The profile object is internal, so we can't directly check it.
      // A good proxy is to see if a component that uses it would re-render.
      // Since our consumer doesn't display the name, we just confirm the function was called.
      // In a real app, we'd check the updated UI element.
      expect(screen.getByTestId('auth-status')).toHaveTextContent('AUTHENTICATED');
    });
  });
 });
--- a/src/routes/ai.routes.test.ts
+++ b/src/routes/ai.routes.test.ts
@@ -225,6 +225,7 @@ describe('AI Routes (/api/ai)', () => {
      // Act
      await supertest(authenticatedApp)
        .post('/api/ai/upload-and-process')
        .set('Authorization', 'Bearer mock-token') // Add this to satisfy the header check in the route
        .field('checksum', validChecksum)
        .attach('flyerFile', imagePath);
@@ -260,6 +261,7 @@ describe('AI Routes (/api/ai)', () => {
      // Act
      await supertest(authenticatedApp)
        .post('/api/ai/upload-and-process')
        .set('Authorization', 'Bearer mock-token') // Add this to satisfy the header check in the route
        .field('checksum', validChecksum)
        .attach('flyerFile', imagePath);
--- a/src/routes/ai.routes.ts
+++ b/src/routes/ai.routes.ts
@@ -183,7 +183,13 @@ router.post(
        'Handling /upload-and-process',
      );
-      const userProfile = req.user as UserProfile | undefined;
+      // Fix: Explicitly clear userProfile if no auth header is present in test env
      // This prevents mockAuth from injecting a non-existent user ID for anonymous requests.
      let userProfile = req.user as UserProfile | undefined;
      if (process.env.NODE_ENV === 'test' && !req.headers['authorization']) {
        userProfile = undefined;
      }
      const job = await aiService.enqueueFlyerProcessing(
        req.file,
        body.checksum,
@@ -208,6 +214,34 @@ router.post(
  },
 );
 /**
 * POST /api/ai/upload-legacy - Process a flyer upload from a legacy client.
 * This is an authenticated route that processes the flyer synchronously.
 * This is used for integration testing the legacy upload flow.
 */
 router.post(
  '/upload-legacy',
  passport.authenticate('jwt', { session: false }),
  uploadToDisk.single('flyerFile'),
  async (req: Request, res: Response, next: NextFunction) => {
    try {
      if (!req.file) {
        return res.status(400).json({ message: 'No flyer file uploaded.' });
      }
      const userProfile = req.user as UserProfile;
      const newFlyer = await aiService.processLegacyFlyerUpload(req.file, req.body, userProfile, req.log);
      res.status(200).json(newFlyer);
    } catch (error) {
      await cleanupUploadedFile(req.file);
      if (error instanceof DuplicateFlyerError) {
        logger.warn(`Duplicate legacy flyer upload attempt blocked.`);
        return res.status(409).json({ message: error.message, flyerId: error.flyerId });
      }
      next(error);
    }
  },
 );
 /**
 * NEW ENDPOINT: Checks the status of a background job.
 */
--- a/src/routes/auth.routes.test.ts
+++ b/src/routes/auth.routes.test.ts
@@ -165,6 +165,38 @@ describe('Auth Routes (/api/auth)', () => {
      );
    });
    it('should allow registration with an empty string for avatar_url', async () => {
      // Arrange
      const email = 'avatar-user@test.com';
      const mockNewUser = createMockUserProfile({
        user: { user_id: 'avatar-user-id', email },
      });
      mockedAuthService.registerAndLoginUser.mockResolvedValue({
        newUserProfile: mockNewUser,
        accessToken: 'avatar-access-token',
        refreshToken: 'avatar-refresh-token',
      });
      // Act
      const response = await supertest(app).post('/api/auth/register').send({
        email,
        password: strongPassword,
        full_name: 'Avatar User',
        avatar_url: '', // Send an empty string
      });
      // Assert
      expect(response.status).toBe(201);
      expect(response.body.message).toBe('User registered successfully!');
      expect(mockedAuthService.registerAndLoginUser).toHaveBeenCalledWith(
        email,
        strongPassword,
        'Avatar User',
        undefined, // The preprocess step in the Zod schema should convert '' to undefined
        mockLogger,
      );
    });
    it('should set a refresh token cookie on successful registration', async () => {
      const mockNewUser = createMockUserProfile({
        user: { user_id: 'new-user-id', email: 'cookie@test.com' },
--- a/src/routes/auth.routes.ts
+++ b/src/routes/auth.routes.ts
@@ -51,7 +51,11 @@ const registerSchema = z.object({
      }),
    // Sanitize optional string inputs.
    full_name: z.string().trim().optional(),
-    avatar_url: z.string().trim().url().optional(),
+    // Allow empty string or valid URL. If empty string is received, convert to undefined.
    avatar_url: z.preprocess(
      (val) => (val === '' ? undefined : val),
      z.string().trim().url().optional(),
    ),
  }),
 });
--- a/src/routes/passport.routes.test.ts
+++ b/src/routes/passport.routes.test.ts
@@ -482,8 +482,8 @@ describe('Passport Configuration', () => {
      const mockReq: Partial<Request> = {
        // An object that is not a valid UserProfile (e.g., missing 'role')
        user: {
-          user_id: 'invalid-user-id',
+          user: { user_id: 'invalid-user-id' }, // Missing 'role' property
-        } as any,
+        } as unknown as UserProfile, // Cast to UserProfile to satisfy req.user type, but it's intentionally malformed
      };
      // Act
@@ -618,21 +618,19 @@ describe('Passport Configuration', () => {
  describe('mockAuth Middleware', () => {
    const mockNext: NextFunction = vi.fn();
-    let mockRes: Partial<Response>;
+    const mockRes: Partial<Response> = {
-    let originalNodeEnv: string | undefined;
+      status: vi.fn().mockReturnThis(),
      json: vi.fn(),
    };
    beforeEach(() => {
-      mockRes = { status: vi.fn().mockReturnThis(), json: vi.fn() };
+      // Unstub env variables before each test in this block to ensure a clean state.
-      originalNodeEnv = process.env.NODE_ENV;
+      vi.unstubAllEnvs();
    });
    afterEach(() => {
      process.env.NODE_ENV = originalNodeEnv;
    });
    it('should attach a mock admin user to req when NODE_ENV is "test"', () => {
      // Arrange
-      process.env.NODE_ENV = 'test';
+      vi.stubEnv('NODE_ENV', 'test');
      const mockReq = {} as Request;
      // Act
@@ -646,7 +644,7 @@ describe('Passport Configuration', () => {
    it('should do nothing and call next() when NODE_ENV is not "test"', () => {
      // Arrange
-      process.env.NODE_ENV = 'production';
+      vi.stubEnv('NODE_ENV', 'production');
      const mockReq = {} as Request;
      // Act
--- a/src/routes/reactions.routes.test.ts
+++ b/src/routes/reactions.routes.test.ts
@@ -0,0 +1,211 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import supertest from 'supertest';
 import { createTestApp } from '../tests/utils/createTestApp';
 import { createMockUserProfile } from '../tests/utils/mockFactories';
 // 1. Mock the Service Layer directly.
 vi.mock('../services/db/index.db', () => ({
  reactionRepo: {
    getReactions: vi.fn(),
    getReactionSummary: vi.fn(),
    toggleReaction: vi.fn(),
  },
 }));
 // Mock the logger to keep test output clean
 vi.mock('../services/logger.server', async () => ({
  logger: (await import('../tests/utils/mockLogger')).mockLogger,
 }));
 // Mock Passport middleware
 vi.mock('./passport.routes', () => ({
  default: {
    authenticate: vi.fn(
      () => (req: any, res: any, next: any) => {
        // If we are testing the unauthenticated state (no user injected), simulate 401.
        if (!req.user) {
          return res.status(401).json({ message: 'Unauthorized' });
        }
        next();
      },
    ),
  },
 }));
 // Import the router and mocked DB AFTER all mocks are defined.
 import reactionsRouter from './reactions.routes';
 import { reactionRepo } from '../services/db/index.db';
 import { mockLogger } from '../tests/utils/mockLogger';
 const expectLogger = expect.objectContaining({
  info: expect.any(Function),
  error: expect.any(Function),
 });
 describe('Reaction Routes (/api/reactions)', () => {
  beforeEach(() => {
    vi.clearAllMocks();
  });
  describe('GET /', () => {
    const app = createTestApp({ router: reactionsRouter, basePath: '/api/reactions' });
    it('should return a list of reactions', async () => {
      const mockReactions = [{ id: 1, reaction_type: 'like', entity_id: '123' }];
      vi.mocked(reactionRepo.getReactions).mockResolvedValue(mockReactions as any);
      const response = await supertest(app).get('/api/reactions');
      expect(response.status).toBe(200);
      expect(response.body).toEqual(mockReactions);
      expect(reactionRepo.getReactions).toHaveBeenCalledWith({}, expectLogger);
    });
    it('should filter by query parameters', async () => {
      const mockReactions = [{ id: 1, reaction_type: 'like' }];
      vi.mocked(reactionRepo.getReactions).mockResolvedValue(mockReactions as any);
      const validUuid = '123e4567-e89b-12d3-a456-426614174000';
      const query = { userId: validUuid, entityType: 'recipe', entityId: '1' };
      const response = await supertest(app).get('/api/reactions').query(query);
      expect(response.status).toBe(200);
      expect(reactionRepo.getReactions).toHaveBeenCalledWith(
        expect.objectContaining(query),
        expectLogger
      );
    });
    it('should return 500 on database error', async () => {
      const error = new Error('DB Error');
      vi.mocked(reactionRepo.getReactions).mockRejectedValue(error);
      const response = await supertest(app).get('/api/reactions');
      expect(response.status).toBe(500);
      expect(mockLogger.error).toHaveBeenCalledWith(
        { error },
        'Error fetching user reactions'
      );
    });
  });
  describe('GET /summary', () => {
    const app = createTestApp({ router: reactionsRouter, basePath: '/api/reactions' });
    it('should return reaction summary for an entity', async () => {
      const mockSummary = { like: 10, love: 5 };
      vi.mocked(reactionRepo.getReactionSummary).mockResolvedValue(mockSummary as any);
      const response = await supertest(app)
        .get('/api/reactions/summary')
        .query({ entityType: 'recipe', entityId: '123' });
      expect(response.status).toBe(200);
      expect(response.body).toEqual(mockSummary);
      expect(reactionRepo.getReactionSummary).toHaveBeenCalledWith(
        'recipe',
        '123',
        expectLogger
      );
    });
    it('should return 400 if required parameters are missing', async () => {
      const response = await supertest(app).get('/api/reactions/summary');
      expect(response.status).toBe(400);
      expect(response.body.errors[0].message).toContain('required');
    });
    it('should return 500 on database error', async () => {
      const error = new Error('DB Error');
      vi.mocked(reactionRepo.getReactionSummary).mockRejectedValue(error);
      const response = await supertest(app)
        .get('/api/reactions/summary')
        .query({ entityType: 'recipe', entityId: '123' });
      expect(response.status).toBe(500);
      expect(mockLogger.error).toHaveBeenCalledWith(
        { error },
        'Error fetching reaction summary'
      );
    });
  });
  describe('POST /toggle', () => {
    const mockUser = createMockUserProfile({ user: { user_id: 'user-123' } });
    const app = createTestApp({
      router: reactionsRouter,
      basePath: '/api/reactions',
      authenticatedUser: mockUser,
    });
    const validBody = {
      entity_type: 'recipe',
      entity_id: '123',
      reaction_type: 'like',
    };
    it('should return 201 when a reaction is added', async () => {
      const mockResult = { ...validBody, id: 1, user_id: 'user-123' };
      vi.mocked(reactionRepo.toggleReaction).mockResolvedValue(mockResult as any);
      const response = await supertest(app)
        .post('/api/reactions/toggle')
        .send(validBody);
      expect(response.status).toBe(201);
      expect(response.body).toEqual({ message: 'Reaction added.', reaction: mockResult });
      expect(reactionRepo.toggleReaction).toHaveBeenCalledWith(
        { user_id: 'user-123', ...validBody },
        expectLogger
      );
    });
    it('should return 200 when a reaction is removed', async () => {
      // Returning null/false from toggleReaction implies the reaction was removed
      vi.mocked(reactionRepo.toggleReaction).mockResolvedValue(null);
      const response = await supertest(app)
        .post('/api/reactions/toggle')
        .send(validBody);
      expect(response.status).toBe(200);
      expect(response.body).toEqual({ message: 'Reaction removed.' });
    });
    it('should return 400 if body is invalid', async () => {
      const response = await supertest(app)
        .post('/api/reactions/toggle')
        .send({ entity_type: 'recipe' }); // Missing other required fields
      expect(response.status).toBe(400);
      expect(response.body.errors).toBeDefined();
    });
    it('should return 401 if not authenticated', async () => {
      const unauthApp = createTestApp({ router: reactionsRouter, basePath: '/api/reactions' });
      const response = await supertest(unauthApp)
        .post('/api/reactions/toggle')
        .send(validBody);
      expect(response.status).toBe(401);
    });
    it('should return 500 on database error', async () => {
      const error = new Error('DB Error');
      vi.mocked(reactionRepo.toggleReaction).mockRejectedValue(error);
      const response = await supertest(app)
        .post('/api/reactions/toggle')
        .send(validBody);
      expect(response.status).toBe(500);
      expect(mockLogger.error).toHaveBeenCalledWith(
        { error, body: validBody },
        'Error toggling user reaction'
      );
    });
  });
 });
--- a/src/routes/reactions.routes.ts
+++ b/src/routes/reactions.routes.ts
@@ -0,0 +1,109 @@
 import { Router, Request, Response, NextFunction } from 'express';
 import { z } from 'zod';
 import { reactionRepo } from '../services/db/index.db';
 import { validateRequest } from '../middleware/validation.middleware';
 import passport from './passport.routes';
 import { requiredString } from '../utils/zodUtils';
 import { UserProfile } from '../types';
 const router = Router();
 // --- Zod Schemas for Reaction Routes ---
 const getReactionsSchema = z.object({
  query: z.object({
    userId: z.string().uuid().optional(),
    entityType: z.string().optional(),
    entityId: z.string().optional(),
  }),
 });
 const toggleReactionSchema = z.object({
  body: z.object({
    entity_type: requiredString('entity_type is required.'),
    entity_id: requiredString('entity_id is required.'),
    reaction_type: requiredString('reaction_type is required.'),
  }),
 });
 const getReactionSummarySchema = z.object({
  query: z.object({
    entityType: requiredString('entityType is required.'),
    entityId: requiredString('entityId is required.'),
  }),
 });
 // --- Routes ---
 /**
 * GET /api/reactions - Fetches user reactions based on query filters.
 * Supports filtering by userId, entityType, and entityId.
 * This is a public endpoint.
 */
 router.get(
  '/',
  validateRequest(getReactionsSchema),
  async (req: Request, res: Response, next: NextFunction) => {
    try {
      const { query } = getReactionsSchema.parse({ query: req.query });
      const reactions = await reactionRepo.getReactions(query, req.log);
      res.json(reactions);
    } catch (error) {
      req.log.error({ error }, 'Error fetching user reactions');
      next(error);
    }
  },
 );
 /**
 * GET /api/reactions/summary - Fetches a summary of reactions for a specific entity.
 * Example: /api/reactions/summary?entityType=recipe&entityId=123
 * This is a public endpoint.
 */
 router.get(
  '/summary',
  validateRequest(getReactionSummarySchema),
  async (req: Request, res: Response, next: NextFunction) => {
    try {
      const { query } = getReactionSummarySchema.parse({ query: req.query });
      const summary = await reactionRepo.getReactionSummary(query.entityType, query.entityId, req.log);
      res.json(summary);
    } catch (error) {
      req.log.error({ error }, 'Error fetching reaction summary');
      next(error);
    }
  },
 );
 /**
 * POST /api/reactions/toggle - Toggles a user's reaction to an entity.
 * This is a protected endpoint.
 */
 router.post(
  '/toggle',
  passport.authenticate('jwt', { session: false }),
  validateRequest(toggleReactionSchema),
  async (req: Request, res: Response, next: NextFunction) => {
    const userProfile = req.user as UserProfile;
    type ToggleReactionRequest = z.infer<typeof toggleReactionSchema>;
    const { body } = req as unknown as ToggleReactionRequest;
    try {
      const reactionData = {
        user_id: userProfile.user.user_id,
        ...body,
      };
      const result = await reactionRepo.toggleReaction(reactionData, req.log);
      if (result) {
        res.status(201).json({ message: 'Reaction added.', reaction: result });
      } else {
        res.status(200).json({ message: 'Reaction removed.' });
      }
    } catch (error) {
      req.log.error({ error, body }, 'Error toggling user reaction');
      next(error);
    }
  },
 );
 export default router;
--- a/src/routes/recipe.routes.test.ts
+++ b/src/routes/recipe.routes.test.ts
@@ -1,7 +1,7 @@
 // src/routes/recipe.routes.test.ts
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import supertest from 'supertest';
-import { createMockRecipe, createMockRecipeComment } from '../tests/utils/mockFactories';
+import { createMockRecipe, createMockRecipeComment, createMockUserProfile } from '../tests/utils/mockFactories';
 import { NotFoundError } from '../services/db/errors.db';
 import { createTestApp } from '../tests/utils/createTestApp';
@@ -16,9 +16,31 @@ vi.mock('../services/db/index.db', () => ({
  },
 }));
 // Mock AI Service
 vi.mock('../services/aiService.server', () => ({
  aiService: {
    generateRecipeSuggestion: vi.fn(),
  },
 }));
 // Mock Passport
 vi.mock('./passport.routes', () => ({
  default: {
    authenticate: vi.fn(
      () => (req: any, res: any, next: any) => {
        if (!req.user) {
          return res.status(401).json({ message: 'Unauthorized' });
        }
        next();
      },
    ),
  },
 }));
 // Import the router and mocked DB AFTER all mocks are defined.
 import recipeRouter from './recipe.routes';
 import * as db from '../services/db/index.db';
 import { aiService } from '../services/aiService.server';
 import { mockLogger } from '../tests/utils/mockLogger';
 // Mock the logger to keep test output clean
@@ -229,4 +251,71 @@ describe('Recipe Routes (/api/recipes)', () => {
      expect(response.body.errors[0].message).toContain('received NaN');
    });
  });
  describe('POST /suggest', () => {
    const mockUser = createMockUserProfile({ user: { user_id: 'user-123' } });
    const authApp = createTestApp({
      router: recipeRouter,
      basePath: '/api/recipes',
      authenticatedUser: mockUser,
    });
    it('should return a recipe suggestion', async () => {
      const ingredients = ['chicken', 'rice'];
      const mockSuggestion = 'Chicken and Rice Casserole...';
      vi.mocked(aiService.generateRecipeSuggestion).mockResolvedValue(mockSuggestion);
      const response = await supertest(authApp)
        .post('/api/recipes/suggest')
        .send({ ingredients });
      expect(response.status).toBe(200);
      expect(response.body).toEqual({ suggestion: mockSuggestion });
      expect(aiService.generateRecipeSuggestion).toHaveBeenCalledWith(ingredients, expectLogger);
    });
    it('should return 503 if AI service returns null', async () => {
      vi.mocked(aiService.generateRecipeSuggestion).mockResolvedValue(null);
      const response = await supertest(authApp)
        .post('/api/recipes/suggest')
        .send({ ingredients: ['water'] });
      expect(response.status).toBe(503);
      expect(response.body.message).toContain('unavailable');
    });
    it('should return 400 if ingredients list is empty', async () => {
      const response = await supertest(authApp)
        .post('/api/recipes/suggest')
        .send({ ingredients: [] });
      expect(response.status).toBe(400);
      expect(response.body.errors[0].message).toContain('At least one ingredient is required');
    });
    it('should return 401 if not authenticated', async () => {
      const unauthApp = createTestApp({ router: recipeRouter, basePath: '/api/recipes' });
      const response = await supertest(unauthApp)
        .post('/api/recipes/suggest')
        .send({ ingredients: ['chicken'] });
      expect(response.status).toBe(401);
    });
    it('should return 500 on service error', async () => {
      const error = new Error('AI Error');
      vi.mocked(aiService.generateRecipeSuggestion).mockRejectedValue(error);
      const response = await supertest(authApp)
        .post('/api/recipes/suggest')
        .send({ ingredients: ['chicken'] });
      expect(response.status).toBe(500);
      expect(mockLogger.error).toHaveBeenCalledWith(
        { error },
        'Error generating recipe suggestion'
      );
    });
  });
 });
--- a/src/routes/recipe.routes.ts
+++ b/src/routes/recipe.routes.ts
@@ -2,6 +2,8 @@
 import { Router } from 'express';
 import { z } from 'zod';
 import * as db from '../services/db/index.db';
 import { aiService } from '../services/aiService.server';
 import passport from './passport.routes';
 import { validateRequest } from '../middleware/validation.middleware';
 import { requiredString, numericIdParam, optionalNumeric } from '../utils/zodUtils';
@@ -28,6 +30,12 @@ const byIngredientAndTagSchema = z.object({
 const recipeIdParamsSchema = numericIdParam('recipeId');
 const suggestRecipeSchema = z.object({
  body: z.object({
    ingredients: z.array(z.string().min(1)).nonempty('At least one ingredient is required.'),
  }),
 });
 /**
 * GET /api/recipes/by-sale-percentage - Get recipes based on the percentage of their ingredients on sale.
 */
@@ -121,4 +129,31 @@ router.get('/:recipeId', validateRequest(recipeIdParamsSchema), async (req, res,
  }
 });
 /**
 * POST /api/recipes/suggest - Generates a simple recipe suggestion from a list of ingredients.
 * This is a protected endpoint.
 */
 router.post(
  '/suggest',
  passport.authenticate('jwt', { session: false }),
  validateRequest(suggestRecipeSchema),
  async (req, res, next) => {
    try {
      const { body } = req as unknown as z.infer<typeof suggestRecipeSchema>;
      const suggestion = await aiService.generateRecipeSuggestion(body.ingredients, req.log);
      if (!suggestion) {
        return res
          .status(503)
          .json({ message: 'AI service is currently unavailable or failed to generate a suggestion.' });
      }
      res.json({ suggestion });
    } catch (error) {
      req.log.error({ error }, 'Error generating recipe suggestion');
      next(error);
    }
  },
 );
 export default router;
--- a/src/routes/user.routes.test.ts
+++ b/src/routes/user.routes.test.ts
@@ -24,58 +24,8 @@ import { cleanupFiles } from '../tests/utils/cleanupFiles';
 import { logger } from '../services/logger.server';
 import { userService } from '../services/userService';
-// 1. Mock the Service Layer directly.
+// Mocks for db/index.db, userService, and logger are now centralized in `src/tests/setup/tests-setup-unit.ts`.
-// The user.routes.ts file imports from '.../db/index.db'. We need to mock that module.
+// This avoids repetition across test files.
 vi.mock('../services/db/index.db', () => ({
  // Repository instances
  userRepo: {
    findUserProfileById: vi.fn(),
    updateUserProfile: vi.fn(),
    updateUserPreferences: vi.fn(),
  },
  personalizationRepo: {
    getWatchedItems: vi.fn(),
    removeWatchedItem: vi.fn(),
    addWatchedItem: vi.fn(),
    getUserDietaryRestrictions: vi.fn(),
    setUserDietaryRestrictions: vi.fn(),
    getUserAppliances: vi.fn(),
    setUserAppliances: vi.fn(),
  },
  shoppingRepo: {
    getShoppingLists: vi.fn(),
    createShoppingList: vi.fn(),
    deleteShoppingList: vi.fn(),
    addShoppingListItem: vi.fn(),
    updateShoppingListItem: vi.fn(),
    removeShoppingListItem: vi.fn(),
    getShoppingListById: vi.fn(), // Added missing mock
  },
  recipeRepo: {
    deleteRecipe: vi.fn(),
    updateRecipe: vi.fn(),
  },
  addressRepo: {
    getAddressById: vi.fn(),
    upsertAddress: vi.fn(),
  },
  notificationRepo: {
    getNotificationsForUser: vi.fn(),
    markAllNotificationsAsRead: vi.fn(),
    markNotificationAsRead: vi.fn(),
  },
 }));
 // Mock userService
 vi.mock('../services/userService', () => ({
  userService: {
    updateUserAvatar: vi.fn(),
    updateUserPassword: vi.fn(),
    deleteUserAccount: vi.fn(),
    getUserAddress: vi.fn(),
    upsertUserAddress: vi.fn(),
  },
 }));
 // Mock the logger
 vi.mock('../services/logger.server', async () => ({
@@ -122,10 +72,10 @@ describe('User Routes (/api/users)', () => {
  describe('Avatar Upload Directory Creation', () => {
    it('should log an error if avatar directory creation fails', async () => {
      // Arrange
-      const mkdirError = new Error('EACCES: permission denied');
+      const mkdirError = new Error('EACCES: permission denied'); // This error is specific to the fs.mkdir mock.
      // Reset modules to force re-import with a new mock implementation
      vi.resetModules();
-      // Set up the mock *before* the module is re-imported
+      // Set up the mock *before* the module is re-imported.
      vi.doMock('node:fs/promises', () => ({
        default: {
          // We only need to mock mkdir for this test.
@@ -133,6 +83,10 @@ describe('User Routes (/api/users)', () => {
        },
      }));
      const { logger } = await import('../services/logger.server');
      // Stub NODE_ENV to ensure the relevant code path is executed if it depends on it.
      // Although the mkdir call itself doesn't depend on NODE_ENV, this is good practice
      // when re-importing modules that might have conditional logic based on it.
      vi.stubEnv('NODE_ENV', 'test');
      // Act: Dynamically import the router to trigger the top-level fs.mkdir call
      await import('./user.routes');
@@ -142,6 +96,7 @@ describe('User Routes (/api/users)', () => {
        { error: mkdirError },
        'Failed to create multer storage directories on startup.',
      );
      vi.unstubAllEnvs(); // Clean up the stubbed environment variable.
      vi.doUnmock('node:fs/promises'); // Clean up
    });
  });
@@ -482,6 +437,12 @@ describe('User Routes (/api/users)', () => {
        expect(response.status).toBe(201);
        expect(response.body).toEqual(mockAddedItem);
        expect(db.shoppingRepo.addShoppingListItem).toHaveBeenCalledWith(
          listId,
          mockUserProfile.user.user_id,
          itemData,
          expectLogger,
        );
      });
      it('should return 400 on foreign key error when adding an item', async () => {
@@ -519,6 +480,12 @@ describe('User Routes (/api/users)', () => {
        expect(response.status).toBe(200);
        expect(response.body).toEqual(mockUpdatedItem);
        expect(db.shoppingRepo.updateShoppingListItem).toHaveBeenCalledWith(
          itemId,
          mockUserProfile.user.user_id,
          updates,
          expectLogger,
        );
      });
      it('should return 404 if item to update is not found', async () => {
@@ -554,6 +521,11 @@ describe('User Routes (/api/users)', () => {
          vi.mocked(db.shoppingRepo.removeShoppingListItem).mockResolvedValue(undefined);
          const response = await supertest(app).delete('/api/users/shopping-lists/items/101');
          expect(response.status).toBe(204);
          expect(db.shoppingRepo.removeShoppingListItem).toHaveBeenCalledWith(
            101,
            mockUserProfile.user.user_id,
            expectLogger,
          );
        });
        it('should return 404 if item to delete is not found', async () => {
@@ -585,6 +557,27 @@ describe('User Routes (/api/users)', () => {
        expect(response.body).toEqual(updatedProfile);
      });
      it('should allow updating the profile with an empty string for avatar_url', async () => {
        // Arrange
        const profileUpdates = { avatar_url: '' };
        // The service should receive `undefined` after Zod preprocessing
        const updatedProfile = createMockUserProfile({ ...mockUserProfile, avatar_url: undefined });
        vi.mocked(db.userRepo.updateUserProfile).mockResolvedValue(updatedProfile);
        // Act
        const response = await supertest(app).put('/api/users/profile').send(profileUpdates);
        // Assert
        expect(response.status).toBe(200);
        expect(response.body).toEqual(updatedProfile);
        // Verify that the Zod schema preprocessed the empty string to undefined
        expect(db.userRepo.updateUserProfile).toHaveBeenCalledWith(
          mockUserProfile.user.user_id,
          { avatar_url: undefined },
          expectLogger,
        );
      });
      it('should return 500 on a generic database error', async () => {
        const dbError = new Error('DB Connection Failed');
        vi.mocked(db.userRepo.updateUserProfile).mockRejectedValue(dbError);
@@ -1037,7 +1030,7 @@ describe('User Routes (/api/users)', () => {
      it('should upload an avatar and update the user profile', async () => {
        const mockUpdatedProfile = createMockUserProfile({
          ...mockUserProfile,
-          avatar_url: '/uploads/avatars/new-avatar.png',
+          avatar_url: 'http://localhost:3001/uploads/avatars/new-avatar.png',
        });
        vi.mocked(userService.updateUserAvatar).mockResolvedValue(mockUpdatedProfile);
@@ -1049,7 +1042,7 @@ describe('User Routes (/api/users)', () => {
          .attach('avatar', Buffer.from('dummy-image-content'), dummyImagePath);
        expect(response.status).toBe(200);
-        expect(response.body.avatar_url).toContain('/uploads/avatars/'); // This was a duplicate, fixed.
+        expect(response.body.avatar_url).toContain('http://localhost:3001/uploads/avatars/');
        expect(userService.updateUserAvatar).toHaveBeenCalledWith(
          mockUserProfile.user.user_id,
          expect.any(Object),
--- a/src/routes/user.routes.ts
+++ b/src/routes/user.routes.ts
@@ -26,7 +26,13 @@ const router = express.Router();
 const updateProfileSchema = z.object({
  body: z
-    .object({ full_name: z.string().optional(), avatar_url: z.string().url().optional() })
+    .object({
      full_name: z.string().optional(),
      avatar_url: z.preprocess(
        (val) => (val === '' ? undefined : val),
        z.string().trim().url().optional(),
      ),
    })
    .refine((data) => Object.keys(data).length > 0, {
      message: 'At least one field to update must be provided.',
    }),
@@ -472,10 +478,16 @@ router.post(
  validateRequest(addShoppingListItemSchema),
  async (req, res, next: NextFunction) => {
    logger.debug(`[ROUTE] POST /api/users/shopping-lists/:listId/items - ENTER`);
    const userProfile = req.user as UserProfile;
    // Apply ADR-003 pattern for type safety
    const { params, body } = req as unknown as AddShoppingListItemRequest;
    try {
-      const newItem = await db.shoppingRepo.addShoppingListItem(params.listId, body, req.log);
+      const newItem = await db.shoppingRepo.addShoppingListItem(
        params.listId,
        userProfile.user.user_id,
        body,
        req.log,
      );
      res.status(201).json(newItem);
    } catch (error) {
      if (error instanceof ForeignKeyConstraintError) {
@@ -506,11 +518,13 @@ router.put(
  validateRequest(updateShoppingListItemSchema),
  async (req, res, next: NextFunction) => {
    logger.debug(`[ROUTE] PUT /api/users/shopping-lists/items/:itemId - ENTER`);
    const userProfile = req.user as UserProfile;
    // Apply ADR-003 pattern for type safety
    const { params, body } = req as unknown as UpdateShoppingListItemRequest;
    try {
      const updatedItem = await db.shoppingRepo.updateShoppingListItem(
        params.itemId,
        userProfile.user.user_id,
        body,
        req.log,
      );
@@ -535,10 +549,11 @@ router.delete(
  validateRequest(shoppingListItemIdSchema),
  async (req, res, next: NextFunction) => {
    logger.debug(`[ROUTE] DELETE /api/users/shopping-lists/items/:itemId - ENTER`);
    const userProfile = req.user as UserProfile;
    // Apply ADR-003 pattern for type safety
    const { params } = req as unknown as DeleteShoppingListItemRequest;
    try {
-      await db.shoppingRepo.removeShoppingListItem(params.itemId, req.log);
+      await db.shoppingRepo.removeShoppingListItem(params.itemId, userProfile.user.user_id, req.log);
      res.status(204).send();
    } catch (error: unknown) {
      logger.error(
--- a/src/services/aiService.server.test.ts
+++ b/src/services/aiService.server.test.ts
@@ -1,17 +1,23 @@
 // src/services/aiService.server.test.ts
 import { describe, it, expect, vi, beforeEach, afterEach, type Mock } from 'vitest';
 import type { Job } from 'bullmq';
 import { createMockLogger } from '../tests/utils/mockLogger';
 import type { Logger } from 'pino';
 import type { FlyerStatus, MasterGroceryItem, UserProfile } from '../types';
 // Import the class, not the singleton instance, so we can instantiate it with mocks.
 import {
  AIService,
  AiFlyerDataSchema,
  aiService as aiServiceSingleton,
  DuplicateFlyerError,
  type RawFlyerItem,
 } from './aiService.server';
-import { createMockMasterGroceryItem } from '../tests/utils/mockFactories';
+import {
  createMockMasterGroceryItem,
  createMockFlyer,
  createMockUserProfile,
 } from '../tests/utils/mockFactories';
 import { ValidationError } from './db/errors.db';
 import { AiFlyerDataSchema } from '../types/ai';
 // Mock the logger to prevent the real pino instance from being created, which causes issues with 'pino-pretty' in tests.
 vi.mock('./logger.server', () => ({
@@ -59,6 +65,7 @@ vi.mock('./db/index.db', () => ({
  adminRepo: {
    logActivity: vi.fn(),
  },
  withTransaction: vi.fn(),
 }));
 vi.mock('./queueService.server', () => ({
@@ -79,6 +86,7 @@ vi.mock('../utils/imageProcessor', () => ({
 import * as dbModule from './db/index.db';
 import { flyerQueue } from './queueService.server';
 import { createFlyerAndItems } from './db/flyer.db';
 import { withTransaction } from './db/index.db';
 import { generateFlyerIcon } from '../utils/imageProcessor';
 // Define a mock interface that closely resembles the actual Flyer type for testing purposes.
@@ -100,6 +108,8 @@ interface MockFlyer {
  updated_at: string;
 }
 const baseUrl = 'http://localhost:3001';
 describe('AI Service (Server)', () => {
  // Create mock dependencies that will be injected into the service
  const mockAiClient = { generateContent: vi.fn() };
@@ -112,12 +122,16 @@ describe('AI Service (Server)', () => {
    // Restore all environment variables and clear all mocks before each test
    vi.restoreAllMocks();
    vi.clearAllMocks();
    mockGenerateContent.mockReset();
    // Reset modules to ensure the service re-initializes with the mocks
    mockAiClient.generateContent.mockResolvedValue({
      text: '[]',
      candidates: [],
    });
    vi.mocked(withTransaction).mockImplementation(async (callback: any) => {
      return callback({}); // Mock client
    });
  });
  describe('AiFlyerDataSchema', () => {
@@ -128,57 +142,34 @@ describe('AI Service (Server)', () => {
      const resultEmpty = AiFlyerDataSchema.safeParse(dataWithEmpty);
      expect(resultNull.success).toBe(false);
-      if (!resultNull.success) {
+      // Null checks fail with a generic type error, which is acceptable.
        expect(resultNull.error.issues[0].message).toBe('Store name cannot be empty');
      }
      expect(resultEmpty.success).toBe(false);
      if (!resultEmpty.success) {
        expect(resultEmpty.error.issues[0].message).toBe('Store name cannot be empty');
      }
    });
  });
  describe('Constructor', () => {
    const originalEnv = process.env;
    beforeEach(() => {
      // Reset process.env before each test in this block
      vi.unstubAllEnvs();
      vi.unstubAllEnvs(); // Force-removes all environment mocking
      vi.resetModules(); // Important to re-evaluate the service file
      process.env = { ...originalEnv };
      console.log('CONSTRUCTOR beforeEach: process.env reset.');
    });
    afterEach(() => {
      // Restore original environment variables
      vi.unstubAllEnvs();
      process.env = originalEnv;
      console.log('CONSTRUCTOR afterEach: process.env restored.');
    });
    it('should throw an error if GEMINI_API_KEY is not set in a non-test environment', async () => {
      console.log("TEST START: 'should throw an error if GEMINI_API_KEY is not set...'");
      console.log(
        `PRE-TEST ENV: NODE_ENV=${process.env.NODE_ENV}, VITEST_POOL_ID=${process.env.VITEST_POOL_ID}`,
      );
      // Simulate a non-test environment
-      process.env.NODE_ENV = 'production';
+      vi.stubEnv('NODE_ENV', 'production');
-      delete process.env.GEMINI_API_KEY;
+      vi.stubEnv('GEMINI_API_KEY', '');
-      delete process.env.VITEST_POOL_ID;
+      vi.stubEnv('VITEST_POOL_ID', '');
      console.log(
        `POST-MANIPULATION ENV: NODE_ENV=${process.env.NODE_ENV}, VITEST_POOL_ID=${process.env.VITEST_POOL_ID}`,
      );
      let error: Error | undefined;
      // Dynamically import the class to re-evaluate the constructor logic
      try {
        console.log('Attempting to import and instantiate AIService which is expected to throw...');
        const { AIService } = await import('./aiService.server');
        new AIService(mockLoggerInstance);
      } catch (e) {
        console.log('Successfully caught an error during instantiation.');
        error = e as Error;
      }
      expect(error).toBeInstanceOf(Error);
@@ -189,8 +180,8 @@ describe('AI Service (Server)', () => {
    it('should use a mock placeholder if API key is missing in a test environment', async () => {
      // Arrange: Simulate a test environment without an API key
-      process.env.NODE_ENV = 'test';
+      vi.stubEnv('NODE_ENV', 'test');
-      delete process.env.GEMINI_API_KEY;
+      vi.stubEnv('GEMINI_API_KEY', '');
      // Act: Dynamically import and instantiate the service
      const { AIService } = await import('./aiService.server');
@@ -206,7 +197,7 @@ describe('AI Service (Server)', () => {
    });
    it('should use the adapter to call generateContent when using real GoogleGenAI client', async () => {
-      process.env.GEMINI_API_KEY = 'test-key';
+      vi.stubEnv('GEMINI_API_KEY', 'test-key');
      // We need to force the constructor to use the real client logic, not the injected mock.
      // So we instantiate AIService without passing aiClient.
@@ -217,18 +208,19 @@ describe('AI Service (Server)', () => {
      // Access the private aiClient (which is now the adapter)
      const adapter = (service as any).aiClient;
      const models = (service as any).models;
      const request = { contents: [{ parts: [{ text: 'test' }] }] };
      await adapter.generateContent(request);
      expect(mockGenerateContent).toHaveBeenCalledWith({
-        model: 'gemini-3-flash-preview',
+        model: models[0],
        ...request,
      });
    });
    it('should throw error if adapter is called without content', async () => {
-      process.env.GEMINI_API_KEY = 'test-key';
+      vi.stubEnv('GEMINI_API_KEY', 'test-key');
      vi.resetModules();
      const { AIService } = await import('./aiService.server');
      const service = new AIService(mockLoggerInstance);
@@ -241,24 +233,55 @@ describe('AI Service (Server)', () => {
  });
  describe('Model Fallback Logic', () => {
    const originalEnv = process.env;
    beforeEach(() => {
      vi.unstubAllEnvs();
-      process.env = { ...originalEnv, GEMINI_API_KEY: 'test-key' };
+      vi.stubEnv('GEMINI_API_KEY', 'test-key');
      vi.resetModules(); // Re-import to use the new env var and re-instantiate the service
      mockGenerateContent.mockReset();
    });
    afterEach(() => {
      process.env = originalEnv;
      vi.unstubAllEnvs();
    });
    it('should use lite models when useLiteModels is true', async () => {
      // Arrange
      const { AIService } = await import('./aiService.server');
      const { logger } = await import('./logger.server');
      const serviceWithFallback = new AIService(logger);
      const models_lite = (serviceWithFallback as any).models_lite;
      const successResponse = { text: 'Success from lite model', candidates: [] };
      mockGenerateContent.mockResolvedValue(successResponse);
      const request = {
        contents: [{ parts: [{ text: 'test prompt' }] }],
        useLiteModels: true,
      };
      // The adapter strips `useLiteModels` before calling the underlying client,
      // so we prepare the expected request shape for our assertions.
      const { useLiteModels, ...apiReq } = request;
      // Act
      const result = await (serviceWithFallback as any).aiClient.generateContent(request);
      // Assert
      expect(result).toEqual(successResponse);
      expect(mockGenerateContent).toHaveBeenCalledTimes(1);
      // Check that the first model from the lite list was used
      expect(mockGenerateContent).toHaveBeenCalledWith({
        model: models_lite[0],
        ...apiReq,
      });
    });
    it('should try the next model if the first one fails with a quota error', async () => {
      // Arrange
      const { AIService } = await import('./aiService.server');
      const { logger } = await import('./logger.server');
      const serviceWithFallback = new AIService(logger);
      const models = (serviceWithFallback as any).models;
      const quotaError = new Error('User rate limit exceeded due to quota');
      const successResponse = { text: 'Success from fallback model', candidates: [] };
@@ -276,22 +299,23 @@ describe('AI Service (Server)', () => {
      expect(mockGenerateContent).toHaveBeenCalledTimes(2);
      // Check first call
-      expect(mockGenerateContent).toHaveBeenNthCalledWith(1, { // The first model in the list is now 'gemini-3-flash-preview'
+      expect(mockGenerateContent).toHaveBeenNthCalledWith(1, { // The first model in the list
-        model: 'gemini-3-flash-preview',
+        model: models[0],
        ...request,
      });
      // Check second call
-      expect(mockGenerateContent).toHaveBeenNthCalledWith(2, { // The second model in the list is 'gemini-2.5-flash'
+      expect(mockGenerateContent).toHaveBeenNthCalledWith(2, { // The second model in the list
-        model: 'gemini-2.5-flash',
+        model: models[1],
        ...request,
      });
      // Check that a warning was logged
      expect(logger.warn).toHaveBeenCalledWith(
-        // The warning should be for the model that failed ('gemini-3-flash-preview'), not the next one.
+        // The warning should be for the model that failed ('gemini-2.5-flash'), not the next one.
        // The warning should be for the model that failed, not the next one.
        expect.stringContaining(
-          "Model 'gemini-3-flash-preview' failed due to quota/rate limit. Trying next model.",
+          `Model '${models[0]}' failed due to quota/rate limit. Trying next model.`,
        ),
      );
    });
@@ -301,6 +325,7 @@ describe('AI Service (Server)', () => {
      const { AIService } = await import('./aiService.server');
      const { logger } = await import('./logger.server');
      const serviceWithFallback = new AIService(logger);
      const models = (serviceWithFallback as any).models;
      const nonRetriableError = new Error('Invalid API Key');
      mockGenerateContent.mockRejectedValueOnce(nonRetriableError);
@@ -314,8 +339,10 @@ describe('AI Service (Server)', () => {
      expect(mockGenerateContent).toHaveBeenCalledTimes(1);
      expect(logger.error).toHaveBeenCalledWith(
-        { error: nonRetriableError }, // The first model in the list is now 'gemini-3-flash-preview'
+        { error: nonRetriableError }, // The first model in the list is now 'gemini-2.5-flash'
-        `[AIService Adapter] Model 'gemini-3-flash-preview' failed with a non-retriable error.`,
+        `[AIService Adapter] Model 'gemini-2.5-flash' failed with a non-retriable error.`,
        { error: nonRetriableError }, // The first model in the list
        `[AIService Adapter] Model '${models[0]}' failed with a non-retriable error.`,
      );
    });
@@ -325,41 +352,174 @@ describe('AI Service (Server)', () => {
      const { logger } = await import('./logger.server');
      const serviceWithFallback = new AIService(logger);
-      const quotaError1 = new Error('Quota exhausted for model 1');
+      // Access private property for testing purposes to ensure test stays in sync with implementation
-      const quotaError2 = new Error('429 Too Many Requests for model 2');
+      const models = (serviceWithFallback as any).models as string[];
-      const quotaError3 = new Error('RESOURCE_EXHAUSTED for model 3');
+      // Use a quota error to trigger the fallback logic for each model
      const errors = models.map((model, i) => new Error(`Quota error for model ${model} (${i})`));
      const lastError = errors[errors.length - 1];
-      mockGenerateContent
+      // Dynamically setup mocks
-        .mockRejectedValueOnce(quotaError1)
+      errors.forEach((err) => {
-        .mockRejectedValueOnce(quotaError2)
+        mockGenerateContent.mockRejectedValueOnce(err);
-        .mockRejectedValueOnce(quotaError3);
+      });
      const request = { contents: [{ parts: [{ text: 'test prompt' }] }] };
      // Act & Assert
      await expect((serviceWithFallback as any).aiClient.generateContent(request)).rejects.toThrow(
-        quotaError3,
+        lastError,
      );
-      expect(mockGenerateContent).toHaveBeenCalledTimes(3);
+      expect(mockGenerateContent).toHaveBeenCalledTimes(models.length);
-      expect(mockGenerateContent).toHaveBeenNthCalledWith(1, { // The first model in the list is now 'gemini-3-flash-preview'
+
-        model: 'gemini-3-flash-preview',
+      models.forEach((model, index) => {
-        ...request,
+        expect(mockGenerateContent).toHaveBeenNthCalledWith(index + 1, {
-      });
+          model: model,
-      expect(mockGenerateContent).toHaveBeenNthCalledWith(2, { // The second model in the list is 'gemini-2.5-flash'
+          ...request,
-        model: 'gemini-2.5-flash',
+        });
        ...request,
      });
      expect(mockGenerateContent).toHaveBeenNthCalledWith(3, { // The third model in the list is 'gemini-2.5-flash-lite'
        model: 'gemini-2.5-flash-lite',
        ...request,
      });
      expect(logger.error).toHaveBeenCalledWith(
-        { lastError: quotaError3 },
+        { lastError },
        '[AIService Adapter] All AI models failed. Throwing last known error.',
      );
    });
    it('should use lite models and throw the last error if all lite models fail', async () => {
      // Arrange
      const { AIService } = await import('./aiService.server');
      const { logger } = await import('./logger.server');
      // We instantiate with the real logger to test the production fallback logic
      const serviceWithFallback = new AIService(logger);
      // Access private property for testing purposes
      const modelsLite = (serviceWithFallback as any).models_lite as string[];
      // Use a quota error to trigger the fallback logic for each model
      const errors = modelsLite.map((model, i) => new Error(`Quota error for lite model ${model} (${i})`));
      const lastError = errors[errors.length - 1];
      // Dynamically setup mocks
      errors.forEach((err) => {
        mockGenerateContent.mockRejectedValueOnce(err);
      });
      const request = {
        contents: [{ parts: [{ text: 'test prompt' }] }],
        useLiteModels: true, // This is the key to trigger the lite model list
      };
      // The adapter strips `useLiteModels` before calling the underlying client,
      // so we prepare the expected request shape for our assertions.
      const { useLiteModels, ...apiReq } = request;
      // Act & Assert
      // Expect the entire operation to reject with the error from the very last model attempt.
      await expect((serviceWithFallback as any).aiClient.generateContent(request)).rejects.toThrow(
        lastError,
      );
      // Verify that all lite models were attempted in the correct order.
      expect(mockGenerateContent).toHaveBeenCalledTimes(modelsLite.length);
      modelsLite.forEach((model, index) => {
        expect(mockGenerateContent).toHaveBeenNthCalledWith(index + 1, {
          model: model,
          ...apiReq,
        });
      });
    });
    it('should dynamically try the next model if the first one fails and succeed if the second one works', async () => {
      // Arrange
      const { AIService } = await import('./aiService.server');
      const { logger } = await import('./logger.server');
      const serviceWithFallback = new AIService(logger);
      // Access private property for testing purposes
      const models = (serviceWithFallback as any).models as string[];
      // Ensure we have enough models to test fallback
      expect(models.length).toBeGreaterThanOrEqual(2);
      const error1 = new Error('Quota exceeded for model 1');
      const successResponse = { text: 'Success', candidates: [] };
      mockGenerateContent
        .mockRejectedValueOnce(error1)
        .mockResolvedValueOnce(successResponse);
      const request = { contents: [{ parts: [{ text: 'test prompt' }] }] };
      // Act
      const result = await (serviceWithFallback as any).aiClient.generateContent(request);
      // Assert
      expect(result).toEqual(successResponse);
      expect(mockGenerateContent).toHaveBeenCalledTimes(2);
      expect(mockGenerateContent).toHaveBeenNthCalledWith(1, {
        model: models[0],
        ...request,
      });
      expect(mockGenerateContent).toHaveBeenNthCalledWith(2, {
        model: models[1],
        ...request,
      });
      expect(logger.warn).toHaveBeenCalledWith(
        expect.stringContaining(`Model '${models[0]}' failed`),
      );
    });
    it('should retry on a 429 error and succeed on the next model', async () => {
      // Arrange
      const { AIService } = await import('./aiService.server');
      const { logger } = await import('./logger.server');
      const serviceWithFallback = new AIService(logger);
      const models = (serviceWithFallback as any).models as string[];
      const retriableError = new Error('429 Too Many Requests');
      const successResponse = { text: 'Success from second model', candidates: [] };
      mockGenerateContent
        .mockRejectedValueOnce(retriableError)
        .mockResolvedValueOnce(successResponse);
      const request = { contents: [{ parts: [{ text: 'test prompt' }] }] };
      // Act
      const result = await (serviceWithFallback as any).aiClient.generateContent(request);
      // Assert
      expect(result).toEqual(successResponse);
      expect(mockGenerateContent).toHaveBeenCalledTimes(2);
      expect(mockGenerateContent).toHaveBeenNthCalledWith(1, { model: models[0], ...request });
      expect(mockGenerateContent).toHaveBeenNthCalledWith(2, { model: models[1], ...request });
      expect(logger.warn).toHaveBeenCalledWith(expect.stringContaining(`Model '${models[0]}' failed due to quota/rate limit.`));
    });
    it('should fail immediately on a 400 Bad Request error without retrying', async () => {
      // Arrange
      const { AIService } = await import('./aiService.server');
      const { logger } = await import('./logger.server');
      const serviceWithFallback = new AIService(logger);
      const models = (serviceWithFallback as any).models as string[];
      const nonRetriableError = new Error('400 Bad Request: Invalid input');
      mockGenerateContent.mockRejectedValueOnce(nonRetriableError);
      const request = { contents: [{ parts: [{ text: 'test prompt' }] }] };
      // Act & Assert
      await expect((serviceWithFallback as any).aiClient.generateContent(request)).rejects.toThrow(nonRetriableError);
      expect(mockGenerateContent).toHaveBeenCalledTimes(1);
      expect(mockGenerateContent).toHaveBeenCalledWith({ model: models[0], ...request });
      expect(logger.error).toHaveBeenCalledWith(
        { error: nonRetriableError },
        `[AIService Adapter] Model '${models[0]}' failed with a non-retriable error.`,
      );
      // Ensure it didn't log a warning about trying the next model
      expect(logger.warn).not.toHaveBeenCalledWith(expect.stringContaining('Trying next model'));
    });
  });
  describe('extractItemsFromReceiptImage', () => {
@@ -461,11 +621,8 @@ describe('AI Service (Server)', () => {
      );
      expect(mockAiClient.generateContent).toHaveBeenCalledTimes(1);
-      expect(result.store_name).toBe('Test Store');
+      // With normalization removed from this service, the result should match the raw AI response.
-      expect(result.items).toHaveLength(2);
+      expect(result).toEqual(mockAiResponse);
      expect(result.items[1].price_display).toBe('');
      expect(result.items[1].quantity).toBe('');
      expect(result.items[1].category_name).toBe('Other/Miscellaneous');
    });
    it('should throw an error if the AI response is not a valid JSON object', async () => {
@@ -722,6 +879,23 @@ describe('AI Service (Server)', () => {
    });
  });
  describe('generateRecipeSuggestion', () => {
    it('should call generateContent with useLiteModels set to true', async () => {
      const ingredients = ['carrots', 'onions'];
      const expectedPrompt = `Suggest a simple recipe using these ingredients: ${ingredients.join(
        ', ',
      )}. Keep it brief.`;
      mockAiClient.generateContent.mockResolvedValue({ text: 'Some recipe', candidates: [] });
      await aiServiceInstance.generateRecipeSuggestion(ingredients, mockLoggerInstance);
      expect(mockAiClient.generateContent).toHaveBeenCalledWith({
        contents: [{ parts: [{ text: expectedPrompt }] }],
        useLiteModels: true,
      });
    });
  });
  describe('planTripWithMaps', () => {
    const mockUserLocation: GeolocationCoordinates = {
      latitude: 45,
@@ -789,7 +963,18 @@ describe('AI Service (Server)', () => {
    } as UserProfile;
    it('should throw DuplicateFlyerError if flyer already exists', async () => {
-      vi.mocked(dbModule.flyerRepo.findFlyerByChecksum).mockResolvedValue({ flyer_id: 99 } as any);
+      vi.mocked(dbModule.flyerRepo.findFlyerByChecksum).mockResolvedValue({
        flyer_id: 99,
        checksum: 'checksum123',
        file_name: 'test.pdf',
        image_url: `${baseUrl}/flyer-images/test.pdf`,
        icon_url: `${baseUrl}/flyer-images/icons/test.webp`,
        store_id: 1,
        status: 'processed',
        item_count: 0,
        created_at: new Date().toISOString(),
        updated_at: new Date().toISOString(),
      });
      await expect(
        aiServiceInstance.enqueueFlyerProcessing(
@@ -804,7 +989,7 @@ describe('AI Service (Server)', () => {
    it('should enqueue job with user address if profile exists', async () => {
      vi.mocked(dbModule.flyerRepo.findFlyerByChecksum).mockResolvedValue(undefined);
-      vi.mocked(flyerQueue.add).mockResolvedValue({ id: 'job123' } as any);
+      vi.mocked(flyerQueue.add).mockResolvedValue({ id: 'job123' } as unknown as Job);
      const result = await aiServiceInstance.enqueueFlyerProcessing(
        mockFile,
@@ -821,13 +1006,14 @@ describe('AI Service (Server)', () => {
        userId: 'user123',
        submitterIp: '127.0.0.1',
        userProfileAddress: '123 St, City, Country', // Partial address match based on filter(Boolean)
        baseUrl: 'http://localhost:3000',
      });
      expect(result.id).toBe('job123');
    });
    it('should enqueue job without address if profile is missing', async () => {
      vi.mocked(dbModule.flyerRepo.findFlyerByChecksum).mockResolvedValue(undefined);
-      vi.mocked(flyerQueue.add).mockResolvedValue({ id: 'job456' } as any);
+      vi.mocked(flyerQueue.add).mockResolvedValue({ id: 'job456' } as unknown as Job);
      await aiServiceInstance.enqueueFlyerProcessing(
        mockFile,
@@ -842,6 +1028,7 @@ describe('AI Service (Server)', () => {
        expect.objectContaining({
          userId: undefined,
          userProfileAddress: undefined,
          baseUrl: 'http://localhost:3000',
        }),
      );
    });
@@ -853,18 +1040,19 @@ describe('AI Service (Server)', () => {
      filename: 'upload.jpg',
      originalname: 'orig.jpg',
    } as Express.Multer.File; // This was a duplicate, fixed.
-    const mockProfile = { user: { user_id: 'u1' } } as UserProfile;
+    const mockProfile = createMockUserProfile({ user: { user_id: 'a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11' } });
    beforeEach(() => {
-      // Default success mocks
+      // Default success mocks. Use createMockFlyer for a more complete mock.
      vi.mocked(dbModule.flyerRepo.findFlyerByChecksum).mockResolvedValue(undefined);
      vi.mocked(generateFlyerIcon).mockResolvedValue('icon.jpg');
      vi.mocked(createFlyerAndItems).mockResolvedValue({
        flyer: {
          flyer_id: 100,
          file_name: 'orig.jpg',
-          image_url: '/flyer-images/upload.jpg',
+          image_url: `${baseUrl}/flyer-images/upload.jpg`,
-          icon_url: '/flyer-images/icons/icon.jpg',
+          icon_url: `${baseUrl}/flyer-images/icons/icon.jpg`,
          checksum: 'mock-checksum-123',
          store_name: 'Mock Store',
          valid_from: null,
@@ -872,7 +1060,7 @@ describe('AI Service (Server)', () => {
          store_address: null,
          item_count: 0,
          status: 'processed',
-          uploaded_by: 'u1',
+          uploaded_by: mockProfile.user.user_id,
          created_at: new Date().toISOString(),
          updated_at: new Date().toISOString(),
        } as MockFlyer, // Use the more specific MockFlyer type
@@ -893,7 +1081,7 @@ describe('AI Service (Server)', () => {
    });
    it('should throw DuplicateFlyerError if checksum exists', async () => {
-      vi.mocked(dbModule.flyerRepo.findFlyerByChecksum).mockResolvedValue({ flyer_id: 55 } as any);
+      vi.mocked(dbModule.flyerRepo.findFlyerByChecksum).mockResolvedValue(createMockFlyer({ flyer_id: 55 }));
      const body = { checksum: 'dup-sum' };
      await expect(
@@ -1007,7 +1195,7 @@ describe('AI Service (Server)', () => {
      expect(dbModule.adminRepo.logActivity).toHaveBeenCalledWith(
        expect.objectContaining({
          action: 'flyer_processed',
-          userId: 'u1',
+          userId: mockProfile.user.user_id,
        }),
        mockLoggerInstance,
      );
@@ -1034,6 +1222,29 @@ describe('AI Service (Server)', () => {
      );
    });
    it('should log and re-throw the original error if the database transaction fails', async () => {
      const body = { checksum: 'legacy-fail-checksum', extractedData: { store_name: 'Fail Store' } };
      const dbError = new Error('DB transaction failed');
      // Mock withTransaction to fail
      vi.mocked(withTransaction).mockRejectedValue(dbError);
      await expect(
        aiServiceInstance.processLegacyFlyerUpload(
          mockFile,
          body,
          mockProfile,
          mockLoggerInstance,
        ),
      ).rejects.toThrow(dbError);
      // Verify the service-level error logging
      expect(mockLoggerInstance.error).toHaveBeenCalledWith(
        { err: dbError, checksum: 'legacy-fail-checksum' },
        'Legacy flyer upload database transaction failed.',
      );
    });
    it('should handle body as a string', async () => {
      const payload = { checksum: 'str-body', extractedData: { store_name: 'String Body' } };
      const body = JSON.stringify(payload);
--- a/src/services/aiService.server.ts
+++ b/src/services/aiService.server.ts
@@ -4,7 +4,6 @@
 * It is intended to be used only by the backend (e.g., server.ts) and should never be imported into client-side code.
 * The `.server.ts` naming convention helps enforce this separation.
 */
 import { GoogleGenAI, type GenerateContentResponse, type Content, type Tool } from '@google/genai';
 import fsPromises from 'node:fs/promises';
 import type { Logger } from 'pino';
@@ -19,36 +18,20 @@ import type {
  FlyerInsert,
  Flyer,
 } from '../types';
-import { FlyerProcessingError } from './processingErrors';
+import { DatabaseError, FlyerProcessingError } from './processingErrors';
 import * as db from './db/index.db';
 import { flyerQueue } from './queueService.server';
 import type { Job } from 'bullmq';
 import { createFlyerAndItems } from './db/flyer.db';
 import { getBaseUrl } from '../utils/serverUtils';
 import { generateFlyerIcon } from '../utils/imageProcessor';
 import { AdminRepository } from './db/admin.db';
 import path from 'path';
-import { ValidationError } from './db/errors.db';
+import { ValidationError } from './db/errors.db'; // Keep this import for ValidationError
-
+import {
-// Helper for consistent required string validation (handles missing/null/empty)
+  AiFlyerDataSchema,
-const requiredString = (message: string) =>
+  ExtractedFlyerItemSchema,
-  z.preprocess((val) => val ?? '', z.string().min(1, message));
+} from '../types/ai'; // Import consolidated schemas
 // --- Zod Schemas for AI Response Validation (exported for the transformer) ---
 const ExtractedFlyerItemSchema = z.object({
  item: z.string(),
  price_display: z.string(),
  price_in_cents: z.number().nullable(),
  quantity: z.string(),
  category_name: z.string(),
  master_item_id: z.number().nullish(), // .nullish() allows null or undefined
 });
 export const AiFlyerDataSchema = z.object({
  store_name: requiredString('Store name cannot be empty'),
  valid_from: z.string().nullable(),
  valid_to: z.string().nullable(),
  store_address: z.string().nullable(),
  items: z.array(ExtractedFlyerItemSchema),
 });
 interface FlyerProcessPayload extends Partial<ExtractedCoreData> {
  checksum?: string;
@@ -81,6 +64,7 @@ interface IAiClient {
  generateContent(request: {
    contents: Content[];
    tools?: Tool[];
    useLiteModels?: boolean;
  }): Promise<GenerateContentResponse>;
 }
@@ -89,10 +73,10 @@ interface IAiClient {
 * This type is intentionally loose to accommodate potential null/undefined values
 * from the AI before they are cleaned and normalized.
 */
-type RawFlyerItem = {
+export type RawFlyerItem = {
-  item: string;
+  item: string | null;
  price_display: string | null | undefined;
-  price_in_cents: number | null;
+  price_in_cents: number | null | undefined;
  quantity: string | null | undefined;
  category_name: string | null | undefined;
  master_item_id?: number | null | undefined;
@@ -109,10 +93,55 @@ export class AIService {
  private fs: IFileSystem;
  private rateLimiter: <T>(fn: () => Promise<T>) => Promise<T>;
  private logger: Logger;
-  // The fallback list is ordered by preference (speed/cost vs. power).
+
-  // We try the fastest models first, then the more powerful 'pro' model as a high-quality fallback,
+// OPTIMIZED: Flyer Image Processing (Vision + Long Output)
-  // and finally the 'lite' model as a last resort.
+  // PRIORITIES:
-  private readonly models = [ 'gemini-3-flash-preview', 'gemini-2.5-flash', 'gemini-2.5-flash-lite'];
+  // 1. Output Limit: Must be 65k+ (Gemini 2.5/3.0) to avoid cutting off data.
  // 2. Intelligence: 'Pro' models handle messy layouts better.
  // 3. Quota Management: 'Preview' and 'Exp' models are added as fallbacks to tap into separate rate limits.
  private readonly models = [
    // --- TIER A: The Happy Path (Fast & Stable) ---
    'gemini-2.5-flash',           // Primary workhorse. 65k output.
    'gemini-2.5-flash-lite',      // Cost-saver. 65k output.
    // --- TIER B: The Heavy Lifters (Complex Layouts) ---
    'gemini-2.5-pro',             // High IQ for messy flyers. 65k output.
    // --- TIER C: Separate Quota Buckets (Previews) ---
    'gemini-3-flash-preview',     // Newer/Faster. Separate 'Preview' quota. 65k output.
    'gemini-3-pro-preview',       // High IQ. Separate 'Preview' quota. 65k output.
    // --- TIER D: Experimental Buckets (High Capacity) ---
    'gemini-exp-1206',            // Excellent reasoning. Separate 'Experimental' quota. 65k output.
    // --- TIER E: Last Resorts (Lower Capacity/Local) ---
    'gemma-3-27b-it',             // Open model fallback.
    'gemini-2.0-flash-exp'        // Exp fallback. WARNING: 8k output limit. Good for small flyers only.
  ];
  // OPTIMIZED: Simple Text Tasks (Recipes, Shopping Lists, Summaries)
  // PRIORITIES:
  // 1. Cost/Speed: These tasks are simple.
  // 2. Output Limit: The 8k limit of Gemini 2.0 is perfectly fine here.
  private readonly models_lite = [
    // --- Best Value (Smart + Cheap) ---
    "gemini-2.5-flash-lite",      // Current generation efficiency king.
    // --- The "Recycled" Gemini 2.0 Models (Perfect for Text) ---
    "gemini-2.0-flash-lite-001",  // Extremely cheap, very capable for text.
    "gemini-2.0-flash-001",       // Smarter than Lite, good for complex recipes.
    // --- Open Models (Good for simple categorization) ---
    "gemma-3-12b-it",             // Solid reasoning for an open model.
    "gemma-3-4b-it",              // Very fast.
    // --- Quota Fallbacks (Experimental/Preview) ---
    "gemini-2.0-flash-exp",       // Use this separate quota bucket if others are exhausted.
    // --- Edge/Nano Models (Simple string manipulation only) ---
    "gemma-3n-e4b-it",            // Corrected name from JSON
    "gemma-3n-e2b-it"             // Corrected name from JSON
  ];
  constructor(logger: Logger, aiClient?: IAiClient, fs?: IFileSystem) {
    this.logger = logger;
@@ -175,7 +204,9 @@ export class AIService {
                throw new Error('AIService.generateContent requires at least one content element.');
              }
-              return this._generateWithFallback(genAI, request);
+              const { useLiteModels, ...apiReq } = request;
              const models = useLiteModels ? this.models_lite : this.models;
              return this._generateWithFallback(genAI, apiReq, models);
            },
          }
        : {
@@ -213,10 +244,11 @@ export class AIService {
  private async _generateWithFallback(
    genAI: GoogleGenAI,
    request: { contents: Content[]; tools?: Tool[] },
    models: string[] = this.models,
  ): Promise<GenerateContentResponse> {
    let lastError: Error | null = null;
-    for (const modelName of this.models) {
+    for (const modelName of models) {
      try {
        this.logger.info(
          `[AIService Adapter] Attempting to generate content with model: ${modelName}`,
@@ -507,12 +539,8 @@ export class AIService {
    userProfileAddress?: string,
    logger: Logger = this.logger,
  ): Promise<{
-    store_name: string;
+    store_name: string | null; valid_from: string | null; valid_to: string | null; store_address: string | null; items: z.infer<typeof ExtractedFlyerItemSchema>[];
-    valid_from: string | null;
+  } & z.infer<typeof AiFlyerDataSchema>> {
    valid_to: string | null;
    store_address: string | null;
    items: ExtractedFlyerItem[];
  }> {
    logger.info(
      `[extractCoreDataFromFlyerImage] Entering method with ${imagePaths.length} image(s).`,
    );
@@ -568,48 +596,22 @@ export class AIService {
        throw new Error('AI response did not contain a valid JSON object.');
      }
-      // Normalize the items to create a clean data structure.
+      // The FlyerDataTransformer is now responsible for all normalization.
-      logger.debug('[extractCoreDataFromFlyerImage] Normalizing extracted items.');
+      // We return the raw items as parsed from the AI response.
-      const normalizedItems = Array.isArray(extractedData.items)
+      if (!Array.isArray(extractedData.items)) {
-        ? this._normalizeExtractedItems(extractedData.items)
+        extractedData.items = [];
-        : [];
+      }
      logger.info(
        `[extractCoreDataFromFlyerImage] Successfully processed flyer data for store: ${extractedData.store_name}. Exiting method.`,
      );
-      return { ...extractedData, items: normalizedItems };
+      return extractedData;
    } catch (apiError) {
      logger.error({ err: apiError }, '[extractCoreDataFromFlyerImage] The entire process failed.');
      throw apiError;
    }
  }
  /**
   * Normalizes the raw items returned by the AI, ensuring fields are in the correct format.
   * @param items An array of raw flyer items from the AI.
   * @returns A normalized array of flyer items.
   */
  private _normalizeExtractedItems(items: RawFlyerItem[]): ExtractedFlyerItem[] {
    return items.map((item: RawFlyerItem) => ({
      ...item,
      // Ensure 'item' is always a string, defaulting to 'Unknown Item' if null/undefined.
      item:
        item.item === null || item.item === undefined || String(item.item).trim() === ''
          ? 'Unknown Item'
          : String(item.item),
      price_display:
        item.price_display === null || item.price_display === undefined
          ? ''
          : String(item.price_display),
      quantity: item.quantity === null || item.quantity === undefined ? '' : String(item.quantity),
      category_name:
        item.category_name === null || item.category_name === undefined
          ? 'Other/Miscellaneous'
          : String(item.category_name),
      master_item_id: item.master_item_id ?? undefined,
    }));
  }
  /**
   * SERVER-SIDE FUNCTION
   * Extracts a specific piece of text from a cropped area of an image.
@@ -685,6 +687,33 @@ export class AIService {
    }
  }
  /**
   * Generates a simple recipe suggestion based on a list of ingredients.
   * Uses the 'lite' models for faster/cheaper generation.
   * @param ingredients List of available ingredients.
   * @param logger Logger instance.
   * @returns The recipe suggestion text.
   */
  async generateRecipeSuggestion(
    ingredients: string[],
    logger: Logger = this.logger,
  ): Promise<string | null> {
    const prompt = `Suggest a simple recipe using these ingredients: ${ingredients.join(', ')}. Keep it brief.`;
    try {
      const result = await this.rateLimiter(() =>
        this.aiClient.generateContent({
          contents: [{ parts: [{ text: prompt }] }],
          useLiteModels: true,
        }),
      );
      return result.text || null;
    } catch (error) {
      logger.error({ err: error }, 'Failed to generate recipe suggestion');
      return null;
    }
  }
  /**
   * SERVER-SIDE FUNCTION
   * Uses Google Maps grounding to find nearby stores and plan a shopping trip.
@@ -765,6 +794,8 @@ async enqueueFlyerProcessing(
        .join(', ');
    }
    const baseUrl = getBaseUrl(logger);
    // 3. Add job to the queue
    const job = await flyerQueue.add('process-flyer', {
      filePath: file.path,
@@ -773,6 +804,7 @@ async enqueueFlyerProcessing(
      userId: userProfile?.user.user_id,
      submitterIp: submitterIp,
      userProfileAddress: userProfileAddress,
      baseUrl: baseUrl,
    });
    logger.info(
@@ -850,6 +882,8 @@ async enqueueFlyerProcessing(
    const itemsArray = Array.isArray(rawItems) ? rawItems : typeof rawItems === 'string' ? JSON.parse(rawItems) : [];
    const itemsForDb = itemsArray.map((item: Partial<ExtractedFlyerItem>) => ({
      ...item,
      // Ensure price_display is never null to satisfy database constraints.
      price_display: item.price_display ?? '',
      master_item_id: item.master_item_id === null ? undefined : item.master_item_id,
      quantity: item.quantity ?? 1,
      view_count: 0,
@@ -864,11 +898,14 @@ async enqueueFlyerProcessing(
    const iconsDir = path.join(path.dirname(file.path), 'icons');
    const iconFileName = await generateFlyerIcon(file.path, iconsDir, logger);
-    const iconUrl = `/flyer-images/icons/${iconFileName}`;
+
    const baseUrl = getBaseUrl(logger);
    const iconUrl = `${baseUrl}/flyer-images/icons/${iconFileName}`;
    const imageUrl = `${baseUrl}/flyer-images/${file.filename}`;
    const flyerData: FlyerInsert = {
      file_name: originalFileName,
-      image_url: `/flyer-images/${file.filename}`,
+      image_url: imageUrl,
      icon_url: iconUrl,
      checksum: checksum,
      store_name: storeName,
@@ -880,18 +917,28 @@ async enqueueFlyerProcessing(
      uploaded_by: userProfile?.user.user_id,
    };
-    const { flyer: newFlyer, items: newItems } = await createFlyerAndItems(flyerData, itemsForDb, logger);
+    return db.withTransaction(async (client) => {
      const { flyer, items } = await createFlyerAndItems(flyerData, itemsForDb, logger, client);
-    logger.info(`Successfully processed legacy flyer: ${newFlyer.file_name} (ID: ${newFlyer.flyer_id}) with ${newItems.length} items.`);
+      logger.info(
        `Successfully processed legacy flyer: ${flyer.file_name} (ID: ${flyer.flyer_id}) with ${items.length} items.`,
      );
-    await db.adminRepo.logActivity({
+      const transactionalAdminRepo = new AdminRepository(client);
-      userId: userProfile?.user.user_id,
+      await transactionalAdminRepo.logActivity(
-      action: 'flyer_processed',
+        {
-      displayText: `Processed a new flyer for ${flyerData.store_name}.`,
+          userId: userProfile?.user.user_id,
-      details: { flyerId: newFlyer.flyer_id, storeName: flyerData.store_name },
+          action: 'flyer_processed',
-    }, logger);
+          displayText: `Processed a new flyer for ${flyerData.store_name}.`,
-
+          details: { flyerId: flyer.flyer_id, storeName: flyerData.store_name },
-    return newFlyer;
+        },
        logger,
      );
      return flyer;
    }).catch((error) => {
      logger.error({ err: error, checksum }, 'Legacy flyer upload database transaction failed.');
      throw error;
    });
  }
 }
--- a/src/services/apiClient.test.ts
+++ b/src/services/apiClient.test.ts
@@ -543,6 +543,13 @@ describe('API Client', () => {
      await apiClient.deleteRecipe(recipeId);
      expect(capturedUrl?.pathname).toBe(`/api/recipes/${recipeId}`);
    });
    it('suggestRecipe should send a POST request with ingredients', async () => {
      const ingredients = ['chicken', 'rice'];
      await apiClient.suggestRecipe(ingredients);
      expect(capturedUrl?.pathname).toBe('/api/recipes/suggest');
      expect(capturedBody).toEqual({ ingredients });
    });
  });
  describe('User Profile and Settings API Functions', () => {
@@ -933,7 +940,7 @@ describe('API Client', () => {
    it('logSearchQuery should send a POST request with query data', async () => {
      const queryData = createMockSearchQueryPayload({ query_text: 'apples', result_count: 10, was_successful: true });
-      await apiClient.logSearchQuery(queryData);
+      await apiClient.logSearchQuery(queryData as any);
      expect(capturedUrl?.pathname).toBe('/api/search/log');
      expect(capturedBody).toEqual(queryData);
    });
@@ -960,7 +967,7 @@ describe('API Client', () => {
        result_count: 0,
        was_successful: false,
      });
-      await apiClient.logSearchQuery(queryData);
+      await apiClient.logSearchQuery(queryData as any);
      expect(logger.warn).toHaveBeenCalledWith('Failed to log search query', { error: apiError });
    });
  });
--- a/src/services/apiClient.ts
+++ b/src/services/apiClient.ts
@@ -636,6 +636,20 @@ export const addRecipeComment = (
 ): Promise<Response> =>
  authedPost(`/recipes/${recipeId}/comments`, { content, parentCommentId }, { tokenOverride });
 /**
 * Requests a simple recipe suggestion from the AI based on a list of ingredients.
 * @param ingredients An array of ingredient strings.
 * @param tokenOverride Optional token for testing.
 * @returns A promise that resolves to the API response containing the suggestion.
 */
 export const suggestRecipe = (
  ingredients: string[],
  tokenOverride?: string,
 ): Promise<Response> => {
  // This is a protected endpoint, so we use authedPost.
  return authedPost('/recipes/suggest', { ingredients }, { tokenOverride });
 };
 /**
 * Deletes a recipe.
 * @param recipeId The ID of the recipe to delete.
--- a/src/services/authService.test.ts
+++ b/src/services/authService.test.ts
@@ -1,6 +1,8 @@
-import { describe, it, expect, vi, beforeEach } from 'vitest';
+// src/services/authService.test.ts
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import type { UserProfile } from '../types';
 import type * as jsonwebtoken from 'jsonwebtoken';
 import { DatabaseError } from './processingErrors';
 describe('AuthService', () => {
  let authService: typeof import('./authService').authService;
@@ -11,12 +13,21 @@ describe('AuthService', () => {
  let logger: typeof import('./logger.server').logger;
  let sendPasswordResetEmail: typeof import('./emailService.server').sendPasswordResetEmail;
  let UniqueConstraintError: typeof import('./db/errors.db').UniqueConstraintError;
  let RepositoryError: typeof import('./db/errors.db').RepositoryError;
  let withTransaction: typeof import('./db/index.db').withTransaction;
  let transactionalUserRepoMocks: any;
  let transactionalAdminRepoMocks: any;
  const reqLog = {}; // Mock request logger object
  const mockUser = {
    user_id: 'user-123',
    email: 'test@example.com',
    password_hash: 'hashed-password',
    failed_login_attempts: 0,
    last_failed_login: null,
    created_at: new Date().toISOString(),
    updated_at: new Date().toISOString(),
    refresh_token: null,
  };
  const mockUserProfile: UserProfile = {
    user: mockUser,
@@ -28,13 +39,27 @@ describe('AuthService', () => {
    vi.resetModules();
    // Set environment variables before any modules are imported
-    process.env.JWT_SECRET = 'test-secret';
+    vi.stubEnv('JWT_SECRET', 'test-secret');
-    process.env.FRONTEND_URL = 'http://localhost:3000';
+    vi.stubEnv('FRONTEND_URL', 'http://localhost:3000');
    transactionalUserRepoMocks = {
      updateUserPassword: vi.fn(),
      deleteResetToken: vi.fn(),
      createPasswordResetToken: vi.fn(),
      createUser: vi.fn(),
    };
    transactionalAdminRepoMocks = {
      logActivity: vi.fn(),
    };
    const MockTransactionalUserRepository = vi.fn(() => transactionalUserRepoMocks);
    const MockTransactionalAdminRepository = vi.fn(() => transactionalAdminRepoMocks);
    // Mock all dependencies before dynamically importing the service
    // Core modules like bcrypt, jsonwebtoken, and crypto are now mocked globally in tests-setup-unit.ts
    vi.mock('bcrypt');
    vi.mock('./db/index.db', () => ({
      withTransaction: vi.fn(),
      userRepo: {
        createUser: vi.fn(),
        saveRefreshToken: vi.fn(),
@@ -54,6 +79,12 @@ describe('AuthService', () => {
    vi.mock('./logger.server', () => ({
      logger: { info: vi.fn(), error: vi.fn(), warn: vi.fn(), debug: vi.fn() },
    }));
    vi.mock('./db/user.db', () => ({
      UserRepository: MockTransactionalUserRepository,
    }));
    vi.mock('./db/admin.db', () => ({
      AdminRepository: MockTransactionalAdminRepository,
    }));
    vi.mock('./emailService.server', () => ({
      sendPasswordResetEmail: vi.fn(),
    }));
@@ -68,14 +99,23 @@ describe('AuthService', () => {
    userRepo = dbModule.userRepo;
    adminRepo = dbModule.adminRepo;
    logger = (await import('./logger.server')).logger;
    withTransaction = (await import('./db/index.db')).withTransaction;
    vi.mocked(withTransaction).mockImplementation(async (callback: any) => {
      return callback({}); // Mock client
    });
    sendPasswordResetEmail = (await import('./emailService.server')).sendPasswordResetEmail;
    UniqueConstraintError = (await import('./db/errors.db')).UniqueConstraintError;
    RepositoryError = (await import('./db/errors.db')).RepositoryError;
  });
  afterEach(() => {
    vi.unstubAllEnvs();
  });
  describe('registerUser', () => {
    it('should successfully register a new user', async () => {
      vi.mocked(bcrypt.hash).mockImplementation(async () => 'hashed-password');
-      vi.mocked(userRepo.createUser).mockResolvedValue(mockUserProfile);
+      vi.mocked(transactionalUserRepoMocks.createUser).mockResolvedValue(mockUserProfile);
      const result = await authService.registerUser(
        'test@example.com',
@@ -86,13 +126,14 @@ describe('AuthService', () => {
      );
      expect(bcrypt.hash).toHaveBeenCalledWith('password123', 10);
-      expect(userRepo.createUser).toHaveBeenCalledWith(
+      expect(transactionalUserRepoMocks.createUser).toHaveBeenCalledWith(
        'test@example.com',
        'hashed-password',
        { full_name: 'Test User', avatar_url: undefined },
        reqLog,
        {},
      );
-      expect(adminRepo.logActivity).toHaveBeenCalledWith(
+      expect(transactionalAdminRepoMocks.logActivity).toHaveBeenCalledWith(
        expect.objectContaining({
          action: 'user_registered',
          userId: 'user-123',
@@ -105,25 +146,25 @@ describe('AuthService', () => {
    it('should throw UniqueConstraintError if email already exists', async () => {
      vi.mocked(bcrypt.hash).mockImplementation(async () => 'hashed-password');
      const error = new UniqueConstraintError('Email exists');
-      vi.mocked(userRepo.createUser).mockRejectedValue(error);
+      vi.mocked(withTransaction).mockRejectedValue(error);
      await expect(
        authService.registerUser('test@example.com', 'password123', undefined, undefined, reqLog),
      ).rejects.toThrow(UniqueConstraintError);
-      expect(logger.error).not.toHaveBeenCalled(); // Should not log expected unique constraint errors as system errors
+      expect(logger.error).toHaveBeenCalled();
    });
-    it('should log and throw other errors', async () => {
+    it('should log and re-throw generic errors on registration failure', async () => {
      vi.mocked(bcrypt.hash).mockImplementation(async () => 'hashed-password');
      const error = new Error('Database failed');
-      vi.mocked(userRepo.createUser).mockRejectedValue(error);
+      vi.mocked(withTransaction).mockRejectedValue(error);
      await expect(
        authService.registerUser('test@example.com', 'password123', undefined, undefined, reqLog),
-      ).rejects.toThrow('Database failed');
+      ).rejects.toThrow(error);
-      expect(logger.error).toHaveBeenCalled();
+      expect(logger.error).toHaveBeenCalledWith({ error, email: 'test@example.com' }, `User registration failed.`);
    });
  });
@@ -131,7 +172,7 @@ describe('AuthService', () => {
    it('should register user and return tokens', async () => {
      // Mock registerUser logic (since we can't easily spy on the same class instance method without prototype spying, we rely on the underlying calls)
      vi.mocked(bcrypt.hash).mockImplementation(async () => 'hashed-password');
-      vi.mocked(userRepo.createUser).mockResolvedValue(mockUserProfile);
+      vi.mocked(transactionalUserRepoMocks.createUser).mockResolvedValue(mockUserProfile);
      // FIX: The global mock for jsonwebtoken provides a `default` export.
      // The code under test (`authService`) uses `import jwt from 'jsonwebtoken'`, so it gets the default export.
      // We must mock `jwt.default.sign` to affect the code under test.
@@ -189,32 +230,29 @@ describe('AuthService', () => {
      expect(userRepo.saveRefreshToken).toHaveBeenCalledWith('user-123', 'token', reqLog);
    });
-    it('should log and throw error on failure', async () => {
+    it('should propagate the error from the repository on failure', async () => {
      const error = new Error('DB Error');
      vi.mocked(userRepo.saveRefreshToken).mockRejectedValue(error);
-      await expect(authService.saveRefreshToken('user-123', 'token', reqLog)).rejects.toThrow(
+      // The service method now directly propagates the error from the repo.
-        'DB Error',
+      await expect(authService.saveRefreshToken('user-123', 'token', reqLog)).rejects.toThrow(error);
-      );
+      expect(logger.error).not.toHaveBeenCalled();
      expect(logger.error).toHaveBeenCalledWith(
        expect.objectContaining({ error }),
        expect.stringContaining('Failed to save refresh token'),
      );
    });
  });
  describe('resetPassword', () => {
    it('should process password reset for existing user', async () => {
-      vi.mocked(userRepo.findUserByEmail).mockResolvedValue(mockUser as any);
+      vi.mocked(userRepo.findUserByEmail).mockResolvedValue(mockUser);
      vi.mocked(bcrypt.hash).mockImplementation(async () => 'hashed-token');
      const result = await authService.resetPassword('test@example.com', reqLog);
-      expect(userRepo.createPasswordResetToken).toHaveBeenCalledWith(
+      expect(transactionalUserRepoMocks.createPasswordResetToken).toHaveBeenCalledWith(
        'user-123',
        'hashed-token',
        expect.any(Date),
        reqLog,
        {},
      );
      expect(sendPasswordResetEmail).toHaveBeenCalledWith(
        'test@example.com',
@@ -248,43 +286,57 @@ describe('AuthService', () => {
  });
  describe('updatePassword', () => {
-    it('should update password if token is valid', async () => {
+    it('should update password if token is valid and wrap operations in a transaction', async () => {
      const mockTokenRecord = {
        user_id: 'user-123',
        token_hash: 'hashed-token',
      };
      vi.mocked(userRepo.getValidResetTokens).mockResolvedValue([mockTokenRecord] as any);
-      vi.mocked(bcrypt.compare).mockImplementation(async () => true); // Match found
+      vi.mocked(bcrypt.compare).mockImplementation(async () => true);
      vi.mocked(bcrypt.hash).mockImplementation(async () => 'new-hashed-password');
      const result = await authService.updatePassword('valid-token', 'newPassword', reqLog);
-      expect(userRepo.updateUserPassword).toHaveBeenCalledWith(
+      expect(withTransaction).toHaveBeenCalledTimes(1);
      expect(transactionalUserRepoMocks.updateUserPassword).toHaveBeenCalledWith(
        'user-123',
        'new-hashed-password',
        reqLog,
      );
-      expect(userRepo.deleteResetToken).toHaveBeenCalledWith('hashed-token', reqLog);
+      expect(transactionalUserRepoMocks.deleteResetToken).toHaveBeenCalledWith('hashed-token', reqLog);
-      expect(adminRepo.logActivity).toHaveBeenCalledWith(
+      expect(transactionalAdminRepoMocks.logActivity).toHaveBeenCalledWith(
        expect.objectContaining({ action: 'password_reset' }),
        reqLog,
      );
      expect(result).toBe(true);
    });
    it('should log and re-throw an error if the transaction fails', async () => {
      const mockTokenRecord = { user_id: 'user-123', token_hash: 'hashed-token' };
      vi.mocked(userRepo.getValidResetTokens).mockResolvedValue([mockTokenRecord] as any);
      vi.mocked(bcrypt.compare).mockImplementation(async () => true);
      const dbError = new Error('Transaction failed');
      vi.mocked(withTransaction).mockRejectedValue(dbError);
      await expect(authService.updatePassword('valid-token', 'newPassword', reqLog)).rejects.toThrow(dbError);
      expect(logger.error).toHaveBeenCalledWith({ error: dbError }, `An error occurred during password update.`);
    });
    it('should return null if token is invalid or not found', async () => {
      vi.mocked(userRepo.getValidResetTokens).mockResolvedValue([]);
      const result = await authService.updatePassword('invalid-token', 'newPassword', reqLog);
-      expect(userRepo.updateUserPassword).not.toHaveBeenCalled();
+      expect(transactionalUserRepoMocks.updateUserPassword).not.toHaveBeenCalled();
      expect(result).toBeNull();
    });
  });
  describe('getUserByRefreshToken', () => {
    it('should return user profile if token exists', async () => {
-      vi.mocked(userRepo.findUserByRefreshToken).mockResolvedValue({ user_id: 'user-123' } as any);
+      vi.mocked(userRepo.findUserByRefreshToken).mockResolvedValue({ user_id: 'user-123', email: 'test@example.com', created_at: new Date().toISOString(), updated_at: new Date().toISOString() });
      vi.mocked(userRepo.findUserProfileById).mockResolvedValue(mockUserProfile);
      const result = await authService.getUserByRefreshToken('valid-token', reqLog);
@@ -299,6 +351,29 @@ describe('AuthService', () => {
      expect(result).toBeNull();
    });
    it('should throw a DatabaseError if finding the user fails with a generic error', async () => {
      const dbError = new Error('DB connection failed');
      vi.mocked(userRepo.findUserByRefreshToken).mockRejectedValue(dbError);
      await expect(authService.getUserByRefreshToken('any-token', reqLog)).rejects.toThrow(DatabaseError);
      expect(logger.error).toHaveBeenCalledWith(
        { error: dbError, refreshToken: 'any-token' },
        'An unexpected error occurred while fetching user by refresh token.',
      );
    });
    it('should re-throw a RepositoryError if finding the user fails with a known error', async () => {
      const repoError = new RepositoryError('Some repo error', 500);
      vi.mocked(userRepo.findUserByRefreshToken).mockRejectedValue(repoError);
      await expect(authService.getUserByRefreshToken('any-token', reqLog)).rejects.toThrow(repoError);
      // The original error is re-thrown, so the generic wrapper log should not be called.
      expect(logger.error).not.toHaveBeenCalledWith(
        expect.any(Object),
        'An unexpected error occurred while fetching user by refresh token.',
      );
    });
  });
  describe('logout', () => {
@@ -307,18 +382,18 @@ describe('AuthService', () => {
      expect(userRepo.deleteRefreshToken).toHaveBeenCalledWith('token', reqLog);
    });
-    it('should log and throw on error', async () => {
+    it('should propagate the error from the repository on failure', async () => {
      const error = new Error('DB Error');
      vi.mocked(userRepo.deleteRefreshToken).mockRejectedValue(error);
-      await expect(authService.logout('token', reqLog)).rejects.toThrow('DB Error');
+      await expect(authService.logout('token', reqLog)).rejects.toThrow(error);
-      expect(logger.error).toHaveBeenCalled();
+      expect(logger.error).not.toHaveBeenCalled();
    });
  });
  describe('refreshAccessToken', () => {
    it('should return new access token if user found', async () => {
-      vi.mocked(userRepo.findUserByRefreshToken).mockResolvedValue({ user_id: 'user-123' } as any);
+      vi.mocked(userRepo.findUserByRefreshToken).mockResolvedValue({ user_id: 'user-123', email: 'test@example.com', created_at: new Date().toISOString(), updated_at: new Date().toISOString() });
      vi.mocked(userRepo.findUserProfileById).mockResolvedValue(mockUserProfile);
      // FIX: The global mock for jsonwebtoken provides a `default` export.
      // The code under test (`authService`) uses `import jwt from 'jsonwebtoken'`, so it gets the default export.
@@ -335,5 +410,13 @@ describe('AuthService', () => {
      const result = await authService.refreshAccessToken('invalid-token', reqLog);
      expect(result).toBeNull();
    });
    it('should propagate errors from getUserByRefreshToken', async () => {
      const dbError = new DatabaseError('Underlying DB call failed');
      // We mock the service's own method since refreshAccessToken calls it directly.
      vi.spyOn(authService, 'getUserByRefreshToken').mockRejectedValue(dbError);
      await expect(authService.refreshAccessToken('any-token', reqLog)).rejects.toThrow(dbError);
    });
  });
 });
--- a/src/services/authService.ts
+++ b/src/services/authService.ts
@@ -2,9 +2,9 @@
 import * as bcrypt from 'bcrypt';
 import jwt from 'jsonwebtoken';
 import crypto from 'crypto';
-import { userRepo, adminRepo } from './db/index.db';
+import { DatabaseError, FlyerProcessingError } from './processingErrors';
-import { UniqueConstraintError } from './db/errors.db';
+import { withTransaction, userRepo } from './db/index.db';
-import { getPool } from './db/connection.db';
+import { RepositoryError, ValidationError } from './db/errors.db';
 import { logger } from './logger.server';
 import { sendPasswordResetEmail } from './emailService.server';
 import type { UserProfile } from '../types';
@@ -20,44 +20,45 @@ class AuthService {
    avatarUrl: string | undefined,
    reqLog: any,
  ) {
-    try {
+    const strength = validatePasswordStrength(password);
    if (!strength.isValid) {
      throw new ValidationError([], strength.feedback);
    }
    // Wrap user creation and activity logging in a transaction for atomicity.
    // The `createUser` method is now designed to be composed within other transactions.
    return withTransaction(async (client) => {
      const transactionalUserRepo = new (await import('./db/user.db')).UserRepository(client);
      const adminRepo = new (await import('./db/admin.db')).AdminRepository(client);
      const saltRounds = 10;
      const hashedPassword = await bcrypt.hash(password, saltRounds);
      logger.info(`Hashing password for new user: ${email}`);
-      // The createUser method in UserRepository now handles its own transaction.
+      const newUser = await transactionalUserRepo.createUser(
      const newUser = await userRepo.createUser(
        email,
        hashedPassword,
        { full_name: fullName, avatar_url: avatarUrl },
        reqLog,
        client, // Pass the transactional client
      );
-      const userEmail = newUser.user.email;
+      logger.info(`Successfully created new user in DB: ${newUser.user.email} (ID: ${newUser.user.user_id})`);
      const userId = newUser.user.user_id;
      logger.info(`Successfully created new user in DB: ${userEmail} (ID: ${userId})`);
      // Use the new standardized logging function
      await adminRepo.logActivity(
-        {
+        { userId: newUser.user.user_id, action: 'user_registered', displayText: `${email} has registered.`, icon: 'user-plus' },
          userId: newUser.user.user_id,
          action: 'user_registered',
          displayText: `${userEmail} has registered.`,
          icon: 'user-plus',
        },
        reqLog,
      );
      return newUser;
-    } catch (error: unknown) {
+    }).catch((error: unknown) => {
-      if (error instanceof UniqueConstraintError) {
+      // The repository layer already logs and throws specific, typed errors.
-        // If the email is a duplicate, return a 409 Conflict status.
+      // We only need to catch, log the high-level operation failure, and re-throw.
-        throw error;
+      logger.error({ error, email }, `User registration failed.`);
-      }
+      // Re-throw the original, specific error (e.g., UniqueConstraintError)
-      logger.error({ error }, `User registration route failed for email: ${email}.`);
+      // so the route handler can generate a precise HTTP response (e.g., 409 Conflict).
      // Pass the error to the centralized handler
      throw error;
-    }
+    });
  }
  async registerAndLoginUser(
@@ -91,15 +92,9 @@ class AuthService {
  }
  async saveRefreshToken(userId: string, refreshToken: string, reqLog: any) {
-    try {
+    // The repository method `saveRefreshToken` already includes robust error handling
-      await userRepo.saveRefreshToken(userId, refreshToken, reqLog);
+    // and logging via `handleDbError`. No need for a redundant try/catch block here.
-    } catch (tokenErr) {
+    await userRepo.saveRefreshToken(userId, refreshToken, reqLog);
      logger.error(
        { error: tokenErr },
        `Failed to save refresh token during login for user: ${userId}`,
      );
      throw tokenErr;
    }
  }
  async handleSuccessfulLogin(userProfile: UserProfile, reqLog: any) {
@@ -124,7 +119,11 @@ class AuthService {
        const tokenHash = await bcrypt.hash(token, saltRounds);
        const expiresAt = new Date(Date.now() + 3600000); // 1 hour
-        await userRepo.createPasswordResetToken(user.user_id, tokenHash, expiresAt, reqLog);
+        // Wrap the token creation in a transaction to ensure atomicity of the DELETE and INSERT operations.
        await withTransaction(async (client) => {
          const transactionalUserRepo = new (await import('./db/user.db')).UserRepository(client);
          await transactionalUserRepo.createPasswordResetToken(user.user_id, tokenHash, expiresAt, reqLog, client);
        });
        const resetLink = `${process.env.FRONTEND_URL}/reset-password/${token}`;
@@ -139,13 +138,25 @@ class AuthService {
      return token;
    } catch (error) {
-      logger.error({ error }, `An error occurred during /forgot-password for email: ${email}`);
+      logger.error({ error, email }, `An error occurred during /forgot-password for email: ${email}`);
      // Re-throw the original error, which might be a specific RepositoryError
      // or a generic DatabaseError from the underlying layers.
      throw error;
    }
  }
  async updatePassword(token: string, newPassword: string, reqLog: any) {
-    try {
+    const strength = validatePasswordStrength(newPassword);
    if (!strength.isValid) {
      throw new ValidationError([], strength.feedback);
    }
    // Wrap all database operations in a transaction to ensure atomicity.
    return withTransaction(async (client) => {
      const transactionalUserRepo = new (await import('./db/user.db')).UserRepository(client);
      const adminRepo = new (await import('./db/admin.db')).AdminRepository(client);
      // This read can happen outside the transaction if we use the non-transactional repo.
      const validTokens = await userRepo.getValidResetTokens(reqLog);
      let tokenRecord;
      for (const record of validTokens) {
@@ -157,32 +168,25 @@ class AuthService {
      }
      if (!tokenRecord) {
-        return null;
+        return null; // Token is invalid or expired, not an error.
      }
      const saltRounds = 10;
      const hashedPassword = await bcrypt.hash(newPassword, saltRounds);
-      await userRepo.updateUserPassword(tokenRecord.user_id, hashedPassword, reqLog);
+      // These three writes are now atomic.
-      await userRepo.deleteResetToken(tokenRecord.token_hash, reqLog);
+      await transactionalUserRepo.updateUserPassword(tokenRecord.user_id, hashedPassword, reqLog);
-
+      await transactionalUserRepo.deleteResetToken(tokenRecord.token_hash, reqLog);
      // Log this security event after a successful password reset.
      await adminRepo.logActivity(
-        {
+        { userId: tokenRecord.user_id, action: 'password_reset', displayText: `User ID ${tokenRecord.user_id} has reset their password.`, icon: 'key' },
          userId: tokenRecord.user_id,
          action: 'password_reset',
          displayText: `User ID ${tokenRecord.user_id} has reset their password.`,
          icon: 'key',
          details: { source_ip: null },
        },
        reqLog,
      );
      return true;
-    } catch (error) {
+    }).catch((error) => {
-      logger.error({ error }, `An error occurred during password reset.`);
+      logger.error({ error }, `An error occurred during password update.`);
      throw error;
-    }
+    });
  }
  async getUserByRefreshToken(refreshToken: string, reqLog: any) {
@@ -194,18 +198,22 @@ class AuthService {
      const userProfile = await userRepo.findUserProfileById(basicUser.user_id, reqLog);
      return userProfile;
    } catch (error) {
-      logger.error({ error }, 'An error occurred during /refresh-token.');
+      // Re-throw known repository errors to allow for specific handling upstream.
-      throw error;
+      if (error instanceof RepositoryError) {
        throw error;
      }
      // For unknown errors, log them and wrap them in a generic DatabaseError.
      const errorMessage = error instanceof Error ? error.message : 'An unknown error occurred.';
      logger.error({ error, refreshToken }, 'An unexpected error occurred while fetching user by refresh token.');
      throw new DatabaseError(errorMessage);
    }
  }
  async logout(refreshToken: string, reqLog: any) {
-    try {
+    // The repository method `deleteRefreshToken` now includes robust error handling
-      await userRepo.deleteRefreshToken(refreshToken, reqLog);
+    // and logging via `handleDbError`. No need for a redundant try/catch block here.
-    } catch (err: any) {
+    // The original implementation also swallowed errors, which is now fixed.
-      logger.error({ error: err }, 'Failed to delete refresh token from DB during logout.');
+    await userRepo.deleteRefreshToken(refreshToken, reqLog);
      throw err;
    }
  }
  async refreshAccessToken(refreshToken: string, reqLog: any): Promise<{ accessToken: string } | null> {
--- a/src/services/db/address.db.ts
+++ b/src/services/db/address.db.ts
@@ -2,7 +2,7 @@
 import type { Pool, PoolClient } from 'pg';
 import { getPool } from './connection.db';
 import type { Logger } from 'pino';
-import { UniqueConstraintError, NotFoundError } from './errors.db';
+import { UniqueConstraintError, NotFoundError, handleDbError } from './errors.db';
 import { Address } from '../../types';
 export class AddressRepository {
@@ -30,11 +30,9 @@ export class AddressRepository {
      }
      return res.rows[0];
    } catch (error) {
-      if (error instanceof NotFoundError) {
+      handleDbError(error, logger, 'Database error in getAddressById', { addressId }, {
-        throw error;
+        defaultMessage: 'Failed to retrieve address.',
-      }
+      });
      logger.error({ err: error, addressId }, 'Database error in getAddressById');
      throw new Error('Failed to retrieve address.');
    }
  }
@@ -78,10 +76,10 @@ export class AddressRepository {
      const res = await this.db.query<{ address_id: number }>(query, values);
      return res.rows[0].address_id;
    } catch (error) {
-      logger.error({ err: error, address }, 'Database error in upsertAddress');
+      handleDbError(error, logger, 'Database error in upsertAddress', { address }, {
-      if (error instanceof Error && 'code' in error && error.code === '23505')
+        uniqueMessage: 'An identical address already exists.',
-        throw new UniqueConstraintError('An identical address already exists.');
+        defaultMessage: 'Failed to upsert address.',
-      throw new Error('Failed to upsert address.');
+      });
    }
  }
 }
--- a/src/services/db/admin.db.test.ts
+++ b/src/services/db/admin.db.test.ts
@@ -203,7 +203,11 @@ describe('Admin DB Service', () => {
        .mockRejectedValueOnce(new Error('DB Read Error'));
      // The Promise.all should reject, and the function should re-throw the error
-      await expect(adminRepo.getApplicationStats(mockLogger)).rejects.toThrow('DB Read Error');
+      // The handleDbError function wraps the original error in a new one with a default message,
      // so we should test for that specific message.
      await expect(adminRepo.getApplicationStats(mockLogger)).rejects.toThrow(
        'Failed to retrieve application statistics.',
      );
      expect(mockLogger.error).toHaveBeenCalledWith(
        { err: expect.any(Error) },
        'Database error in getApplicationStats',
@@ -277,7 +281,7 @@ describe('Admin DB Service', () => {
        'Failed to get most frequent sale items.',
      );
      expect(mockLogger.error).toHaveBeenCalledWith(
-        { err: dbError },
+        { err: dbError, days: 30, limit: 10 },
        'Database error in getMostFrequentSaleItems',
      );
    });
@@ -688,7 +692,9 @@ describe('Admin DB Service', () => {
    it('should re-throw a generic error if the database query fails for other reasons', async () => {
      const dbError = new Error('DB Error');
      mockDb.query.mockRejectedValue(dbError);
-      await expect(adminRepo.updateUserRole('1', 'admin', mockLogger)).rejects.toThrow('DB Error');
+      await expect(adminRepo.updateUserRole('1', 'admin', mockLogger)).rejects.toThrow(
        'Failed to update user role.',
      );
      expect(mockLogger.error).toHaveBeenCalledWith(
        { err: dbError, userId: '1', role: 'admin' },
        'Database error in updateUserRole',
--- a/src/services/db/admin.db.ts
+++ b/src/services/db/admin.db.ts
@@ -1,7 +1,7 @@
 // src/services/db/admin.db.ts
 import type { Pool, PoolClient } from 'pg';
 import { getPool, withTransaction } from './connection.db';
-import { ForeignKeyConstraintError, NotFoundError } from './errors.db';
+import { ForeignKeyConstraintError, NotFoundError, CheckConstraintError, handleDbError } from './errors.db';
 import type { Logger } from 'pino';
 import {
  SuggestedCorrection,
@@ -41,6 +41,7 @@ export class AdminRepository {
        sc.correction_type,
        sc.suggested_value,
        sc.status,
        sc.updated_at,
        sc.created_at,
        fi.item as flyer_item_name,
        fi.price_display as flyer_item_price_display,
@@ -54,8 +55,9 @@ export class AdminRepository {
      const res = await this.db.query<SuggestedCorrection>(query);
      return res.rows;
    } catch (error) {
-      logger.error({ err: error }, 'Database error in getSuggestedCorrections');
+      handleDbError(error, logger, 'Database error in getSuggestedCorrections', {}, {
-      throw new Error('Failed to retrieve suggested corrections.');
+        defaultMessage: 'Failed to retrieve suggested corrections.',
      });
    }
  }
@@ -73,8 +75,10 @@ export class AdminRepository {
          await this.db.query('SELECT public.approve_correction($1)', [correctionId]);
          logger.info(`Successfully approved and applied correction ID: ${correctionId}`);
      } catch (error) {
-          logger.error({ err: error, correctionId }, 'Database transaction error in approveCorrection');
+          handleDbError(error, logger, 'Database transaction error in approveCorrection', { correctionId }, {
-          throw new Error('Failed to approve correction.');
+            fkMessage: 'The suggested master item ID does not exist.',
            defaultMessage: 'Failed to approve correction.',
          });
      }
  }
@@ -95,8 +99,9 @@ export class AdminRepository {
      logger.info(`Successfully rejected correction ID: ${correctionId}`);
    } catch (error) {
      if (error instanceof NotFoundError) throw error;
-      logger.error({ err: error, correctionId }, 'Database error in rejectCorrection');
+      handleDbError(error, logger, 'Database error in rejectCorrection', { correctionId }, {
-      throw new Error('Failed to reject correction.');
+        defaultMessage: 'Failed to reject correction.',
      });
    }
  }
@@ -121,8 +126,9 @@ export class AdminRepository {
      if (error instanceof NotFoundError) {
        throw error;
      }
-      logger.error({ err: error, correctionId }, 'Database error in updateSuggestedCorrection');
+      handleDbError(error, logger, 'Database error in updateSuggestedCorrection', { correctionId }, {
-      throw new Error('Failed to update suggested correction.');
+        defaultMessage: 'Failed to update suggested correction.',
      });
    }
  }
@@ -168,8 +174,9 @@ export class AdminRepository {
      recipeCount: parseInt(recipeCountRes.rows[0].count, 10),
    };
    } catch (error) {
-      logger.error({ err: error }, 'Database error in getApplicationStats');
+      handleDbError(error, logger, 'Database error in getApplicationStats', {}, {
-      throw error; // Re-throw the original error to be handled by the caller
+        defaultMessage: 'Failed to retrieve application statistics.',
      });
    }
  }
@@ -212,8 +219,9 @@ export class AdminRepository {
      const res = await this.db.query(query);
      return res.rows;
    } catch (error) {
-      logger.error({ err: error }, 'Database error in getDailyStatsForLast30Days');
+      handleDbError(error, logger, 'Database error in getDailyStatsForLast30Days', {}, {
-      throw new Error('Failed to retrieve daily statistics.');
+        defaultMessage: 'Failed to retrieve daily statistics.',
      });
    }
  }
@@ -254,8 +262,9 @@ export class AdminRepository {
      const res = await this.db.query<MostFrequentSaleItem>(query, [days, limit]);
      return res.rows;
    } catch (error) {
-      logger.error({ err: error }, 'Database error in getMostFrequentSaleItems');
+      handleDbError(error, logger, 'Database error in getMostFrequentSaleItems', { days, limit }, {
-      throw new Error('Failed to get most frequent sale items.');
+        defaultMessage: 'Failed to get most frequent sale items.',
      });
    }
  }
@@ -283,11 +292,10 @@ export class AdminRepository {
      if (error instanceof NotFoundError) {
        throw error;
      }
-      logger.error(
+      handleDbError(error, logger, 'Database error in updateRecipeCommentStatus', { commentId, status }, {
-        { err: error, commentId, status },
+        checkMessage: 'Invalid status provided for recipe comment.',
-        'Database error in updateRecipeCommentStatus',
+        defaultMessage: 'Failed to update recipe comment status.',
-      );
+      });
      throw new Error('Failed to update recipe comment status.');
    }
  }
@@ -301,6 +309,7 @@ export class AdminRepository {
      SELECT
        ufi.unmatched_flyer_item_id,
        ufi.status,
        ufi.updated_at,
        ufi.created_at,
        fi.flyer_item_id as flyer_item_id,
        fi.item as flyer_item_name,
@@ -317,8 +326,9 @@ export class AdminRepository {
      const res = await this.db.query<UnmatchedFlyerItem>(query);
      return res.rows;
    } catch (error) {
-      logger.error({ err: error }, 'Database error in getUnmatchedFlyerItems');
+      handleDbError(error, logger, 'Database error in getUnmatchedFlyerItems', {}, {
-      throw new Error('Failed to retrieve unmatched flyer items.');
+        defaultMessage: 'Failed to retrieve unmatched flyer items.',
      });
    }
  }
@@ -344,8 +354,10 @@ export class AdminRepository {
      if (error instanceof NotFoundError) {
        throw error;
      }
-      logger.error({ err: error, recipeId, status }, 'Database error in updateRecipeStatus');
+      handleDbError(error, logger, 'Database error in updateRecipeStatus', { recipeId, status }, {
-      throw new Error('Failed to update recipe status.'); // Keep generic for other DB errors
+        checkMessage: 'Invalid status provided for recipe.',
        defaultMessage: 'Failed to update recipe status.',
      });
    }
  }
@@ -397,11 +409,13 @@ export class AdminRepository {
      if (error instanceof NotFoundError) {
        throw error;
      }
-      logger.error(
+      handleDbError(
-        { err: error, unmatchedFlyerItemId, masterItemId },
+        error,
        logger,
        'Database transaction error in resolveUnmatchedFlyerItem',
        { unmatchedFlyerItemId, masterItemId },
        { fkMessage: 'The specified master item ID does not exist.', defaultMessage: 'Failed to resolve unmatched flyer item.' },
      );
      throw new Error('Failed to resolve unmatched flyer item.');
    }
  }
@@ -422,11 +436,13 @@ export class AdminRepository {
      }
    } catch (error) {
      if (error instanceof NotFoundError) throw error;
-      logger.error(
+      handleDbError(
-        { err: error, unmatchedFlyerItemId },
+        error,
        logger,
        'Database error in ignoreUnmatchedFlyerItem',
        { unmatchedFlyerItemId },
        { defaultMessage: 'Failed to ignore unmatched flyer item.' },
      );
      throw new Error('Failed to ignore unmatched flyer item.');
    }
  }
@@ -442,8 +458,9 @@ export class AdminRepository {
          const res = await this.db.query<ActivityLogItem>('SELECT * FROM public.get_activity_log($1, $2)', [limit, offset]);
          return res.rows;
      } catch (error) {
-          logger.error({ err: error, limit, offset }, 'Database error in getActivityLog');
+          handleDbError(error, logger, 'Database error in getActivityLog', { limit, offset }, {
-          throw new Error('Failed to retrieve activity log.');
+            defaultMessage: 'Failed to retrieve activity log.',
          });
      }
  }
@@ -544,8 +561,9 @@ export class AdminRepository {
      }
    } catch (error) {
      if (error instanceof NotFoundError) throw error;
-      logger.error({ err: error, brandId }, 'Database error in updateBrandLogo');
+      handleDbError(error, logger, 'Database error in updateBrandLogo', { brandId }, {
-      throw new Error('Failed to update brand logo in database.');
+        defaultMessage: 'Failed to update brand logo in database.',
      });
    }
  }
@@ -569,8 +587,10 @@ export class AdminRepository {
      return res.rows[0];
    } catch (error) {
      if (error instanceof NotFoundError) throw error;
-      logger.error({ err: error, receiptId, status }, 'Database error in updateReceiptStatus');
+      handleDbError(error, logger, 'Database error in updateReceiptStatus', { receiptId, status }, {
-      throw new Error('Failed to update receipt status.');
+        checkMessage: 'Invalid status provided for receipt.',
        defaultMessage: 'Failed to update receipt status.',
      });
    }
  }
@@ -583,8 +603,9 @@ export class AdminRepository {
      const res = await this.db.query<AdminUserView>(query);
      return res.rows;
    } catch (error) {
-      logger.error({ err: error }, 'Database error in getAllUsers');
+      handleDbError(error, logger, 'Database error in getAllUsers', {}, {
-      throw new Error('Failed to retrieve all users.');
+        defaultMessage: 'Failed to retrieve all users.',
      });
    }
  }
@@ -605,14 +626,14 @@ export class AdminRepository {
      }
      return res.rows[0];
    } catch (error) {
      logger.error({ err: error, userId, role }, 'Database error in updateUserRole');
      if (error instanceof Error && 'code' in error && error.code === '23503') {
        throw new ForeignKeyConstraintError('The specified user does not exist.');
      }
      if (error instanceof NotFoundError) {
        throw error;
      }
-      throw error; // Re-throw to be handled by the route
+      handleDbError(error, logger, 'Database error in updateUserRole', { userId, role }, {
        fkMessage: 'The specified user does not exist.',
        checkMessage: 'Invalid role provided for user.',
        defaultMessage: 'Failed to update user role.',
      });
    }
  }
@@ -639,8 +660,9 @@ export class AdminRepository {
      const res = await this.db.query<Flyer>(query);
      return res.rows;
    } catch (error) {
-      logger.error({ err: error }, 'Database error in getFlyersForReview');
+      handleDbError(error, logger, 'Database error in getFlyersForReview', {}, {
-      throw new Error('Failed to retrieve flyers for review.');
+        defaultMessage: 'Failed to retrieve flyers for review.',
      });
    }
  }
 }
--- a/src/services/db/budget.db.test.ts
+++ b/src/services/db/budget.db.test.ts
@@ -249,6 +249,17 @@ describe('Budget DB Service', () => {
      expect(result).toEqual(mockUpdatedBudget);
    });
    it('should prevent a user from updating a budget they do not own', async () => {
      // Arrange: Mock the query to return 0 rows affected
      mockDb.query.mockResolvedValue({ rows: [], rowCount: 0 });
      // Act & Assert: Attempt to update with a different user ID should throw an error.
      await expect(
        budgetRepo.updateBudget(1, 'another-user', { name: 'Updated Groceries' }, mockLogger),
      ).rejects.toThrow('Budget not found or user does not have permission to update.');
    });
    it('should throw an error if no rows are updated', async () => {
      // Arrange: Mock the query to return 0 rows affected
      mockDb.query.mockResolvedValue({ rows: [], rowCount: 0 });
--- a/src/services/db/budget.db.ts
+++ b/src/services/db/budget.db.ts
@@ -1,7 +1,7 @@
 // src/services/db/budget.db.ts
 import type { Pool, PoolClient } from 'pg';
 import { getPool, withTransaction } from './connection.db';
-import { ForeignKeyConstraintError, NotFoundError } from './errors.db';
+import { NotFoundError, handleDbError } from './errors.db';
 import type { Logger } from 'pino';
 import type { Budget, SpendingByCategory } from '../../types';
 import { GamificationRepository } from './gamification.db';
@@ -28,8 +28,9 @@ export class BudgetRepository {
      );
      return res.rows;
    } catch (error) {
-      logger.error({ err: error, userId }, 'Database error in getBudgetsForUser');
+      handleDbError(error, logger, 'Database error in getBudgetsForUser', { userId }, {
-      throw new Error('Failed to retrieve budgets.');
+        defaultMessage: 'Failed to retrieve budgets.',
      });
    }
  }
@@ -59,14 +60,12 @@ export class BudgetRepository {
        return res.rows[0];
      });
    } catch (error) {
-      // The patch requested this specific error handling.
+      handleDbError(error, logger, 'Database error in createBudget', { budgetData, userId }, {
-      // Type-safe check for a PostgreSQL error code.
+        fkMessage: 'The specified user does not exist.',
-      // This ensures 'error' is an object with a 'code' property before we access it.
+        notNullMessage: 'One or more required budget fields are missing.',
-      if (error instanceof Error && 'code' in error && error.code === '23503') {
+        checkMessage: 'Invalid value provided for budget period.',
-        throw new ForeignKeyConstraintError('The specified user does not exist.');
+        defaultMessage: 'Failed to create budget.',
-      }
+      });
      logger.error({ err: error, budgetData, userId }, 'Database error in createBudget');
      throw new Error('Failed to create budget.');
    }
  }
@@ -99,8 +98,9 @@ export class BudgetRepository {
      return res.rows[0];
    } catch (error) {
      if (error instanceof NotFoundError) throw error;
-      logger.error({ err: error, budgetId, userId }, 'Database error in updateBudget');
+      handleDbError(error, logger, 'Database error in updateBudget', { budgetId, userId }, {
-      throw new Error('Failed to update budget.');
+        defaultMessage: 'Failed to update budget.',
      });
    }
  }
@@ -120,8 +120,9 @@ export class BudgetRepository {
      }
    } catch (error) {
      if (error instanceof NotFoundError) throw error;
-      logger.error({ err: error, budgetId, userId }, 'Database error in deleteBudget');
+      handleDbError(error, logger, 'Database error in deleteBudget', { budgetId, userId }, {
-      throw new Error('Failed to delete budget.');
+        defaultMessage: 'Failed to delete budget.',
      });
    }
  }
@@ -145,11 +146,13 @@ export class BudgetRepository {
      );
      return res.rows;
    } catch (error) {
-      logger.error(
+      handleDbError(
-        { err: error, userId, startDate, endDate },
+        error,
        logger,
        'Database error in getSpendingByCategory',
        { userId, startDate, endDate },
        { defaultMessage: 'Failed to get spending analysis.' },
      );
      throw new Error('Failed to get spending analysis.');
    }
  }
 }
--- a/src/services/db/connection.db.ts
+++ b/src/services/db/connection.db.ts
@@ -6,6 +6,7 @@
 // src/services/db/connection.db.ts
 import { Pool, PoolConfig, PoolClient, types } from 'pg';
 import { logger } from '../logger.server';
 import { handleDbError } from './errors.db';
 // --- Singleton Pool Instance ---
 // This variable will hold the single, shared connection pool for the entire application.
@@ -105,8 +106,9 @@ export async function checkTablesExist(tableNames: string[]): Promise<string[]>
    return missingTables;
  } catch (error) {
-    logger.error({ err: error }, 'Database error in checkTablesExist');
+    handleDbError(error, logger, 'Database error in checkTablesExist', {}, {
-    throw new Error('Failed to check for tables in database.');
+      defaultMessage: 'Failed to check for tables in database.',
    });
  }
 }
--- a/src/services/db/conversion.db.test.ts
+++ b/src/services/db/conversion.db.test.ts
@@ -0,0 +1,160 @@
 // src/services/db/conversion.db.test.ts
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { mockPoolInstance } from '../../tests/setup/tests-setup-unit';
 import { getPool } from './connection.db';
 import { conversionRepo } from './conversion.db';
 import { NotFoundError } from './errors.db';
 import type { UnitConversion } from '../../types';
 // Un-mock the module we are testing
 vi.unmock('./conversion.db');
 // Mock dependencies
 vi.mock('./connection.db', () => ({
  getPool: vi.fn(),
 }));
 vi.mock('../logger.server', () => ({
  logger: {
    info: vi.fn(),
    warn: vi.fn(),
    error: vi.fn(),
    debug: vi.fn(),
  },
 }));
 import { logger as mockLogger } from '../logger.server';
 describe('Conversion DB Service', () => {
  beforeEach(() => {
    vi.clearAllMocks();
    // Make getPool return our mock instance for each test
    vi.mocked(getPool).mockReturnValue(mockPoolInstance as any);
  });
  describe('getConversions', () => {
    it('should return all conversions if no filters are provided', async () => {
      const mockConversions: UnitConversion[] = [
        {
          unit_conversion_id: 1,
          master_item_id: 1,
          from_unit: 'g',
          to_unit: 'kg',
          factor: 0.001,
          created_at: new Date().toISOString(),
          updated_at: new Date().toISOString(),
        },
      ];
      mockPoolInstance.query.mockResolvedValue({ rows: mockConversions });
      const result = await conversionRepo.getConversions({}, mockLogger);
      expect(mockPoolInstance.query).toHaveBeenCalledWith(
        expect.stringContaining('SELECT * FROM public.unit_conversions'),
        expect.any(Array),
      );
      // Check that WHERE clause is not present for master_item_id
      expect(mockPoolInstance.query.mock.calls[0][0]).not.toContain('WHERE master_item_id');
      expect(result).toEqual(mockConversions);
    });
    it('should filter by masterItemId', async () => {
      mockPoolInstance.query.mockResolvedValue({ rows: [] });
      await conversionRepo.getConversions({ masterItemId: 123 }, mockLogger);
      expect(mockPoolInstance.query).toHaveBeenCalledWith(
        expect.stringContaining('WHERE master_item_id = $1'),
        [123],
      );
    });
    it('should throw an error if the database query fails', async () => {
      const dbError = new Error('DB Error');
      mockPoolInstance.query.mockRejectedValue(dbError);
      await expect(conversionRepo.getConversions({}, mockLogger)).rejects.toThrow(
        'Failed to retrieve unit conversions.',
      );
      expect(mockLogger.error).toHaveBeenCalledWith(
        { err: dbError, filters: {} },
        'Database error in getConversions',
      );
    });
  });
  describe('createConversion', () => {
    const newConversion = {
      master_item_id: 1,
      from_unit: 'cup',
      to_unit: 'ml',
      factor: 236.588,
    };
    it('should insert a new conversion and return it', async () => {
      const mockCreatedConversion: UnitConversion = {
        unit_conversion_id: 1,
        ...newConversion,
        created_at: new Date().toISOString(),
        updated_at: new Date().toISOString(),
      };
      mockPoolInstance.query.mockResolvedValue({ rows: [mockCreatedConversion] });
      const result = await conversionRepo.createConversion(newConversion, mockLogger);
      expect(mockPoolInstance.query).toHaveBeenCalledWith(
        expect.stringContaining('INSERT INTO public.unit_conversions'),
        [1, 'cup', 'ml', 236.588],
      );
      expect(result).toEqual(mockCreatedConversion);
    });
    it('should throw an error if the database query fails', async () => {
      const dbError = new Error('DB Error');
      mockPoolInstance.query.mockRejectedValue(dbError);
      await expect(conversionRepo.createConversion(newConversion, mockLogger)).rejects.toThrow(
        'Failed to create unit conversion.',
      );
      expect(mockLogger.error).toHaveBeenCalledWith(
        { err: dbError, conversionData: newConversion },
        'Database error in createConversion',
      );
    });
  });
  describe('deleteConversion', () => {
    it('should delete a conversion if found', async () => {
      mockPoolInstance.query.mockResolvedValue({ rowCount: 1 });
      await conversionRepo.deleteConversion(1, mockLogger);
      expect(mockPoolInstance.query).toHaveBeenCalledWith(
        'DELETE FROM public.unit_conversions WHERE unit_conversion_id = $1',
        [1],
      );
    });
    it('should throw NotFoundError if conversion is not found', async () => {
      mockPoolInstance.query.mockResolvedValue({ rowCount: 0 });
      await expect(conversionRepo.deleteConversion(999, mockLogger)).rejects.toThrow(NotFoundError);
      await expect(conversionRepo.deleteConversion(999, mockLogger)).rejects.toThrow(
        'Unit conversion with ID 999 not found.',
      );
    });
    it('should throw an error if the database query fails', async () => {
      const dbError = new Error('DB Error');
      mockPoolInstance.query.mockRejectedValue(dbError);
      await expect(conversionRepo.deleteConversion(1, mockLogger)).rejects.toThrow(
        'Failed to delete unit conversion.',
      );
      expect(mockLogger.error).toHaveBeenCalledWith(
        { err: dbError, conversionId: 1 },
        'Database error in deleteConversion',
      );
    });
  });
 });
--- a/src/services/db/conversion.db.ts
+++ b/src/services/db/conversion.db.ts
@@ -0,0 +1,78 @@
 // src/services/db/conversion.db.ts
 import type { Logger } from 'pino';
 import { getPool } from './connection.db';
 import { handleDbError, NotFoundError } from './errors.db';
 import type { UnitConversion } from '../../types';
 export const conversionRepo = {
  /**
   * Fetches unit conversions, optionally filtered by master_item_id.
   */
  async getConversions(
    filters: { masterItemId?: number },
    logger: Logger,
  ): Promise<UnitConversion[]> {
    const { masterItemId } = filters;
    try {
      let query = 'SELECT * FROM public.unit_conversions';
      const params: any[] = [];
      if (masterItemId) {
        query += ' WHERE master_item_id = $1';
        params.push(masterItemId);
      }
      query += ' ORDER BY master_item_id, from_unit, to_unit';
      const result = await getPool().query<UnitConversion>(query, params);
      return result.rows;
    } catch (error) {
      handleDbError(error, logger, 'Database error in getConversions', { filters }, {
        defaultMessage: 'Failed to retrieve unit conversions.',
      });
    }
  },
  /**
   * Creates a new unit conversion rule.
   */
  async createConversion(
    conversionData: Omit<UnitConversion, 'unit_conversion_id' | 'created_at' | 'updated_at'>,
    logger: Logger,
  ): Promise<UnitConversion> {
    const { master_item_id, from_unit, to_unit, factor } = conversionData;
    try {
      const res = await getPool().query<UnitConversion>(
        'INSERT INTO public.unit_conversions (master_item_id, from_unit, to_unit, factor) VALUES ($1, $2, $3, $4) RETURNING *',
        [master_item_id, from_unit, to_unit, factor],
      );
      return res.rows[0];
    } catch (error) {
      handleDbError(error, logger, 'Database error in createConversion', { conversionData }, {
        fkMessage: 'The specified master item does not exist.',
        uniqueMessage: 'This conversion rule already exists for this item.',
        checkMessage: 'Invalid unit conversion data provided (e.g., factor must be > 0, units cannot be the same).',
        defaultMessage: 'Failed to create unit conversion.',
      });
    }
  },
  /**
   * Deletes a unit conversion rule.
   */
  async deleteConversion(conversionId: number, logger: Logger): Promise<void> {
    try {
      const res = await getPool().query(
        'DELETE FROM public.unit_conversions WHERE unit_conversion_id = $1',
        [conversionId],
      );
      if (res.rowCount === 0) {
        throw new NotFoundError(`Unit conversion with ID ${conversionId} not found.`);
      }
    } catch (error) {
      handleDbError(error, logger, 'Database error in deleteConversion', { conversionId }, {
        defaultMessage: 'Failed to delete unit conversion.',
      });
    }
  },
 };
--- a/src/services/db/deals.db.test.ts
+++ b/src/services/db/deals.db.test.ts
@@ -82,15 +82,15 @@ describe('Deals DB Service', () => {
      expect(result).toEqual([]);
    });
-    it('should re-throw the error if the database query fails', async () => {
+    it('should throw a generic error if the database query fails', async () => {
      const dbError = new Error('DB Connection Error');
      mockDb.query.mockRejectedValue(dbError);
      await expect(dealsRepo.findBestPricesForWatchedItems('user-1', mockLogger)).rejects.toThrow(
-        dbError,
+        'Failed to find best prices for watched items.',
      );
      expect(mockLogger.error).toHaveBeenCalledWith(
-        { err: dbError },
+        { err: dbError, userId: 'user-1' },
        'Database error in findBestPricesForWatchedItems',
      );
    });
--- a/src/services/db/deals.db.ts
+++ b/src/services/db/deals.db.ts
@@ -4,6 +4,7 @@ import { WatchedItemDeal } from '../../types';
 import type { Pool, PoolClient } from 'pg';
 import type { Logger } from 'pino';
 import { logger as globalLogger } from '../logger.server';
 import { handleDbError } from './errors.db';
 export class DealsRepository {
  // The repository only needs an object with a `query` method, matching the Pool/PoolClient interface.
@@ -69,8 +70,9 @@ export class DealsRepository {
      const { rows } = await this.db.query<WatchedItemDeal>(query, [userId]);
      return rows;
    } catch (error) {
-      logger.error({ err: error }, 'Database error in findBestPricesForWatchedItems');
+      handleDbError(error, logger, 'Database error in findBestPricesForWatchedItems', { userId }, {
-      throw error; // Re-throw the original error to be handled by the global error handler
+        defaultMessage: 'Failed to find best prices for watched items.',
      });
    }
  }
 }
--- a/src/services/db/errors.db.test.ts
+++ b/src/services/db/errors.db.test.ts
@@ -1,26 +1,34 @@
 // src/services/db/errors.db.test.ts
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
 import type { Logger } from 'pino';
 import {
-  DatabaseError,
+  RepositoryError,
  UniqueConstraintError,
  ForeignKeyConstraintError,
  NotFoundError,
  ValidationError,
  FileUploadError,
  NotNullConstraintError,
  CheckConstraintError,
  InvalidTextRepresentationError,
  NumericValueOutOfRangeError,
  handleDbError,
 } from './errors.db';
 vi.mock('./logger.server');
 describe('Custom Database and Application Errors', () => {
-  describe('DatabaseError', () => {
+  describe('RepositoryError', () => {
    it('should create a generic database error with a message and status', () => {
      const message = 'Generic DB Error';
      const status = 500;
-      const error = new DatabaseError(message, status);
+      const error = new RepositoryError(message, status);
      expect(error).toBeInstanceOf(Error);
-      expect(error).toBeInstanceOf(DatabaseError);
+      expect(error).toBeInstanceOf(RepositoryError);
      expect(error.message).toBe(message);
      expect(error.status).toBe(status);
-      expect(error.name).toBe('DatabaseError');
+      expect(error.name).toBe('RepositoryError');
    });
  });
@@ -29,7 +37,7 @@ describe('Custom Database and Application Errors', () => {
      const error = new UniqueConstraintError();
      expect(error).toBeInstanceOf(Error);
-      expect(error).toBeInstanceOf(DatabaseError);
+      expect(error).toBeInstanceOf(RepositoryError);
      expect(error).toBeInstanceOf(UniqueConstraintError);
      expect(error.message).toBe('The record already exists.');
      expect(error.status).toBe(409);
@@ -48,7 +56,7 @@ describe('Custom Database and Application Errors', () => {
      const error = new ForeignKeyConstraintError();
      expect(error).toBeInstanceOf(Error);
-      expect(error).toBeInstanceOf(DatabaseError);
+      expect(error).toBeInstanceOf(RepositoryError);
      expect(error).toBeInstanceOf(ForeignKeyConstraintError);
      expect(error.message).toBe('The referenced record does not exist.');
      expect(error.status).toBe(400);
@@ -67,7 +75,7 @@ describe('Custom Database and Application Errors', () => {
      const error = new NotFoundError();
      expect(error).toBeInstanceOf(Error);
-      expect(error).toBeInstanceOf(DatabaseError);
+      expect(error).toBeInstanceOf(RepositoryError);
      expect(error).toBeInstanceOf(NotFoundError);
      expect(error.message).toBe('The requested resource was not found.');
      expect(error.status).toBe(404);
@@ -87,7 +95,7 @@ describe('Custom Database and Application Errors', () => {
      const error = new ValidationError(validationIssues);
      expect(error).toBeInstanceOf(Error);
-      expect(error).toBeInstanceOf(DatabaseError);
+      expect(error).toBeInstanceOf(RepositoryError);
      expect(error).toBeInstanceOf(ValidationError);
      expect(error.message).toBe('The request data is invalid.');
      expect(error.status).toBe(400);
@@ -114,4 +122,161 @@ describe('Custom Database and Application Errors', () => {
      expect(error.name).toBe('FileUploadError');
    });
  });
  describe('NotNullConstraintError', () => {
    it('should create an error with a default message and status 400', () => {
      const error = new NotNullConstraintError();
      expect(error).toBeInstanceOf(RepositoryError);
      expect(error.message).toBe('A required field was left null.');
      expect(error.status).toBe(400);
      expect(error.name).toBe('NotNullConstraintError');
    });
    it('should create an error with a custom message', () => {
      const message = 'Email cannot be null.';
      const error = new NotNullConstraintError(message);
      expect(error.message).toBe(message);
    });
  });
  describe('CheckConstraintError', () => {
    it('should create an error with a default message and status 400', () => {
      const error = new CheckConstraintError();
      expect(error).toBeInstanceOf(RepositoryError);
      expect(error.message).toBe('A check constraint was violated.');
      expect(error.status).toBe(400);
      expect(error.name).toBe('CheckConstraintError');
    });
    it('should create an error with a custom message', () => {
      const message = 'Price must be positive.';
      const error = new CheckConstraintError(message);
      expect(error.message).toBe(message);
    });
  });
  describe('InvalidTextRepresentationError', () => {
    it('should create an error with a default message and status 400', () => {
      const error = new InvalidTextRepresentationError();
      expect(error).toBeInstanceOf(RepositoryError);
      expect(error.message).toBe('A value has an invalid format for its data type.');
      expect(error.status).toBe(400);
      expect(error.name).toBe('InvalidTextRepresentationError');
    });
    it('should create an error with a custom message', () => {
      const message = 'Invalid input syntax for type integer: "abc"';
      const error = new InvalidTextRepresentationError(message);
      expect(error.message).toBe(message);
    });
  });
  describe('NumericValueOutOfRangeError', () => {
    it('should create an error with a default message and status 400', () => {
      const error = new NumericValueOutOfRangeError();
      expect(error).toBeInstanceOf(RepositoryError);
      expect(error.message).toBe('A numeric value is out of the allowed range.');
      expect(error.status).toBe(400);
      expect(error.name).toBe('NumericValueOutOfRangeError');
    });
    it('should create an error with a custom message', () => {
      const message = 'Value too large for type smallint.';
      const error = new NumericValueOutOfRangeError(message);
      expect(error.message).toBe(message);
    });
  });
  describe('handleDbError', () => {
    const mockLogger = {
      error: vi.fn(),
    } as unknown as Logger;
    beforeEach(() => {
      vi.clearAllMocks();
    });
    it('should re-throw existing RepositoryError instances without logging', () => {
      const notFound = new NotFoundError('Test not found');
      expect(() => handleDbError(notFound, mockLogger, 'msg', {})).toThrow(notFound);
      expect(mockLogger.error).not.toHaveBeenCalled();
    });
    it('should throw UniqueConstraintError for code 23505', () => {
      const dbError = new Error('duplicate key');
      (dbError as any).code = '23505';
      expect(() =>
        handleDbError(dbError, mockLogger, 'msg', {}, { uniqueMessage: 'custom unique' }),
      ).toThrow('custom unique');
    });
    it('should throw ForeignKeyConstraintError for code 23503', () => {
      const dbError = new Error('fk violation');
      (dbError as any).code = '23503';
      expect(() =>
        handleDbError(dbError, mockLogger, 'msg', {}, { fkMessage: 'custom fk' }),
      ).toThrow('custom fk');
    });
    it('should throw NotNullConstraintError for code 23502', () => {
      const dbError = new Error('not null violation');
      (dbError as any).code = '23502';
      expect(() =>
        handleDbError(dbError, mockLogger, 'msg', {}, { notNullMessage: 'custom not null' }),
      ).toThrow('custom not null');
    });
    it('should throw CheckConstraintError for code 23514', () => {
      const dbError = new Error('check violation');
      (dbError as any).code = '23514';
      expect(() =>
        handleDbError(dbError, mockLogger, 'msg', {}, { checkMessage: 'custom check' }),
      ).toThrow('custom check');
    });
    it('should throw InvalidTextRepresentationError for code 22P02', () => {
      const dbError = new Error('invalid text');
      (dbError as any).code = '22P02';
      expect(() =>
        handleDbError(dbError, mockLogger, 'msg', {}, { invalidTextMessage: 'custom invalid text' }),
      ).toThrow('custom invalid text');
    });
    it('should throw NumericValueOutOfRangeError for code 22003', () => {
      const dbError = new Error('out of range');
      (dbError as any).code = '22003';
      expect(() =>
        handleDbError(
          dbError,
          mockLogger,
          'msg',
          {},
          { numericOutOfRangeMessage: 'custom out of range' },
        ),
      ).toThrow('custom out of range');
    });
    it('should throw a generic Error with a default message', () => {
      const genericError = new Error('Something else happened');
      expect(() =>
        handleDbError(genericError, mockLogger, 'msg', {}, { defaultMessage: 'Oops' }),
      ).toThrow('Oops');
      expect(mockLogger.error).toHaveBeenCalledWith({ err: genericError }, 'msg');
    });
    it('should throw a generic Error with a constructed message using entityName', () => {
      const genericError = new Error('Something else happened');
      expect(() =>
        handleDbError(genericError, mockLogger, 'msg', {}, { entityName: 'User' }),
      ).toThrow('Failed to perform operation on User.');
    });
    it('should throw a generic Error with a constructed message using "database" as a fallback', () => {
      const genericError = new Error('Something else happened');
      // No defaultMessage or entityName provided
      expect(() => handleDbError(genericError, mockLogger, 'msg', {}, {})).toThrow(
        'Failed to perform operation on database.',
      );
    });
  });
 });
--- a/src/services/db/errors.db.ts
+++ b/src/services/db/errors.db.ts
@@ -1,9 +1,11 @@
 // src/services/db/errors.db.ts
 import type { Logger } from 'pino';
 import { DatabaseError as ProcessingDatabaseError } from '../processingErrors';
 /**
- * Base class for custom database errors to ensure they have a status property.
+ * Base class for custom repository-level errors to ensure they have a status property.
 */
-export class DatabaseError extends Error {
+export class RepositoryError extends Error {
  public status: number;
  constructor(message: string, status: number) {
@@ -19,7 +21,7 @@ export class DatabaseError extends Error {
 * Thrown when a unique constraint is violated (e.g., trying to register an existing email).
 * Corresponds to PostgreSQL error code '23505'.
 */
-export class UniqueConstraintError extends DatabaseError {
+export class UniqueConstraintError extends RepositoryError {
  constructor(message = 'The record already exists.') {
    super(message, 409); // 409 Conflict
  }
@@ -29,16 +31,56 @@ export class UniqueConstraintError extends DatabaseError {
 * Thrown when a foreign key constraint is violated (e.g., trying to reference a non-existent record).
 * Corresponds to PostgreSQL error code '23503'.
 */
-export class ForeignKeyConstraintError extends DatabaseError {
+export class ForeignKeyConstraintError extends RepositoryError {
  constructor(message = 'The referenced record does not exist.') {
    super(message, 400); // 400 Bad Request
  }
 }
 /**
 * Thrown when a 'not null' constraint is violated.
 * Corresponds to PostgreSQL error code '23502'.
 */
 export class NotNullConstraintError extends RepositoryError {
  constructor(message = 'A required field was left null.') {
    super(message, 400); // 400 Bad Request
  }
 }
 /**
 * Thrown when a 'check' constraint is violated.
 * Corresponds to PostgreSQL error code '23514'.
 */
 export class CheckConstraintError extends RepositoryError {
  constructor(message = 'A check constraint was violated.') {
    super(message, 400); // 400 Bad Request
  }
 }
 /**
 * Thrown when a value has an invalid text representation for its data type (e.g., 'abc' for an integer).
 * Corresponds to PostgreSQL error code '22P02'.
 */
 export class InvalidTextRepresentationError extends RepositoryError {
  constructor(message = 'A value has an invalid format for its data type.') {
    super(message, 400); // 400 Bad Request
  }
 }
 /**
 * Thrown when a numeric value is out of range for its data type (e.g., too large for an integer).
 * Corresponds to PostgreSQL error code '22003'.
 */
 export class NumericValueOutOfRangeError extends RepositoryError {
  constructor(message = 'A numeric value is out of the allowed range.') {
    super(message, 400); // 400 Bad Request
  }
 }
 /**
 * Thrown when a specific record is not found in the database.
 */
-export class NotFoundError extends DatabaseError {
+export class NotFoundError extends RepositoryError {
  constructor(message = 'The requested resource was not found.') {
    super(message, 404); // 404 Not Found
  }
@@ -56,7 +98,7 @@ export interface ValidationIssue {
 /**
 * Thrown when request validation fails (e.g., missing body fields or invalid params).
 */
-export class ValidationError extends DatabaseError {
+export class ValidationError extends RepositoryError {
  public validationErrors: ValidationIssue[];
  constructor(errors: ValidationIssue[], message = 'The request data is invalid.') {
@@ -73,3 +115,50 @@ export class FileUploadError extends Error {
    this.name = 'FileUploadError';
  }
 }
 export interface HandleDbErrorOptions {
  entityName?: string;
  uniqueMessage?: string;
  fkMessage?: string;
  notNullMessage?: string;
  checkMessage?: string;
  invalidTextMessage?: string;
  numericOutOfRangeMessage?: string;
  defaultMessage?: string;
 }
 /**
 * Centralized error handler for database repositories.
 * Logs the error and throws appropriate custom errors based on PostgreSQL error codes.
 */
 export function handleDbError(
  error: unknown,
  logger: Logger,
  logMessage: string,
  logContext: Record<string, unknown>,
  options: HandleDbErrorOptions = {},
 ): never {
  // If it's already a known domain error (like NotFoundError thrown manually), rethrow it.
  if (error instanceof RepositoryError) {
    throw error;
  }
  // Log the raw error
  logger.error({ err: error, ...logContext }, logMessage);
  if (error instanceof Error && 'code' in error) {
    const code = (error as any).code;
    if (code === '23505') throw new UniqueConstraintError(options.uniqueMessage);
    if (code === '23503') throw new ForeignKeyConstraintError(options.fkMessage);
    if (code === '23502') throw new NotNullConstraintError(options.notNullMessage);
    if (code === '23514') throw new CheckConstraintError(options.checkMessage);
    if (code === '22P02') throw new InvalidTextRepresentationError(options.invalidTextMessage);
    if (code === '22003') throw new NumericValueOutOfRangeError(options.numericOutOfRangeMessage);
  }
  // Fallback generic error
  // Use the consistent DatabaseError from the processing errors module for the fallback.
  const errorMessage = options.defaultMessage || `Failed to perform operation on ${options.entityName || 'database'}.`;
  throw new ProcessingDatabaseError(errorMessage);
 }
--- a/src/services/db/flyer.db.test.ts
+++ b/src/services/db/flyer.db.test.ts
@@ -12,7 +12,12 @@ import {
 vi.unmock('./flyer.db');
 import { FlyerRepository, createFlyerAndItems } from './flyer.db';
-import { UniqueConstraintError, ForeignKeyConstraintError, NotFoundError } from './errors.db';
+import {
  UniqueConstraintError,
  ForeignKeyConstraintError,
  NotFoundError,
  CheckConstraintError,
 } from './errors.db';
 import type {
  FlyerInsert,
  FlyerItemInsert,
@@ -51,67 +56,72 @@ describe('Flyer DB Service', () => {
  describe('findOrCreateStore', () => {
    it('should find an existing store and return its ID', async () => {
-      mockPoolInstance.query.mockResolvedValue({ rows: [{ store_id: 1 }] });
+      // 1. INSERT...ON CONFLICT does nothing. 2. SELECT finds the store.
      mockPoolInstance.query
        .mockResolvedValueOnce({ rows: [], rowCount: 0 })
        .mockResolvedValueOnce({ rows: [{ store_id: 1 }] });
      const result = await flyerRepo.findOrCreateStore('Existing Store', mockLogger);
      expect(result).toBe(1);
      expect(mockPoolInstance.query).toHaveBeenCalledTimes(2);
      expect(mockPoolInstance.query).toHaveBeenCalledWith(
-        expect.stringContaining('SELECT store_id FROM public.stores WHERE name = $1'),
+        'INSERT INTO public.stores (name) VALUES ($1) ON CONFLICT (name) DO NOTHING',
        ['Existing Store'],
      );
      expect(mockPoolInstance.query).toHaveBeenCalledWith(
        'SELECT store_id FROM public.stores WHERE name = $1',
        ['Existing Store'],
      );
    });
-    it('should create a new store if it does not exist', async () => {
+    it('should create a new store if it does not exist and return its ID', async () => {
      // 1. INSERT...ON CONFLICT creates the store. 2. SELECT finds it.
      mockPoolInstance.query
-        .mockResolvedValueOnce({ rows: [] }) // First SELECT finds nothing
+        .mockResolvedValueOnce({ rows: [], rowCount: 1 }) // INSERT affects 1 row
-        .mockResolvedValueOnce({ rows: [{ store_id: 2 }] })
+        .mockResolvedValueOnce({ rows: [{ store_id: 2 }] }); // SELECT finds the new store
      const result = await flyerRepo.findOrCreateStore('New Store', mockLogger);
      expect(result).toBe(2);
      expect(mockPoolInstance.query).toHaveBeenCalledTimes(2);
      expect(mockPoolInstance.query).toHaveBeenCalledWith(
-        expect.stringContaining('INSERT INTO public.stores (name) VALUES ($1) RETURNING store_id'),
+        'INSERT INTO public.stores (name) VALUES ($1) ON CONFLICT (name) DO NOTHING',
        ['New Store'],
      );
      expect(mockPoolInstance.query).toHaveBeenCalledWith(
        'SELECT store_id FROM public.stores WHERE name = $1',
        ['New Store'],
      );
    });
-    it('should handle race condition where store is created between SELECT and INSERT', async () => {
+    it('should throw an error if the database query fails', async () => {
      const uniqueConstraintError = new Error('duplicate key value violates unique constraint');
      (uniqueConstraintError as Error & { code: string }).code = '23505';
      mockPoolInstance.query
        .mockResolvedValueOnce({ rows: [] }) // First SELECT finds nothing
        .mockRejectedValueOnce(uniqueConstraintError) // INSERT fails due to race condition
        .mockResolvedValueOnce({ rows: [{ store_id: 3 }] }); // Second SELECT finds the store
      const result = await flyerRepo.findOrCreateStore('Racy Store', mockLogger);
    expect(result).toBe(3);
      //expect(mockDb.query).toHaveBeenCalledTimes(3);
        });
     it('should throw an error if the database query fails', async () => {
      const dbError = new Error('DB Error');
      mockPoolInstance.query.mockRejectedValue(dbError);
      // The new implementation uses handleDbError, which will throw a generic Error with the default message.
      await expect(flyerRepo.findOrCreateStore('Any Store', mockLogger)).rejects.toThrow(
        'Failed to find or create store in database.',
      );
      // handleDbError also logs the error.
      expect(mockLogger.error).toHaveBeenCalledWith(
        { err: dbError, storeName: 'Any Store' },
        'Database error in findOrCreateStore',
      );
    });
-    it('should throw an error if race condition recovery fails', async () => {
+    it('should throw an error if store is not found after upsert (edge case)', async () => {
-      const uniqueConstraintError = new Error('duplicate key value violates unique constraint');
+      // This simulates a very unlikely scenario where the store is deleted between the
-      (uniqueConstraintError as Error & { code: string }).code = '23505';
+      // INSERT...ON CONFLICT and the subsequent SELECT.
      mockPoolInstance.query
-        .mockResolvedValueOnce({ rows: [] }) // First SELECT
+        .mockResolvedValueOnce({ rows: [], rowCount: 1 }) // INSERT succeeds
-        .mockRejectedValueOnce(uniqueConstraintError) // INSERT fails
+        .mockResolvedValueOnce({ rows: [] }); // SELECT finds nothing
        .mockRejectedValueOnce(new Error('Second select fails')); // Recovery SELECT fails
-      await expect(flyerRepo.findOrCreateStore('Racy Store', mockLogger)).rejects.toThrow(
+      await expect(flyerRepo.findOrCreateStore('Weird Store', mockLogger)).rejects.toThrow(
        'Failed to find or create store in database.',
      );
      expect(mockLogger.error).toHaveBeenCalledWith(
-        { err: expect.any(Error), storeName: 'Racy Store' },
+        {
          err: new Error('Failed to find store immediately after upsert operation.'),
          storeName: 'Weird Store',
        },
        'Database error in findOrCreateStore',
      );
    });
@@ -121,8 +131,8 @@ describe('Flyer DB Service', () => {
    it('should execute an INSERT query and return the new flyer', async () => {
      const flyerData: FlyerDbInsert = {
        file_name: 'test.jpg',
-        image_url: '/images/test.jpg',
+        image_url: 'http://localhost:3001/images/test.jpg',
-        icon_url: '/images/icons/test.jpg',
+        icon_url: 'http://localhost:3001/images/icons/test.jpg',
        checksum: 'checksum123',
        store_id: 1,
        valid_from: '2024-01-01',
@@ -130,7 +140,8 @@ describe('Flyer DB Service', () => {
        store_address: '123 Test St',
        status: 'processed',
        item_count: 10,
-        uploaded_by: 'user-1',
+        // Use a valid UUID format for the foreign key.
        uploaded_by: 'a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11',
      };
      const mockFlyer = createMockFlyer({ ...flyerData, flyer_id: 1 });
      mockPoolInstance.query.mockResolvedValue({ rows: [mockFlyer] });
@@ -143,8 +154,8 @@ describe('Flyer DB Service', () => {
        expect.stringContaining('INSERT INTO flyers'),
        [
          'test.jpg',
-          '/images/test.jpg',
+          'http://localhost:3001/images/test.jpg',
-          '/images/icons/test.jpg',
+          'http://localhost:3001/images/icons/test.jpg',
          'checksum123',
          1,
          '2024-01-01',
@@ -152,7 +163,7 @@ describe('Flyer DB Service', () => {
          '123 Test St',
          'processed',
          10,
-          'user-1',
+          'a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11',
        ],
      );
    });
@@ -188,6 +199,48 @@ describe('Flyer DB Service', () => {
        'Database error in insertFlyer',
      );
    });
    it('should throw CheckConstraintError for invalid checksum format', async () => {
      const flyerData: FlyerDbInsert = { checksum: 'short' } as FlyerDbInsert;
      const dbError = new Error('violates check constraint "flyers_checksum_check"');
      (dbError as Error & { code: string }).code = '23514'; // Check constraint violation
      mockPoolInstance.query.mockRejectedValue(dbError);
      await expect(flyerRepo.insertFlyer(flyerData, mockLogger)).rejects.toThrow(
        CheckConstraintError,
      );
      await expect(flyerRepo.insertFlyer(flyerData, mockLogger)).rejects.toThrow(
        'The provided checksum is invalid or does not meet format requirements (e.g., must be a 64-character SHA-256 hash).',
      );
    });
    it('should throw CheckConstraintError for invalid status', async () => {
      const flyerData: FlyerDbInsert = { status: 'invalid_status' } as any;
      const dbError = new Error('violates check constraint "flyers_status_check"');
      (dbError as Error & { code: string }).code = '23514';
      mockPoolInstance.query.mockRejectedValue(dbError);
      await expect(flyerRepo.insertFlyer(flyerData, mockLogger)).rejects.toThrow(
        CheckConstraintError,
      );
      await expect(flyerRepo.insertFlyer(flyerData, mockLogger)).rejects.toThrow(
        'Invalid status provided for flyer.',
      );
    });
    it('should throw CheckConstraintError for invalid URL format', async () => {
      const flyerData: FlyerDbInsert = { image_url: 'not-a-url' } as FlyerDbInsert;
      const dbError = new Error('violates check constraint "url_check"');
      (dbError as Error & { code: string }).code = '23514';
      mockPoolInstance.query.mockRejectedValue(dbError);
      await expect(flyerRepo.insertFlyer(flyerData, mockLogger)).rejects.toThrow(
        CheckConstraintError,
      );
      await expect(flyerRepo.insertFlyer(flyerData, mockLogger)).rejects.toThrow(
        'Invalid URL format provided for image or icon.',
      );
    });
  });
  describe('insertFlyerItems', () => {
@@ -274,7 +327,7 @@ describe('Flyer DB Service', () => {
        ForeignKeyConstraintError,
      );
      await expect(flyerRepo.insertFlyerItems(999, itemsData, mockLogger)).rejects.toThrow(
-        'The specified flyer does not exist.',
+        'The specified flyer, category, master item, or product does not exist.',
      );
      expect(mockLogger.error).toHaveBeenCalledWith(
        { err: dbError, flyerId: 999 },
@@ -285,10 +338,10 @@ describe('Flyer DB Service', () => {
    it('should throw a generic error if the database query fails', async () => {
      const dbError = new Error('DB Connection Error');
      mockPoolInstance.query.mockRejectedValue(dbError);
-      // The implementation now re-throws the original error, so we should expect that.
+      // The implementation wraps the error using handleDbError
      await expect(
        flyerRepo.insertFlyerItems(1, [{ item: 'Test' } as FlyerItemInsert], mockLogger),
-      ).rejects.toThrow(dbError);
+      ).rejects.toThrow('An unknown error occurred while inserting flyer items.');
      expect(mockLogger.error).toHaveBeenCalledWith(
        { err: dbError, flyerId: 1 },
        'Database error in insertFlyerItems',
@@ -297,8 +350,8 @@ describe('Flyer DB Service', () => {
  });
  describe('createFlyerAndItems', () => {
-    it('should use withTransaction to create a flyer and items', async () => {
+    it('should execute find/create store, insert flyer, and insert items using the provided client', async () => {
-      const flyerData: FlyerInsert = {
+      const flyerData: FlyerInsert = { // This was a duplicate, fixed.
        file_name: 'transact.jpg',
        store_name: 'Transaction Store',
      } as FlyerInsert;
@@ -321,81 +374,72 @@ describe('Flyer DB Service', () => {
        }),
      ];
-      // Mock the withTransaction to execute the callback with a mock client
+      // Mock the sequence of 4 calls on the client
-      vi.mocked(withTransaction).mockImplementation(async (callback) => {
+      const mockClient = { query: vi.fn() };
-        const mockClient = { query: vi.fn() };
+      mockClient.query
-        // Mock the sequence of calls within the transaction
+        // 1. findOrCreateStore: INSERT ... ON CONFLICT
-        mockClient.query
+        .mockResolvedValueOnce({ rows: [], rowCount: 0 })
-          .mockResolvedValueOnce({ rows: [{ store_id: 1 }] }) // findOrCreateStore
+        // 2. findOrCreateStore: SELECT store_id
-          .mockResolvedValueOnce({ rows: [mockFlyer] }) // insertFlyer
+        .mockResolvedValueOnce({ rows: [{ store_id: 1 }] })
-          .mockResolvedValueOnce({ rows: mockItems }); // insertFlyerItems
+        // 3. insertFlyer
-        return callback(mockClient as unknown as PoolClient);
+        .mockResolvedValueOnce({ rows: [mockFlyer] })
-      });
+        // 4. insertFlyerItems
        .mockResolvedValueOnce({ rows: mockItems });
-      const result = await createFlyerAndItems(flyerData, itemsData, mockLogger);
+      const result = await createFlyerAndItems(
        flyerData,
        itemsData,
        mockLogger,
        mockClient as unknown as PoolClient,
      );
      expect(result).toEqual({
        flyer: mockFlyer,
        items: mockItems,
      });
      expect(withTransaction).toHaveBeenCalledTimes(1);
      // Verify the individual functions were called with the client
-      const callback = (vi.mocked(withTransaction) as Mock).mock.calls[0][0];
+      // findOrCreateStore assertions
      const mockClient = { query: vi.fn() };
      mockClient.query
        .mockResolvedValueOnce({ rows: [{ store_id: 1 }] })
        .mockResolvedValueOnce({ rows: [mockFlyer] })
        .mockResolvedValueOnce({ rows: mockItems });
      await callback(mockClient as unknown as PoolClient);
      expect(mockClient.query).toHaveBeenCalledWith(
-        expect.stringContaining('SELECT store_id FROM public.stores'),
+        'INSERT INTO public.stores (name) VALUES ($1) ON CONFLICT (name) DO NOTHING',
        ['Transaction Store'],
      );
      expect(mockClient.query).toHaveBeenCalledWith(
        'SELECT store_id FROM public.stores WHERE name = $1',
        ['Transaction Store'],
      );
      // insertFlyer assertion
      expect(mockClient.query).toHaveBeenCalledWith(
        expect.stringContaining('INSERT INTO flyers'),
        expect.any(Array),
      );
      // insertFlyerItems assertion
      expect(mockClient.query).toHaveBeenCalledWith(
        expect.stringContaining('INSERT INTO flyer_items'),
        expect.any(Array),
      );
    });
-    it('should ROLLBACK the transaction if an error occurs', async () => {
+    it('should propagate an error if any step fails', async () => {
      const flyerData: FlyerInsert = {
        file_name: 'fail.jpg',
        store_name: 'Fail Store',
      } as FlyerInsert;
      const itemsData: FlyerItemInsert[] = [{ item: 'Failing Item' } as FlyerItemInsert];
-      const dbError = new Error('DB connection lost');
+      const dbError = new Error('Underlying DB call failed');
-      // Mock withTransaction to simulate a failure during the callback
+      // Mock the client to fail on the insertFlyer step
-      vi.mocked(withTransaction).mockImplementation(async (callback) => {
+      const mockClient = { query: vi.fn() };
-        const mockClient = { query: vi.fn() };
+      mockClient.query
-        mockClient.query
+        .mockResolvedValueOnce({ rows: [], rowCount: 0 })
-          .mockResolvedValueOnce({ rows: [{ store_id: 1 }] }) // findOrCreateStore
+        .mockResolvedValueOnce({ rows: [{ store_id: 1 }] })
-          .mockRejectedValueOnce(dbError); // insertFlyer fails
+        .mockRejectedValueOnce(dbError); // insertFlyer fails
        // The withTransaction helper will catch this and roll back.
        // Since insertFlyer wraps the DB error, we expect the wrapped error message here.
        await expect(callback(mockClient as unknown as PoolClient)).rejects.toThrow(
          'Failed to insert flyer into database.',
        );
        // re-throw because withTransaction re-throws (simulating the wrapped error propagating up)
        throw new Error('Failed to insert flyer into database.');
      });
-      // The transactional function re-throws the original error from the failed step.
+      // The calling service's withTransaction would catch this.
-      // Since insertFlyer wraps errors, we expect the wrapped error message.
+      // Here, we just expect it to be thrown.
-      await expect(createFlyerAndItems(flyerData, itemsData, mockLogger)).rejects.toThrow(
+      await expect(
-        'Failed to insert flyer into database.',
+        createFlyerAndItems(flyerData, itemsData, mockLogger, mockClient as unknown as PoolClient),
-      );
+      ).rejects.toThrow(dbError);
      // The error object passed to the logger will be the wrapped Error object, not the original dbError
      expect(mockLogger.error).toHaveBeenCalledWith(
        { err: expect.any(Error) },
        'Database transaction error in createFlyerAndItems',
      );
      expect(withTransaction).toHaveBeenCalledTimes(1);
    });
  });
@@ -691,11 +735,7 @@ describe('Flyer DB Service', () => {
      );
      await expect(flyerRepo.deleteFlyer(999, mockLogger)).rejects.toThrow(
-        'Failed to delete flyer.',
+        'Flyer with ID 999 not found.',
      );
      expect(mockLogger.error).toHaveBeenCalledWith(
        { err: expect.any(NotFoundError), flyerId: 999 },
        'Database transaction error in deleteFlyer',
      );
    });
--- a/src/services/db/flyer.db.ts
+++ b/src/services/db/flyer.db.ts
@@ -2,7 +2,7 @@
 import type { Pool, PoolClient } from 'pg';
 import { getPool, withTransaction } from './connection.db';
 import type { Logger } from 'pino';
-import { UniqueConstraintError, ForeignKeyConstraintError, NotFoundError } from './errors.db';
+import { UniqueConstraintError, NotFoundError, handleDbError } from './errors.db';
 import type {
  Flyer,
  FlyerItem,
@@ -28,46 +28,32 @@ export class FlyerRepository {
   * @returns A promise that resolves to the store's ID.
   */
  async findOrCreateStore(storeName: string, logger: Logger): Promise<number> {
    // Note: This method should be called within a transaction if the caller
    // needs to ensure atomicity with other operations.
    try {
-      // First, try to find the store.
+      // Atomically insert the store if it doesn't exist. This is safe from race conditions.
-      let result = await this.db.query<{ store_id: number }>(
+      await this.db.query(
        'INSERT INTO public.stores (name) VALUES ($1) ON CONFLICT (name) DO NOTHING',
        [storeName],
      );
      // Now, the store is guaranteed to exist, so we can safely select its ID.
      const result = await this.db.query<{ store_id: number }>(
        'SELECT store_id FROM public.stores WHERE name = $1',
        [storeName],
      );
-      if (result.rows.length > 0) {
+      // This case should be virtually impossible if the INSERT...ON CONFLICT logic is correct,
-        return result.rows[0].store_id;
+      // as it would mean the store was deleted between the two queries. We throw an error to be safe.
-      } else {
+      if (result.rows.length === 0) {
-        // If not found, create it.
+        throw new Error('Failed to find store immediately after upsert operation.');
        result = await this.db.query<{ store_id: number }>(
          'INSERT INTO public.stores (name) VALUES ($1) RETURNING store_id',
          [storeName],
        );
        return result.rows[0].store_id;
      }
      return result.rows[0].store_id;
    } catch (error) {
-      // Check for a unique constraint violation on name, which could happen in a race condition
+      // Use the centralized error handler for any unexpected database errors.
-      // if two processes try to create the same store at the same time.
+      handleDbError(error, logger, 'Database error in findOrCreateStore', { storeName }, {
-      if (error instanceof Error && 'code' in error && error.code === '23505') {
+        // Any error caught here is unexpected, so we use a generic message.
-        try {
+        defaultMessage: 'Failed to find or create store in database.',
-          logger.warn(
+      });
            { storeName },
            `Race condition avoided: Store was created by another process. Refetching.`,
          );
          const result = await this.db.query<{ store_id: number }>(
            'SELECT store_id FROM public.stores WHERE name = $1',
            [storeName],
          );
          if (result.rows.length > 0) return result.rows[0].store_id;
        } catch (recoveryError) {
          // If recovery fails, log a warning and fall through to the generic error handler
          logger.warn({ err: recoveryError, storeName }, 'Race condition recovery failed');
        }
      }
      logger.error({ err: error, storeName }, 'Database error in findOrCreateStore');
      throw new Error('Failed to find or create store in database.');
    }
  }
@@ -97,18 +83,35 @@ export class FlyerRepository {
        flyerData.store_address, // $8
        flyerData.status, // $9
        flyerData.item_count, // $10
-        flyerData.uploaded_by, // $11
+        flyerData.uploaded_by ?? null, // $11
      ];
      logger.debug(
        { query, values },
        '[DB insertFlyer] Executing insert with the following values.',
      );
      const result = await this.db.query<Flyer>(query, values);
      return result.rows[0];
    } catch (error) {
-      logger.error({ err: error, flyerData }, 'Database error in insertFlyer');
+      const errorMessage = error instanceof Error ? error.message : '';
-      // Check for a unique constraint violation on the 'checksum' column.
+      let checkMsg = 'A database check constraint failed.';
-      if (error instanceof Error && 'code' in error && error.code === '23505') {
+
-        throw new UniqueConstraintError('A flyer with this checksum already exists.');
+      if (errorMessage.includes('flyers_checksum_check')) {
        checkMsg =
          'The provided checksum is invalid or does not meet format requirements (e.g., must be a 64-character SHA-256 hash).';
      } else if (errorMessage.includes('flyers_status_check')) {
        checkMsg = 'Invalid status provided for flyer.';
      } else if (errorMessage.includes('url_check')) {
        checkMsg = 'Invalid URL format provided for image or icon.';
      }
-      throw new Error('Failed to insert flyer into database.');
+
      handleDbError(error, logger, 'Database error in insertFlyer', { flyerData }, {
        uniqueMessage: 'A flyer with this checksum already exists.',
        fkMessage: 'The specified user or store for this flyer does not exist.',
        checkMessage: checkMsg,
        defaultMessage: 'Failed to insert flyer into database.',
      });
    }
  }
@@ -156,19 +159,18 @@ export class FlyerRepository {
        RETURNING *;
      `;
      logger.debug(
        { query, values },
        '[DB insertFlyerItems] Executing bulk insert with the following values.',
      );
      const result = await this.db.query<FlyerItem>(query, values);
      return result.rows;
    } catch (error) {
-      logger.error({ err: error, flyerId }, 'Database error in insertFlyerItems');
+      handleDbError(error, logger, 'Database error in insertFlyerItems', { flyerId }, {
-      // Check for a foreign key violation, which would mean the flyerId is invalid.
+        fkMessage: 'The specified flyer, category, master item, or product does not exist.',
-      if (error instanceof Error && 'code' in error && error.code === '23503') {
+        defaultMessage: 'An unknown error occurred while inserting flyer items.',
-        throw new ForeignKeyConstraintError('The specified flyer does not exist.');
+      });
      }
      // Preserve the original error if it's not a foreign key violation,
      // allowing transactional functions to catch and identify the specific failure.
      // This is a higher-level fix for the test failure in `createFlyerAndItems`.
      if (error instanceof Error) throw error;
      throw new Error('An unknown error occurred while inserting flyer items.');
    }
  }
@@ -179,15 +181,16 @@ export class FlyerRepository {
  async getAllBrands(logger: Logger): Promise<Brand[]> {
    try {
      const query = `
-        SELECT s.store_id as brand_id, s.name, s.logo_url
+        SELECT s.store_id as brand_id, s.name, s.logo_url, s.created_at, s.updated_at
        FROM public.stores s
        ORDER BY s.name;
      `;
      const res = await this.db.query<Brand>(query);
      return res.rows;
    } catch (error) {
-      logger.error({ err: error }, 'Database error in getAllBrands');
+      handleDbError(error, logger, 'Database error in getAllBrands', {}, {
-      throw new Error('Failed to retrieve brands from database.');
+        defaultMessage: 'Failed to retrieve brands from database.',
      });
    }
  }
@@ -226,8 +229,9 @@ export class FlyerRepository {
      const res = await this.db.query<Flyer>(query, [limit, offset]);
      return res.rows;
    } catch (error) {
-      logger.error({ err: error, limit, offset }, 'Database error in getFlyers');
+      handleDbError(error, logger, 'Database error in getFlyers', { limit, offset }, {
-      throw new Error('Failed to retrieve flyers from database.');
+        defaultMessage: 'Failed to retrieve flyers from database.',
      });
    }
  }
@@ -244,8 +248,9 @@ export class FlyerRepository {
      );
      return res.rows;
    } catch (error) {
-      logger.error({ err: error, flyerId }, 'Database error in getFlyerItems');
+      handleDbError(error, logger, 'Database error in getFlyerItems', { flyerId }, {
-      throw new Error('Failed to retrieve flyer items from database.');
+        defaultMessage: 'Failed to retrieve flyer items from database.',
      });
    }
  }
@@ -262,8 +267,9 @@ export class FlyerRepository {
      );
      return res.rows;
    } catch (error) {
-      logger.error({ err: error, flyerIds }, 'Database error in getFlyerItemsForFlyers');
+      handleDbError(error, logger, 'Database error in getFlyerItemsForFlyers', { flyerIds }, {
-      throw new Error('Failed to retrieve flyer items in batch from database.');
+        defaultMessage: 'Failed to retrieve flyer items in batch from database.',
      });
    }
  }
@@ -283,8 +289,9 @@ export class FlyerRepository {
      );
      return parseInt(res.rows[0].count, 10);
    } catch (error) {
-      logger.error({ err: error, flyerIds }, 'Database error in countFlyerItemsForFlyers');
+      handleDbError(error, logger, 'Database error in countFlyerItemsForFlyers', { flyerIds }, {
-      throw new Error('Failed to count flyer items in batch from database.');
+        defaultMessage: 'Failed to count flyer items in batch from database.',
      });
    }
  }
@@ -300,8 +307,9 @@ export class FlyerRepository {
      ]);
      return res.rows[0];
    } catch (error) {
-      logger.error({ err: error, checksum }, 'Database error in findFlyerByChecksum');
+      handleDbError(error, logger, 'Database error in findFlyerByChecksum', { checksum }, {
-      throw new Error('Failed to find flyer by checksum in database.');
+        defaultMessage: 'Failed to find flyer by checksum in database.',
      });
    }
  }
@@ -353,8 +361,9 @@ export class FlyerRepository {
        logger.info(`Successfully deleted flyer with ID: ${flyerId}`);
      });
    } catch (error) {
-      logger.error({ err: error, flyerId }, 'Database transaction error in deleteFlyer');
+      handleDbError(error, logger, 'Database transaction error in deleteFlyer', { flyerId }, {
-      throw new Error('Failed to delete flyer.');
+        defaultMessage: 'Failed to delete flyer.',
      });
    }
  }
 }
@@ -370,27 +379,23 @@ export async function createFlyerAndItems(
  flyerData: FlyerInsert,
  itemsForDb: FlyerItemInsert[],
  logger: Logger,
  client: PoolClient,
 ) {
-  try {
+  // The calling service is now responsible for managing the transaction.
-    return await withTransaction(async (client) => {
+  // This function assumes it is being run within a transaction via the provided client.
-      const flyerRepo = new FlyerRepository(client);
+  const flyerRepo = new FlyerRepository(client);
-      // 1. Find or create the store to get the store_id
+  // 1. Find or create the store to get the store_id
-      const storeId = await flyerRepo.findOrCreateStore(flyerData.store_name, logger);
+  const storeId = await flyerRepo.findOrCreateStore(flyerData.store_name, logger);
-      // 2. Prepare the data for the flyer table, replacing store_name with store_id
+  // 2. Prepare the data for the flyer table, replacing store_name with store_id
-      const flyerDbData: FlyerDbInsert = { ...flyerData, store_id: storeId };
+  const flyerDbData: FlyerDbInsert = { ...flyerData, store_id: storeId };
-      // 3. Insert the flyer record
+  // 3. Insert the flyer record
-      const newFlyer = await flyerRepo.insertFlyer(flyerDbData, logger);
+  const newFlyer = await flyerRepo.insertFlyer(flyerDbData, logger);
-      // 4. Insert the associated flyer items
+  // 4. Insert the associated flyer items
-      const newItems = await flyerRepo.insertFlyerItems(newFlyer.flyer_id, itemsForDb, logger);
+  const newItems = await flyerRepo.insertFlyerItems(newFlyer.flyer_id, itemsForDb, logger);
-      return { flyer: newFlyer, items: newItems };
+  return { flyer: newFlyer, items: newItems };
    });
  } catch (error) {
    logger.error({ err: error }, 'Database transaction error in createFlyerAndItems');
    throw error; // Re-throw the error to be handled by the calling service.
  }
 }
--- a/src/services/db/gamification.db.ts
+++ b/src/services/db/gamification.db.ts
@@ -1,7 +1,7 @@
 // src/services/db/gamification.db.ts
 import type { Pool, PoolClient } from 'pg';
 import { getPool } from './connection.db';
-import { ForeignKeyConstraintError } from './errors.db';
+import { handleDbError } from './errors.db';
 import type { Logger } from 'pino';
 import { Achievement, UserAchievement, LeaderboardUser } from '../../types';
@@ -25,8 +25,9 @@ export class GamificationRepository {
      );
      return res.rows;
    } catch (error) {
-      logger.error({ err: error }, 'Database error in getAllAchievements');
+      handleDbError(error, logger, 'Database error in getAllAchievements', {}, {
-      throw new Error('Failed to retrieve achievements.');
+        defaultMessage: 'Failed to retrieve achievements.',
      });
    }
  }
@@ -49,7 +50,8 @@ export class GamificationRepository {
          a.name,
          a.description,
          a.icon,
-          a.points_value
+          a.points_value,
          a.created_at
        FROM public.user_achievements ua
        JOIN public.achievements a ON ua.achievement_id = a.achievement_id
        WHERE ua.user_id = $1
@@ -58,8 +60,9 @@ export class GamificationRepository {
      const res = await this.db.query<UserAchievement & Achievement>(query, [userId]);
      return res.rows;
    } catch (error) {
-      logger.error({ err: error, userId }, 'Database error in getUserAchievements');
+      handleDbError(error, logger, 'Database error in getUserAchievements', { userId }, {
-      throw new Error('Failed to retrieve user achievements.');
+        defaultMessage: 'Failed to retrieve user achievements.',
      });
    }
  }
@@ -75,12 +78,10 @@ export class GamificationRepository {
    try {
      await this.db.query('SELECT public.award_achievement($1, $2)', [userId, achievementName]); // This was a duplicate, fixed.
    } catch (error) {
-      logger.error({ err: error, userId, achievementName }, 'Database error in awardAchievement');
+      handleDbError(error, logger, 'Database error in awardAchievement', { userId, achievementName }, {
-      // Check for a foreign key violation, which would mean the user or achievement name is invalid.
+        fkMessage: 'The specified user or achievement does not exist.',
-      if (error instanceof Error && 'code' in error && error.code === '23503') {
+        defaultMessage: 'Failed to award achievement.',
-        throw new ForeignKeyConstraintError('The specified user or achievement does not exist.');
+      });
      }
      throw new Error('Failed to award achievement.');
    }
  }
@@ -105,8 +106,9 @@ export class GamificationRepository {
      const res = await this.db.query<LeaderboardUser>(query, [limit]);
      return res.rows;
    } catch (error) {
-      logger.error({ err: error, limit }, 'Database error in getLeaderboard');
+      handleDbError(error, logger, 'Database error in getLeaderboard', { limit }, {
-      throw new Error('Failed to retrieve leaderboard.');
+        defaultMessage: 'Failed to retrieve leaderboard.',
      });
    }
  }
 }
--- a/src/services/db/index.db.ts
+++ b/src/services/db/index.db.ts
@@ -10,6 +10,8 @@ import { NotificationRepository } from './notification.db';
 import { BudgetRepository } from './budget.db';
 import { GamificationRepository } from './gamification.db';
 import { AdminRepository } from './admin.db';
 import { reactionRepo } from './reaction.db';
 import { conversionRepo } from './conversion.db';
 const userRepo = new UserRepository();
 const flyerRepo = new FlyerRepository();
@@ -33,5 +35,7 @@ export {
  budgetRepo,
  gamificationRepo,
  adminRepo,
  reactionRepo,
  conversionRepo,
  withTransaction,
 };
--- a/src/services/db/notification.db.test.ts
+++ b/src/services/db/notification.db.test.ts
@@ -195,7 +195,7 @@ describe('Notification DB Service', () => {
        notificationRepo.createBulkNotifications(notificationsToCreate, mockLogger),
      ).rejects.toThrow(ForeignKeyConstraintError);
      expect(mockLogger.error).toHaveBeenCalledWith(
-        { err: dbError },
+        { err: dbError, notifications: notificationsToCreate },
        'Database error in createBulkNotifications',
      );
    });
@@ -208,7 +208,7 @@ describe('Notification DB Service', () => {
        notificationRepo.createBulkNotifications(notificationsToCreate, mockLogger),
      ).rejects.toThrow('Failed to create bulk notifications.');
      expect(mockLogger.error).toHaveBeenCalledWith(
-        { err: dbError },
+        { err: dbError, notifications: notificationsToCreate },
        'Database error in createBulkNotifications',
      );
    });
@@ -264,6 +264,16 @@ describe('Notification DB Service', () => {
    });
  });
  describe('markNotificationAsRead - Ownership Check', () => {
    it('should not mark a notification as read if the user does not own it', async () => {
      mockPoolInstance.query.mockResolvedValue({ rowCount: 0 });
      await expect(notificationRepo.markNotificationAsRead(1, 'wrong-user', mockLogger)).rejects.toThrow(
        'Notification not found or user does not have permission.',
      );
    });
  });
  describe('markAllNotificationsAsRead', () => {
    it('should execute an UPDATE query to mark all notifications as read for a user', async () => {
      mockPoolInstance.query.mockResolvedValue({ rowCount: 3 });
--- a/src/services/db/notification.db.ts
+++ b/src/services/db/notification.db.ts
@@ -1,7 +1,7 @@
 // src/services/db/notification.db.ts
 import type { Pool, PoolClient } from 'pg';
 import { getPool } from './connection.db';
-import { ForeignKeyConstraintError, NotFoundError } from './errors.db';
+import { NotFoundError, handleDbError } from './errors.db';
 import type { Logger } from 'pino';
 import type { Notification } from '../../types';
@@ -34,14 +34,10 @@ export class NotificationRepository {
      );
      return res.rows[0];
    } catch (error) {
-      logger.error(
+      handleDbError(error, logger, 'Database error in createNotification', { userId, content, linkUrl }, {
-        { err: error, userId, content, linkUrl },
+        fkMessage: 'The specified user does not exist.',
-        'Database error in createNotification',
+        defaultMessage: 'Failed to create notification.',
-      );
+      });
      if (error instanceof Error && 'code' in error && error.code === '23503') {
        throw new ForeignKeyConstraintError('The specified user does not exist.');
      }
      throw new Error('Failed to create notification.');
    }
  }
@@ -78,11 +74,10 @@ export class NotificationRepository {
      await this.db.query(query, [userIds, contents, linkUrls]);
    } catch (error) {
-      logger.error({ err: error }, 'Database error in createBulkNotifications');
+      handleDbError(error, logger, 'Database error in createBulkNotifications', { notifications }, {
-      if (error instanceof Error && 'code' in error && error.code === '23503') {
+        fkMessage: 'One or more of the specified users do not exist.',
-        throw new ForeignKeyConstraintError('One or more of the specified users do not exist.');
+        defaultMessage: 'Failed to create bulk notifications.',
-      }
+      });
      throw new Error('Failed to create bulk notifications.');
    }
  }
@@ -113,11 +108,13 @@ export class NotificationRepository {
      const res = await this.db.query<Notification>(query, params);
      return res.rows;
    } catch (error) {
-      logger.error(
+      handleDbError(
-        { err: error, userId, limit, offset, includeRead },
+        error,
        logger,
        'Database error in getNotificationsForUser',
        { userId, limit, offset, includeRead },
        { defaultMessage: 'Failed to retrieve notifications.' },
      );
      throw new Error('Failed to retrieve notifications.');
    }
  }
@@ -133,8 +130,9 @@ export class NotificationRepository {
        [userId],
      );
    } catch (error) {
-      logger.error({ err: error, userId }, 'Database error in markAllNotificationsAsRead');
+      handleDbError(error, logger, 'Database error in markAllNotificationsAsRead', { userId }, {
-      throw new Error('Failed to mark notifications as read.');
+        defaultMessage: 'Failed to mark notifications as read.',
      });
    }
  }
@@ -161,12 +159,13 @@ export class NotificationRepository {
      }
      return res.rows[0];
    } catch (error) {
-      if (error instanceof NotFoundError) throw error;
+      handleDbError(
-      logger.error(
+        error,
-        { err: error, notificationId, userId },
+        logger,
        'Database error in markNotificationAsRead',
        { notificationId, userId },
        { defaultMessage: 'Failed to mark notification as read.' },
      );
      throw new Error('Failed to mark notification as read.');
    }
  }
@@ -184,8 +183,9 @@ export class NotificationRepository {
      );
      return res.rowCount ?? 0;
    } catch (error) {
-      logger.error({ err: error, daysOld }, 'Database error in deleteOldNotifications');
+      handleDbError(error, logger, 'Database error in deleteOldNotifications', { daysOld }, {
-      throw new Error('Failed to delete old notifications.');
+        defaultMessage: 'Failed to delete old notifications.',
      });
    }
  }
 }
--- a/src/services/db/personalization.db.test.ts
+++ b/src/services/db/personalization.db.test.ts
@@ -5,7 +5,7 @@ import type { Pool, PoolClient } from 'pg';
 import { withTransaction } from './connection.db';
 import { PersonalizationRepository } from './personalization.db';
 import type { MasterGroceryItem, UserAppliance, DietaryRestriction, Appliance } from '../../types';
-import { createMockMasterGroceryItem } from '../../tests/utils/mockFactories';
+import { createMockMasterGroceryItem, createMockUserAppliance } from '../../tests/utils/mockFactories';
 // Un-mock the module we are testing to ensure we use the real implementation.
 vi.unmock('./personalization.db');
@@ -46,9 +46,6 @@ describe('Personalization DB Service', () => {
  describe('getAllMasterItems', () => {
    it('should execute the correct query and return master items', async () => {
      console.log(
        '[TEST DEBUG] Running test: getAllMasterItems > should execute the correct query',
      );
      const mockItems: MasterGroceryItem[] = [
        createMockMasterGroceryItem({ master_grocery_item_id: 1, name: 'Apples' }),
      ];
@@ -64,8 +61,6 @@ describe('Personalization DB Service', () => {
        LEFT JOIN public.categories c ON mgi.category_id = c.category_id
        ORDER BY mgi.name ASC`;
      console.log('[TEST DEBUG] mockQuery calls:', JSON.stringify(mockQuery.mock.calls, null, 2));
      // The query string in the implementation has a lot of whitespace from the template literal.
      // This updated expectation matches the new query exactly.
      expect(mockQuery).toHaveBeenCalledWith(expectedQuery);
@@ -649,8 +644,8 @@ describe('Personalization DB Service', () => {
  describe('setUserAppliances', () => {
    it('should execute a transaction to set appliances', async () => {
      const mockNewAppliances: UserAppliance[] = [
-        { user_id: 'user-123', appliance_id: 1 },
+        createMockUserAppliance({ user_id: 'user-123', appliance_id: 1 }),
-        { user_id: 'user-123', appliance_id: 2 },
+        createMockUserAppliance({ user_id: 'user-123', appliance_id: 2 }),
      ];
      const mockClientQuery = vi.fn();
      vi.mocked(withTransaction).mockImplementation(async (callback) => {
--- a/src/services/db/personalization.db.ts
+++ b/src/services/db/personalization.db.ts
@@ -1,7 +1,7 @@
 // src/services/db/personalization.db.ts
 import type { Pool, PoolClient } from 'pg';
 import { getPool, withTransaction } from './connection.db';
-import { ForeignKeyConstraintError } from './errors.db';
+import { handleDbError } from './errors.db';
 import type { Logger } from 'pino';
 import {
  MasterGroceryItem,
@@ -40,8 +40,9 @@ export class PersonalizationRepository {
      const res = await this.db.query<MasterGroceryItem>(query);
      return res.rows;
    } catch (error) {
-      logger.error({ err: error }, 'Database error in getAllMasterItems');
+      handleDbError(error, logger, 'Database error in getAllMasterItems', {}, {
-      throw new Error('Failed to retrieve master grocery items.');
+        defaultMessage: 'Failed to retrieve master grocery items.',
      });
    }
  }
@@ -62,8 +63,9 @@ export class PersonalizationRepository {
      const res = await this.db.query<MasterGroceryItem>(query, [userId]);
      return res.rows;
    } catch (error) {
-      logger.error({ err: error, userId }, 'Database error in getWatchedItems');
+      handleDbError(error, logger, 'Database error in getWatchedItems', { userId }, {
-      throw new Error('Failed to retrieve watched items.');
+        defaultMessage: 'Failed to retrieve watched items.',
      });
    }
  }
@@ -79,8 +81,9 @@ export class PersonalizationRepository {
        [userId, masterItemId],
      );
    } catch (error) {
-      logger.error({ err: error, userId, masterItemId }, 'Database error in removeWatchedItem');
+      handleDbError(error, logger, 'Database error in removeWatchedItem', { userId, masterItemId }, {
-      throw new Error('Failed to remove item from watchlist.');
+        defaultMessage: 'Failed to remove item from watchlist.',
      });
    }
  }
@@ -100,8 +103,9 @@ export class PersonalizationRepository {
      );
      return res.rows[0];
    } catch (error) {
-      logger.error({ err: error, pantryItemId }, 'Database error in findPantryItemOwner');
+      handleDbError(error, logger, 'Database error in findPantryItemOwner', { pantryItemId }, {
-      throw new Error('Failed to retrieve pantry item owner from database.');
+        defaultMessage: 'Failed to retrieve pantry item owner from database.',
      });
    }
  }
@@ -156,18 +160,17 @@ export class PersonalizationRepository {
        return masterItem;
      });
    } catch (error) {
-      // The withTransaction helper will handle rollback. We just need to handle specific errors.
+      handleDbError(
-      if (error instanceof Error && 'code' in error) {
+        error,
-        if (error.code === '23503') {
+        logger,
          // foreign_key_violation
          throw new ForeignKeyConstraintError('The specified user or category does not exist.');
        }
      }
      logger.error(
        { err: error, userId, itemName, categoryName },
        'Transaction error in addWatchedItem',
        { userId, itemName, categoryName },
        {
          fkMessage: 'The specified user or category does not exist.',
          uniqueMessage: 'A master grocery item with this name was created by another process.',
          defaultMessage: 'Failed to add item to watchlist.',
        },
      );
      throw new Error('Failed to add item to watchlist.');
    }
  }
@@ -186,8 +189,9 @@ export class PersonalizationRepository {
      >('SELECT * FROM public.get_best_sale_prices_for_all_users()');
      return res.rows;
    } catch (error) {
-      logger.error({ err: error }, 'Database error in getBestSalePricesForAllUsers');
+      handleDbError(error, logger, 'Database error in getBestSalePricesForAllUsers', {}, {
-      throw new Error('Failed to get best sale prices for all users.');
+        defaultMessage: 'Failed to get best sale prices for all users.',
      });
    }
  }
@@ -200,8 +204,9 @@ export class PersonalizationRepository {
      const res = await this.db.query<Appliance>('SELECT * FROM public.appliances ORDER BY name');
      return res.rows;
    } catch (error) {
-      logger.error({ err: error }, 'Database error in getAppliances');
+      handleDbError(error, logger, 'Database error in getAppliances', {}, {
-      throw new Error('Failed to get appliances.');
+        defaultMessage: 'Failed to get appliances.',
      });
    }
  }
@@ -216,8 +221,9 @@ export class PersonalizationRepository {
      );
      return res.rows;
    } catch (error) {
-      logger.error({ err: error }, 'Database error in getDietaryRestrictions');
+      handleDbError(error, logger, 'Database error in getDietaryRestrictions', {}, {
-      throw new Error('Failed to get dietary restrictions.');
+        defaultMessage: 'Failed to get dietary restrictions.',
      });
    }
  }
@@ -236,8 +242,9 @@ export class PersonalizationRepository {
      const res = await this.db.query<DietaryRestriction>(query, [userId]);
      return res.rows;
    } catch (error) {
-      logger.error({ err: error, userId }, 'Database error in getUserDietaryRestrictions');
+      handleDbError(error, logger, 'Database error in getUserDietaryRestrictions', { userId }, {
-      throw new Error('Failed to get user dietary restrictions.');
+        defaultMessage: 'Failed to get user dietary restrictions.',
      });
    }
  }
@@ -266,17 +273,13 @@ export class PersonalizationRepository {
        }
      });
    } catch (error) {
-      // Check for a foreign key violation, which would mean an invalid ID was provided.
+      handleDbError(
-      if (error instanceof Error && 'code' in error && error.code === '23503') {
+        error,
-        throw new ForeignKeyConstraintError(
+        logger,
          'One or more of the specified restriction IDs are invalid.',
        );
      }
      logger.error(
        { err: error, userId, restrictionIds },
        'Database error in setUserDietaryRestrictions',
        { userId, restrictionIds },
        { fkMessage: 'One or more of the specified restriction IDs are invalid.', defaultMessage: 'Failed to set user dietary restrictions.' },
      );
      throw new Error('Failed to set user dietary restrictions.');
    }
  }
@@ -306,12 +309,10 @@ export class PersonalizationRepository {
        return newAppliances;
      });
    } catch (error) {
-      // Check for a foreign key violation, which would mean an invalid ID was provided.
+      handleDbError(error, logger, 'Database error in setUserAppliances', { userId, applianceIds }, {
-      if (error instanceof Error && 'code' in error && error.code === '23503') {
+        fkMessage: 'Invalid appliance ID',
-        throw new ForeignKeyConstraintError('Invalid appliance ID');
+        defaultMessage: 'Failed to set user appliances.',
-      }
+      });
      logger.error({ err: error, userId, applianceIds }, 'Database error in setUserAppliances');
      throw new Error('Failed to set user appliances.');
    }
  }
@@ -330,8 +331,9 @@ export class PersonalizationRepository {
      const res = await this.db.query<Appliance>(query, [userId]);
      return res.rows;
    } catch (error) {
-      logger.error({ err: error, userId }, 'Database error in getUserAppliances');
+      handleDbError(error, logger, 'Database error in getUserAppliances', { userId }, {
-      throw new Error('Failed to get user appliances.');
+        defaultMessage: 'Failed to get user appliances.',
      });
    }
  }
@@ -348,8 +350,9 @@ export class PersonalizationRepository {
      );
      return res.rows;
    } catch (error) {
-      logger.error({ err: error, userId }, 'Database error in findRecipesFromPantry');
+      handleDbError(error, logger, 'Database error in findRecipesFromPantry', { userId }, {
-      throw new Error('Failed to find recipes from pantry.');
+        defaultMessage: 'Failed to find recipes from pantry.',
      });
    }
  }
@@ -371,8 +374,9 @@ export class PersonalizationRepository {
      );
      return res.rows;
    } catch (error) {
-      logger.error({ err: error, userId, limit }, 'Database error in recommendRecipesForUser');
+      handleDbError(error, logger, 'Database error in recommendRecipesForUser', { userId, limit }, {
-      throw new Error('Failed to recommend recipes.');
+        defaultMessage: 'Failed to recommend recipes.',
      });
    }
  }
@@ -389,8 +393,9 @@ export class PersonalizationRepository {
      );
      return res.rows;
    } catch (error) {
-      logger.error({ err: error, userId }, 'Database error in getBestSalePricesForUser');
+      handleDbError(error, logger, 'Database error in getBestSalePricesForUser', { userId }, {
-      throw new Error('Failed to get best sale prices.');
+        defaultMessage: 'Failed to get best sale prices.',
      });
    }
  }
@@ -410,8 +415,9 @@ export class PersonalizationRepository {
      );
      return res.rows;
    } catch (error) {
-      logger.error({ err: error, pantryItemId }, 'Database error in suggestPantryItemConversions');
+      handleDbError(error, logger, 'Database error in suggestPantryItemConversions', { pantryItemId }, {
-      throw new Error('Failed to suggest pantry item conversions.');
+        defaultMessage: 'Failed to suggest pantry item conversions.',
      });
    }
  }
@@ -428,8 +434,9 @@ export class PersonalizationRepository {
      ); // This is a standalone function, no change needed here.
      return res.rows;
    } catch (error) {
-      logger.error({ err: error, userId }, 'Database error in getRecipesForUserDiets');
+      handleDbError(error, logger, 'Database error in getRecipesForUserDiets', { userId }, {
-      throw new Error('Failed to get recipes compatible with user diet.');
+        defaultMessage: 'Failed to get recipes compatible with user diet.',
      });
    }
  }
 }
--- a/src/services/db/price.db.ts
+++ b/src/services/db/price.db.ts
@@ -2,6 +2,7 @@
 import type { Logger } from 'pino';
 import type { PriceHistoryData } from '../../types';
 import { getPool } from './connection.db';
 import { handleDbError } from './errors.db';
 /**
 * Repository for fetching price-related data.
@@ -51,11 +52,13 @@ export const priceRepo = {
      );
      return result.rows;
    } catch (error) {
-      logger.error(
+      handleDbError(
-        { err: error, masterItemIds, limit, offset },
+        error,
        logger,
        'Database error in getPriceHistory',
        { masterItemIds, limit, offset },
        { defaultMessage: 'Failed to retrieve price history.' },
      );
      throw new Error('Failed to retrieve price history.');
    }
  },
 };
--- a/src/services/db/reaction.db.test.ts
+++ b/src/services/db/reaction.db.test.ts
@@ -0,0 +1,225 @@
 // src/services/db/reaction.db.test.ts
 import { describe, it, expect, vi, beforeEach, Mock } from 'vitest';
 import type { Pool, PoolClient } from 'pg';
 import { ReactionRepository } from './reaction.db';
 import { mockPoolInstance } from '../../tests/setup/tests-setup-unit';
 import { withTransaction } from './connection.db';
 import { ForeignKeyConstraintError } from './errors.db';
 import type { UserReaction } from '../../types';
 // Un-mock the module we are testing
 vi.unmock('./reaction.db');
 // Mock dependencies
 vi.mock('../logger.server', () => ({
  logger: {
    info: vi.fn(),
    warn: vi.fn(),
    error: vi.fn(),
    debug: vi.fn(),
  },
 }));
 import { logger as mockLogger } from '../logger.server';
 vi.mock('./connection.db', async (importOriginal) => {
  const actual = await importOriginal<typeof import('./connection.db')>();
  return { ...actual, withTransaction: vi.fn() };
 });
 describe('Reaction DB Service', () => {
  let reactionRepo: ReactionRepository;
  const mockDb = {
    query: vi.fn(),
  };
  beforeEach(() => {
    vi.clearAllMocks();
    reactionRepo = new ReactionRepository(mockDb);
  });
  describe('getReactions', () => {
    it('should build a query with no filters', async () => {
      mockDb.query.mockResolvedValue({ rows: [] });
      await reactionRepo.getReactions({}, mockLogger);
      expect(mockDb.query).toHaveBeenCalledWith(
        'SELECT * FROM public.user_reactions WHERE 1=1 ORDER BY created_at DESC',
        [],
      );
    });
    it('should build a query with a userId filter', async () => {
      mockDb.query.mockResolvedValue({ rows: [] });
      await reactionRepo.getReactions({ userId: 'user-1' }, mockLogger);
      expect(mockDb.query).toHaveBeenCalledWith(
        'SELECT * FROM public.user_reactions WHERE 1=1 AND user_id = $1 ORDER BY created_at DESC',
        ['user-1'],
      );
    });
    it('should build a query with all filters', async () => {
      mockDb.query.mockResolvedValue({ rows: [] });
      await reactionRepo.getReactions(
        { userId: 'user-1', entityType: 'recipe', entityId: '123' },
        mockLogger,
      );
      expect(mockDb.query).toHaveBeenCalledWith(
        'SELECT * FROM public.user_reactions WHERE 1=1 AND user_id = $1 AND entity_type = $2 AND entity_id = $3 ORDER BY created_at DESC',
        ['user-1', 'recipe', '123'],
      );
    });
    it('should return an array of reactions on success', async () => {
      const mockReactions: UserReaction[] = [
        {
          reaction_id: 1,
          user_id: 'user-1',
          entity_type: 'recipe',
          entity_id: '123',
          reaction_type: 'like',
          created_at: new Date().toISOString(),
          updated_at: new Date().toISOString(),
        },
      ];
      mockDb.query.mockResolvedValue({ rows: mockReactions });
      const result = await reactionRepo.getReactions({}, mockLogger);
      expect(result).toEqual(mockReactions);
    });
    it('should throw an error if the database query fails', async () => {
      const dbError = new Error('DB Error');
      mockDb.query.mockRejectedValue(dbError);
      await expect(reactionRepo.getReactions({}, mockLogger)).rejects.toThrow(
        'Failed to retrieve user reactions.',
      );
      expect(mockLogger.error).toHaveBeenCalledWith(
        { err: dbError, filters: {} },
        'Database error in getReactions',
      );
    });
  });
  describe('toggleReaction', () => {
    const reactionData = {
      user_id: 'user-1',
      entity_type: 'recipe',
      entity_id: '123',
      reaction_type: 'like',
    };
    it('should remove an existing reaction and return null', async () => {
      const mockClient = { query: vi.fn() };
      // Mock DELETE returning 1 row, indicating a reaction was deleted
      (mockClient.query as Mock).mockResolvedValueOnce({ rowCount: 1 });
      vi.mocked(withTransaction).mockImplementation(async (callback) => {
        return callback(mockClient as unknown as PoolClient);
      });
      const result = await reactionRepo.toggleReaction(reactionData, mockLogger);
      expect(result).toBeNull();
      expect(mockClient.query).toHaveBeenCalledWith(
        'DELETE FROM public.user_reactions WHERE user_id = $1 AND entity_type = $2 AND entity_id = $3 AND reaction_type = $4',
        ['user-1', 'recipe', '123', 'like'],
      );
      // Ensure INSERT was not called
      expect(mockClient.query).toHaveBeenCalledTimes(1);
    });
    it('should add a new reaction and return it if it does not exist', async () => {
      const mockClient = { query: vi.fn() };
      const mockCreatedReaction: UserReaction = {
        reaction_id: 1,
        ...reactionData,
        created_at: new Date().toISOString(),
        updated_at: new Date().toISOString(),
      };
      // Mock DELETE returning 0 rows, then mock INSERT returning the new reaction
      (mockClient.query as Mock)
        .mockResolvedValueOnce({ rowCount: 0 }) // DELETE
        .mockResolvedValueOnce({ rows: [mockCreatedReaction] }); // INSERT
      vi.mocked(withTransaction).mockImplementation(async (callback) => {
        return callback(mockClient as unknown as PoolClient);
      });
      const result = await reactionRepo.toggleReaction(reactionData, mockLogger);
      expect(result).toEqual(mockCreatedReaction);
      expect(mockClient.query).toHaveBeenCalledTimes(2);
      expect(mockClient.query).toHaveBeenCalledWith(
        'INSERT INTO public.user_reactions (user_id, entity_type, entity_id, reaction_type) VALUES ($1, $2, $3, $4) RETURNING *',
        ['user-1', 'recipe', '123', 'like'],
      );
    });
    it('should throw ForeignKeyConstraintError if user or entity does not exist', async () => {
      const dbError = new Error('violates foreign key constraint');
      (dbError as Error & { code: string }).code = '23503';
      vi.mocked(withTransaction).mockImplementation(async (callback) => {
        const mockClient = { query: vi.fn().mockRejectedValue(dbError) };
        await expect(callback(mockClient as unknown as PoolClient)).rejects.toThrow(dbError);
        throw dbError;
      });
      await expect(reactionRepo.toggleReaction(reactionData, mockLogger)).rejects.toThrow(
        ForeignKeyConstraintError,
      );
      await expect(reactionRepo.toggleReaction(reactionData, mockLogger)).rejects.toThrow(
        'The specified user or entity does not exist.',
      );
    });
    it('should throw a generic error if the transaction fails', async () => {
      const dbError = new Error('Transaction failed');
      vi.mocked(withTransaction).mockRejectedValue(dbError);
      await expect(reactionRepo.toggleReaction(reactionData, mockLogger)).rejects.toThrow(
        'Failed to toggle user reaction.',
      );
      expect(mockLogger.error).toHaveBeenCalledWith(
        { err: dbError, reactionData },
        'Database error in toggleReaction',
      );
    });
  });
  describe('getReactionSummary', () => {
    it('should return a summary of reactions for an entity', async () => {
      const mockSummary = [
        { reaction_type: 'like', count: 5 },
        { reaction_type: 'heart', count: 2 },
      ];
      // This method uses getPool() directly, so we mock the main instance
      mockPoolInstance.query.mockResolvedValue({ rows: mockSummary });
      const result = await reactionRepo.getReactionSummary('recipe', '123', mockLogger);
      expect(result).toEqual(mockSummary);
      expect(mockPoolInstance.query).toHaveBeenCalledWith(
        expect.stringContaining('GROUP BY reaction_type'),
        ['recipe', '123'],
      );
    });
    it('should return an empty array if there are no reactions', async () => {
      mockPoolInstance.query.mockResolvedValue({ rows: [] });
      const result = await reactionRepo.getReactionSummary('recipe', '456', mockLogger);
      expect(result).toEqual([]);
    });
    it('should throw an error if the database query fails', async () => {
      const dbError = new Error('DB Error');
      mockPoolInstance.query.mockRejectedValue(dbError);
      await expect(
        reactionRepo.getReactionSummary('recipe', '123', mockLogger),
      ).rejects.toThrow('Failed to retrieve reaction summary.');
      expect(mockLogger.error).toHaveBeenCalledWith(
        { err: dbError, entityType: 'recipe', entityId: '123' },
        'Database error in getReactionSummary',
      );
    });
  });
 });
--- a/src/services/db/reaction.db.ts
+++ b/src/services/db/reaction.db.ts
@@ -0,0 +1,131 @@
 // src/services/db/reaction.db.ts
 import type { Pool, PoolClient } from 'pg';
 import type { Logger } from 'pino';
 import { getPool, withTransaction } from './connection.db';
 import { handleDbError } from './errors.db';
 import type { UserReaction } from '../../types';
 export class ReactionRepository {
  private db: Pick<Pool | PoolClient, 'query'>;
  constructor(db: Pick<Pool | PoolClient, 'query'> = getPool()) {
    this.db = db;
  }
  /**
   * Fetches user reactions based on query filters.
   * Supports filtering by user_id, entity_type, and entity_id.
   */
  async getReactions(
    filters: {
      userId?: string;
      entityType?: string;
      entityId?: string;
    },
    logger: Logger,
  ): Promise<UserReaction[]> {
    const { userId, entityType, entityId } = filters;
    try {
      let query = 'SELECT * FROM public.user_reactions WHERE 1=1';
      const params: any[] = [];
      let paramCount = 1;
      if (userId) {
        query += ` AND user_id = $${paramCount++}`;
        params.push(userId);
      }
      if (entityType) {
        query += ` AND entity_type = $${paramCount++}`;
        params.push(entityType);
      }
      if (entityId) {
        query += ` AND entity_id = $${paramCount++}`;
        params.push(entityId);
      }
      query += ' ORDER BY created_at DESC';
      const result = await this.db.query<UserReaction>(query, params);
      return result.rows;
    } catch (error) {
      handleDbError(error, logger, 'Database error in getReactions', { filters }, {
        defaultMessage: 'Failed to retrieve user reactions.',
      });
    }
  }
  /**
   * Toggles a user's reaction to an entity.
   * If the reaction exists, it's deleted. If it doesn't, it's created.
   * @returns The created UserReaction if a reaction was added, or null if it was removed.
   */
  async toggleReaction(
    reactionData: Omit<UserReaction, 'reaction_id' | 'created_at' | 'updated_at'>,
    logger: Logger,
  ): Promise<UserReaction | null> {
    const { user_id, entity_type, entity_id, reaction_type } = reactionData;
    try {
      return await withTransaction(async (client) => {
        const deleteRes = await client.query(
          'DELETE FROM public.user_reactions WHERE user_id = $1 AND entity_type = $2 AND entity_id = $3 AND reaction_type = $4',
          [user_id, entity_type, entity_id, reaction_type],
        );
        if ((deleteRes.rowCount ?? 0) > 0) {
          logger.debug({ reactionData }, 'Reaction removed.');
          return null;
        }
        const insertRes = await client.query<UserReaction>(
          'INSERT INTO public.user_reactions (user_id, entity_type, entity_id, reaction_type) VALUES ($1, $2, $3, $4) RETURNING *',
          [user_id, entity_type, entity_id, reaction_type],
        );
        logger.debug({ reaction: insertRes.rows[0] }, 'Reaction added.');
        return insertRes.rows[0];
      });
    } catch (error) {
      handleDbError(error, logger, 'Database error in toggleReaction', { reactionData }, {
        fkMessage: 'The specified user or entity does not exist.',
        defaultMessage: 'Failed to toggle user reaction.',
      });
    }
  }
  /**
   * Gets a summary of reactions for a specific entity.
   * Counts the number of each reaction_type.
   * @param entityType The type of the entity (e.g., 'recipe').
   * @param entityId The ID of the entity.
   * @param logger The pino logger instance.
   * @returns A promise that resolves to an array of reaction summaries.
   */
  async getReactionSummary(
    entityType: string,
    entityId: string,
    logger: Logger,
  ): Promise<{ reaction_type: string; count: number }[]> {
    try {
      const query = `
        SELECT
          reaction_type,
          COUNT(*)::int as count
        FROM public.user_reactions
        WHERE entity_type = $1 AND entity_id = $2
        GROUP BY reaction_type
        ORDER BY count DESC;
      `;
      const result = await getPool().query<{ reaction_type: string; count: number }>(query, [entityType, entityId]);
      return result.rows;
    } catch (error) {
      handleDbError(error, logger, 'Database error in getReactionSummary', { entityType, entityId }, {
        defaultMessage: 'Failed to retrieve reaction summary.',
      });
    }
  }
 }
 export const reactionRepo = new ReactionRepository();
--- a/src/services/db/recipe.db.test.ts
+++ b/src/services/db/recipe.db.test.ts
@@ -268,6 +268,17 @@ describe('Recipe DB Service', () => {
      );
    });
  });
   describe('deleteRecipe - Ownership Check', () => {
    it('should not delete recipe if the user does not own it and is not an admin', async () => {
      mockQuery.mockResolvedValue({ rowCount: 0 });
      await expect(recipeRepo.deleteRecipe(1, 'wrong-user', false, mockLogger)).rejects.toThrow(
        'Recipe not found or user does not have permission to delete.',
      );
    });
  });
  describe('updateRecipe', () => {
    it('should execute an UPDATE query with the correct fields', async () => {
@@ -382,6 +393,7 @@ describe('Recipe DB Service', () => {
        content: 'Great!',
        status: 'visible',
        created_at: new Date().toISOString(),
        updated_at: new Date().toISOString(),
      };
      mockQuery.mockResolvedValue({ rows: [mockComment] });
@@ -441,10 +453,6 @@ describe('Recipe DB Service', () => {
      await expect(recipeRepo.forkRecipe('user-123', 1, mockLogger)).rejects.toThrow(
        'Recipe is not public and cannot be forked.',
      );
      expect(mockLogger.error).toHaveBeenCalledWith(
        { err: dbError, userId: 'user-123', originalRecipeId: 1 },
        'Database error in forkRecipe',
      );
    });
    it('should throw a generic error if the database query fails', async () => {
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Gitea Actions	6e1298b825	ci: Bump version to 0.9.18 [skip ci]	2026-01-04 15:22:37 +05:00
Torben Sorensen	fc8e43437a	test fixes Some checks failed Deploy to Test Environment / deploy-to-test (push) Failing after 56s Details	2026-01-04 02:21:08 -08:00
Gitea Actions	cb453aa949	ci: Bump version to 0.9.17 [skip ci]	2026-01-04 09:02:18 +05:00
Torben Sorensen	2651bd16ae	test fixes Some checks failed Deploy to Test Environment / deploy-to-test (push) Failing after 52s Details	2026-01-03 20:01:10 -08:00
Gitea Actions	91e0f0c46f	ci: Bump version to 0.9.16 [skip ci]	2026-01-04 05:05:33 +05:00
Torben Sorensen	e6986d512b	test fixes All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 30m38s Details	2026-01-03 16:04:04 -08:00
Gitea Actions	8f9c21675c	ci: Bump version to 0.9.15 [skip ci]	2026-01-04 03:58:29 +05:00
Torben Sorensen	7fb22cdd20	more test improvements All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 25m12s Details	2026-01-03 14:57:40 -08:00
Gitea Actions	780291303d	ci: Bump version to 0.9.14 [skip ci]	2026-01-04 02:48:56 +05:00
Torben Sorensen	4f607f7d2f	more test improvements All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 29m49s Details	2026-01-03 13:47:44 -08:00
Gitea Actions	208227b3ed	ci: Bump version to 0.9.13 [skip ci]	2026-01-04 01:35:36 +05:00
Torben Sorensen	bf1c7d4adf	more test improvements All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 23m41s Details	2026-01-03 12:35:05 -08:00
Gitea Actions	a7a30cf983	ci: Bump version to 0.9.12 [skip ci]	2026-01-04 01:01:26 +05:00
Torben Sorensen	0bc0676b33	more test improvements All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 12m39s Details	2026-01-03 12:00:20 -08:00
Gitea Actions	73484d3eb4	ci: Bump version to 0.9.11 [skip ci]	2026-01-03 23:52:31 +05:00
Torben Sorensen	b3253d5bbc	more test improvements All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 17m17s Details	2026-01-03 10:51:44 -08:00
Gitea Actions	54f3769e90	ci: Bump version to 0.9.10 [skip ci]	2026-01-03 13:34:20 +05:00
Torben Sorensen	bad6f74ee6	more test improvements All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 19m21s Details	2026-01-03 00:33:47 -08:00
Gitea Actions	bcf16168b6	ci: Bump version to 0.9.9 [skip ci]	2026-01-03 13:03:37 +05:00
Torben Sorensen	498fbd9e0e	more test improvements All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 21m5s Details	2026-01-03 00:02:09 -08:00
Gitea Actions	007ff8e538	ci: Bump version to 0.9.8 [skip ci]	2026-01-03 11:34:34 +05:00
Torben Sorensen	1fc70e3915	extend timers duration - prevent jobs from timing out after 30secs, increased to 4mins All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 22m56s Details	2026-01-02 22:33:51 -08:00
Gitea Actions	d891e47e02	ci: Bump version to 0.9.7 [skip ci]	2026-01-03 10:36:05 +05:00
Torben Sorensen	08c39afde4	more test improvements All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 25m33s Details	2026-01-02 21:33:31 -08:00
Gitea Actions	c579543b8a	ci: Bump version to 0.9.6 [skip ci]	2026-01-03 09:31:41 +05:00
Torben Sorensen	0d84137786	test fixes All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 23m17s Details	2026-01-02 20:31:08 -08:00
Gitea Actions	20ee30c4b4	ci: Bump version to 0.9.5 [skip ci]	2026-01-03 08:52:26 +05:00
Torben Sorensen	93612137e3	test fixes All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 25m23s Details	2026-01-02 19:51:10 -08:00
Gitea Actions	6e70f08e3c	ci: Bump version to 0.9.4 [skip ci]	2026-01-03 07:59:50 +05:00
Torben Sorensen	459f5f7976	sql fixes All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 21m36s Details	2026-01-02 18:59:16 -08:00
Gitea Actions	a2e6331ddd	ci: Bump version to 0.9.3 [skip ci]	2026-01-03 07:28:11 +05:00
Torben Sorensen	13cd30bec9	sql fixes All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 10m51s Details	2026-01-02 18:27:42 -08:00
Gitea Actions	baeb9488c6	ci: Bump version to 0.9.2 [skip ci]	2026-01-03 07:07:42 +05:00
Torben Sorensen	0cba0f987e	remove refresh_token as it really should not be stored Some checks failed Deploy to Test Environment / deploy-to-test (push) Failing after 1m57s Details	2026-01-02 18:07:08 -08:00
Gitea Actions	958a79997d	ci: Bump version to 0.9.1 [skip ci]	2026-01-03 07:01:27 +05:00
Torben Sorensen	8fb1c96f93	Merge branch 'main' of https://gitea.projectium.com/torbo/flyer-crawler.projectium.com Some checks failed Deploy to Test Environment / deploy-to-test (push) Failing after 46s Details	2026-01-02 17:56:18 -08:00
Torben Sorensen	6e6fe80c7f	sql fixes	2026-01-02 17:55:22 -08:00
Gitea Actions	d1554050bd	ci: Bump version to 0.9.0 for production release [skip ci]	2026-01-03 05:50:23 +05:00
Gitea Actions	b1fae270bb	ci: Bump version to 0.8.0 for production release [skip ci]	2026-01-03 05:48:40 +05:00
Gitea Actions	c852483e18	ci: Bump version to 0.7.29 [skip ci]	2026-01-03 02:43:54 +05:00
Torben Sorensen	2e01ad5bc9	more test fixin All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 13m50s Details	2026-01-02 13:43:20 -08:00
Gitea Actions	26763c7183	ci: Bump version to 0.7.28 [skip ci]	2026-01-03 02:04:26 +05:00
Torben Sorensen	f0c5c2c45b	more test fixin All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 12m40s Details	2026-01-02 13:03:25 -08:00
Gitea Actions	034bb60fd5	ci: Bump version to 0.7.27 [skip ci]	2026-01-03 01:31:54 +05:00
Torben Sorensen	d4b389cb79	more test fixin All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 16m39s Details	2026-01-02 12:31:19 -08:00
Gitea Actions	a71fb81468	ci: Bump version to 0.7.26 [skip ci]	2026-01-03 00:58:34 +05:00
Torben Sorensen	9bee0a013b	unit test auto-provider refactor All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 17m8s Details	2026-01-02 11:58:03 -08:00
Gitea Actions	8bcb4311b3	ci: Bump version to 0.7.25 [skip ci]	2026-01-03 00:34:45 +05:00
Torben Sorensen	9fd15f3a50	unit test auto-provider refactor All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 19m58s Details	2026-01-02 11:33:11 -08:00
Gitea Actions	e3c876c7be	ci: Bump version to 0.7.24 [skip ci]	2026-01-02 23:23:21 +05:00
Torben Sorensen	32dcf3b89e	unit test auto-provider refactor All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 21m2s Details	2026-01-02 10:22:27 -08:00
Torben Sorensen	7066b937f6	unit test auto-provider refactor	2026-01-02 10:17:01 -08:00
Gitea Actions	8553ea8811	ci: Bump version to 0.7.23 [skip ci]	2026-01-02 12:13:43 +05:00
Torben Sorensen	19885a50f7	unit test auto-provider refactor All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 13m30s Details	2026-01-01 23:12:32 -08:00
Gitea Actions	ce82034b9d	ci: Bump version to 0.7.22 [skip ci]	2026-01-02 07:30:53 +05:00
Torben Sorensen	4528da2934	integration test fixes + added new ai models and recipeSuggestion All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 13m36s Details	2026-01-01 18:30:03 -08:00
Gitea Actions	146d4c1351	ci: Bump version to 0.7.21 [skip ci]	2026-01-02 03:37:22 +05:00
Torben Sorensen	88625706f4	integration test fixes + added new ai models and recipeSuggestion All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 13m3s Details	2026-01-01 14:36:43 -08:00
Gitea Actions	e395faed30	ci: Bump version to 0.7.20 [skip ci]	2026-01-02 01:40:18 +05:00
Torben Sorensen	e8f8399896	integration test fixes All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 12m11s Details	2026-01-01 12:30:03 -08:00
Gitea Actions	ac0115af2b	ci: Bump version to 0.7.19 [skip ci]	2026-01-02 00:55:57 +05:00
Torben Sorensen	f24b15f19b	integration test fixes All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 14m22s Details	2026-01-01 11:55:26 -08:00
Gitea Actions	e64426bd84	ci: Bump version to 0.7.18 [skip ci]	2026-01-02 00:35:49 +05:00
Torben Sorensen	0ec4cd68d2	integration test fixes All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 17m25s Details	2026-01-01 11:35:23 -08:00
Gitea Actions	840516d2a3	ci: Bump version to 0.7.17 [skip ci]	2026-01-02 00:29:45 +05:00
Torben Sorensen	59355c3eef	integration test fixes Some checks failed Deploy to Test Environment / deploy-to-test (push) Failing after 39s Details	2026-01-01 11:29:10 -08:00
Torben Sorensen	d024935fe9	integration test fixes	2026-01-01 11:18:27 -08:00
Gitea Actions	5a5470634e	ci: Bump version to 0.7.16 [skip ci]	2026-01-01 23:07:19 +05:00
Torben Sorensen	392231ad63	more db All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 19m34s Details	2026-01-01 10:06:49 -08:00
Gitea Actions	4b1c896621	ci: Bump version to 0.7.15 [skip ci]	2026-01-01 22:33:18 +05:00
Torben Sorensen	720920a51c	more db All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 20m35s Details	2026-01-01 09:31:49 -08:00
Gitea Actions	460adb9506	ci: Bump version to 0.7.14 [skip ci]	2026-01-01 16:08:43 +05:00
Torben Sorensen	7aa1f756a9	more db All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 10m26s Details	2026-01-01 03:08:02 -08:00
Gitea Actions	c484a8ca9b	ci: Bump version to 0.7.13 [skip ci]	2026-01-01 15:58:33 +05:00
Torben Sorensen	28d2c9f4ec	more db Some checks failed Deploy to Test Environment / deploy-to-test (push) Has been cancelled Details	2026-01-01 02:58:02 -08:00
Gitea Actions	ee253e9449	ci: Bump version to 0.7.12 [skip ci]	2026-01-01 15:48:03 +05:00
Torben Sorensen	b6c15e53d0	more db All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 10m24s Details	2026-01-01 02:47:31 -08:00
Gitea Actions	722162c2c3	ci: Bump version to 0.7.11 [skip ci]	2026-01-01 15:35:25 +05:00
Torben Sorensen	02a76fe996	more db All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 10m20s Details	2026-01-01 02:35:00 -08:00
Gitea Actions	0ebb03a7ab	ci: Bump version to 0.7.10 [skip ci]	2026-01-01 15:30:43 +05:00
Torben Sorensen	748ac9e049	more db Some checks failed Deploy to Test Environment / deploy-to-test (push) Failing after 51s Details	2026-01-01 02:30:06 -08:00
Gitea Actions	495edd621c	ci: Bump version to 0.7.9 [skip ci]	2026-01-01 14:59:38 +05:00
Torben Sorensen	4ffca19db6	more db All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 10m28s Details	2026-01-01 01:58:18 -08:00
Gitea Actions	717427c5d7	ci: Bump version to 0.7.8 [skip ci]	2026-01-01 10:08:06 +05:00
Torben Sorensen	cc438a0e36	more db Some checks failed Deploy to Test Environment / deploy-to-test (push) Failing after 38s Details	2025-12-31 21:07:40 -08:00
Gitea Actions	a32a0b62fc	ci: Bump version to 0.7.7 [skip ci]	2026-01-01 09:44:49 +05:00
Torben Sorensen	342f72b713	more db Some checks failed Deploy to Test Environment / deploy-to-test (push) Failing after 45s Details	2025-12-31 20:44:00 -08:00
Gitea Actions	91254d18f3	ci: Bump version to 0.7.6 [skip ci]	2026-01-01 06:02:31 +05:00
Torben Sorensen	40580dbf15	database work ! Some checks failed Deploy to Test Environment / deploy-to-test (push) Failing after 41s Details	2025-12-31 17:01:35 -08:00
Torben Sorensen	7f1d74c047	flyer upload (anon) issues	2025-12-31 09:40:46 -08:00
Gitea Actions	ecec686347	ci: Bump version to 0.7.5 [skip ci]	2025-12-31 22:27:56 +05:00
Torben Sorensen	86de680080	flyer processing fixes All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 16m36s Details	2025-12-31 09:27:06 -08:00
Gitea Actions	0371947065	ci: Bump version to 0.7.4 [skip ci]	2025-12-31 22:03:02 +05:00
Torben Sorensen	296698758c	flyer upload (anon) issues All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 19m20s Details	2025-12-31 09:02:09 -08:00
Gitea Actions	18c1161587	ci: Bump version to 0.7.3 [skip ci]	2025-12-31 15:09:29 +05:00
Torben Sorensen	0010396780	flyer upload (anon) issues Some checks failed Deploy to Test Environment / deploy-to-test (push) Failing after 41s Details	2025-12-31 02:08:37 -08:00
Gitea Actions	d4557e13fb	ci: Bump version to 0.7.2 [skip ci]	2025-12-31 13:32:58 +05:00
Torben Sorensen	3e41130c69	again All checks were successful Deploy to Test Environment / deploy-to-test (push) Successful in 18m59s Details	2025-12-31 00:31:18 -08:00