YomU - יום-You | Birthday Benefits Platform

YomU (יום-You) is a mobile-first web application that aggregates and displays personal birthday benefits, deals, and freebies for users in Israel. The platform helps users never miss a birthday deal again by consolidating information they would otherwise have to find manually.

🌟 Features

Core Features

• Birthday Benefits Tracking: Centralized platform for all birthday benefits
• Membership Management: Easy management of loyalty program memberships
• Real-time Notifications: Push notifications for new benefits and expiring deals
• Multi-language Support: Full Hebrew and English interface with 10 additional beta languages
• Dark Mode: Global dark mode support
• Mobile-First Design: Responsive design optimized for mobile devices
• Admin Dashboard: Complete CRUD interface for managing brands and benefits
• Language Management: Advanced language selector with RTL/LTR support

User Features

• Onboarding & Profile Setup: Simple sign-up with Date of Birth requirement
• My Memberships Screen: Checklist of popular Israeli brands and loyalty clubs
• Dashboard: Card-based layout showing active and upcoming benefits
• Benefit Details: Full descriptions, terms & conditions, and redemption methods
• Search & Filter: Advanced search and filtering capabilities
• Custom Memberships: Add and manage custom membership programs
• Language Selection: Choose from 12 supported languages with native names and flags

Admin Features

• Brand Management: Add, edit, delete, and toggle brands
• Benefit Management: Create and manage benefits with full validation
• Bulk Operations: Import/export data via command-line tools
• Status Control: Toggle active/inactive status for brands and benefits
• Data Integrity: Automatic cascade deletion for related records

Supported Languages

• Fully Supported: Hebrew (עברית), English
• Beta Languages: Arabic (العربية), Russian (Русский), French (Français), Spanish (Español), German (Deutsch), Italian (Italiano), Portuguese (Português), Japanese (日本語), Korean (한국어), Chinese (中文)

Supported Brands & Services

• Food & Restaurants: McDonald's, Starbucks, KFC, Buckaroo, Shegev, Jem's, Little Prague, Humongous, Giraffe, BBB, Cafe Mandarin, M32
• Fashion: Fox, H&M, Max, Shilav, Castro CU, Delta, WOW, Factory 54, Golf & Co, Honigman, Brill Group / Gali
• Health & Beauty: Super-Pharm LifeStyle
• Transport / Finance: Isracard
• Home & DIY: מנמ - MNM
• Grocery: Shufersal, Mika Convenience Stores
• Entertainment / Leisure: Escape Room, Jump / עונות

🚀 Getting Started

Prerequisites

• Node.js: 22.14.0 or higher (any 22.x, 23.x, or 26.x version works)
  • Recommended: Use nvm, fnm, or volta
  • The project includes .nvmrc for automatic version detection
• npm: 10.0.0 or higher (comes with Node.js)
  • ⚠️ Yarn is not supported due to dependency override requirements
• Git: Any recent version
• Docker (optional): For containerized development/deployment

Installation

1. Clone the repository

   git clone <repository-url>
   cd yomu

2. Install dependencies

   npm install

3. Set up environment variables

   cp .env.example .env

   Update .env with your configuration:

   # Database (PostgreSQL - see options below)
   DATABASE_URL=postgresql://yomu:yomu@localhost:5432/yomu
   
   # NextAuth Configuration
   NEXTAUTH_URL=http://localhost:3000
   NEXTAUTH_SECRET=your-secret-key-here-change-in-production
   
   # Google OAuth (Optional)
   GOOGLE_CLIENT_ID=your-google-client-id-here
   GOOGLE_CLIENT_SECRET=your-google-client-secret-here

4. Choose a PostgreSQL setup method:

   Option A: Docker Compose (Recommended)

   ./scripts/docker-setup.sh setup
   ./scripts/docker-setup.sh start-dev
   ./scripts/docker-setup.sh init-db

   Access at: http://localhost:3001

   Option B: Manual PostgreSQL Setup

   # Install PostgreSQL first (see CLAUDE.md for instructions)
   npx prisma generate
   npx prisma db push
   npm run db:seed
   npm run dev

   Access at: http://localhost:3000

   Option C: Vercel Postgres (Development Database)

   npm i -g vercel
   vercel link
   vercel env pull .env
   npx prisma generate
   npx prisma db push
   npm run db:seed
   npm run dev

   Access at: http://localhost:3000

🐳 Docker & Podman Support

Quick Start with Docker

1. Clone the repository

   git clone <repository-url>
   cd yomu

2. Run the setup script

   ./scripts/docker-setup.sh setup

3. Start the application

   # Production mode
   ./scripts/docker-setup.sh start
   
   # Development mode (with hot reload)
   ./scripts/docker-setup.sh start-dev

4. Initialize the database

   ./scripts/docker-setup.sh init-db

5. Access the application

   • Production: http://localhost:3000
   • Development: http://localhost:3001

Using Podman

The same commands work with Podman. The setup script automatically detects and uses Podman if Docker is not available.

