mitlist/docs/mitlist_doc.md

Project Documentation: Shared Household Management PWA

Version: 1.1 (Tech Stack Update) Date: 2025-04-22

1. Project Overview

1.1. Concept: Develop a Progressive Web App (PWA) designed to streamline household coordination and shared responsibilities. The application enables users within defined groups (e.g., households, roommates, families) to collaboratively manage shopping lists, track and split expenses with historical accuracy, and manage recurring or one-off household chores.

1.2. Goals:

• Simplify the creation, management, and sharing of shopping lists.
• Provide an efficient way to add items via image capture and OCR (using Gemini 1.5 Flash).
• Enable transparent and traceable tracking and splitting of shared expenses related to shopping lists.
• Offer a clear system for managing and assigning recurring or single-instance household chores.
• Deliver a seamless, near-native user experience across devices through PWA technologies, including robust offline capabilities.
• Foster better communication and coordination within shared living environments.

1.3. Target Audience:

• Roommates sharing household expenses and chores.
• Families coordinating grocery shopping and household tasks.
• Couples managing shared finances and responsibilities.
• Groups organizing events or trips involving shared purchases.

2. Key Features (V1 Scope)

The Minimum Viable Product (V1) focuses on delivering the core functionalities with a high degree of polish and reliability:

• User Authentication & Group Management (using fastapi-users):
  • Secure email/password signup, login, password reset, email verification (leveraging fastapi-users features).
  • Ability to create user groups (e.g., "Home", "Trip").
  • Invite members to groups via unique, shareable codes/links.
  • Basic role distinction (Owner, Member) for group administration.
  • Ability for users to view groups and leave groups.
• Shared Shopping List Management:
  • CRUD operations for shopping lists (Create, Read, Update, Delete).
  • Option to create personal lists or share lists with specific groups.
  • Real-time (or near real-time via polling/basic WebSocket) updates for shared lists.
  • CRUD operations for items within lists (name, quantity, notes).
  • Ability to mark items as purchased.
  • Attribution for who added/completed items in shared lists.
• OCR Integration (Gemini 1.5 Flash):
  • Capture images (receipts, handwritten lists) via browser (input capture / getUserMedia).
  • Backend processing using Google AI API (Gemini 1.5 Flash model) with tailored prompts to extract item names.
  • User review and edit screen for confirming/correcting extracted items before adding them to the list.
  • Clear progress indicators and error handling.
• Cost Splitting (Traceable):
  • Ability to add prices to completed items on a list, recording who added the price and when.
  • Functionality to trigger an expense calculation for a list based on items with prices.
  • Creation of immutable ExpenseRecord entries detailing the total amount, participants, and calculation time/user.
  • Generation of ExpenseShare entries detailing the amount owed per participant for each ExpenseRecord.
  • Ability for participants to mark their specific ExpenseShare as paid, logged via a SettlementActivity record for full traceability.
  • View displaying historical expense records and their settlement status for each list.
  • V1 focuses on equal splitting among all group members associated with the list at the time of calculation.
• Chore Management (Recurring & Assignable):
  • CRUD operations for chores within a group context.
  • Ability to define chores as one-time or recurring (daily, weekly, monthly, custom intervals).
  • System calculates next_due_date based on frequency.
  • Manual assignment of chores (specific instances/due dates) to group members via ChoreAssignments.
  • Ability for assigned users to mark their specific ChoreAssignment as complete.
  • Automatic update of the parent chore's last_completed_at and recalculation of next_due_date upon completion of recurring chores.
  • Dedicated view for users to see their pending assigned chores ("My Chores").
• PWA Core Functionality:
  • Installable on user devices via manifest.json.
  • Offline access to cached data (lists, items, chores, basic expense info) via Service Workers and IndexedDB.
  • Background synchronization queue for actions performed offline (adding items, marking complete, adding prices, completing chores).
  • Basic conflict resolution strategy (e.g., last-write-wins with user notification) for offline data sync.

3. User Experience (UX) Philosophy

• User-Centered & Collaborative: Focus on intuitive workflows for both individual task management and seamless group collaboration. Minimize friction in common tasks like adding items, splitting costs, and completing chores.
• Native-like PWA Experience: Leverage Service Workers, caching (IndexedDB), and manifest.json to provide fast loading, reliable offline functionality, and installability, mimicking a native app experience.
• Clarity & Accessibility: Prioritize clear information hierarchy, legible typography, sufficient contrast, and adherence to WCAG accessibility standards for usability by all users. Utilize Valerie UI components designed with accessibility in mind.
• Informative Feedback: Provide immediate visual feedback for user actions (loading states, confirmations, animations). Clearly communicate offline status, sync progress, OCR processing status, and data conflicts.

