MyRecipeBox PWA

A Progressive Web Application for collecting, organizing, and accessing recipes both online and offline. Features AI-powered recipe extraction from URLs and images, comprehensive search functionality, and role-based access control.

🚀 Features

• Progressive Web App with offline functionality
• AI-Powered Recipe Extraction from URLs and images using Google Gemini API
• Triple Input Methods (URL, manual form, and image upload with OCR)
• Recipe Publishing System with draft/published states and role-based visibility
• Advanced Search & Tagging system
• Role-Based Access Control (Admin/Reader) with granular permissions
• Offline-First Architecture with smart caching
• Material Design with theme support and visual indicators

📋 Development Progress

✅ Phase 1: Core Foundation & Setup

• Set up SvelteKit project with TypeScript
• Install dependencies (PocketBase SDK, Dexie, Gemini API)
• Create project folder structure
• Configure environment variables
• Define TypeScript interfaces and data models
• Create service classes for API interactions
• Set up Svelte stores for state management
• Set up PocketBase backend with collections
• Create development scripts and environment

✅ Phase 2: Authentication & Authorization

• Implement PocketBase authentication
• Create login/register components with Svelte 5 runes
• Set up OAuth providers (Google, GitHub)
• Implement role-based access control
• Create authentication guards and navigation
• Write comprehensive unit and E2E tests
• Update components to use modern Svelte 5 syntax

✅ Phase 3: Recipe Management

• Build manual recipe creation form with comprehensive validation
• Implement recipe CRUD operations with PocketBase integration
• Create recipe listing and detail views with responsive design
• Add admin-only edit/delete functionality with role-based access
• Create admin routes (/admin/recipes/new, /admin/recipes/[id]/edit)
• Implement recipe detail view (/recipes/[id]) with breadcrumbs
• Update homepage to display recipe collection
• Add comprehensive E2E tests with test IDs and CSS classes
• Fix registration bug (passwordConfirm field missing)
• Update E2E tests to use real PocketBase instead of mocks
• Set up interactive coverage UI with Vitest
• Implement recipe publishing system with draft/published states
• Add role-based recipe visibility (admin sees all, readers see published only)
• Create draft indicators and visual badges for unpublished recipes
• Add publish toggle in recipe creation and editing forms
• Implement proper error handling with custom error pages

✅ Phase 4: AI Integration

• Integrate Google Gemini API for URL extraction
• Implement image upload and preprocessing
• Add Gemini Vision API for OCR capabilities
• Create review/edit interface for extracted content
• Build comprehensive extraction UI with three modes (manual, URL, image)
• Add API endpoints for server-side extraction processing
• Implement proper error handling and validation

✅ Phase 5: Search & Discovery

• Implement advanced search functionality with multiple filter options
• Create dedicated search page (/search) with comprehensive filtering
• Build tag management interface for administrators (/admin/tags)
• Add popular tags display and quick filtering on homepage
• Enhanced navigation with search functionality in header
• Integrate cuisine, difficulty, and dietary preference filters
• Add real-time search with auto-complete functionality
• Create tag-based filtering with visual tag indicators

📋 Phase 6: PWA & Offline Features

• Implement caching strategy with service workers
• Add offline data synchronization
• Configure PWA manifest and installation
• Handle offline/online state transitions

📋 Phase 7: Testing & Quality

• Write unit tests for all components
• Create integration tests with Playwright
• Test authentication and authorization
• Test AI extraction features
• Test offline functionality

📋 Phase 8: Deployment & Production

• Docker deployment with custom PocketBase v0.29.0
• Production-ready Docker Compose configuration
• Multi-stage frontend build with Node.js adapter
• Environment variable configuration for production
• Health checks and container orchestration
• Configure Cloudflare Pages deployment
• Set up CI/CD pipeline
• Add error tracking and monitoring
• Performance optimization

🛠 Tech Stack

• Frontend: SvelteKit with TypeScript
• Backend: PocketBase v0.29.0 (SQLite/PostgreSQL)
• Authentication: PocketBase Auth (OAuth2, email/password)
• AI Integration: Google Gemini API (text & vision)
• Styling: Tailwind CSS with forms and typography plugins
• Offline Storage: Dexie.js (IndexedDB wrapper)
• Testing: Vitest (unit/component) + Playwright (E2E)
• Deployment: Docker Compose with custom PocketBase v0.29.0

📝 Recipe Publishing System

Publishing States

• Published: Recipes visible to all authenticated users (admin and readers)
• Draft: Recipes only visible to admin users who created them

Role-Based Visibility

• Admin Users: Can see all recipes (published and drafts) and manage publishing status
• Reader Users: Can only see published recipes, no access to drafts

Visual Indicators

• Draft Badge: Yellow "Draft" indicator appears on unpublished recipe cards (admin view only)
• Publishing Toggle: Checkbox in recipe creation/edit forms to control published status
• Error Pages: Custom error handling for invalid recipe access

