match-vault

Role-aware matchmaking app powered by Next.js, Prisma, Auth.js, and Pusher.

match-vault — README

Modern full-stack matchmaking application built with Next.js App Router, Prisma, PostgreSQL, NextAuth v5, and real-time messaging/notifications with Pusher.

Table of Contents

• 🚀 Project intro
• 📁 Project structure
• ⭐ Differentiators
• 🔧 Features
  • Flow diagram
• 🧰 Tech stack
• ⚙️ Install methods
  • 📦 npm / Node
• 🔐 Environment variables
• 🗄️ Database structure
• 📜 Available scripts
• 🚀 Deployment notes
• 🤝 Contributing
• 📄 License

🚀 Project intro

match-vault is a role-aware matchmaking platform with:

• Email/password + social authentication (Google/GitHub)
• Profile onboarding and completion flow
• Member discovery with filters/pagination
• Likes (including mutual likes)
• Real-time chat and real-time notifications
• FaceTime-style video calling with scheduled and instant meeting flows
• Admin photo moderation

It is designed as an MVP-friendly production-ready foundation for social/match applications.

📁 Project structure

match-vault/
├── prisma/
│   ├── schema.prisma
│   ├── seed.ts
│   └── migrations/
├── public/
│   └── images/
├── scripts/
│   ├── checkCounts.js
│   └── with-db-env.mjs
├── src/
│   ├── app/
│   │   ├── (auth)/               # login/register/verify/reset/profile-complete
│   │   ├── actions/              # server actions (auth/member/like/message/admin)
│   │   ├── admin/moderation/
│   │   ├── api/                  # auth, health, pusher-auth, sign-image
│   │   ├── lists/
│   │   ├── members/
│   │   └── messages/
│   ├── components/
│   ├── hooks/
│   ├── lib/
│   ├── auth.ts
│   ├── auth.config.ts
│   ├── middleware.ts
│   └── routes.ts
├── package.json
└── README.md

⭐ Differentiators

• Server Actions first approach for core domain operations
• Auth.js + Prisma adapter with role and profile-completion-aware middleware guards
• Real-time UX via Pusher (chat updates, likes, presence-style notifications)
• Practical Neon/Vercel database env fallback handling (DATABASE_URL/DIRECT_URL auto-resolution)
• Admin moderation workflow for uploaded photos

🔧 Features

Core features

Feature	Status	Notes
Credentials auth	✅ Current	Register, login, email verification, password reset
Social auth	✅ Current	Google + GitHub providers (optional via env vars)
Profile completion flow	✅ Current	OAuth users are redirected until profile is completed
Member browsing	✅ Current	Filter by age/gender/photo + pagination
Likes & lists	✅ Current	Source likes, target likes, mutual likes
Messaging	✅ Current	Real-time thread updates + inbox/outbox view
Video calling	✅ Current	FaceTime meetings with instant creation, scheduling, and join links
Photo uploads	✅ Current	Cloudinary upload + signed API route
Admin moderation	✅ Current	Approve/reject pending photos

Flow diagram

The Mermaid flow below shows the main application journey, from public entry points through auth, profile completion, member discovery, messaging, video calls, and admin moderation.

flowchart TD
	A[Visitor] --> B[/Home /]
	B --> C{Authenticated?}

	C -- No --> D[Register]
	C -- No --> E[Login]
	D --> F[Verify email]
	F --> G{OAuth account?}
	E --> H[Session created]
	F --> H
	G -- No --> H
	G -- Yes --> I{Profile complete?}
	H --> I

	I -- No --> J[Complete profile]
	I -- Yes --> K[Members feed]
	J --> K

	K --> L[Open member profile]
	L --> M[Like / Unlike]
	L --> N[Start chat]
	L --> O[Start video call]
	L --> P[View member photos]

	M --> Q{Mutual like?}
	Q -- Yes --> N
	N --> R[Real-time messages + notifications]
	O --> S[Facetime meeting]
	S --> T[Join scheduled or instant call]

	K --> U[Lists]
	K --> V[Edit profile]
	K --> W{ADMIN?}
	W -- Yes --> X[Admin moderation]
	W -- No --> Y[Redirect to Home]
	X --> Z[Review photo uploads]

Loading

Route protection behavior