4. Architecture & Technology Stack

• Frontend:
  • Framework: Vue.js (Vue 3 with Composition API, built with Vite).
  • Styling & UI Components: Valerie UI (as the primary component library and design system).
  • State Management: Pinia (official state management library for Vue).
  • PWA: Vite PWA plugin (leveraging Workbox.js under the hood) for Service Worker generation, manifest management, and caching strategies. IndexedDB for offline data storage.
• Backend:
  • Framework: FastAPI (Python, high-performance, async support, automatic docs).
  • Database: PostgreSQL (reliable relational database with JSONB support).
  • ORM: SQLAlchemy (version 2.0+ with native async support).
  • Migrations: Alembic (for managing database schema changes).
  • Authentication & User Management: fastapi-users (handles user models, password hashing, JWT/cookie authentication, and core auth endpoints like signup, login, password reset, email verification).
• Cloud Services & APIs:
  • OCR: Google AI API (using gemini-1.5-flash-latest model).
  • Hosting (Backend): Containerized deployment (Docker) on cloud platforms like Google Cloud Run, AWS Fargate, or DigitalOcean App Platform.
  • Hosting (Frontend): Static hosting platforms like Vercel, Netlify, or Cloudflare Pages (optimized for Vite-built Vue apps).
• DevOps & Monitoring:
  • Version Control: Git (hosted on GitHub, GitLab, etc.).
  • Containerization: Docker & Docker Compose (for local development and deployment consistency).
  • CI/CD: GitHub Actions (or similar) for automated testing and deployment pipelines (using Vite build commands for frontend).
  • Error Tracking: Sentry (or similar) for real-time error monitoring.
  • Logging: Standard Python logging configured within FastAPI.

5. Data Model Highlights

Key database tables supporting the application's features:

• Users: Stores user account information. The schema will align with fastapi-users requirements (e.g., id, email, hashed_password, is_active, is_superuser, is_verified), with potential custom fields added as needed.
• Groups: Defines shared groups (name, owner).
• UserGroups: Many-to-many relationship linking users to groups with roles (owner/member).
• Lists: Stores shopping list details (name, description, creator, associated group, completion status).
• Items: Stores individual shopping list items (name, quantity, price, completion status, list association, user attribution for adding/pricing).
• ExpenseRecords: Logs each instance of a cost split calculation for a list (total amount, participants, calculation time/user, overall settlement status).
• ExpenseShares: Details the amount owed by each participant for a specific ExpenseRecord (links to user and record, amount, paid status).
• SettlementActivities: Records every action taken to mark an ExpenseShare as paid (links to record, payer, affected user, timestamp).
• Chores: Defines chore templates (name, description, group association, recurrence rules, next due date).
• ChoreAssignments: Tracks specific instances of chores assigned to users (links to chore, user, due date, completion status).

6. Core User Flows (Summarized)

