# PunimTag Photo Viewer - Setup Instructions

## ✅ What's Been Completed

1. ✅ Next.js 14 project created with TypeScript and Tailwind CSS
2. ✅ Core dependencies installed:
   - Prisma ORM
   - TanStack Query
   - React Photo Album
   - Yet Another React Lightbox
   - Lucide React (icons)
   - Framer Motion (animations)
   - Date-fns (date handling)
   - shadcn/ui components (button, input, select, calendar, popover, badge, checkbox, tooltip)
3. ✅ Prisma schema created matching PunimTag database structure
4. ✅ Database connection utility created (`lib/db.ts`)
5. ✅ Initial home page with photo grid component
6. ✅ Next.js image optimization configured
7. ✅ shadcn/ui initialized
8. ✅ **Collapsible search bar** on main page
9. ✅ **Search functionality** - Search by people, dates, and tags
10. ✅ **Search API endpoint** (`/api/search`)
11. ✅ **Search page** at `/search`
12. ✅ **Photo tooltips** showing people names on hover
13. ✅ **Filter components** - People, Date Range, and Tag filters

## 🔧 Next Steps to Complete Setup

### 1. Configure Database Connection

Create a `.env` file in the project root:

```bash
DATABASE_URL="postgresql://viewer_readonly:your_password@localhost:5432/punimtag"
NEXT_PUBLIC_SITE_NAME="PunimTag Photo Viewer"
NEXT_PUBLIC_SITE_DESCRIPTION="Family Photo Gallery"
```

**Important:** Replace `your_password` with the actual password for the read-only database user.

### 2. Create Read-Only Database User (if not already done)

Connect to your PostgreSQL database and run:

```sql
-- Create read-only user
CREATE USER viewer_readonly WITH PASSWORD 'your_secure_password';

-- Grant permissions
GRANT CONNECT ON DATABASE punimtag TO viewer_readonly;
GRANT USAGE ON SCHEMA public TO viewer_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO viewer_readonly;

-- Grant on future tables
ALTER DEFAULT PRIVILEGES IN SCHEMA public 
GRANT SELECT ON TABLES TO viewer_readonly;

-- Verify no write permissions
REVOKE INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public FROM viewer_readonly;
```

### 3. Install System Dependencies (Optional but Recommended)

**For Image Watermarking (libvips):**
```bash
# Ubuntu/Debian
sudo apt update
sudo apt install libvips-dev

# Rebuild sharp package after installing libvips
cd viewer-frontend
npm rebuild sharp
```

**For Video Thumbnails (FFmpeg):**
```bash
# Ubuntu/Debian
sudo apt install ffmpeg
```

**Note:** The application will work without these, but:
- Without libvips: Images will be served without watermarks
- Without FFmpeg: Videos will show placeholder thumbnails

### 4. Generate Prisma Client

```bash
cd /home/ladmin/Code/punimtag-viewer
npx prisma generate
```

### 5. Test Database Connection

```bash
# Optional: Open Prisma Studio to browse database
npx prisma studio
```

### 6. Run Development Server

```bash
npm run dev
```

Open http://localhost:3000 in your browser.

## ⚠️ Known Issues

### Node.js Version Warning

The project was created with Next.js 16, which requires Node.js >=20.9.0, but the system currently has Node.js 18.19.1.

**Solutions:**

1. **Upgrade Node.js** (Recommended):
   ```bash
   # Using nvm (Node Version Manager)
   nvm install 20
   nvm use 20
   ```

2. **Or use Next.js 14** (if you prefer to stay on Node 18):
   ```bash
   npm install next@14 react@18 react-dom@18
   ```

## 📁 Project Structure

