Project Documentation

🚀 1. Overview

Project Overview

The repository is a full‑stack, role‑aware web application built on top of Next.js 14 (App Router). Its primary purpose is to provide a ready‑to‑use authentication layer—complete with secure credential verification, JWT‑based sessions, and role propagation—so that developers can focus on the business logic of their product instead of reinventing the login flow. By wiring NextAuth.js with a MongoDB backend (via Mongoose) and bcrypt for password hashing, the codebase delivers a production‑grade sign‑in experience that can be dropped into any Next.js project, whether the final host is Vercel, Netlify, or a self‑managed server.

Beyond authentication, the app is structured as a typical Next.js “app” directory project. Pages are written in TypeScript, the UI is styled with Tailwind CSS (the default in most create‑next‑app templates) and enriched with the Geist font using the built‑in next/font optimisation. The authentication flow is tightly integrated with the routing layer: a custom /login page is declared in the pages section of the NextAuth configuration, and protected routes can read the enriched session.user object (which now contains id and role) via the useSession hook. This enables role‑based access control (RBAC) throughout the UI without any additional boiler‑plate.

The back‑end side is deliberately lightweight. A single helper connectDB establishes a Mongoose connection to a MongoDB Atlas cluster (or any compatible MongoDB instance). The User model (found in models/User.ts) defines fields such as email, password (hashed with bcrypt), name, and role. All data access happens through this model, keeping the persistence layer abstracted away from the rest of the code. Because the authentication strategy is set to JWT, the server remains stateless, which simplifies horizontal scaling and aligns perfectly with serverless deployment targets like Netlify Functions (as evidenced by the netlify.toml configuration).

Deployment is first‑class. The netlify.toml file configures Netlify to run npm run build and serve the generated .next directory, while the @netlify/plugin-nextjs plugin automatically handles server‑less function routing for API routes and NextAuth callbacks. The same code can be deployed to Vercel with zero changes thanks to the generic Next.js build pipeline. This dual‑deployment flexibility makes the starter attractive for teams that are still deciding on a hosting provider or that need to mirror production locally on Netlify for preview builds.

Overall, the project solves the “authentication boilerplate” problem for modern React/Next.js applications. It encapsulates best‑practice security (bcrypt, environment‑based secrets, JWT), provides a clean TypeScript‑typed session object, and is wired for immediate production deployment. Developers can clone the repo, run npm install && npm run dev, create a MongoDB connection string, and have a fully functional sign‑in system with role awareness ready to be extended with custom business pages, API routes, and data visualisation components.

Tech Stack at a Glance

📂 2. Project Structure

📁 Code‑base Overview – Logical Grouping

Below is an exhaustive mapping of every file/folder in the repository to a logical domain (Authentication, UI, API, State, DB, Utils, Configuration, Public Assets, etc.).
The table lists Category, Sub‑folder (relative to repository root), and a concise Key Responsibility for each entry.

🏗️ Architectural Patterns in This Project

1. Next.js App Router (Hybrid Server‑Client) + Clean / Onion Architecture

• Dependency Rule: Inner layers (models) never import from outer layers (lib, app). All dependencies point inward.
• Separation of Concerns: UI, business rules, and external adapters are isolated, making unit‑testing straightforward.
• Testability: Use‑case services can be exercised with in‑memory mocks of DB/email/payment without bootstrapping Next.js.

2. MVC‑like Interpretation within Next.js

3. Feature‑Folder / Module‑Based Organization

Each feature (e.g., rooms, admin, feedback) lives under a dedicated sub‑folder inside src/app/. This encourages:

• Collocated Routing + UI – the folder name matches the URL segment.
• Scalability – new features can be added by creating a new folder with its own page.tsx and component tree.

4. Server‑Side Rendering (SSR) + Static Site Generation (SSG)