Docker Commands

# Start production services
docker-compose up -d

# Start development services
docker-compose --profile dev up -d

# View logs
docker-compose logs -f app

# Stop services
docker-compose down

# Rebuild images
docker-compose build --no-cache

Podman Commands

# Start production services
podman-compose up -d

# Start development services
podman-compose --profile dev up -d

# View logs
podman-compose logs -f app

# Stop services
podman-compose down

For detailed Docker/Podman documentation, see docs/DOCKER.md.

🧪 Testing & Scripts

Test Coverage

• 71/71 unit test suites passing (100%)
• 255/255 individual tests passing (100%)
• Comprehensive E2E test suite with Playwright
• Accessibility testing compliance
• Mobile responsiveness testing

Unit Tests

# Run all unit tests
npm test

# Watch mode for development
npm run test:watch

# Generate coverage report
npm run test:coverage

End-to-End Tests

# Run all E2E tests
npm run test:e2e

# Run with browser UI visible
npm run test:e2e:headed

# Debug mode (step-by-step)
npm run test:e2e:debug

# Mobile-specific tests
npm run test:e2e:mobile

# Accessibility tests
npm run test:e2e:accessibility

# View test reports
npm run test:e2e:report

Specialized Tests

# Lint code quality
npm run lint

# Translation checks
npm run test:translations

# Docker smoke test
npm run test:docker

# Partnership tests
npm run test:partnerships

Test Structure

• Unit Tests: tests/unit/ - Component, page, and utility testing
• E2E Tests: tests/e2e/ - Full user journey testing
• Integration Tests: tests/integration/ - API and system integration
• Accessibility: Automated ARIA compliance and keyboard navigation
• Mobile Testing: Responsive design and touch interactions

🛠️ Tech Stack

Frontend

• Next.js 15: React framework with App Router
• TypeScript: Type-safe development
• Tailwind CSS: Utility-first CSS framework
• Lucide React: Beautiful icons
• NextAuth.js: Authentication solution

Backend

• Node.js 22+: JavaScript runtime
• Prisma 7: Next-generation ORM with PostgreSQL driver adapter
• PostgreSQL 16: Production-ready relational database
• bcryptjs: Password hashing

Database

• PostgreSQL: Used for all environments (local, CI, production)
• Docker Compose: PostgreSQL service for local development
• Prisma Migrations: Type-safe database schema management
• Vercel Postgres: Managed PostgreSQL for production deployments

Note: This project uses PostgreSQL exclusively. SQLite is no longer supported (migrated to PostgreSQL with Prisma 7 upgrade).

Auth

• NextAuth.js: Email/password and Google OAuth
• JWT: Session management

📱 Features in Detail

Authentication

• Email/password registration and login
• Google OAuth integration
• Secure session management
• Password hashing with bcrypt

Membership Management

• Pre-configured popular Israeli brands
• Custom membership creation
• Search and filter functionality
• Free vs. paid membership indicators
• Cost details for paid memberships

Benefits Dashboard

• Active benefits display
• Upcoming benefits preview
• Copy-to-clipboard functionality for promo codes
• Detailed benefit information
• Brand logos and descriptions

Dark Mode

• Global dark mode support
• Persistent user preference
• System preference detection
• Toggle available on all pages

Internationalization

• Full Hebrew and English support
• RTL (Right-to-Left) layout support
• Language switching functionality
• Context-based translation management

🎨 Design Principles

• Mobile-First: Designed for mobile screens first, then desktop
• Clean & Intuitive: Minimalist design avoiding clutter
• Festive but Mature: Pleasant color palette hinting at celebration
• Visual Hierarchy: Clear typography and brand logos
• Accessibility: Proper contrast ratios and screen reader support

📁 Project Structure

yomu/
├── src/
│   ├── app/                   # Next.js App Router pages
│   │   ├── api/               # API routes
│   │   ├── auth/              # Authentication pages
│   │   ├── dashboard/         # Main dashboard
│   │   ├── memberships/       # Membership management
│   │   ├── settings/          # User settings
│   │   └── globals.css        # Global styles
│   ├── components/            # Reusable components
│   │   └── ui/                # UI components
│   ├── contexts/              # React contexts
│   ├── lib/                   # Utility functions
│   └── types/                 # TypeScript types
├── prisma/                    # Database schema
├── public/                    # Static assets
│   └── images/                # Brand logos
└── package.json               # Dependencies

📦 Database Seeding & Loyalty Catalog

We use a single, unified seed entry point that covers brands, partnerships, and benefits.

• Main script: scripts/seed.js
• Canonical names (upsert renames legacy aliases): יומנגס - Humongous, מנמ - MNM, באקרו - Buckaroo, ג'מס - Jem's

Catalog sync (seed ↔ Notion)