```
punimtag-viewer/
├── app/
│   ├── layout.tsx          # Root layout with Inter font
│   ├── page.tsx             # Home page (server component)
│   ├── HomePageContent.tsx  # Home page client component with search
│   ├── search/              # Search page
│   │   ├── page.tsx         # Search page (server component)
│   │   └── SearchContent.tsx # Search content (client component)
│   ├── api/                 # API routes
│   │   ├── search/          # Search API endpoint
│   │   │   └── route.ts     # Search route handler
│   │   └── photos/          # Photo API endpoints
│   └── globals.css          # Global styles (updated by shadcn)
├── components/
│   ├── PhotoGrid.tsx        # Photo grid with tooltips
│   ├── search/              # Search components
│   │   ├── CollapsibleSearch.tsx # Collapsible search bar
│   │   ├── FilterPanel.tsx  # Filter panel container
│   │   ├── PeopleFilter.tsx # People filter component
│   │   ├── DateRangeFilter.tsx # Date range filter
│   │   ├── TagFilter.tsx    # Tag filter component
│   │   └── SearchBar.tsx    # Search bar (for future text search)
│   └── ui/                  # shadcn/ui components
│       ├── button.tsx
│       ├── input.tsx
│       ├── select.tsx
│       ├── calendar.tsx
│       ├── popover.tsx
│       ├── badge.tsx
│       ├── checkbox.tsx
│       └── tooltip.tsx
├── lib/
│   ├── db.ts               # Prisma client
│   ├── queries.ts          # Database query helpers
│   └── utils.ts            # Utility functions (from shadcn)
├── prisma/
│   └── schema.prisma        # Database schema
└── .env                     # Environment variables (create this)
```

## 🎨 Adding shadcn/ui Components

To add UI components as needed:

```bash
npx shadcn@latest add button
npx shadcn@latest add card
npx shadcn@latest add input
npx shadcn@latest add dialog
# ... etc
```

## 🚀 Next Development Steps

After setup is complete, follow the Quick Start Guide to add:

1. **Photo Detail Page** - Individual photo view with lightbox
2. **People Browser** - Browse photos by person
3. **Tags Browser** - Browse photos by tag
4. **Infinite Scroll** - Load more photos as user scrolls
5. **Favorites System** - Allow users to favorite photos

## ✨ Current Features

### Search & Filtering
- ✅ **Collapsible Search Bar** on main page
  - Minimized by default, click to expand
  - Shows active filter count badge
  - Real-time photo filtering
  
- ✅ **Search Filters**
  - People filter with searchable dropdown
  - Date range filter with presets and custom range
  - Tag filter with searchable dropdown
  - All filters work together (AND logic)

- ✅ **Search Page** (`/search`)
  - Full search interface
  - URL query parameter sync
  - Pagination support

### Photo Display
- ✅ **Photo Tooltips**
  - Hover over photos to see people names
  - Shows "People: Name1, Name2" format
  - Falls back to filename if no people identified

- ✅ **Photo Grid**
  - Responsive grid layout
  - Optimized image loading
  - Hover effects

## 📚 Documentation

- **Quick Start Guide:** `/home/ladmin/Code/punimtag/docs/PHOTO_VIEWER_QUICKSTART.md`
- **Complete Plan:** `/home/ladmin/Code/punimtag/docs/PHOTO_VIEWER_PLAN.md`
- **Architecture:** `/home/ladmin/Code/punimtag/docs/PHOTO_VIEWER_ARCHITECTURE.md`

## 🆘 Troubleshooting

### "Can't connect to database"
- Check `.env` file has correct `DATABASE_URL`
- Verify database is running
- Test connection: `psql -U viewer_readonly -d punimtag -h localhost`

### "Prisma Client not generated"
- Run: `npx prisma generate`

### "Module not found: @/..."
- Check `tsconfig.json` has `"@/*": ["./*"]` in paths

### "Images not loading"

**For File System Paths:**
- Verify photo file paths in database are accessible from the Next.js server
- Check that the API route (`/api/photos/[id]/image`) is working
- Check server logs for file not found errors

**For HTTP/HTTPS URLs (SharePoint, CDN):**
- Verify the URL format in database (should start with `http://` or `https://`)
- Check `next.config.ts` has the domain configured in `remotePatterns`
- For SharePoint Online: `**.sharepoint.com` is already configured
- For on-premises SharePoint: Uncomment and update the hostname in `next.config.ts`
- Verify the URLs are publicly accessible or authentication is configured

---

**Project Location:** `/home/ladmin/Code/punimtag-viewer`

**Ready to continue development!** 🚀