Evently — Documentation

What is this?

Evently is a full-stack template that ships two products in one codebase:

Features

Tech Stack

Requirements

Before installing, make sure you have the following available:

• Node.js 18.18+ (Node 20 LTS or newer recommended).
• pnpm — install with npm install -g pnpm.
• MongoDB database — a free MongoDB Atlas cluster or a local mongod instance.
• Cloudinary account (optional, for image uploads) — configured later from the admin panel.
• SMTP credentials (optional, for email) — e.g. Gmail App Password, SendGrid, Mailgun.

Quick Start

1. Unzip & install dependencies

   # from the project root
   pnpm install

2. Create your environment file

   Copy the example and fill in the values (see Environment Variables).

   cp .env.example .env.local

3. Run the development server

   pnpm dev

   Open http://localhost:3000 — the public site loads. Staff dashboards live at /super-admin and /organizer; attendees use /attendee.

4. Build for production

   pnpm build
   pnpm start

Environment Variables

Create .env.local in the project root. Required keys are marked below.

# ── Core ──────────────────────────────────────────────
MONGODB_URI="mongodb+srv://user:pass@cluster.mongodb.net/event-management"
AUTH_SECRET="a-long-random-secret-string"
NEXTAUTH_SECRET="a-long-random-secret-string"
NEXTAUTH_URL="http://localhost:3000"
AUTH_TRUST_HOST="true"
JWT_SECRET="a-long-random-secret-string"

# ── Public URLs ───────────────────────────────────────
NEXT_PUBLIC_SITE_URL="http://localhost:3000"
NEXT_API_URL="http://localhost:3000"

# ── Cron (waitlist expiry authorization) ──────────────
CRON_SECRET="a-random-cron-secret"

# ── SMTP fallback (optional — preferably set in admin Settings) ──
SMTP_HOST="smtp.gmail.com"
SMTP_PORT="587"
SMTP_SECURE="false"
SMTP_USER="you@gmail.com"
SMTP_PASS="your-app-password"
FROM_EMAIL="you@gmail.com"
FROM_NAME="Evently"

# ── Cloudinary (optional — preferably set in admin Settings) ──
CLOUDINARY_CLOUD_NAME=""
CLOUDINARY_API_KEY=""
CLOUDINARY_API_SECRET=""

First-Run Setup

On its first connection to an empty database, the app auto-creates a default Super Admin so you can sign in immediately.

1. Start the app & sign in

   Run pnpm dev, open /staff/login, and sign in with the default Super Admin credentials above.

2. Seed demo data (optional)

   Open Super Admin → Seed (or POST /api/events/seed as a Super Admin) to populate demo organizers, attendees, venues, events, tickets, registrations, speakers, sponsors, team members, contacts and newsletter subscribers.

   Warning: Seeding replaces demo content and is intended for a fresh/dev database only. Do not run it against production data.

3. Secure the account

   Immediately change the default Super Admin password (and email) from Profile / Settings before going live.

Demo Accounts

The default Super Admin is created automatically on first run. Additional demo organizer and attendee accounts are created by the seeder — the exact emails and shared password are listed on the Super Admin → Seed page after seeding.

Project Structure

The project follows the Next.js App Router convention with route groups for clean separation between public, auth, and dashboard areas.

User Roles & Access

Three roles drive access control. Staff (Super Admin, Organizer) sign in at /staff/login; attendees sign in at /login.

Routing & Pages

Page URLs are centralised in lib/routes.ts via the ROUTES helper. Middleware (proxy.ts) guards dashboard routes and redirects users to the correct area based on their role.

Public routes

Auth routes

Dashboard roots

Authentication

The template uses a hybrid auth model:

• NextAuth v5 session protects pages via the proxy.ts middleware and stores the access token in the session.
• Bearer JWT protects the REST API. Tokens are signed with JWT_SECRET and verified by the API auth helper.

Login flow

Calling a protected endpoint

fetch("/api/events/attendee/registrations", {
  headers: { "Authorization": `Bearer ${token}` }
})

Every protected handler is wrapped with asyncHandler, which connects to the database, verifies the Bearer token, enforces an optional allowed-roles list, and validates the request body against a Zod schema before your handler runs. Passwords are hashed with bcrypt; email verification uses a time-limited OTP and password reset uses a signed token delivered by email.

Admin Settings

Almost everything is configurable from Super Admin → Settings — no code edits needed. Settings are stored as a single document and cached (revalidated when saved).

Theming & Branding

The design system is driven by CSS variables in app/globals.css and Tailwind v4 tokens. Light and dark modes are handled by next-themes. The template ships a green & white theme by default.

Brand colors

Primary, secondary and accent brand colors are exposed as CSS variables. The public site and dashboards read the admin-configured colors from the landingPage branding settings, applied through a scoped wrapper (brandVars() in the layouts) so the UI restyles without touching component classes. Defaults live in lib/landing-page-defaults.ts.

