Humanize READMEs and guides for clearer, professional tone
Align with project-template docs/writing-docs.md: plain openings, no emoji decoration, archive scratch plans where they cluttered live docs.
This commit is contained in:
+5
-5
@@ -148,11 +148,11 @@ Write clear, descriptive commit messages:
|
||||
- **Reference issues:** If applicable, reference issue numbers
|
||||
|
||||
**Examples:**
|
||||
- ✅ "Add password strength validation to change password form"
|
||||
- ✅ "Fix case-insensitive guess matching bug"
|
||||
- ✅ "Update README with new environment variables"
|
||||
- ❌ "Fixed stuff"
|
||||
- ❌ "Updates"
|
||||
- "Add password strength validation to change password form"
|
||||
- "Fix case-insensitive guess matching bug"
|
||||
- "Update README with new environment variables"
|
||||
- "Fixed stuff"
|
||||
- "Updates"
|
||||
|
||||
### Code Review Checklist
|
||||
|
||||
|
||||
+6
-6
@@ -2,7 +2,7 @@
|
||||
|
||||
This document contains ideas, suggestions, and potential enhancements to make MirrorMatch better, faster, and more professional.
|
||||
|
||||
## 🚀 Performance Optimizations
|
||||
## Performance Optimizations
|
||||
|
||||
### Database & Query Optimization
|
||||
- [ ] **Add database indexes** - Create indexes on frequently queried fields (`Photo.createdAt`, `User.points`) to speed up queries
|
||||
@@ -64,7 +64,7 @@ This document contains ideas, suggestions, and potential enhancements to make Mi
|
||||
- [ ] **CDN integration** - Add CDN for static assets and uploaded images to reduce server load
|
||||
- **Why:** Serving files from your server uses bandwidth and slows responses. A CDN serves files from locations closer to users, reducing latency by 50-80% and offloading server load.
|
||||
|
||||
## 🎨 UI/UX Enhancements
|
||||
## UI/UX Enhancements
|
||||
|
||||
### User Interface
|
||||
- [ ] **Dark mode support** - Add dark mode toggle with user preference persistence
|
||||
@@ -128,7 +128,7 @@ This document contains ideas, suggestions, and potential enhancements to make Mi
|
||||
- [ ] **Photo filtering** - Add filters to show: unguessed photos, correct guesses, wrong guesses, and photos by specific users
|
||||
- **Why:** Users want to focus on specific subsets of photos. Filtering helps users find unguessed photos to play, review their performance, or follow specific uploaders, significantly improving usability.
|
||||
|
||||
## 🔒 Security Improvements
|
||||
## Security Improvements
|
||||
|
||||
- [ ] **CSRF protection** - Implement CSRF tokens for all state-changing operations
|
||||
- **Why:** CSRF attacks can trick users into performing unwanted actions. CSRF protection is a security best practice that prevents unauthorized state changes and protects user accounts.
|
||||
@@ -151,7 +151,7 @@ This document contains ideas, suggestions, and potential enhancements to make Mi
|
||||
- [ ] **Audit logging** - Log all admin actions for security auditing and compliance
|
||||
- **Why:** Admin actions can have significant impact. Audit logs provide accountability, help detect unauthorized access, and are essential for security compliance and incident investigation.
|
||||
|
||||
## 📊 Features & Functionality
|
||||
## Features & Functionality
|
||||
|
||||
### Game Mechanics
|
||||
- [ ] **Streak tracking** - Track consecutive correct guesses and display current streak
|
||||
@@ -208,7 +208,7 @@ This document contains ideas, suggestions, and potential enhancements to make Mi
|
||||
- [ ] **Photo approval workflow** - Add optional admin approval workflow (can be toggled on/off)
|
||||
- **Why:** Content moderation ensures quality and safety. An approval workflow lets admins control what goes public, prevents inappropriate content, and maintains content standards.
|
||||
|
||||
## 🧪 Testing & Quality
|
||||
## Testing & Quality
|
||||
|
||||
- [ ] **Increase test coverage** - Expand test coverage to all critical paths and edge cases
|
||||
- **Why:** Bugs in production are expensive and damage trust. Comprehensive tests catch issues early, reduce regressions, and give confidence when making changes.
|
||||
@@ -237,7 +237,7 @@ This document contains ideas, suggestions, and potential enhancements to make Mi
|
||||
- [ ] **Error logging and monitoring** - Create comprehensive error logging and monitoring system
|
||||
- **Why:** You can't fix what you can't see. Error monitoring catches production bugs, provides context for debugging, and helps prioritize fixes based on impact.
|
||||
|
||||
## 🔧 Technical Improvements
|
||||
## Technical Improvements
|
||||
|
||||
### Architecture
|
||||
- [ ] **Microservices migration** - Consider migrating to microservices if scale requires it
|
||||
|
||||
@@ -1,348 +1,59 @@
|
||||
# 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.
|
||||
Photo guessing game: upload a photo, others guess who is in it, points on
|
||||
the leaderboard. Next.js, PostgreSQL, Prisma, NextAuth.
|
||||
|
||||
## 📚 Important: Read Documentation First
|
||||
Status: active. MIT. See [LICENSE](LICENSE).
|
||||
|
||||
**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
|
||||
## Setup
|
||||
|
||||
**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
|
||||
cd mirrormatch # or mirror_match
|
||||
npm install
|
||||
cp .env.example .env # if present; otherwise create .env
|
||||
```
|
||||
|
||||
3. **Set up environment variables**:
|
||||
Create a `.env` file in the root directory with the following variables:
|
||||
Required env (placeholders):
|
||||
|
||||
```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>"
|
||||
NEXTAUTH_SECRET="$(openssl rand -base64 32)"
|
||||
# Production email:
|
||||
# SMTP_HOST= SMTP_PORT= SMTP_USER= SMTP_PASSWORD= SMTP_FROM=
|
||||
```
|
||||
|
||||
**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
|
||||
npm run db:migrate # or npm run db:push for quick local
|
||||
npm run db:seed # default admin: admin@mirrormatch.com / admin123 — change it
|
||||
npm run dev # http://localhost:3000
|
||||
```
|
||||
|
||||
5. **Seed the database** (creates default admin user):
|
||||
```bash
|
||||
npm run db:seed
|
||||
```
|
||||
Dev mail can use Ethereal or console; SMTP is for production.
|
||||
|
||||
This creates an admin user with:
|
||||
- Email: `admin@mirrormatch.com`
|
||||
- Password: `admin123`
|
||||
- **⚠️ Important**: Change this password after first login!
|
||||
## What it does
|
||||
|
||||
## Basic Usage
|
||||
- Admin creates users (email/password)
|
||||
- Users upload photos with an answer name
|
||||
- Others guess for points; leaderboard ranks scores
|
||||
- Optional email when new photos land
|
||||
- Profile: view points, change password
|
||||
|
||||
### Workflow Overview
|
||||
## Docs
|
||||
|
||||
1. **Admin creates users:**
|
||||
- Admin logs in and navigates to `/admin`
|
||||
- Creates new users with email, password, and role
|
||||
- Users receive temporary passwords
|
||||
| Doc | Purpose |
|
||||
|-----|---------|
|
||||
| [ARCHITECTURE.md](ARCHITECTURE.md) | Design |
|
||||
| [CONTRIBUTING.md](CONTRIBUTING.md) | Conventions |
|
||||
| [SECURITY.md](SECURITY.md) | Security practices |
|
||||
| [TESTING.md](TESTING.md) | Tests |
|
||||
| `.cursor/rules/mirrormatch.mdc` | Agent rules |
|
||||
|
||||
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
|
||||
## Production
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
NODE_ENV=production npm run build && npm start
|
||||
```
|
||||
|
||||
Open [http://localhost:3000](http://localhost:3000) in your browser.
|
||||
|
||||
### Production
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
npm start
|
||||
```
|
||||
|
||||
### Deployment Notes
|
||||
|
||||
**Important Configuration:**
|
||||
- Ensure `NODE_ENV=production` is set in production
|
||||
- Set `NEXTAUTH_URL` to your production domain (e.g., `https://yourdomain.com`)
|
||||
- Set `AUTH_TRUST_HOST=true` if using reverse proxy
|
||||
- Ensure `DATABASE_URL` points to your production database
|
||||
- Files are stored in `public/uploads/` directory - ensure this directory persists across deployments
|
||||
|
||||
**File Uploads:**
|
||||
- Photos are uploaded to `public/uploads/` directory
|
||||
- Files are served via `/api/uploads/[filename]` API route
|
||||
- Ensure the uploads directory has proper write permissions
|
||||
|
||||
**Upload Endpoints:**
|
||||
- `POST /api/photos/upload` - Single photo upload (supports both file and URL uploads)
|
||||
- `POST /api/photos/upload-multiple` - Multiple photo uploads in batch (used by upload page)
|
||||
- Files are stored on the filesystem (not in database)
|
||||
|
||||
**Monitoring Activity:**
|
||||
- User activity is logged to console/systemd logs
|
||||
- Watch logs in real-time: `sudo journalctl -u app-backend -f | grep -E "\[ACTIVITY\]|\[PHOTO_UPLOAD\]|\[GUESS_SUBMIT\]"`
|
||||
- Activity logs include: page visits, photo uploads, guess submissions
|
||||
- **Note:** For local development, use `./watch-activity.sh` script (if systemd/journalctl is not available, check application logs directly)
|
||||
|
||||
## 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
|
||||
|
||||
### Querying the Database
|
||||
|
||||
**Get all photo answers:**
|
||||
```bash
|
||||
psql "postgresql://user:password@host:5432/database" -c "SELECT \"answerName\" FROM \"Photo\" ORDER BY \"createdAt\" DESC;"
|
||||
```
|
||||
|
||||
**Get answers with uploader info:**
|
||||
```bash
|
||||
psql "postgresql://user:password@host:5432/database" -c "SELECT p.\"answerName\", p.url, u.name as uploader, p.\"createdAt\" FROM \"Photo\" p JOIN \"User\" u ON p.\"uploaderId\" = u.id ORDER BY p.\"createdAt\" DESC;"
|
||||
```
|
||||
|
||||
## 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 file upload or URL
|
||||
- Files are stored in `public/uploads/` directory
|
||||
- Files are served via `/api/uploads/[filename]` API route
|
||||
- Set answer name for guessing
|
||||
- Automatically sends email notifications to all other users
|
||||
- Duplicate file detection (SHA256 hash)
|
||||
|
||||
### 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
|
||||
- Set `AUTH_TRUST_HOST=true` if using reverse proxy
|
||||
- Clear browser cookies if needed
|
||||
- Check middleware logs: `sudo journalctl -u app-backend | grep "Middleware"`
|
||||
|
||||
### Photo Upload Issues
|
||||
- Verify `public/uploads/` directory exists and has write permissions
|
||||
- Check file upload logs: `sudo journalctl -u app-backend | grep "UPLOAD"`
|
||||
- Ensure files are being saved: check `public/uploads/` directory
|
||||
- Files are served via `/api/uploads/[filename]` - verify API route is accessible
|
||||
|
||||
### Build Issues
|
||||
- If build fails with `DATABASE_URL not set`, this is expected - Prisma initialization is lazy
|
||||
- Ensure all environment variables are set in production
|
||||
- Check for TypeScript errors: `npm run type-check`
|
||||
|
||||
## 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
|
||||
Set real `NEXTAUTH_SECRET`, SMTP, and rotate the seeded admin password.
|
||||
|
||||
+6
-6
@@ -167,12 +167,12 @@ When adding new features, ensure:
|
||||
## Known Security Considerations
|
||||
|
||||
**Current Implementation:**
|
||||
- ✅ Passwords hashed with bcrypt
|
||||
- ✅ Session management via NextAuth
|
||||
- ✅ Route protection via middleware
|
||||
- ✅ Role-based access control
|
||||
- ✅ Input validation on server side
|
||||
- ✅ SQL injection prevention via Prisma
|
||||
- Passwords hashed with bcrypt
|
||||
- Session management via NextAuth
|
||||
- Route protection via middleware
|
||||
- Role-based access control
|
||||
- Input validation on server side
|
||||
- SQL injection prevention via Prisma
|
||||
|
||||
**Future Considerations:**
|
||||
- Consider rate limiting for API routes
|
||||
|
||||
+8
-8
@@ -6,10 +6,10 @@ This guide will help you set up and test the MirrorMatch application locally.
|
||||
|
||||
Before starting, ensure you have:
|
||||
|
||||
- ✅ **Node.js 18+** installed (`node --version`)
|
||||
- ✅ **npm** installed (`npm --version`)
|
||||
- ✅ **PostgreSQL** installed and running (`psql --version`)
|
||||
- ✅ **Git** (if cloning the repository)
|
||||
- **Node.js 18+** installed (`node --version`)
|
||||
- **npm** installed (`npm --version`)
|
||||
- **PostgreSQL** installed and running (`psql --version`)
|
||||
- **Git** (if cloning the repository)
|
||||
|
||||
## Step-by-Step Setup
|
||||
|
||||
@@ -99,7 +99,7 @@ This creates the default admin user:
|
||||
- **Email:** `admin@mirrormatch.com`
|
||||
- **Password:** `admin123`
|
||||
|
||||
⚠️ **Important:** Change this password after first login!
|
||||
**Important:** Change this password after first login!
|
||||
|
||||
### 6. Start the Development Server
|
||||
|
||||
@@ -213,7 +213,7 @@ npm run db:generate
|
||||
**Error:** `Migration failed`
|
||||
|
||||
**Solutions:**
|
||||
- Reset database (⚠️ deletes all data):
|
||||
- Reset database ( deletes all data):
|
||||
```bash
|
||||
npm run db:push -- --force-reset
|
||||
```
|
||||
@@ -274,7 +274,7 @@ Opens a GUI at [http://localhost:5555](http://localhost:5555) to browse and edit
|
||||
|
||||
### Reset Database
|
||||
|
||||
⚠️ **Warning:** This deletes all data!
|
||||
**Warning:** This deletes all data!
|
||||
|
||||
```bash
|
||||
npm run db:push -- --force-reset
|
||||
@@ -317,4 +317,4 @@ After testing locally:
|
||||
|
||||
---
|
||||
|
||||
**Happy Testing! 🎯**
|
||||
**Happy Testing! **
|
||||
|
||||
Reference in New Issue
Block a user