punimtag/viewer-frontend/SETUP.md

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:

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:

-- 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):

# 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):

# 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

cd /path/to/punimtag/viewer-frontend
npx prisma generate

5. Test Database Connection

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

6. Run Development Server

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):

   # 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):

   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:

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: /path/to/punimtag/docs/PHOTO_VIEWER_QUICKSTART.md
• Complete Plan: /path/to/punimtag/docs/PHOTO_VIEWER_PLAN.md
• Architecture: /path/to/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: /path/to/punimtag/viewer-frontend

Ready to continue development! 🚀