// lib/landing-page-defaults.ts
BRAND_DEFAULTS = {
  primaryColor: "#16a34a",   /* green-600 */
  secondaryColor: "#22c55e", /* green-500 */
  accentColor: "#06b6d4",    /* cyan-500 */
}

Change the brand colors

Set them from Super Admin → Settings → Landing Page (branding). The public site and admin dashboards pick them up automatically.

Logo & favicon

Upload your logo and favicon under Settings → General; they are wired into the header and document <head> automatically.

Landing Page Builder

The homepage is fully data-driven from Settings → Landing Page. Each section can be edited and populated with images without touching code.

Database Models

All Mongoose schemas live in /model (28 total). Every model includes timestamps and a softDelete flag (records are flagged, not physically removed).

Lifecycles & Status Enums

Event

Registration & Ticket

Registration: confirmed · pending · cancelled · waitlisted. Ticket: active · sold_out · cancelled. When a ticket sells out, new registrations are added to the Waitlist.

Waitlist

When a spot opens, the next person is notified and holds it for 48 hours. If they don't convert, a cron job marks them expired and notifies the next in line.

Other enums

Cron Jobs

A single scheduled job keeps the waitlist moving. It releases expired 48-hour holds, promotes the next person in the queue, and sends the relevant emails.

Schedule it with a Vercel Cron entry or an external scheduler (e.g. cron-job.org) hitting the endpoint with Authorization: Bearer <CRON_SECRET>.

API Conventions

All endpoints live under /api. The main API is namespaced under /api/events. NextAuth's handler lives at /api/auth/[...nextauth].

Standard response envelope

{
  "status": true,
  "message": "Operation successful!",
  "data": { /* payload or null */ },
  "pagination": { /* present on list endpoints */ }
}

Authentication header

Authorization: Bearer <jwt-token>

Public = no token required  ·  Auth = Bearer token + role required

Auth API

Base path: /api/events/auth

Public API

Base path: /api/events/public — no authentication required.

Attendee API

Base path: /api/events/attendee — requires an attendee Bearer token.

Organizer API

Base path: /api/events/organizer — requires an organizer Bearer token. Scoped to the organizer's own resources.

Super Admin API

Base path: /api/events/super-admin — requires a Super Admin Bearer token. Full CRUD across every module. Each resource below supports the standard set (GET list & [id], POST, PUT, DELETE) unless noted.

Dashboard & Platform

Events & Content

People & Growth

Settings

Notifications & Seed

Base path: /api/events/notifications

Deployment

The app deploys anywhere that runs Node.js. Vercel is the simplest path.

Vercel

1. Push to Git

   Push the project to a GitHub/GitLab repo.

2. Import to Vercel

   Create a new project and import the repo.

3. Add environment variables

   Copy every key from your .env.local into the Vercel project settings. Set NEXTAUTH_URL and the public URLs to your production domain.

4. Add the waitlist cron

   Configure a Vercel Cron (or external scheduler) to POST /api/events/cron/waitlist-expiry every ~15 min with the CRON_SECRET.

5. Deploy

   Vercel builds with pnpm build automatically.

Self-hosted / VPS

pnpm install
pnpm build
pnpm start   # serves on port 3000 — put Nginx/PM2 in front

Troubleshooting & FAQ

Which login page do I use?

Staff (Super Admin, Organizer) sign in at /staff/login; attendees at /login. New registrations are created with the attendee role.

The build fails trying to reach the database

The template is designed to build without a live DB — settings are skipped during the build phase and DB-backed pages are dynamic. Make sure you're on the latest code and that config/database.ts only reads MONGODB_URI lazily (inside dbConnect).

Database connection fails at runtime

Verify MONGODB_URI and that your IP is whitelisted in MongoDB Atlas (Network Access). The app uses the database name template-event-management.

Emails aren't sending

Configure SMTP in Settings → SMTP and use the Send test email button. For Gmail, use an App Password, not your account password.

Image uploads fail

Fill in Cloudinary credentials under Settings → Cloudinary. Without them, image upload features are disabled.

Waitlist holds never expire

The /api/events/cron/waitlist-expiry job must run on a schedule with the correct CRON_SECRET. Check your Vercel Cron / external scheduler.

Build error: middleware not found

This project uses Next.js 16, where middleware is proxy.ts with a default export — do not rename it to middleware.ts.

Public site shows a maintenance screen

Maintenance Mode is enabled in Settings → General. Turn it off to restore the public site.

Support & Credits

Thank you for choosing Evently — Event Management System. We hope it accelerates your project.

Built with

Next.js · React · TypeScript · MongoDB · Mongoose · Tailwind CSS · Radix UI · NextAuth · Zod · React Hook Form · TanStack Table · Recharts · Framer Motion · Cloudinary · Nodemailer · jsPDF · qrcode · TipTap · Zustand.