Template Architecture

Overview

Template Architecture is a comprehensive full-stack web application built with Next.js 16 (App Router), React 19, TypeScript, and MongoDB. It provides a complete admin CMS dashboard for managing content and a public-facing portfolio website for showcasing work.

The application follows modern web development best practices with server components, server actions, API routes organized by feature, role-based access control, and a fully type-safe codebase.

Features

Tech Stack

Prerequisites

• Node.js v20 or higher
• pnpm (recommended) or npm
• MongoDB — A MongoDB Atlas cluster or local instance
• Cloudinary Account — For image and video uploads

Installation

1. Clone the Repository

git clone <repository-url>
cd template-architecture

2. Install Dependencies

pnpm install

3. Configure Environment Variables

Create a .env file in the project root (see Environment Variables section for details).

4. Run the Development Server

pnpm dev

The application will be available at http://localhost:3000.

5. Build for Production

pnpm build
pnpm start

Environment Variables

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

AUTH_TRUST_HOST="true"
NEXTAUTH_SECRET="your-secret-key-here"
NEXTAUTH_URL="http://localhost:3000"
NEXT_PUBLIC_BASE_URL="http://localhost:3000"
MONGODB_URI="mongodb+srv://<username>:<password>@<cluster>.mongodb.net/<database>?retryWrites=true&w=majority"

Default Admin Credentials

On first run, the application automatically seeds a default admin account:

Project Structure

template-architecture/
├── app/                              # Next.js App Router
│   ├── (auth)/                       # Auth layout group
│   │   └── admin/login/              # Admin login page
│   ├── (private)/                    # Protected admin routes
│   │   └── admin/dashboard/          # Dashboard & sub-routes
│   │       ├── (showcase)/           # About Us, Our Work, Story
│   │       ├── banner/               # Banner management
│   │       ├── collaborations/       # Collaborations CRUD
│   │       ├── contact-list/         # Contact submissions
│   │       ├── projects/             # Project CRUD (create, edit)
│   │       ├── services/             # Service types management
│   │       ├── settings/             # App settings
│   │       ├── subscribe/            # Newsletter subscribers
│   │       ├── teams/                # Team management
│   │       ├── testimonials/         # Testimonials management
│   │       └── _components/          # Dashboard UI components
│   ├── (public)/                     # Public-facing pages
│   │   ├── about/                    # About page
│   │   ├── contact/                  # Contact form
│   │   ├── portfolio/                # Portfolio grid
│   │   ├── project/[id]/            # Project detail
│   │   ├── policy/                   # Privacy policy
│   │   └── terms/                    # Terms & conditions
│   ├── api/
│   │   ├── admin/                    # Protected API routes
│   │   │   ├── auth/                 # Login, me, password
│   │   │   ├── banner/              # Banner CRUD
│   │   │   ├── collaborations/      # Collaborations CRUD
│   │   │   ├── contact-us/          # Contact management
│   │   │   ├── dashboard/stats/     # Dashboard statistics
│   │   │   ├── file/               # File upload/delete
│   │   │   ├── home-section/       # Home section CRUD
│   │   │   ├── project/            # Project CRUD
│   │   │   ├── service-type/       # Service type CRUD
│   │   │   ├── settings/           # Settings management
│   │   │   ├── subscribe/          # Subscription management
│   │   │   ├── team/               # Team CRUD
│   │   │   ├── testimonial/        # Testimonial CRUD
│   │   │   └── about-section/      # About section CRUD
│   │   ├── auth/[...nextauth]/     # NextAuth configuration
│   │   └── public/                  # Public API routes
│   └── layout.tsx                   # Root layout
├── actions/                          # Server Actions
│   ├── about/                       # About section actions
│   ├── admin/                       # Admin auth actions
│   ├── banner/                      # Banner actions
│   ├── collaborations/              # Collaboration actions
│   ├── contact-list/                # Contact list actions
│   ├── dashboard/                   # Dashboard statistics
│   ├── fileUpload/                  # File upload actions
│   ├── profile/                     # Profile actions
│   ├── projects/                    # Project actions
│   ├── services/                    # Service actions
│   ├── settings/                    # Settings actions
│   ├── showcase/                    # Showcase actions
│   ├── subscribe/                   # Subscribe actions
│   ├── teams/                       # Team actions
│   └── testimonial/                 # Testimonial actions
├── components/                       # React Components
│   ├── custom/                      # Reusable UI components
│   │   ├── data-table/             # DataTable with pagination
│   │   ├── CustomImage.tsx         # Cloudinary image wrapper
│   │   ├── DateTimePicker.tsx      # Date picker component
│   │   ├── RichTextEditor.tsx      # SunEditor wrapper
│   │   ├── img-dropzone-single.tsx # Drag-drop image upload
│   │   ├── PhoneInputField.tsx     # Phone input component
│   │   └── ToasterComponents.tsx   # Toast notifications
│   └── features/landing/           # Landing page components
├── model/                            # Mongoose Schemas
│   ├── User.ts                      # Admin user model
│   ├── Project.ts                   # Project model
│   ├── Team.ts                      # Team member model
│   ├── ServiceType.ts               # Service type model
│   ├── Testimonial.ts               # Testimonial model
│   ├── Banner.ts                    # Banner model
│   ├── ContactUs.ts                 # Contact submission model
│   ├── Subscribe.ts                 # Email subscription model
│   ├── HomeSection.ts               # Home section model
│   ├── AboutSection.ts              # About section model
│   ├── Settings.ts                  # Global settings model
│   └── collaborations.ts            # Collaborations model
├── lib/                              # Utilities & Helpers
│   ├── async-handler.ts             # API route error handler
│   ├── async-formdata-handler.ts    # FormData handler
│   ├── authenticate.ts              # JWT auth middleware
│   ├── api-client.ts                # Server-side API client
│   ├── server-utils.ts              # Cloudinary, JWT, validation
│   ├── validation-schema.ts         # Zod validation schemas
│   ├── mongo-adapter.ts             # MongoDB aggregation helper
│   ├── fileUpload.ts                # File upload utilities
│   ├── file-validator.ts            # File type/size validation
│   ├── compressImages.ts            # Image compression
│   ├── metadata.ts                  # SEO metadata helpers
│   ├── helper-funcs.ts              # General utilities
│   ├── utils.ts                     # Client-side utilities
│   └── types.ts                     # TypeScript definitions
├── config/                           # Configuration
│   ├── database.ts                  # MongoDB connection & seeding
│   ├── cloudinary.ts                # Cloudinary SDK setup
│   ├── routes.ts                    # Route constants
│   ├── constant.ts                  # App constants & enums
│   └── cache.ts                     # Node Cache setup
├── hooks/                            # React Custom Hooks
├── public/                           # Static Assets
├── Dockerfile                        # Docker deployment
├── next.config.ts                    # Next.js configuration
├── tsconfig.json                     # TypeScript configuration
├── components.json                   # ShadCN/UI configuration
└── .env                              # Environment variables