• Files in src/app are Server Components by default, enabling SSR for SEO‑critical pages (/rooms/[id], /dashboard).
• Static assets (public/*.svg) are served via the Next.js static file handler, suitable for SSG.

5. Infrastructure as Code (IaC) via Netlify

• netlify.toml describes build commands, redirects, and environment variables – the CI/CD pipeline is versioned alongside application code, aligning with modern DevOps practices.

6. Styling – Tailwind + CSS Modules

• Global Tailwind configuration (tailwind.config.ts) + PostCSS pipeline.
• Scoped CSS (page.module.css) for page‑level overrides, ensuring no CSS bleed.

🔎 Deep‑Dive Into Key Architectural Decisions

1. Separation of Auth Concerns

   • auth.ts houses low‑level token creation/validation logic, while NextAuth (src/app/api/auth/[...nextauth]/route.ts) provides a high‑level session framework. This dual‑layer approach isolates provider‑specific code (OAuth, credentials) from generic JWT utilities, making it easy to swap providers without touching business logic.

2. Action‑Centric Service Layer (src/lib/*)

   • Instead of embedding DB calls directly inside React components or API routes, the project uses action files (actions.ts, adminActions.ts). These are pure functions that accept DTOs and return domain objects or result types.
   • Example flow: BookingForm → calls createBooking from actions.ts → actions.ts uses db.ts (Prisma) → returns a Booking model → UI updates via React state or redirects.

3. Database Abstraction

   • src/lib/db.ts likely exports a singleton Prisma client (prisma). All data access is funneled through this file, which means:
     • Connection pooling is centralised.
     • Environment‑specific config (connection string) lives in one spot.
     • Tests can mock the client by swapping the export during Jest setup.

4. External Service Wrappers

   • cloudinary.ts, email.ts, paymentAction.ts each expose domain‑friendly functions (uploadImage, sendMail, createCheckoutSession). They hide provider SDK quirks, allowing the rest of the codebase to stay provider‑agnostic. This is a hallmark of Dependency Inversion in Clean Architecture.

5. Static Assets & SEO

   • By placing SVGs in public/, they are served without additional bundling, keeping the bundle size low and enabling direct <img src="/globe.svg"> usage. SEO‑critical pages (/rooms/[id]) are server‑rendered, ensuring crawlers receive fully‑populated HTML.

6. Tailwind + PostCSS

   • The config chain (tailwind.config.ts → postcss.config.mjs → globals.css) provides utility‑first styling while still permitting custom CSS via modules. This hybrid approach balances rapid UI development with precise design overrides.

📐 Summary of Architectural Strengths

📌 Bottom Line

The repository follows Clean Architecture principles while leveraging Next.js’ hybrid rendering model. The logical separation into Configuration, Authentication, UI (Pages & Components), Domain Models, Application Services, and Infrastructure creates a maintainable, testable, and scalable codebase that can evolve (e.g., adding more providers, swapping databases) with minimal friction.

🏗️ 3. Architecture & Data Flow

1️⃣ Architecture Deep‑Dive

Below is a layer‑by‑layer walkthrough of how the repository is wired together, why certain patterns were chosen, and how the pieces cooperate at runtime.
All observations are based on the concrete files that exist in the tree you supplied.

📦 High‑level Layer Stack

🧩 Module Interactions & Design Patterns

🔄 Request Lifecycle (Typical Flows)

2️⃣ Data Flow & State Transitions

3️⃣ Mermaid Diagram (Component Map)

The diagram groups the concrete files into four logical sub‑graphs that mirror the layer stack above.
Node IDs are short alphanumeric identifiers; the human‑readable labels contain the actual file paths.

How to read the diagram

• Arrows indicate invocation or data‑dependency (e.g., a page component posts to an API route).
• Sub‑graphs are logical boundaries; they are not separate processes – all run inside the same Next.js serverless environment, but the visual grouping helps reason about responsibilities.
• External nodes (E1‑E3) represent third‑party services that are only touched through thin wrapper libraries (cloudinary.ts, email.ts, paymentAction.ts).

📚 Take‑away Summary

1. Clear separation of concerns – UI, API, service, persistence, and external‑integration layers are each encapsulated in their own directories.
2. Reusable patterns – Singleton DB, Repository‑style Mongoose models, Strategy‑based auth, Factory for external SDKs, CQS in server actions.
3. Extensibility – Adding a new auth provider, swapping Cloudinary for another media store, or swapping the email transporter requires only changes inside the Factory wrapper files; the rest of the codebase remains untouched.
4. State management – The only mutable “global” state lives in the JWT/session (role, user id) and in the MongoDB collections; everything else is derived per‑request, which aligns with Next.js’s serverless nature.
5. Testability – Because each layer only depends on interfaces (models, wrapper functions) you can unit‑test the service layer by mocking User, Room, etc., and integration‑test the API routes with an in‑memory MongoDB.

Feel free to ask for deeper dives into any specific file (e.g., the exact implementation of src/lib/paymentAction.ts) or for suggestions on how to improve the architecture (e.g., introducing a GraphQL layer, adding a caching layer with Redis, etc.).

📈 System Architecture Diagram

🛠️ 4. Function Breakdowns

Below is a function‑level breakdown of every executable export and internal routine that appears in the source files you supplied.
For each file a Markdown table lists:

auth.ts

Supporting Imports & Types (not functions but important for context)

next.config.ts

netlify.toml

This file is a static configuration for Netlify; it contains no executable functions, therefore no table is required.

Summary of the Authentication Flow

1. Client calls signIn('credentials', { email, password }).
2. NextAuth forwards the request to the CredentialsProvider.authorize function.
3. authorize connects to MongoDB, fetches the user, verifies the password with bcrypt.
4. On success it returns a user payload; NextAuth creates a JWT.
5. The jwt callback stores role and id inside the token.
6. The session callback copies those fields onto session.user.
7. Subsequent useSession calls (client) or getServerSession (server) expose session.user.id and session.user.role.
8. signOut clears the JWT cookie, ending the session.

All exported helpers (handlers, signIn, signOut, auth) are intended to be wired into a Next.js API route (e.g., pages/api/auth/[...nextauth].ts) like so:

import { handlers } from '@/auth';
export const GET = handlers.GET;
export const POST = handlers.POST;
export const OPTIONS = handlers.OPTIONS;

That wiring is what makes the authentication system operational throughout the app.