Production Deployment Fixes and Enhancements (#3)

# Merge Request: Production Deployment Fixes and Enhancements

## Summary

This MR includes critical fixes for production deployment, authentication improvements, file upload serving, and monitoring capabilities. All changes have been tested and are ready for production.

## 🐛 Critical Fixes

### 1. Authentication & Session Management
- **Fixed TypeScript error in session callback** (`lib/auth.ts`)
  - Removed `return null` that caused build failures
  - Session callback now always returns a valid session object
- **Fixed login redirect loop** (`app/login/page.tsx`)
  - Changed from `router.push()` to `window.location.href` for full page reload
  - Ensures session cookie is available before middleware checks
- **Created proper middleware** (`proxy.ts`)
  - Next.js 16 requires `proxy.ts` instead of `middleware.ts`
  - Fixed authentication checks in Edge runtime
  - Explicitly specifies cookie name for `getToken`

### 2. Build & Deployment
- **Fixed Prisma initialization** (`lib/prisma.ts`)
  - Made Prisma client initialization lazy to fix build without DATABASE_URL
  - Uses Proxy pattern for on-demand initialization
  - Prevents build failures when DATABASE_URL not set

### 3. File Upload & Serving
- **Fixed photo upload serving** (`app/api/uploads/[filename]/route.ts`)
  - Created dedicated API route to serve uploaded files
  - Files now served via `/api/uploads/[filename]` instead of static `/uploads/`
  - Ensures files are accessible regardless of filesystem location
  - Added file existence verification and proper error handling
- **Updated upload routes** to use new API endpoint
  - `app/api/photos/upload/route.ts` - Updated to use `/api/uploads/` URLs
  - `app/api/photos/upload-multiple/route.ts` - Updated to use `/api/uploads/` URLs
- **Fixed photo display components**
  - `components/PhotoThumbnail.tsx` - Uses regular `img` tag for uploads
  - `components/PhotoImage.tsx` - Uses regular `img` tag for uploads
  - Avoids Next.js Image component issues with dynamically uploaded files

### 4. Middleware & Route Protection
- **Updated proxy middleware** (`proxy.ts`)
  - Added `/uploads` and `/api/uploads` to public routes
  - Added comprehensive activity logging
  - Improved error handling and logging

## ✨ New Features

### Activity Logging
- **Created activity logging utility** (`lib/activity-log.ts`)
  - Structured logging for user actions
  - Tracks: page visits, photo uploads, guess submissions
  - Includes user info, IP, timestamps, and action details
- **Added activity logging to key routes**
  - `proxy.ts` - Logs all page visits and API calls
  - `app/api/photos/upload/route.ts` - Logs photo uploads
  - `app/api/photos/[photoId]/guess/route.ts` - Logs guess submissions

### Monitoring
- **Activity monitoring commands**
  - Watch logs: `sudo journalctl -u app-backend -f | grep -E "\[ACTIVITY\]|\[PHOTO_UPLOAD\]|\[GUESS_SUBMIT\]"`
  - Filter by user, action type, or time range

## 📝 Documentation Updates

- **README.md**
  - Added deployment notes section
  - Added file upload details and troubleshooting
  - Added activity monitoring commands
  - Added database query examples
  - Updated troubleshooting section

- **ARCHITECTURE.md**
  - Updated middleware references (proxy.ts instead of middleware.ts)
  - Added activity logging documentation
  - Updated photo upload flow with file upload details
  - Added file serving architecture
  - Updated guess submission flow

- **CLEANUP.md** (new)
  - Created cleanup checklist for future improvements
  - Documents debug code and verbose logging
  - Provides recommendations for optimization

## 🔧 Technical Changes

### Files Modified
- `lib/auth.ts` - Fixed session callback return type
- `app/login/page.tsx` - Fixed redirect to use full page reload
- `proxy.ts` - Created/updated middleware with activity logging
- `lib/prisma.ts` - Made initialization lazy
- `app/api/photos/upload/route.ts` - Updated file serving, added logging
- `app/api/photos/upload-multiple/route.ts` - Updated file serving
- `components/PhotoThumbnail.tsx` - Fixed image display
- `components/PhotoImage.tsx` - Fixed image display

### Files Created
- `app/api/uploads/[filename]/route.ts` - File serving API route
- `lib/activity-log.ts` - Activity logging utility
- `CLEANUP.md` - Cleanup checklist

## ✅ Testing

- [x] Authentication flow tested (login, session persistence)
- [x] Photo upload tested (file and URL uploads)
- [x] Photo display tested (uploaded files visible to all users)
- [x] Guess submission tested
- [x] Build tested (no TypeScript errors)
- [x] Middleware tested (route protection working)
- [x] Activity logging verified

## 🚀 Deployment Notes

### Environment Variables Required
- `NODE_ENV=production`
- `NEXTAUTH_URL` - Production domain
- `NEXTAUTH_SECRET` - Secret key
- `AUTH_TRUST_HOST=true` (if using reverse proxy)
- `DATABASE_URL` - Production database connection

### Post-Deployment
1. Verify `public/uploads/` directory exists and has write permissions
2. Test photo upload and verify files are accessible
3. Monitor activity logs to ensure logging is working
4. Verify authentication flow works correctly

### Monitoring
- Watch activity logs: `sudo journalctl -u app-backend -f | grep -E "\[ACTIVITY\]|\[PHOTO_UPLOAD\]|\[GUESS_SUBMIT\]"`
- Check for errors: `sudo journalctl -u app-backend --since "1 hour ago" | grep -i error`

## 🔄 Breaking Changes

**None** - All changes are backward compatible. Existing photos with `/uploads/` URLs may need to be updated to `/api/uploads/` if files are not accessible, but the system will continue to work.

## 📋 Migration Notes

### For Existing Photos
- Photos uploaded before this change use `/uploads/` URLs
- New photos use `/api/uploads/` URLs
- Old photos will continue to work if files exist in `public/uploads/`
- Consider migrating old photo URLs if needed (optional)

## 🎯 Next Steps (Future)

See `CLEANUP.md` for recommended cleanup tasks:
- Reduce verbose logging in production
- Add log levels (DEBUG, INFO, WARN, ERROR)
- Protect debug endpoints
- Optimize activity logging

---

**Ready for Production:** ✅ Yes
**Breaking Changes:** ❌ No
**Requires Migration:** ⚠️ Optional (old photo URLs)

Reviewed-on: #3

ARCHITECTURE.md

@@ -26,16 +26,19 @@ mirrormatch/
 │   ├── Navigation.tsx   # Navigation bar (client component)
 │   └── [others]         # Form components, UI components
 ├── lib/                   # Utility libraries and helpers
-│   ├── prisma.ts        # Prisma client singleton
+│   ├── prisma.ts        # Prisma client singleton (lazy initialization)
 │   ├── auth.ts          # NextAuth configuration
 │   ├── email.ts         # Email sending utilities
-│   └── utils.ts         # Helper functions (hashing, etc.)
+│   ├── utils.ts         # Helper functions (hashing, etc.)
+│   └── activity-log.ts  # Activity logging utility
 ├── prisma/                # Database schema and migrations
 │   ├── schema.prisma     # Prisma schema definition
 │   └── seed.ts          # Database seeding script
 ├── types/                 # TypeScript type definitions
 │   └── next-auth.d.ts   # NextAuth type extensions
-└── middleware.ts         # Next.js middleware for route protection
+├── proxy.ts              # Next.js proxy/middleware for route protection (Next.js 16)
+└── lib/
+    └── activity-log.ts  # Activity logging utility
 ```
 
 ## Data Model
@@ -153,21 +156,31 @@ model Guess {
 
 ### Route Protection
 
-**Location:** `middleware.ts`
+**Location:** `proxy.ts` (Next.js 16 uses `proxy.ts` instead of `middleware.ts`)
 
 **Public Routes:**
 - `/login`
 - `/api/auth/*` (NextAuth endpoints)
+- `/uploads/*` (uploaded files - legacy, now served via API)
+- `/api/uploads/*` (uploaded files served via API route)
 
 **Protected Routes:**
 - All other routes require authentication
 - `/admin/*` routes additionally require `role === "ADMIN"`
 
 **Implementation:**
-- Uses NextAuth `withAuth` middleware
-- Checks JWT token on each request
-- Redirects unauthenticated users to `/login`
+- Uses NextAuth `getToken` from `next-auth/jwt` in Edge runtime
+- Checks JWT token on each request via `proxy.ts`
+- Explicitly specifies cookie name: `__Secure-authjs.session-token`
+- Redirects unauthenticated users to `/login` with `callbackUrl`
 - Redirects non-admin users trying to access admin routes to home
+- Logs all user activity (page visits, API calls)
+
+**Activity Logging:**
+- All authenticated requests are logged with user info, IP, path, method
+- Unauthenticated access attempts are also logged
+- Photo uploads and guess submissions have dedicated activity logs
+- Logs format: `[ACTIVITY] timestamp | method path | User: email (role) | IP: ip`
 
 ## Application Flows
 
@@ -219,16 +232,37 @@ model Guess {
 
 **Flow:**
 1. User navigates to `/upload`
-2. Enters photo URL and answer name
-3. Form submits to `POST /api/photos`
+2. Uploads photo file or enters photo URL and answer name
+3. Form submits to `POST /api/photos/upload` (file upload) or `POST /api/photos` (URL)
 4. API route:
    - Verifies session
-   - Creates Photo record with `uploaderId`, `url`, `answerName`
+   - For file uploads:
+     - Validates file type and size (max 10MB)
+     - Calculates SHA256 hash for duplicate detection
+     - Generates unique filename: `timestamp-randomstring.extension`
+     - Saves file to `public/uploads/` directory
+     - Sets photo URL to `/api/uploads/[filename]`
+   - For URL uploads:
+     - Validates URL format
+     - Checks for duplicate URLs
+     - Uses provided URL directly
+   - Creates Photo record with `uploaderId`, `url`, `answerName`, `fileHash`
    - Queries all other users (excluding uploader)
    - Sends email notifications to all other users (async, non-blocking)
+   - Logs activity: `[PHOTO_UPLOAD]`
 5. User redirected to photo detail page
 
-**API Route:** `app/api/photos/route.ts`
+**API Routes:**
+- `app/api/photos/upload/route.ts` - File upload endpoint
+- `app/api/photos/route.ts` - URL upload endpoint (legacy)
+- `app/api/uploads/[filename]/route.ts` - Serves uploaded files
+
+**File Storage:**
+- Files stored in `public/uploads/` directory
+- Served via `/api/uploads/[filename]` API route
+- Files verified after write to ensure successful save
+- Duplicate detection via SHA256 hash
+
 **Email:** `lib/email.ts` - `sendNewPhotoEmail()`
 **Page:** `app/upload/page.tsx` (client component)
 
@@ -260,10 +294,13 @@ model Guess {
 4. API route:
    - Verifies session
    - Checks if user already has correct guess (prevent duplicate points)
+   - Prevents users from guessing their own photos
    - Normalizes guess text and answer (trim, lowercase)
    - Compares normalized strings
    - Creates Guess record with `correct` boolean
-   - If correct: increments user's points by 1
+   - If correct: increments user's points by photo's `points` value
+   - If wrong and penalty enabled: deducts penalty points
+   - Logs activity: `[GUESS_SUBMIT]` with result
 5. Page refreshes to show feedback
 
 **API Route:** `app/api/photos/[photoId]/guess/route.ts`
@@ -274,6 +311,7 @@ model Guess {
 - Case-insensitive comparison
 - Trims whitespace
 - Exact match required (no fuzzy matching)
+- Points awarded based on photo's `points` field (default: 1)
 
 ### 7. Leaderboard