App Routing

The application uses Next.js App Router with route groups to organize pages by access level:

Public Routes

Admin Routes

Authentication

Authentication Flow

1. Admin submits email and password at /admin/login.
2. Server validates credentials against the database using bcrypt.
3. A JWT token is generated (signed with NEXTAUTH_SECRET, 30-day expiry).
4. Token is stored in the NextAuth session.
5. All subsequent admin API requests include the token as Authorization: Bearer <token>.
6. The authenticate() middleware verifies the JWT on every protected endpoint.

JWT Configuration

Role-Based Access Control

The system supports two roles: admin and user. All admin dashboard and API routes require the admin role. The role is embedded in the JWT payload and verified on each request.

Database Models

All models are defined using Mongoose ODM and stored in the model/ directory. Timestamps (createdAt, updatedAt) are automatically added to all models.

User

Project

Team

ServiceType

Testimonial

Banner

ContactUs

HomeSection

AboutSection

Settings

Collaborations

Middleware & Utilities

asyncHandler

Wraps API route handlers with automatic database connection, JWT authentication (when enabled), Zod request validation, and standardized error handling.

// With validation and auth
export const POST = asyncHandler(createProjectSchema, async (req, data, params) => {
  // data is validated and typed
  return apiResponse(true, 201, 'Created', result);
}, true); // true = require authentication

// Without validation, with auth
export const GET = asyncHandler(async (req, params) => {
  return apiResponse(true, 200, 'Success', data);
}, true);

authenticate

