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, James, Little Prague, Humongous, Giraffe
Fashion: Fox, H&M, Max, Shilav
Health & Beauty: Super-Pharm LifeStyle
Transport: Isracard
Home & DIY: BBB, Manam DIY
Grocery: Shufersal, Mika Convenience Stores
Entertainment: Escape Room

🚀 Getting Started

Prerequisites

Node.js 18+
npm or yarn
Git

Installation

Clone the repository
```
git clone <repository-url>
cd yomu
```
Install dependencies
```
npm install
```

Set up environment variables

cp .env.example .env

Update .env with your configuration:

DATABASE_URL=file:./dev.db
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=your-secret-key-here-change-in-production
GOOGLE_CLIENT_ID=your-google-client-id-here
GOOGLE_CLIENT_SECRET=your-google-client-secret-here

Set up the database
```
npx prisma generate
npx prisma db push
```
Run the development server
```
npm run dev
```
Open your browser
Navigate to http://localhost:3000

🐳 Docker & Podman Support

Quick Start with Docker

Clone the repository
```
git clone <repository-url>
cd yomu
```
Run the setup script
```
./scripts/docker-setup.sh setup
```

Start the application

# Production mode
./scripts/docker-setup.sh start

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

Initialize the database
```
./scripts/docker-setup.sh init-db
```
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: JavaScript runtime
Prisma ORM: Database toolkit
SQLite: Local development database
bcryptjs: Password hashing

Database

SQLite: Local development (can be switched to PostgreSQL for production)

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

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

Main script: scripts/seed.js
Run locally:

# Prisma generate + schema push (first run)
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)
Creates missing partnerships if needed

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
Brand: Brand information and logos
Benefit: Birthday benefits and details
UserMembership: User's active memberships
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)

Connect your GitHub repository to Vercel
Configure environment variables
Deploy automatically on push to main branch

Other Platforms

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

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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! 🎉

maximunited/yomu