Mehfil - Complete System Documentation

1. Goal

Mehfil is a premium event venue booking platform designed to streamline the process of discovering, checking availability, and booking event spaces such as party halls, wedding venues, and conference rooms. The goal is to provide a seamless, beautiful user experience for customers while offering robust management tools for venue owners and system administrators.


2. Description

Mehfil bridges the gap between venue owners and customers looking to host events. It offers location-based search, real-time date availability, and integrated optional services like catering. Behind the scenes, it features a comprehensive role-based dashboard system that allows different levels of staff (Super Admins, Venue Owners, and Venue Staff) to manage bookings, block out dates, and oversee operations effortlessly.


3. Features

  • Role-Based Access Control (RBAC): Distinct interfaces and permissions for Super Admins, Venue Owners, Venue Staff, and Customers.
  • Location-Based Discovery: Browse venues segmented by cities/locations.
  • Real-time Availability: Prevent double-booking with dynamic venue blocking and date checking.
  • Add-on Services: Select and attach catering packages directly to a booking.
  • Dual Authentication System: Secure JWT HTTP-only cookies and Bearer tokens for all users (Customers, Admins, and Staff) via unified MongoDB user schemas.
  • Server-side Pagination: Highly optimized paginated APIs for efficient data loading on dashboards.
  • Interactive API Documentation: Auto-generated Swagger UI for developers.

4. Architecture

Mehfil uses a modern, hybrid architecture combining a serverless-ready frontend with a robust Express backend, all within a Next.js monorepo.

  • Frontend: Next.js 14+ (App Router), React Query (data fetching/caching), Tailwind CSS + shadcn/ui (styling).
  • Backend: Express.js mounted via Next.js catch-all API routes (/api/[...slug]).
  • Database: MongoDB Atlas (NoSQL Document Store).
  • Documentation: swagger-jsdoc, swagger-ui-express, and internal markdown viewer (/docs).

Architecture Diagram

graph TD
    Client[Web Browser Client]
    NextJS[Next.js App Router\nFrontend]
    Express[Express.js API\nBackend]
    Auth[Authentication System]
    DB[(MongoDB Atlas)]

    Client -->|Renders Pages & UI| NextJS
    Client -->|API Requests| Express
    NextJS -->|API Requests| Express
    
    Express -->|Validates Token| Auth
    Express -->|CRUD Operations| DB

    subgraph Authentication
    Auth -->|All Users| JWTAuth[JWT Bearer / Secure Cookies]
    end

5. User Flow

The Customer flow is designed for ease of use, guiding the user from discovery to booking confirmation.

flowchart LR
    A[Home Page] --> B[Browse Locations]
    B --> C[View Venues in City]
    C --> D[Venue Details & Calendar]
    D --> E{Logged In?}
    E -- No --> F[Login / Register Form]
    F --> G
    E -- Yes --> G[Booking Form]
    G --> H[Select Date & Catering]
    H --> I[Confirm Booking]
    I --> J[User Bookings Dashboard]

Page Breakdown (User)

  • / (Home): Landing page with striking visuals and clear call-to-actions to start browsing.
  • /login: Secure authentication portal utilizing MongoDB-backed JWT authentication. Includes a toggle to switch between Login and Register for new customers.
  • /user/locations: Displays available cities where Mehfil venues operate.
  • /user/locations/[locationId]/venues: A listing of all active venues in the selected city.
  • /user/locations/[locationId]/venues/[venueId]: Deep-dive into a specific venue showing pricing, capacity, and descriptions.
  • /user/locations/[locationId]/venues/[venueId]/book: The checkout/booking form where users select dates and catering options.
  • /user/bookings: A customer dashboard showing past, upcoming, and cancelled bookings.
  • /docs: Internal Markdown documentation viewer to browse architecture and test logs.

6. Admin Flow

The Internal User flow provides administrative controls based on the user's role (Admin vs. Venue Owner vs. Staff).

