mitlist/Untitled-1.md at d2d484c3272cba2eebf1e927324c3d99b29754f2

mo/mitlist

Fork 0

mohamad d2d484c327 001

2025-05-07 20:16:16 +02:00

10 KiB

Raw Blame History

Polished PWA Plan: Shared Lists & Household Management

1. Product Overview

Concept: Develop a Progressive Web App (PWA) focused on simplifying household coordination. Users can:

Create, manage, and share shopping lists within defined groups (e.g., households, trip members).
Capture images of receipts or shopping lists via the browser and extract items using Google Cloud Vision API for OCR.
Track item costs on shared lists and easily split expenses among group participants.
(Future) Manage and assign household chores.

Target Audience: Households, roommates, families, groups organizing shared purchases.

UX Philosophy:

User-Centered & Collaborative: Design intuitive flows for both individual use and group collaboration with minimal friction.
Native-like PWA Experience: Leverage service workers, caching, and manifest files for reliable offline use, installability, and smooth performance.
Clarity & Accessibility: Prioritize high contrast, legible typography, straightforward navigation, and adherence to accessibility standards (WCAG).
Informative Feedback: Provide clear visual feedback for actions (animations, loading states), OCR processing status, and data synchronization, including handling potential offline conflicts gracefully.

2. MVP Scope (Refined & Focused)

The MVP will focus on delivering a robust, shareable shopping list experience with integrated OCR and cost splitting, built as a high-quality PWA. Chore management is deferred post-MVP to ensure a polished core experience at launch.

Shared Shopping List Management:
- Core Features: Create, update, delete lists and items. Mark items as complete. Basic item sorting/reordering (e.g., manual drag-and-drop).
- Collaboration: Share lists within user-defined groups. Real-time (or near real-time) updates visible to group members (via polling or simple WebSocket for MVP).
- PWA/UX: Responsive design, offline access to cached lists, basic conflict indication if offline edits clash (e.g., "Item updated by another user, refresh needed").
OCR Integration (Google Cloud Vision):
- Core Features: Capture images via browser (<input type="file" capture> or getUserMedia). Upload images to the FastAPI backend. Backend securely calls Google Cloud Vision API (Text Detection / Document Text Detection). Process results, suggest items to add to the list.
- PWA/UX: Clear instructions for image capture. Progress indicators during upload/processing. Display editable OCR results for user review and confirmation before adding to the list. Handle potential API errors or low-confidence results gracefully.
Cost Splitting (Integrated with Lists):
- Core Features: Assign prices to items on the shopping list as they are purchased. Add participants (from the shared group) to a list's expense split. Calculate totals per list and simple equal splits per participant.
- PWA/UX: Clear display of totals and individual shares. Easy interface for marking items as bought and adding their price.
User Authentication & Group Management:
- Core Features: Secure email/password signup & login (JWT-based). Ability to create simple groups (e.g., "Household"). Mechanism to invite/add users to a group (e.g., unique invite code/link). Basic role distinction (e.g., group owner/admin, member) if necessary for managing participants.
- PWA/UX: Minimalist forms, clear inline validation, smooth onboarding explaining the group concept.
Core PWA Functionality:
- Core Features: Installable via manifest.json. Offline access via service worker caching (app shell, static assets, user data). Basic background sync strategy for offline actions (e.g., "last write wins" for simple edits, potentially queueing adds/deletes).

3. Feature Breakdown & UX Enhancements (MVP Focus)

A. Shared Shopping Lists

Screens: Dashboard (list overview), List Detail (items), Group Management.
Flows: Create list -> (Optional) Share with group -> Add/edit/check items -> See updates from others -> Mark list complete.
UX Focus: Smooth transitions, clear indication of shared status, offline caching, simple conflict notification (not full resolution in MVP).

B. OCR with Google Cloud Vision

Flow: Tap "Add via OCR" -> Capture/Select Image -> Upload -> Show Progress -> Display Review Screen (editable text boxes for potential items) -> User confirms/edits -> Items added to list.
UX Focus: Clear instructions, robust error handling (API errors, poor image quality feedback if possible), easy correction interface, manage user expectations regarding OCR accuracy. Monitor API costs/quotas.

C. Integrated Cost Splitting

