Skip to content

[2026-01-21] Guest Mode: Frontend Implementation

Task Metadata

  • 📆 Date: 2026-01-21
  • 🚥 Status: Complete

Objective

Goal: Enable users to log meals and view their history immediately without creating an account (Guest Mode), and seamlessly sync that data when they eventually sign up.

  • Trigger: Phase 2 of the roadmap (Onboarding & First User Experience).
  • Constraints:
    • Must strictly follow the IMealService and ISettingsService interfaces.
    • Must use Dexie.js (IndexedDB) for persistence (per Decision 006).
    • Must not break existing authenticated functionality.

Technical Strategy

We will implement the Service Provider Pattern to switch between LocalMealService (Guest) and ApiMealService (Auth) based on the user's authentication state, as defined in Decision 006: Guest Mode Architecture.

  • Key Decisions:
    • Persistence: Install dexie for performant, indexed querying of local meals (solving the "4 AM Rule" range query problem efficiently).
    • Service Injection: Implement ServiceProvider (Context) to inject the correct service implementations.
    • ID Generation: Use crypto.randomUUID() (with fallback) for guest meal IDs.

Testing Strategy

  • Must Test:
  • LocalMealService methods (add, get, delete, update).
  • Service Provider switching logic.
  • Data persistence in IndexedDB.
  • Skip: Heavy UI testing (covered by existing visual tests), focusing on logic first.

Risk Analysis

  • Potential Regressions: If the service switch isn't clean, authenticated users might accidentally write to local storage or vice versa.
  • Security Implications: None (Local data is user-owned).
  • Files to Modify:
    • frontend/package.json (Added dexie, fake-indexeddb)
    • frontend/src/db/GuestDB.ts (New: Dexie Schema)
    • frontend/src/services/LocalMealService.ts (New)
    • frontend/src/services/LocalSettingsService.ts (New)
    • frontend/src/services/IMealService.ts (New Interface)
    • frontend/src/services/ISettingsService.ts (New Interface)
    • frontend/src/services/ApiMealService.ts (Refactored to Class)
    • frontend/src/providers/ServiceProvider.tsx (New)
    • frontend/src/hooks/useMeals.ts (Updated to use context)
    • frontend/src/hooks/useSettings.ts (Updated to use context)
    • frontend/src/pages/Dashboard.tsx (Removed apiClient prop)
    • frontend/src/pages/Tracker.tsx (Removed apiClient prop)
    • frontend/src/App.tsx (Wrapped Providers)
    • frontend/src/services/__tests__/LocalMealService.test.ts (New)
    • frontend/src/services/__tests__/ApiMealService.test.ts (Updated)
    • frontend/src/hooks/__tests__/useMeals.test.tsx (Updated)
    • frontend/src/hooks/__tests__/useSettings.test.tsx (Updated)

Critique & Gaps

  • Critique 1 (Compliance): Previous plan naively used localStorage. ADR 006 mandates Dexie.js for performance and query capability. This is critical for the getMeals date range filter.
  • Critique 2 (Service Separation): Splitting IMealService and ISettingsService is cleaner and follows the ADR.
  • Critique 3 (React Query Safety): The ServiceProvider must ensure that changing the service instance (on login) invalidates relevant React Query keys to prevent stale data.

Gap Analysis

  • Gap: crypto.randomUUID availability. Mitigation: Use a simple fallback if missing.

Execution Plan

Stop: User Approval Required

Do not proceed with execution until the user has explicitly approved the Approach and Execution Plan above.

  • Step 1: Install dexie.
  • Step 2: Define IMealService and ISettingsService interfaces.
  • Step 3: Implement GuestDB (Dexie) and Local Services (LocalMealService, LocalSettingsService).
  • Step 4: Implement ServiceProvider context.
  • Step 5: Update consumers (useMeals, useSettings) to use the provider.
  • Verify: Run full test suite.

Execution Notes

  • Refactoring: Converted ApiMealService from a static object to a Class to conform to IMealService. This required significant updates to tests.
  • Testing: Had to mock useServices hook instead of ApiMealService directly in consumer tests (useMeals, useSettings), which resulted in much cleaner, integration-style tests.
  • Validation: Added a dedicated unit test for LocalMealService using fake-indexeddb to verify the Dexie integration and Date Range filtering logic.
  • Cleanup: Removed apiClient prop drilling from Dashboard.tsx and Tracker.tsx.

User Approval & Key Learnings

Key Learnings

  • (List items here)

(User to confirm approval and add notes/learnings)

Context Memory (AI-Only)

Summary for Future Context

Implemented Guest Mode Frontend using Service Provider Pattern and Dexie.js.

  • Persistence: ChatKcalGuestDB (IndexedDB) stores meals and settings locally.
  • Abstractions: IMealService & ISettingsService define the contract.
  • Injection: ServiceProvider injects Local*Service (Guest) or Api*Service (Auth).
  • Refactor: ApiMealService is now a class. Dashboard no longer receives apiClient.
  • Testing: Added fake-indexeddb for verifying local storage logic.