• Source of truth for the app: scripts/seed.js (and Prisma).
• Research / ops tracker: Notion parent YomU Loyalty — Brands + Benefits DBs with Brand↔Benefits relation. Membership fields (Joined, Member ID, Remind me) live on Brands only.
• Sync direction: research in Notion → update seed → upsert DB. The audit script does not write Notion (no in-repo Notion token).

Verification & reminders

Field	Model	Meaning
verified	Benefit	true when research is solid; soft/uncertain clubs seed false
lastChecked	Benefit	When the benefit/URL was last reviewed (null for soft brands)
remindEnabled	UserMembership	Default true; PATCH /api/user/memberships; bell toggle on Memberships; dashboard Reminders section filters on this

Soft brands (seed verified: false): H&M, שילב, Shufersal, Isracard, Honigman, Brill Group / Gali, Jump / עונות.

Loyalty URL audit

npm run audit:loyalty-urls

• Script: scripts/audit-loyalty-urls.js — HEAD/GET checks brand/benefit URLs from seed (optional JSON override).
• Scheduled monthly via .github/workflows/audit-loyalty-urls.yml (continue-on-error; does not block CI).

Seed commands

# Prisma generate + schema push (first run)
# Note: Neon may warn about dropping legacy User.password — prefer additive ALTERs for new columns
npx prisma generate && npx prisma db push

# Seed everything (clears existing data)
npm run db:seed

Modes:

• Fresh install (wipe + seed):

  node scripts/seed.js --mode=fresh

• Upsert/update without wipe (safe for existing DBs):

  node scripts/seed.js --mode=upsert

• Seed a subset of brands only (comma-separated):

  node scripts/seed.js --mode=upsert --brands="Giraffe,Nono & Mimi"

What it does (fresh):

• Clears benefits, userMemberships, brand_partnerships, and brands
• Creates all brands and partnerships
• Seeds a comprehensive set of benefits (including co-branded examples)

What it does (upsert):

• Does NOT wipe data
• Upserts brands by name and benefits by (brandId + title)
• Renames legacy brand aliases to canonical names
• Creates missing partnerships if needed
• Sets verified / lastChecked per soft vs researched clubs

Advanced: partial brand/benefit imports

• Use scripts/admin-helper.js to import/export JSON for brands/benefits without wiping the DB.

Production/Shared envs

• Prefer running seed only on fresh databases
• For updates, use the Admin UI or the admin helper instead of reseeding

🔧 Configuration

Environment Variables

• DATABASE_URL: Database connection string
• NEXTAUTH_URL: NextAuth.js base URL
• NEXTAUTH_SECRET: JWT encryption secret
• GOOGLE_CLIENT_ID: Google OAuth client ID
• GOOGLE_CLIENT_SECRET: Google OAuth client secret

Database Schema

The application uses Prisma with the following main models:

• User: User accounts and profiles (Clerk via clerkId)
• Brand: Brand information and logos
• Benefit: Birthday benefits and details (verified, lastChecked)
• UserMembership: User's active memberships (remindEnabled)
• Notification: User notifications
• CustomMembership: User-defined membership programs
• BrandPartnership: Brand partnership relationships

🛠️ Admin Tools

Admin Dashboard

Access the admin interface at /admin to manage brands and benefits:

• Brand Management: Add, edit, delete, and toggle brands
• Benefit Management: Create and manage benefits with validation
• Real-time Updates: Immediate reflection of changes
• Data Integrity: Automatic cascade deletion

Command-Line Tools

Use the admin helper script for bulk operations:

# Import brands from JSON file
node scripts/admin-helper.js import-brands brands.json

# Export current brands to JSON
node scripts/admin-helper.js export-brands

# List all brands
node scripts/admin-helper.js list-brands

# Toggle brand status
node scripts/admin-helper.js toggle-brand <brand-id>

# Similar commands for benefits
node scripts/admin-helper.js import-benefits benefits.json
node scripts/admin-helper.js export-benefits
node scripts/admin-helper.js list-benefits
node scripts/admin-helper.js toggle-benefit <benefit-id>

Language Management

The application supports 12 languages with automatic RTL/LTR detection:

• Language Detection: Browser language, localStorage, or manual selection
• RTL Support: Automatic text direction for Arabic and Hebrew
• Translation Fallbacks: Robust fallback chain (current → English → Hebrew → key)
• Beta Languages: 10 additional languages in beta with partial translations

🚀 Deployment

Vercel (Recommended)

1. Connect your GitHub repository to Vercel
2. Configure environment variables
3. Deploy automatically on push to main branch

Other Platforms

• Netlify: Static site hosting
• Railway: Full-stack deployment
• Heroku: Traditional hosting

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Contributors: The team behind YomU
• Brand Partners: All the brands providing birthday benefits
• Open Source Community: For the amazing tools and libraries used

📞 Support

For support, email support@yomu.app or create an issue in this repository.

If you find this project helpful, you can support the work here:

• Buy Me A Coffee: https://buymeacoffee.com/maxim_united

---

YomU - Never miss a birthday deal again! 🎉

Pre-commit hooks added