Flow: Open shared list -> Mark item "bought" -> Input price -> View updated list total -> Go to "Split Costs" view for the list -> Confirm participants (group members) -> See calculated equal split.
UX Focus: Seamless transition from shopping to cost entry. Clear, real-time calculation display. Simple participant management within the list context.

D. User Auth & Groups

Flow: Sign up/Login -> Create a group -> Invite members (e.g., share code) -> Member joins group -> Access shared lists.
UX Focus: Secure and straightforward auth. Simple group creation and joining process. Clear visibility of group members.

E. PWA Essentials

Manifest: Define app name, icons, theme, display mode.
Service Worker: Cache app shell, assets, API responses (user data). Implement basic offline sync queue for actions performed offline (e.g., adding/checking items). Define a clear sync conflict strategy (e.g., last-write-wins, notify user on conflict).

4. Architecture & Technology Stack

Frontend: Svelte PWA

Framework: Svelte/SvelteKit (Excellent for performant, component-based PWAs).
State Management: Svelte Stores for managing UI state and cached data.
PWA Tools: Workbox.js (via SvelteKit integration or standalone) for robust service worker generation and caching strategies.
Styling: Tailwind CSS or standard CSS with scoped styles.
UX: Design system (e.g., using Figma), Storybook for component development.

Backend: FastAPI & PostgreSQL

Framework: FastAPI (High performance, async support, auto-docs, Pydantic validation).
Database: PostgreSQL (Reliable, supports JSONB for flexibility if needed). Schema designed to handle users, groups, lists, items, costs, and relationships. Basic indexing on foreign keys and frequently queried fields (user IDs, group IDs, list IDs).
ORM: SQLAlchemy (async support with v2.0+) or Tortoise ORM (async-native). Alembic for migrations.
OCR Integration: Use the official Google Cloud Client Libraries for Python to interact with the Vision API. Implement robust error handling, retries, and potentially rate limiting/cost control logic. Ensure API calls are async to avoid blocking.
Authentication: JWT tokens for stateless session management.
Deployment: Containerize using Docker/Docker Compose for development and deployment consistency. Deploy on a scalable cloud platform (e.g., Google Cloud Run, AWS Fargate, DigitalOcean App Platform).
Monitoring: Logging (standard Python logging), Error Tracking (Sentry), Performance Monitoring (Prometheus/Grafana if needed later).

1. User Stories

Authentication & User Management

As a new user, I want to sign up with my email so I can create and manage shopping lists
As a returning user, I want to log in securely to access my lists and groups
As a user, I want to reset my password if I forget it
As a user, I want to edit my profile information (name, avatar)

Group Management

As a user, I want to create a new group (e.g., "Household", "Roommates") to organize shared lists
As a group creator, I want to invite others to join my group via a shareable link/code
As an invitee, I want to easily join a group by clicking a link or entering a code
As a group owner, I want to remove members if needed
As a user, I want to leave a group I no longer wish to be part of
As a user, I want to see all groups I belong to and switch between them

List Management

As a user, I want to create a personal shopping list with a title and optional description
As a user, I want to share a list with a specific group so members can collaborate
As a user, I want to view all my lists (personal and shared) from a central dashboard
As a user, I want to archive or delete lists I no longer need
As a user, I want to mark a list as "shopping complete" when finished
As a user, I want to see which group a list is shared with

Item Management

As a user, I want to add items to a list with names and optional quantities
As a user, I want to mark items as purchased when shopping
As a user, I want to edit item details (name, quantity, notes)
As a user, I want to delete items from a list
As a user, I want to reorder items on my list for shopping efficiency
As a user, I want to see who added or marked items as purchased in shared lists

OCR Integration

As a user, I want to capture a photo of a physical shopping list or receipt
As a user, I want the app to extract text and convert it into list items
As a user, I want to review and edit OCR results before adding to my list
As a user, I want clear feedback on OCR processing status
As a user, I want to retry OCR if the results aren't satisfactory

Cost Splitting

As a user, I want to add prices to items as I purchase them
As a user, I want to see the total cost of all purchased items in a list
As a user, I want to split costs equally among group members
As a user, I want to see who owes what amount based on the split
As a user, I want to mark expenses as settled

PWA & Offline Experience

As a user, I want to install the app on my home screen for quick access
As a user, I want to view and edit my lists even when offline
As a user, I want my changes to sync automatically when I'm back online
As a user, I want to be notified if my offline changes conflict with others' changes

10 KiB Raw Blame History