Skip to content

[2026-01-17] Tech Design: Guest Mode Architecture

Task Metadata

  • 📆 Date: 2026-01-17
  • 🚥 Status: Complete
  • Beads Issue: 2512_genai_food_tracking-kzq

Objective

Goal: Design the technical architecture to support "Guest Mode" (offline/unauthenticated usage).

  • Trigger: UX requirement for "First Log Experience".
  • Outcome: Validated Architecture Proposal (ACP-001) and defined Implementation Tasks.

Technical Strategy

Define the "Guest Mode" architecture (Dexie.js + Repository Pattern) and "Sync Strategy" (Lambda Batching).

  • Key Decisions:
    • ACP-001: Guest Mode Architecture (The Spec).
    • ACP-002: Deep Research (The Rationale).

Testing Strategy

  • Review: Validate design against "Senior Critique" (Race conditions, Data integrity).

Architecture Smells (Addressed)

  • Naive Sync: Solved via Atomic Batch Write (Lambda).
  • Cache Poisoning: Solved via explicit resetQueries.
  • Service Swap Race: Solved by bypassing abstraction in usePromotion.

Risk Analysis

  • Complexity: High. Requires new Lambda, IndexedDB, and React Query management.
  • Files to Modify:
    • docs/architecture/proposals/...

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: Create Architecture Proposal (docs/architecture/proposals/001_guest_mode_architecture.md).
  • Step 2: Conduct Deep Research (docs/architecture/proposals/002_guest_mode_deep_research.md).
  • Step 3: Incorporate "Senior Critique" into Proposal (Address Race Conditions/Validation).
  • Step 4: Create Implementation Tasks in Beads (Split into Backend/Frontend/QA).
  • Step 5: Close Design Task.

Execution Notes

(AI to add details discovered during implementation)

  • Design Process: Extensive iterative discussion and "Senior Developer" critique significantly refined the architecture (ACP-002) before approval.
  • Side Quest: Pivot to awesome-pages plugin for MkDocs navigation.
    • Removed manual .pages configuration files.
    • Removed nav section from mkdocs.yml (if it existed, though it was clean).
    • Verified Taskfile.yml includes the plugin.
    • Result: docs/architecture/proposals/ and other new directories are now auto-discovered.

User Approval & Key Learnings

Key Learnings

  • Plan First: Using the "Senior Critique" persona effectively identified race conditions (Service Swap) that would have caused bugs in production.
  • Docs as Code: Migrating to awesome-pages simplified the doc maintenance workflow.

(User to confirm approval and add notes/learnings)

Context Memory (AI-Only)

Summary for Future Context

Designed Guest Mode Architecture (ACP-001/002).

  • Strategy: Dexie.js (Frontend) + Repository Pattern + Batch Lambda Sync (Backend).
  • Key Decisions:
    • Data Source: Local Authority (IndexedDB) for guests.
    • Sync: Idempotent importGuestHistory mutation via BatchWriteItem.
    • Conflict: Smart Merge (Trust Guest Recency).
  • Next: Implementation split into Backend (7sc), Frontend (48p), and QA (zdq).