Features

• ✅ Publish Toggle: Easy one-click publishing from recipe forms
• ✅ Draft Management: Create and refine recipes before publishing
• ✅ Role-Based Access: Automatic filtering based on user permissions
• ✅ Visual Feedback: Clear indicators for recipe status
• ✅ Error Handling: Graceful handling of access denied scenarios

🚀 Getting Started

Prerequisites

• Node.js 22.x (managed with asdf)
• npm 10.x

Installation

1. Clone the repository

2. Install dependencies:

   npm install

3. Set up environment variables:

   cp .env.example .env
   # Edit .env with your configuration

4. Start the development server:

   npm run dev

Development Commands

# Development server
npm run dev

# Run tests
npm run test

# Run unit tests only
npm run test:unit

# Run E2E tests
npm run test:e2e

# Build for production
npm run build

# Preview production build
npm run preview

# Lint and format code
npm run lint
npm run format

📚 Project Structure

src/
├── lib/
│   ├── components/
│   │   ├── ui/          # Reusable UI components
│   │   ├── forms/       # Form components
│   │   ├── recipe/      # Recipe-specific components
│   │   ├── auth/        # Authentication components
│   │   └── layout/      # Layout components
│   ├── stores/          # Svelte stores for state management
│   ├── services/        # API services and business logic
│   ├── types/           # TypeScript type definitions
│   └── utils/           # Utility functions
├── routes/              # SvelteKit routes
└── tests/               # Test files

🔧 Configuration

Environment Variables

See .env.example for all required environment variables.

PocketBase Setup

1. Install PocketBase
2. Run PocketBase server
3. Configure collections and authentication
4. Set up admin user

🧪 Testing

This project follows a comprehensive testing strategy with multiple test types and tools to ensure reliability and quality.

Test Types & Coverage

• Unit Tests: Service layer logic, store management, utility functions
• Component Tests: Svelte component rendering and interactions
• E2E Tests: Complete user journeys and authentication flows
• Integration Tests: API interactions and cross-component workflows

Testing Stack

• Vitest - Unit and component testing framework
• Playwright - End-to-end testing with real browsers
• Testing Library - Component testing utilities and DOM queries
• jsdom - DOM simulation for unit tests

Running Tests

All Tests

npm run test                    # Run all tests (unit + E2E)

Unit Tests

npm run test:unit               # Run in watch mode (development)
npm run test:unit -- --run     # Run once and exit
npm run test:unit:coverage     # Run with coverage report (text output)
npm run test:coverage          # Interactive coverage UI with browser

# Run specific test files
npm run test:unit -- --run src/lib/services/pocketbase.test.ts
npm run test:unit -- --run src/lib/stores/auth.test.ts

Coverage Reports

npm run test:coverage          # Opens interactive Vitest UI with coverage
                              # - Live coverage visualization
                              # - Click-through source files
                              # - Real-time test running
                              # - Auto-opens at http://localhost:51204/__vitest__/

E2E Tests

npm run test:e2e                # Run all E2E tests headless
npm run test:e2e -- --headed   # Run with visible browser
npm run test:e2e -- --debug    # Run in debug mode

# Run specific test files or patterns
npm run test:e2e -- e2e/auth.test.ts
npm run test:e2e -- --grep "authentication"
npm run test:e2e -- --grep "should show welcome page"

Test Files Structure

src/
├── lib/
│   ├── services/
│   │   └── pocketbase.test.ts      # PocketBase service tests
│   ├── stores/
│   │   └── auth.test.ts            # Authentication store tests
│   └── components/
│       └── auth/
│           └── LoginForm.test.ts   # Component tests (when needed)
├── routes/
│   └── page.svelte.test.ts         # Route component tests
└── demo.spec.ts                    # Example unit test

e2e/
├── auth.test.ts                    # Authentication flow tests
└── demo.test.ts                    # Example E2E test

# Test configuration
├── vitest.config.ts                # Vitest configuration
├── playwright.config.ts            # Playwright configuration
├── vitest-setup-client.ts          # Client-side test setup
└── vitest-setup-server.ts          # Server-side test setup

Current Test Coverage

Unit Tests ✅ (74/74 passing)

• PocketBase Service (src/lib/services/pocketbase.test.ts)

  • Authentication methods (login, register, OAuth)
  • Error handling and validation
  • Token management and refresh
  • File URL generation and utilities

• Recipe Service (src/lib/services/recipe.test.ts)

  • CRUD operations with role-based filtering
  • Published status handling and visibility
  • Recipe creation, update, and deletion
  • URL and image extraction workflows

• Authentication Store (src/lib/stores/auth.test.ts)

  • State management and reactivity
  • Login/logout workflows
  • Role-based derived stores
  • Error state handling

E2E Tests ✅ (50/50 passing)

