Photography Portfolio & CMS

Overview

Photography Portfolio & CMS is a complete, full-stack web application built specifically for photographers, studios, and creative professionals. It ships with everything you need out of the box:

• A beautifully designed public website with a homepage, photo gallery with category filters, photography stories, about page, and a contact form.
• A feature-rich Admin Dashboard for managing gallery photos, categories, stories, team members, testimonials, banners, services, contact submissions, and all site settings — without touching any code.
• A robust REST API layer with JWT-based authentication, Zod validation, and a consistent response format.
• Cloudinary integration for image hosting and CDN delivery, configured entirely from the admin panel.
• MongoDB as the database with Mongoose ODM, optimised for serverless environments with connection pooling.

Features

Public Website

Admin Dashboard

Technology Stack

Requirements

Installation & Setup

Step 1 — Extract Files

unzip template-photography.zip -d template-photography
cd template-photography

Step 2 — Install Dependencies

npm install

Step 3 — Configure Environment Variables

cp .env.example .env
# Then edit .env with your actual values

See the Environment Variables section for all required values.

Step 4 — Set Up MongoDB

Create a free cluster on MongoDB Atlas, create a database user with read/write access, whitelist your IP (or 0.0.0.0/0 for all), and copy the connection string into MONGODB_URI.

Step 5 — Create Initial Admin User

Connect to your MongoDB database (via Atlas UI or Compass) and insert a document into the users collection:

{
  "name": "Admin",
  "email": "admin@example.com",
  "password": "<bcrypt-hashed-password>",
  "role": "admin"
}

Step 6 — Configure Cloudinary (After First Login)

Log into the admin dashboard and navigate to Admin → Settings → Cloudinary. Enter your Cloud Name, API Key, API Secret, and folder name, then save.

Step 7 — Start Development Server

npm run dev

Open http://localhost:3000 for the portfolio site. The admin dashboard is at http://localhost:3000/admin/login. Documentation is at http://localhost:3000/documentation.

Environment Variables

Create a .env file in the project root with the following variables:

# ── App ────────────────────────────────────────────────────────
# Public base URL used for internal API calls
NEXT_PUBLIC_BASE_URL=http://localhost:3000

# ── Authentication ──────────────────────────────────────────────
# Set true when running behind a proxy or on platforms like Vercel
AUTH_TRUST_HOST=true

# NextAuth callback URL — must match your deployment domain
NEXTAUTH_URL=http://localhost:3000

# Secret key for signing JWT tokens
# Generate: openssl rand -base64 32
NEXTAUTH_SECRET=your_strong_random_secret_min_32_chars

# ── Database ────────────────────────────────────────────────────
MONGODB_URI=mongodb+srv://<user>:<password>@cluster.mongodb.net/photography

Running the Application

Project Structure

Pages & Routes

Public Pages

Admin Dashboard Pages (Protected)

All admin routes are under /admin/dashboard/ and require a valid authentication session.

Authentication