flowchart TD
    Login[Admin Login] --> Auth{Verify Role}
    
    Auth -- Super Admin --> DashA[Global Dashboard]
    Auth -- Venue Owner --> DashO[Owner Dashboard]
    Auth -- Venue Staff --> DashS[Venue Dashboard]

    DashA --> V[Manage All Venues]
    DashA --> L[Manage Locations]
    DashA --> U[Manage Admins/Owners]
    
    DashO --> MV[Manage Owned Venues]
    DashO --> MB[View Bookings]
    DashO --> MS[Manage Staff]

    DashS --> SB[View/Manage Venue Bookings]
    DashS --> BC[Block Dates]

Page Breakdown (Admin)

  • /admin (Dashboard): High-level metrics, upcoming bookings, and recent activity.
  • /admin/locations: CRUD operations for cities (Super Admin only).
  • /admin/venues: Table list of venues. Allows creating new venues and editing existing ones (capacity, price, status).
  • /admin/catering: Manage catering packages linked to specific locations.
  • /admin/bookings: Master list of all bookings across the platform. Includes filters for date and venue. Supports updating payment/booking statuses.
  • /admin/users: Invite and manage Venue Owners and Staff.
  • /venue/calendar & /venue/team: Dedicated pages for Venue Owners to view block-out dates and manage their localized staff.

7. API Endpoints

Mehfil provides a RESTful API powered by Express. Responses generally follow this structure:

{
  "status": true,
  "data": [...],
  "pagination": {
    "total": 50,
    "page": 1,
    "limit": 10,
    "totalPages": 5
  }
}

(Note: Full interactive API documentation is available at /api/v1/docs via Swagger UI).

Venues (/api/venues)

  • GET /api/venues
    • Description: Retrieves a paginated list of venues.
    • Query Params: page, limit, locationId, ownerUid.
    • Response: Array of Venue objects.
  • GET /api/venues/:id
    • Description: Retrieves a single venue by ID.
  • POST /api/venues (Admin)
    • Body: name, address, locationId, capacity, pricePerDay, description, timings (array of strings).
    • Response: Created venue ID.
  • PATCH /api/venues/:id (Admin/Owner)
    • Body: Partial Venue fields.
  • DELETE /api/venues/:id (Admin)

Bookings (/api/bookings)

  • GET /api/bookings
    • Description: Retrieves a paginated list of bookings.
    • Query Params: page, limit, venueId, userId, bookingDate.
  • POST /api/bookings
    • Body: venueId, userId, bookingDate, timing (string), cateringId (optional).
    • Response: Created booking ID.
  • PATCH /api/bookings/:id
    • Body: bookingStatus (e.g., 'confirmed', 'cancelled') or paymentStatus.

Locations (/api/locations)

  • GET /api/locations
    • Description: Retrieves all active locations/cities.
    • Query Params: page, limit.
  • POST /api/locations (Admin)
    • Body: name, latitude, longitude.

Catering (/api/caterings)

  • GET /api/caterings
    • Description: Retrieves catering packages.
    • Query Params: page, limit.
  • POST /api/caterings (Admin)
    • Body: name, description, locationId, pricePerPlate, isActive.

Internal Users (/api/users & /api/admins)

  • GET /api/users
    • Description: Retrieves venue owners and staff.
    • Query Params: page, limit, role.
  • GET /api/admins
    • Description: Retrieves super admins.

Auth (/api/auth)

  • POST /api/auth/unified/login (Mobile)
    • Body: email, password.
    • Description: Unified login for mobile apps. Queries Admin collection first, then falls back to User collection.
  • POST /api/auth/unified/google (Mobile)
    • Body: idToken.
    • Description: Unified Google OAuth login.
  • POST /api/auth/admin/login (Web)
    • Body: email, password.
    • Response: Returns JWT token and sets mehfil_session cookie.
  • POST /api/auth/admin/register (Admin)
    • Body: email, password, name, role, venueId (if staff).
  • POST /api/auth/admin/logout (Web)
    • Description: Clears the HTTP-only cookie.