Shopping Mission 🛒

Shopping Mission is a real-time, collaborative Progressive Web App (PWA) designed to make grocery shopping efficient and focused. Built with Svelte 5 (Runes) and Firebase, it features a unique "Mission Mode" for distraction-free shopping and a smart input system for rapid list creation.

✨ Key Features

• Real-time Collaboration: Lists sync instantly across devices using Firestore.
• Mission Mode: A distracted-free UI optimized for the actual shopping trip (the "Mission").
• Smart Input: Intelligent category suggestion and item management.
• Secure: Role-based access control with "Whitelist" enforcement via Custom Claims and Firestore Rules.
• Optimistic UI: Instant interactions with background synchronization.
• PWA Ready: Installable on mobile devices for a native app-like experience.

🛠 Tech Stack

• Frontend Framework: Svelte 5 (using the new Runes reactivity model)
• Styling: TailwindCSS
• Backend: Firebase
  • Firestore: NoSQL Real-time Database
  • Authentication: Firebase Auth with Custom Claims
  • Cloud Functions: Serverless backend logic (v2)
• Build Tool: Vite
• Testing: Vitest

🚀 Getting Started

Prerequisites

• Node.js (Version 22+)
• Firebase CLI (npm install -g firebase-tools)

Installation

1. Clone the repository:

   git clone <repository-url>
   cd ShoppingList

2. Install dependencies:

   npm install

Configuration

Create a .env file in the root directory with your Firebase configuration:

# Firebase Configuration
VITE_FIREBASE_API_KEY=your_api_key
VITE_FIREBASE_AUTH_DOMAIN=your_project.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=your_project_id
VITE_FIREBASE_APP_ID=your_app_id
VITE_FIREBASE_REGION=eu-north1 # Or your specific region

# Development Flags
VITE_MOCK=false # Set to 'true' to use in-memory mock data

💻 Usage

Development Server

Start the local development server. This connects to your live development database unless mocked.

npm run dev

Mock Mode

Run the app completely offline with in-memory data (great for UI work).

npm run dev:mock

Quality Assurance

This project enforces strict code quality. Run the full validation suite before pushing:

npm run validate

This command runs:

1. Linting: ESLint
2. Type Checking: svelte-check
3. Formatting: Prettier
4. Unit Tests: Vitest

See CHECKS.md for more details on the CI/CD pipeline.

🏗 Architecture

The application follows a store-driven architecture where separate stores manage data logic, keeping UI components clean.

• list.ts: Central store for shopping list data and optimistic updates.
• auth.ts: Manages authentication and whitelist verification.
• app.ts: Global UI state.

graph TD
    User((User)) -->|Action| Component
    Component -->|Method Call| Store
    Store -->|Write| Firestore
    Firestore -->|onSnapshot| Store
    Store -->|Reactivity| Component

Loading

Security Model

Access is strictly controlled via a 3-tier "Whitelist" system:

1. Auth Blocking Function: Prevents sign-ups from non-whitelisted emails.
2. Firestore Rules: Enforces request.auth.token.whitelisted == true for data access.
3. Client-Side Check: UI guards prevent access until the claim is verified.

📦 Deployment

Deploy the frontend and backend to Firebase:

# Deploy everything
firebase deploy

# Deploy only specific targets
firebase deploy --only hosting
firebase deploy --only functions

Important

Ensure your local firebase-tools are updated to support Firebase Functions v2.

📄 License

This project is licensed under the BSD 3-Clause License.