feat: Add photo management features, duplicate detection, attempt limits, and admin deletion

- Add duplicate photo detection (file hash and URL checking) - Add max attempts per photo with UI counter - Simplify penalty system (auto-enable when points > 0) - Prevent scores from going below 0 - Add admin photo deletion functionality - Improve navigation with always-visible logout - Prevent users from guessing their own photos
2026-01-02 14:57:30 -05:00
commit 9640627972
69 changed files with 20858 additions and 0 deletions
@@ -0,0 +1,295 @@
+# MirrorMatch
+
+A photo guessing game where users upload photos and other users guess who is in the picture to earn points. Built with Next.js, PostgreSQL, and NextAuth.
+
+## 📚 Important: Read Documentation First
+
+**Before making code changes, please read:**
+- **`.cursor/rules/mirrormatch.mdc`** - Project rules and guidelines
+- **`ARCHITECTURE.md`** - System design and data flows
+- **`CONTRIBUTING.md`** - Coding conventions and workflow
+- **`SECURITY.md`** - Security practices
+- **This README** - Setup and usage
+
+**Keep documentation updated:** When you modify code that changes behavior or architecture, update the relevant documentation files to keep them in sync.
+
+## Features
+
+- **User Management**: Admin can create users with email/password authentication
+- **Photo Upload**: Users can upload photos with answer names
+- **Guessing Game**: Users guess who is in photos to earn points
+- **Email Notifications**: Users receive emails when new photos are uploaded
+- **Leaderboard**: Track user points and rankings
+- **Profile Management**: Users can view their points and change passwords
+
+## Tech Stack
+
+- **Framework**: Next.js 16 (App Router)
+- **Language**: TypeScript
+- **Database**: PostgreSQL
+- **ORM**: Prisma
+- **Authentication**: NextAuth.js (Credentials Provider)
+- **Styling**: Tailwind CSS
+- **Email**: Nodemailer (Ethereal in dev, SMTP in production)
+
+## Prerequisites
+
+- Node.js 18+ and npm
+- PostgreSQL database (local or remote)
+- For production: SMTP email server credentials
+
+## Installation
+
+1. **Clone the repository** (if applicable) or navigate to the project directory:
+   ```bash
+   cd mirrormatch
+   ```
+
+2. **Install dependencies**:
+   ```bash
+   npm install
+   ```
+
+3. **Set up environment variables**:
+   Create a `.env` file in the root directory with the following variables:
+   ```env
+   # Database
+   DATABASE_URL="postgresql://user:password@localhost:5432/mirrormatch?schema=public"
+
+   # NextAuth
+   NEXTAUTH_URL="http://localhost:3000"
+   NEXTAUTH_SECRET="your-secret-key-here-generate-with-openssl-rand-base64-32"
+
+   # Email Configuration (for production)
+   SMTP_HOST="smtp.example.com"
+   SMTP_PORT="587"
+   SMTP_USER="your-email@example.com"
+   SMTP_PASSWORD="your-email-password"
+   SMTP_FROM="MirrorMatch <noreply@mirrormatch.com>"
+   ```
+
+   **Generate NEXTAUTH_SECRET**:
+   ```bash
+   openssl rand -base64 32
+   ```
+
+   **Note**: In development, emails will use Ethereal (test emails) or console logging. No SMTP config is needed for dev mode.
+
+4. **Set up the database**:
+   ```bash
+   # Generate Prisma Client
+   npm run db:generate
+
+   # Run migrations
+   npm run db:migrate
+
+   # Or push schema directly (for development)
+   npm run db:push
+   ```
+
+5. **Seed the database** (creates default admin user):
+   ```bash
+   npm run db:seed
+   ```
+
+   This creates an admin user with:
+   - Email: `admin@mirrormatch.com`
+   - Password: `admin123`
+   - **⚠️ Important**: Change this password after first login!
+
+## Basic Usage
+
+### Workflow Overview
+
+1. **Admin creates users:**
+   - Admin logs in and navigates to `/admin`
+   - Creates new users with email, password, and role
+   - Users receive temporary passwords
+
+2. **Users log in:**
+   - Users navigate to `/login`
+   - Enter email and password
+   - Access the main application
+
+3. **Users upload photos:**
+   - Navigate to `/upload`
+   - Enter photo URL and answer name (the correct name to guess)
+   - Photo is saved and emails are sent to all other users
+
+4. **Users guess photos:**
+   - View photos on `/photos` page
+   - Click a photo to view details
+   - Submit guesses for who is in the photo
+   - Earn points for correct guesses (case-insensitive matching)
+
+5. **Leaderboard:**
+   - View rankings on `/leaderboard` page
+   - See all users sorted by points
+   - Track your own position
+
+### Key Features
+
+- **Admin Panel:** Create and manage users, reset passwords
+- **Photo Upload:** Upload photos with answer names
+- **Guessing System:** Submit guesses and earn points
+- **Email Notifications:** Get notified when new photos are uploaded
+- **Leaderboard:** Track user rankings by points
+- **Profile Management:** View points and change password
+
+## Running the Application
+
+### Development
+
+```bash
+npm run dev
+```
+
+Open [http://localhost:3000](http://localhost:3000) in your browser.
+
+### Production
+
+```bash
+npm run build
+npm start
+```
+
+## Database Commands
+
+- `npm run db:generate` - Generate Prisma Client
+- `npm run db:migrate` - Run database migrations
+- `npm run db:push` - Push schema changes to database (dev only)
+- `npm run db:studio` - Open Prisma Studio (database GUI)
+- `npm run db:seed` - Seed database with initial admin user
+
+## Creating the First Admin User
+
+The seed script automatically creates an admin user. If you need to create one manually:
+
+1. Run the seed script: `npm run db:seed`
+2. Or use Prisma Studio: `npm run db:studio` and create a user with `role: "ADMIN"`
+
+## Project Structure
+
+```
+mirrormatch/
+├── app/                    # Next.js App Router pages
+│   ├── api/               # API routes
+│   │   ├── admin/        # Admin API routes
+│   │   ├── auth/         # NextAuth routes
+│   │   ├── photos/       # Photo-related API routes
+│   │   └── profile/      # Profile API routes
+│   ├── admin/            # Admin panel page
+│   ├── leaderboard/      # Leaderboard page
+│   ├── login/            # Login page
+│   ├── photos/           # Photos listing and detail pages
+│   ├── profile/          # User profile page
+│   └── upload/           # Photo upload page
+├── components/            # React components
+├── lib/                   # Utility libraries
+│   ├── auth.ts           # NextAuth configuration
+│   ├── email.ts          # Email sending utilities
+│   ├── prisma.ts         # Prisma client instance
+│   └── utils.ts          # Helper functions
+├── prisma/                # Prisma schema and migrations
+│   ├── schema.prisma     # Database schema
+│   └── seed.ts           # Database seed script
+└── types/                 # TypeScript type definitions
+```
+
+## Features Overview
+
+### Authentication
+- Email/password login via NextAuth
+- Protected routes with middleware
+- Role-based access control (ADMIN/USER)
+
+### Admin Panel (`/admin`)
+- View all users
+- Create new users
+- Reset user passwords
+- View user points and roles
+
+### Photo Upload (`/upload`)
+- Upload photos via URL
+- Set answer name for guessing
+- Automatically sends email notifications to all other users
+
+### Photo Guessing (`/photos/[id]`)
+- View photo and uploader info
+- Submit guesses
+- Get instant feedback (correct/wrong)
+- Earn points for correct guesses
+- Case-insensitive matching
+
+### Leaderboard (`/leaderboard`)
+- View all users ranked by points
+- See your own ranking highlighted
+
+### Profile (`/profile`)
+- View your points and account info
+- Change password (requires current password)
+
+## Email Configuration
+
+### Development
+In development mode, the app uses:
+- **Ethereal Email** (if available) - provides test email accounts with preview URLs
+- **Console transport** (fallback) - logs emails to console
+
+Check the console for email preview URLs when using Ethereal.
+
+### Production
+Set up SMTP credentials in `.env`:
+- `SMTP_HOST` - Your SMTP server hostname
+- `SMTP_PORT` - SMTP port (usually 587 for TLS, 465 for SSL)
+- `SMTP_USER` - SMTP username
+- `SMTP_PASSWORD` - SMTP password
+- `SMTP_FROM` - From address for emails
+
+## Security Notes
+
+- Passwords are hashed using bcrypt
+- NextAuth handles session management
+- Middleware protects routes
+- Admin routes are restricted to ADMIN role
+- SQL injection protection via Prisma
+
+## Troubleshooting
+
+### Database Connection Issues
+- Verify `DATABASE_URL` is correct
+- Ensure PostgreSQL is running
+- Check database exists and user has permissions
+
+### Email Not Sending
+- In dev: Check console for Ethereal preview URLs
+- In production: Verify SMTP credentials
+- Check email service logs
+
+### Authentication Issues
+- Verify `NEXTAUTH_SECRET` is set
+- Check `NEXTAUTH_URL` matches your app URL
+- Clear browser cookies if needed
+
+## Documentation
+
+This project maintains comprehensive documentation:
+
+- **README.md** (this file) - Setup, installation, and basic usage
+- **ARCHITECTURE.md** - System architecture, data models, and application flows
+- **CONTRIBUTING.md** - Coding conventions and development workflow
+- **SECURITY.md** - Security practices and vulnerability reporting
+- **.cursor/rules/mirrormatch.mdc** - Project rules for AI tools and developers
+
+**For Developers and AI Tools:**
+
+**⚠️ Important:** Before making code changes, read `.cursor/rules/mirrormatch.mdc`, `ARCHITECTURE.md`, `CONTRIBUTING.md`, `SECURITY.md`, and this README. Keep them updated when behavior or architecture changes.
+
+- Always read the relevant documentation before making changes
+- Update documentation when behavior or architecture changes
+- Keep all documentation files in sync with code changes
+- Follow the guidelines in each document
+
+## License
+
+MIT