• Onboarding: Signup/Login (via fastapi-users flow) -> Optional guided tour -> Create/Join first group -> Dashboard.
• List Creation & Sharing: Create List -> Choose Personal or Share with Group -> List appears on dashboard (and shared members' dashboards).
• Adding Items (Manual): Open List -> Type item name -> Item added.
• Adding Items (OCR): Open List -> Tap "Add via Photo" -> Capture/Select Image -> Upload/Process (Gemini) -> Review/Edit extracted items -> Confirm -> Items added to list.
• Shopping & Price Entry: Open List -> Check off items -> Enter price for completed items -> Price saved.
• Cost Splitting Cycle: View List -> Click "Calculate Split" -> Backend creates traceable ExpenseRecord & ExpenseShares -> View Expense History -> Participants mark their shares paid (creating SettlementActivity).
• Chore Cycle: Create Chore (define recurrence) -> Chore appears in group list -> (Manual Assignment) Assign chore instance to user -> User views "My Chores" -> User marks assignment complete -> Backend updates status and recalculates next due date for recurring chores.
• Offline Usage: Open app offline -> View cached lists/chores -> Add/complete items/chores -> Changes queued -> Go online -> Background sync processes queue -> UI updates, conflicts notified.

7. Development Roadmap (Phase Summary)

1. Phase 1: Planning & Design: User stories, flows, sharing/sync models, tech stack, architecture, schema design.
2. Phase 2: Core App Setup: Project initialization (Git, Vue.js with Vite, FastAPI), DB connection (SQLAlchemy/Alembic), basic PWA config (Vite PWA plugin, manifest, SW), Valerie UI integration, Pinia setup, Docker setup, CI checks.
3. Phase 3: User Auth & Group Management: Backend: Integrate fastapi-users, configure its routers, adapt user model. Frontend: Implement auth pages using Vue components, Pinia for auth state, and calling fastapi-users endpoints. Implement Group Management features.
4. Phase 4: Shared Shopping List CRUD: Backend/Frontend for List/Item CRUD, permissions, basic real-time updates (polling), offline sync refinement for lists/items.
5. Phase 5: OCR Integration (Gemini Flash): Backend integration with Google AI SDK, image capture/upload UI, OCR processing endpoint, review/edit screen, integration with list items.
6. Phase 6: Cost Splitting (Traceable): Backend/Frontend for adding prices, calculating splits (creating historical records), viewing expense history, marking shares paid (with activity logging).
7. Phase 7: Chore Splitting Module: Backend/Frontend for Chore CRUD (including recurrence), manual assignment, completion tracking, "My Chores" view, recurrence handling logic.
8. Phase 8: Testing, Refinement & Beta Launch: Comprehensive E2E testing, usability testing, accessibility checks, performance tuning, deployment to beta environment, feedback collection.
9. Phase 9: Final Release & Post-Launch Monitoring: Address beta feedback, final deployment to production, setup monitoring (errors, performance, costs).

(Estimated Total Duration: Approx. 17-19 Weeks for V1)

8. Risk Management & Mitigation

• Collaboration Complexity: (Risk) Permissions and real-time sync can be complex. (Mitigation) Start simple, test permissions thoroughly, use clear data models.
• OCR Accuracy/Cost (Gemini): (Risk) OCR isn't perfect; API calls have costs/quotas. (Mitigation) Use capable model (Gemini Flash), mandatory user review step, clear error feedback, monitor API usage/costs, secure API keys.
• Offline Sync Conflicts: (Risk) Concurrent offline edits can clash. (Mitigation) Implement defined strategy (last-write-wins + notify), robust queue processing, thorough testing of conflict scenarios.
• PWA Consistency: (Risk) Behavior varies across browsers/OS (esp. iOS). (Mitigation) Rigorous cross-platform testing, use standard tools (Vite PWA plugin/Workbox), follow best practices.
• Traceability Overhead: (Risk) Storing detailed history increases DB size/complexity. (Mitigation) Design efficient queries, use appropriate indexing, plan for potential data archiving later.
• User Adoption: (Risk) Users might not consistently use groups/features. (Mitigation) Smooth onboarding, clear value proposition, reliable core features.
• Valerie UI Maturity/Flexibility: (Risk, if "Valerie UI" is niche or custom) Potential limitations in component availability or customization. (Mitigation) Thoroughly evaluate Valerie UI early, have fallback styling strategies if needed, or contribute to/extend the library.

9. Testing Strategy

• Unit Tests: Backend logic (calculations, permissions, recurrence), Frontend component logic (Vue Test Utils for Vue components, Pinia store testing).
• Integration Tests: Backend API endpoints interacting with DB and external APIs (Gemini - mocked).
• End-to-End (E2E) Tests: (Playwright/Cypress) Simulate full user flows across features.
• PWA Testing: Manual and automated checks for installability, offline functionality (caching, sync queue), cross-browser/OS compatibility.
• Accessibility Testing: Automated tools (axe-core) + manual checks (keyboard nav, screen readers), leveraging Valerie UI's accessibility features.
• Usability Testing: Regular sessions with target users throughout development.
• Security Testing: Basic checks (OWASP Top 10 awareness), dependency scanning, secure handling of secrets/tokens (rely on fastapi-users security practices).
• Manual Testing: Exploratory testing, edge case validation, testing diverse OCR inputs.

10. Future Enhancements (Post-V1)

• Advanced Cost Splitting (by item, percentage, unequal splits).
• Payment Integration (Stripe Connect for settling debts).
• Real-time Collaboration (WebSockets for instant updates).
• Push Notifications (reminders for chores, expenses, list updates).
• Advanced Chore Features (assignment algorithms, calendar view).
• Enhanced OCR (handling more formats, potential fine-tuning).
• User Profile Customization (avatars, etc., extending fastapi-users model).
• Analytics Dashboard (spending insights, chore completion stats).
• Recipe Integration / Pantry Inventory Tracking.

11. Conclusion

This project aims to deliver a modern, user-friendly PWA that effectively addresses common household coordination challenges. By combining collaborative list management, intelligent OCR, traceable expense splitting, and flexible chore tracking with a robust offline-first PWA architecture built on Vue.js, Pinia, Valerie UI, and FastAPI with fastapi-users, the application will provide significant value to roommates, families, and other shared living groups. The focus on a well-defined V1, traceable data, and a solid technical foundation sets the stage for future growth and feature expansion.