JWT verification middleware that extracts the Bearer token from the Authorization header, verifies its signature, and returns the decoded user data.

validation-schema

Centralized Zod validation schemas for all API inputs including admin login, projects, teams, testimonials, settings, and more. Each schema enforces type safety and business rules.

mongo-adapter

Provides a reusable aggregateWithPagination() method for MongoDB aggregation queries with built-in pagination, sorting, matching, and lookup support.

api-client

Server-side fetch wrapper that automatically includes the JWT token from the NextAuth session, handles errors, and supports both JSON and FormData requests.

Server Utilities

• uploadImage() — Upload files to Cloudinary
• cleanupCloudinaryAssets() — Delete uploaded files on error
• transformCloudinaryPaths() — Convert stored paths to full URLs
• apiResponse() — Standardized API response builder
• Custom Zod field helpers: requiredStringField(), optionalStringField(), requiredObjectIdField(), etc.

Server Actions

Server actions in the actions/ directory provide server-side functions for handling mutations from the admin dashboard. They use the api-client utility to make authenticated requests to the API routes.

API Overview

All API routes are located in app/api/ and follow RESTful conventions. The API is divided into two main groups:

• Admin API (/api/admin/*) — Protected endpoints that require a valid JWT token
• Public API (/api/public/*) — Open endpoints for the public website

Response Format

{
  "status": true,
  "message": "Success message",
  "data": { },
  "pagination": {
    "totalDocs": 100,
    "page": 1,
    "limit": 10,
    "pages": 10,
    "hasNext": true,
    "hasPrev": false
  }
}

Query Parameters (Paginated Endpoints)

Authentication Header

Authorization: Bearer <jwt-token>

Authentication API

POST /api/admin/auth/login

// Request Body
{
  "email": "admin@example.com",
  "password": "ChangeMe123!"
}

// Response
{
  "status": true,
  "message": "Login successful",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "user": { "name": "Admin", "email": "admin@example.com", "role": "admin" }
  }
}

Projects API

Admin Endpoints

Public Endpoints

Service Types API

Public: GET /api/public/service-type — List active services

Teams API

Public: GET /api/public/team — List active team members

Testimonials API

Public: GET /api/public/testimonial — List active testimonials

Collaborations API

Public: GET /api/public/collaborations — List active collaborations

Contact API

Admin Endpoints

Public Endpoint

Banner API

Public: GET /api/public/banner — Get banner content

Home Sections API

Public: GET /api/public/home-section and GET /api/public/home-section/:slug

About Section API

Public: GET /api/public/about-section — Get about section content

Settings API

Public: GET /api/public/settings — Get public settings

File Upload API

File uploads use multipart/form-data. Supported formats include JPEG, PNG, WebP, SVG, and video files. Maximum upload size is 50MB (configurable in next.config.ts).

Dashboard API

Returns counts and summaries of all content types for the admin dashboard overview.

Newsletter API

Admin Endpoints

Public Endpoint

Public Endpoints Summary

All public endpoints are accessible without authentication.

Cloudinary Setup

1. Create a free account at cloudinary.com.
2. From your Cloudinary dashboard, note your Cloud Name, API Key, and API Secret.
3. Log into the admin panel and go to Settings → Cloudinary.
4. Enter your Cloudinary credentials and set a Folder Name to organize uploads.

Settings Management

The admin dashboard provides a comprehensive settings panel with the following tabs:

SEO & Metadata

The application generates dynamic metadata for each page using the settings configured in the admin panel. The lib/metadata.ts helper generates page-specific metadata with:

• Dynamic page titles
• Meta descriptions
• Keywords
• Open Graph images
• Application name

Configure these values from Admin Dashboard → Settings → Metadata.

Docker Deployment

# Build the image
docker build -t template-architecture .

# Run the container
docker run -p 3000:3000 --env-file .env template-architecture

The Dockerfile uses Node 20 with pnpm, installs dependencies, builds the Next.js application, and exposes port 3000.

Dockerfile Overview

FROM node:20
WORKDIR /app
RUN corepack enable
RUN corepack prepare pnpm@latest --activate
COPY package.json pnpm-lock.yaml ./
RUN pnpm install
COPY . .
EXPOSE 3000
RUN pnpm build
CMD ["pnpm", "start"]

Scripts