• Authentication Flows (e2e/auth.test.ts)

  • Welcome page for unauthenticated users
  • Login and registration form validation
  • OAuth button availability
  • Role-based UI differences (Admin vs Reader)
  • Navigation and redirects
  • Error message display

• Recipe CRUD Operations (e2e/recipe-crud.test.ts)

  • Recipe creation, editing, and deletion
  • Form validation and error handling
  • Image upload functionality
  • Admin-only access controls

• Recipe Full Flow (e2e/recipe-full-flow.test.ts)

  • Complete recipe creation workflows
  • Recipe viewing and navigation
  • Recipe editing with data persistence

• Recipe Visibility & Publishing (e2e/recipe-visibility.test.ts)

  • Draft vs published recipe visibility
  • Role-based access to recipes
  • Publishing system functionality
  • Visual indicators for draft recipes

• Error Handling (e2e/recipes.test.ts)

  • Invalid recipe ID handling
  • Network error scenarios
  • Proper error page display
  • Authentication-required routes

Development Workflow

For Test-Driven Development

# Start tests in watch mode while developing
npm run test:unit

# Start dev server for E2E testing
npm run dev:full  # Starts both PocketBase and SvelteKit

Before Committing

# Run all tests to ensure nothing is broken
npm run test

# Run linting and formatting
npm run lint
npm run format

Test Setup Requirements

For E2E Tests

The development server must be running:

npm run dev:full    # Recommended: starts both services
# OR separately:
npm run pocketbase  # Terminal 1
npm run dev         # Terminal 2

Playwright Browsers

Install required browsers (done automatically on first run):

npx playwright install

Writing New Tests

Unit Tests

Create .test.ts files next to your source files:

// src/lib/services/example.test.ts
import { describe, it, expect, vi } from 'vitest';
import { exampleFunction } from './example';

describe('Example Service', () => {
	it('should work correctly', () => {
		expect(exampleFunction()).toBe('expected result');
	});
});

E2E Tests

Add test files in the e2e/ directory:

// e2e/example.test.ts
import { test, expect } from '@playwright/test';

test.describe('Example Feature', () => {
	test('should work as expected', async ({ page }) => {
		await page.goto('/');
		await expect(page.getByText('Expected Text')).toBeVisible();
	});
});

Troubleshooting Tests

Common Issues

1. E2E tests timeout or fail to start

   # Ensure dev server is running
   npm run dev:full
   
   # Check if PocketBase is accessible
   curl http://localhost:8090/api/health

2. Unit tests can't find modules

   # Clear Vitest cache
   npm run test:unit -- --run --no-cache

3. Playwright browser issues

   # Reinstall browsers
   npx playwright install --force

4. Node version compatibility

   # Ensure Node 22.x is being used
   node --version
   asdf current nodejs

Debugging Tests

# Debug specific test with browser devtools
npm run test:e2e -- --debug --grep "specific test name"

# Run tests with verbose logging
npm run test:unit -- --run --reporter=verbose

# Generate test coverage report with interactive UI
npm run test:coverage

Continuous Integration

The test suite is designed to run in CI environments:

• All tests run on every commit
• E2E tests use headless browsers
• Test results integrate with PR status checks
• Coverage reports can be generated for monitoring

This comprehensive testing strategy ensures the authentication system is robust, reliable, and ready for production use.

🚀 Deployment

Docker Deployment (Production Ready)

The app is configured for production deployment using Docker Compose with a custom PocketBase v0.29.0 image:

Prerequisites

• Docker Engine 20.10+
• Docker Compose 2.0+
• Server with at least 2GB RAM and 10GB storage

Quick Start

# Clone the repository
git clone https://github.com/comdotlinux/ReceipeBox.git
cd ReceipeBox

# Configure environment
cd docker/
cp .env.production .env
# Edit .env with your settings

# Deploy
docker-compose up --build -d

# Check status
docker-compose ps
docker logs myrecipebox-pocketbase

Services

• Frontend: SvelteKit app (port 3001) - http://localhost:3001
• Backend: PocketBase v0.29.0 API (port 8090) - http://localhost:8090
• Health Checks: Built-in container health monitoring
• Volumes: Persistent data storage for database and uploads

Key Features

• ✅ Custom PocketBase v0.29.0 - Official binary, latest features
• ✅ Multi-stage builds - Optimized production images
• ✅ Environment configuration - Flexible deployment settings
• ✅ Health monitoring - Container dependency management
• ✅ Persistent storage - Database and file uploads preserved

Alternative: Cloudflare Pages

For static deployment (frontend only):

1. Connect your repository to Cloudflare Pages
2. Set build command: npm run build
3. Set output directory: dist
4. Configure environment variables in Cloudflare
5. Deploy separate PocketBase instance

📖 Documentation

• Product Requirements Document
• Development Instructions

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Write tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

📄 License

This project is licensed under the MIT License.