• Public route: /
• Auth routes: /login, /register, /register/success, /verify-email, /forgot-password, /reset-password
• All other app routes require authentication
• /admin/* routes require ADMIN role
• OAuth users with incomplete profile are redirected to /profile-complete

🧰 Tech stack

• Framework: Next.js 16 (App Router), React 19, TypeScript
• Auth: NextAuth/Auth.js v5 + Prisma Adapter
• Database: PostgreSQL + Prisma ORM
• UI: HeroUI + Tailwind CSS 4
• Forms/Validation: React Hook Form + Zod
• Realtime: Pusher + pusher-js
• Video calling: Stream Video React SDK + Stream Node SDK
• Media: Cloudinary + next-cloudinary
• Email: Resend

⚙️ Install methods

📦 npm / Node

Prerequisites:

• Node.js 20+
• PostgreSQL database (local or hosted, e.g. Neon)

git clone <your-repo-url> match-vault
cd match-vault
npm install

1. Create your .env file (see Environment variables).

2. Apply migrations:

npx prisma migrate dev

3. Seed sample data:

npx prisma db seed

Resetting the Database

To clear and reset the database:

• Recommended (restore all sample data including meetings):

  npm run db:reset

  This resets the schema and re-seeds all users, admin, and FaceTime meeting fixtures.

• Quick reset without seeding:

  npx prisma migrate reset --skip-seed

  ⚠️ This will drop all data including user accounts and scheduled meetings (no data is restored automatically).

• Just seed data (if database is already migrated):

  npx prisma db seed

  This clears and re-creates all sample users and FaceTime meetings.

4. Start development server:

npm run dev

Open http://localhost:3000.

🔐 Environment variables

Create a .env in project root:

# Database (minimum)
DATABASE_URL="postgresql://..."
DIRECT_URL="postgresql://..."

# Optional DB fallbacks supported by this repo
POSTGRES_PRISMA_URL=""
POSTGRES_URL=""
POSTGRES_URL_NON_POOLING=""
NEON_DATABASE_URL=""
NEON_POSTGRES_URL=""

# Auth.js / NextAuth
AUTH_SECRET="your-random-secret"
NEXTAUTH_URL="http://localhost:3000"

# Credentials email flows
RESEND_API_KEY=""
NEXT_PUBLIC_BASE_URL="http://localhost:3000"

# Optional social providers
GOOGLE_CLIENT_ID=""
GOOGLE_CLIENT_SECRET=""
GITHUB_CLIENT_ID=""
GITHUB_CLIENT_SECRET=""

# Cloudinary (upload + signature)
NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME=""
NEXT_PUBLIC_CLOUDINARY_API_KEY=""
CLOUDINARY_API_SECRET=""

# Pusher (real-time)
PUSHER_APP_ID=""
NEXT_PUBLIC_PUSHER_APP_KEY=""
PUSHER_APP_SECRET=""

# Optional diagnostics
DEBUG_ERRORS="false"

Notes:

• src/lib/prisma.ts and scripts/with-db-env.mjs auto-map several Vercel/Neon env names into DATABASE_URL and DIRECT_URL.
• If Pusher env vars are missing, real-time features will fail where server/client instances are required.

🗄️ Database structure

Prisma models in this repo:

• User (role, profile completion, auth data)
• Member (public profile, demographic details)
• Photo (member media + moderation state)
• Like (source/target relation; composite PK)
• Message (thread messages with soft-delete flags)
• Token (email verification + password reset tokens)
• Account (OAuth account linkage)

Enums:

• Role: ADMIN, MEMBER
• TokenType: VERIFICATION, PASSWORD_RESET

📜 Available scripts

npm run dev            # start dev server
npm run build          # production build
npm run start          # run production server
npm run lint           # lint project
npm run vercel-build   # prisma generate + migrate deploy + seed + build

Utility scripts:

• node scripts/checkCounts.js — quick sanity counts for User and Member
• node scripts/with-db-env.mjs <command> — run command with DB env fallbacks resolved

🚀 Deployment notes

• The vercel-build script is configured for deploy-time Prisma generation, migration, seeding, and Next.js build.
• Seed creates demo users and an admin account:
  • Admin email: admin@test.com
  • Default seed password: password
• Rotate seed credentials and production secrets before public deployment.

🤝 Contributing

• Fork the repository and create a feature branch.
• Keep pull requests focused and include verification steps.
• Never commit secrets or real credentials.

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.