The template uses NextAuth v5 with a JWT strategy. The middleware in proxy.ts protects all routes under /admin/* and /api/admin/*.

Authentication Flow

1. Admin submits email and password at /admin/login.
2. Server looks up the user by email and compares the password using bcrypt.
3. On success, a JWT access token is returned and stored in the NextAuth session.
4. lib/api-client.ts automatically injects the Bearer token into all admin API requests.
5. All /api/admin/* routes verify the token before processing the request.
6. Unauthenticated requests to protected routes are redirected to /admin/login.

API Reference — Public Endpoints

All API responses use a consistent envelope format:

// Success
{ "success": true, "statusCode": 200, "message": "...", "data": { ... } }

// Error
{ "success": false, "statusCode": 400, "message": "...", "errors": [ ... ] }

Gallery

Stories

Categories & Other Public Endpoints

{ "name": "Alice Johnson", "email": "alice@example.com",
  "phone": "+1234567890", "message": "I'm interested in wedding photography.",
  "category": "Wedding" }

API Reference — Admin Authentication

// Request
{ "email": "admin@example.com", "password": "your_password" }

// Response
{
  "success": true,
  "data": {
    "token": "eyJhbGci...",
    "user": { "name": "Admin", "email": "admin@example.com", "role": "admin" }
  }
}

{ "currentPassword": "old_password", "newPassword": "new_password" }

API Reference — Gallery

// Create Gallery Item — Request Body
{
  "image": "https://res.cloudinary.com/...",
  "title": "Golden Hour Portrait",
  "author": "Jane Smith",
  "category": "portrait",
  "status": true,
  "isFeatured": false
}

// Sort — Request Body
{ "items": [{ "id": "item_id", "orderBy": 1 }, ...] }

API Reference — Categories

// Create Category — Request Body
{
  "name": "Portrait",
  "slug": "portrait",
  "status": true,
  "featured": false,
  "parent": null  // ObjectId for sub-category, null for root
}

API Reference — Stories

// Create Story — Request Body
{
  "title": "Golden Sunset Wedding",
  "slug": "golden-sunset-wedding",
  "description": "<p>Rich HTML content from SunEditor...</p>",
  "image": "https://res.cloudinary.com/...",
  "photos": ["url1", "url2"],
  "client": "Sarah & James",
  "photographer": "Jane Smith",
  "mood": "Romantic",
  "category": ["categoryObjectId"],
  "camera": "Sony A7R IV",
  "shutterSpeed": "1/500s",
  "lensUsed": "85mm f/1.4",
  "focus": ["Natural light", "Bokeh"],
  "approach": ["Candid moments", "Golden hour"],
  "eventDate": "2024-06-15",
  "isFeatured": true,
  "status": true
}

API Reference — Banner

// Create Banner — Request Body
{
  "sectionName": "gallery-hero",
  "heading": "Our Photography",
  "shortDesc": "Capturing moments that last a lifetime",
  "categories": "Wedding, Portrait",
  "position": 1,
  "status": true
}

API Reference — Team

// Create Team Member — Request Body
{
  "name": "Jane Smith",
  "designation": "Lead Photographer",
  "image": "https://res.cloudinary.com/...",
  "status": true
}

API Reference — Testimonial

// Create Testimonial — Request Body
{
  "quote": "The photos were absolutely stunning. Highly recommended!",
  "authorName": "Sarah Johnson",
  "authorRole": "Wedding Client",
  "order": 1,
  "status": true
}

API Reference — Contact

API Reference — Service Gallery

// Create Service — Request Body
{
  "heading": "Wedding Photography",
  "shortDesc": "Timeless wedding moments captured with elegance.",
  "image": "https://res.cloudinary.com/...",
  "position": 1,
  "status": true
}

API Reference — Home Sections

Section Keys: hero, about, services, gallery, testimonials, cta

API Reference — File Upload

// Response
{
  "success": true,
  "url": "https://res.cloudinary.com/your-cloud/image/upload/v1234/folder/file.jpg",
  "publicId": "folder/file"
}

API Reference — Settings

API Reference — Dashboard Stats

// Response
{
  "success": true,
  "data": {
    "gallery": 124,
    "stories": 18,
    "contacts": 45,
    "teams": 6,
    "testimonials": 12
  }
}

Database Models

User

{ name: String, email: String (unique), password: String (bcrypt), role: "admin" | "user" }

Gallery

{ image: String, title: String, author: String, category: String,
  status: Boolean, isFeatured: Boolean, orderBy: Number }

Category

{ name: String, slug: String (unique), status: Boolean, featured: Boolean,
  position: Number, parent: ObjectId (nullable) }

Stories

{ title: String, slug: String (unique), description: String (HTML),
  image: String, photos: [String], client: String, photographer: String,
  mood: String, category: [ObjectId], camera: String, shutterSpeed: String,
  lensUsed: String, focus: [String], approach: [String],
  eventDate: Date, isFeatured: Boolean, status: Boolean }

Team

{ name: String, designation: String, image: String, status: Boolean }

Testimonial

{ quote: String, authorName: String, authorRole: String, order: Number, status: Boolean }

ContactUs

{ name: String, email: String, phone: String, message: String, category: String, status: Boolean }

ServiceGallery

{ heading: String, shortDesc: String, image: String, position: Number, status: Boolean }

Settings (single document)

{ general: { companyName, companyPhone, companyAddress, supportEmail, ownerName, ownerEmail,
              logo, favicon, facebook, instagram, twitter, youtube },
  cloudinary: { cloudName, apiKey, apiSecret, folder, secureUrlBase },
  metadata:   { title, applicationName, description, keywords: [String], openGraphImage },
  termsPolicy:{ terms: String (HTML), policy: String (HTML) },
  businessHours: [{ dayOfWeek: 0-6, openTime: Number, closeTime: Number, isClosed: Boolean }] }

Image Management

Upload Flow

1. Admin selects file(s) in any dashboard form.
2. Frontend sends the file to POST /api/admin/file.
3. Server streams the file to Cloudinary via upload_stream.
4. Cloudinary returns a secure CDN URL.
5. The URL is stored in the MongoDB document field.

Cloudinary Configuration

Credentials are loaded dynamically from the Settings database document — not from environment variables. This enables live configuration changes from the admin dashboard without redeployment.

To configure: Log in → Admin → Settings → Cloudinary → enter Cloud Name, API Key, API Secret, and folder name → Save.

Deployment Guide

Vercel (Recommended)

# 1. Push your project to a GitHub repository
git push origin main

# 2. Import at vercel.com → New Project → select your repo
# 3. Add environment variables in Vercel project settings
# 4. Deploy — Vercel rebuilds automatically on every push

Self-Hosted (Node.js)

# Build the application
npm run build

# Start production server (runs on port 3000)
npm start

Nginx Reverse Proxy

server {
    listen 80;
    server_name yourdomain.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

Changelog

v1.0.0 — Initial Release

• Full photography portfolio with public website and admin CMS
• MongoDB + Mongoose database layer with serverless-optimised connection pooling
• Cloudinary dynamic image hosting (credentials managed from admin panel)
• NextAuth v5 JWT authentication with bcrypt password hashing
• Gallery with category filtering and drag-and-drop reordering
• Stories / blog module with SunEditor rich text, multi-photo upload, and camera metadata
• Team, testimonial, banner, and service gallery management
• Site settings: general info, SEO metadata, Cloudinary, page banners, terms & policy
• Contact form with admin review and delete interface
• Built-in documentation page at /documentation
• Full TypeScript coverage with Zod schema validation on all API routes
• Tag-based Next.js cache invalidation for instant content updates