Skip to content

README.md

Latest commit

 

History

History
1724 lines (1384 loc) · 49.4 KB

README.md

File metadata and controls

1724 lines (1384 loc) · 49.4 KB
Raw

🚀 Next.js Frontend Starter

Next.js React TypeScript Prisma Tailwind CSS Socket.io License Status Docker

Enterprise-Grade Next.js Frontend Application with Real-time Features

A comprehensive, production-ready Next.js 15 frontend application built with React 19, featuring JWT authentication, real-time WebSocket communication, advanced media management, role-based access control, internationalization, and a beautiful modern UI with shadcn/ui components.

📋 Table of Contents

✨ Features

🎯 Core Capabilities

  • 🔐 Advanced Authentication System

    • Multi-token JWT authentication (Access, Session, Refresh tokens)
    • OTP verification via Email, SMS, and WhatsApp
    • Password management (set, change, reset)
    • Email/Phone verification
    • Session management with token rotation
    • Secure logout with token blacklisting

  • 👥 User Management

    • Comprehensive user profiles with rich metadata
    • User status management (active, inactive, suspended, verified)
    • User type classification
    • Profile picture upload with MediaPicker integration
    • User search and filtering
    • Bulk operations support

  • 🔑 Role-Based Access Control (RBAC)

    • Flexible permission system with groups and permissions
    • Permission-based route guards
    • Component-level permission checks
    • User group management
    • Permission analytics and statistics

  • 📊 Real-time Dashboard

    • Live statistics with WebSocket updates
    • Interactive charts (Line, Bar, Pie, Area)
    • User growth tracking
    • Analytics by status, type, country, language, auth type
    • Recent sign-ins monitoring
    • Real-time data refresh

  • 📁 Advanced Media Management

    • Google Cloud Storage & Local Storage support
    • MediaPicker component for easy media selection
    • Folder organization system
    • Public/Private media with access keys
    • Image caching and optimization
    • Bulk upload and delete operations
    • Media statistics and analytics
    • Thumbnail generation
    • File type detection and organization

  • 📝 Activity Logging

    • Comprehensive audit trail
    • Real-time activity updates via WebSocket
    • User action tracking
    • Filtering and search capabilities
    • Activity statistics (INFO, WARNING, ERROR)
    • Detailed activity metadata

  • 🌍 Internationalization (i18n)

    • Full English and Arabic support
    • RTL (Right-to-Left) layout support
    • Dynamic language switching
    • Module-based translation system
    • Automatic locale detection

  • 🎨 Modern UI/UX

    • Beautiful, responsive design with Tailwind CSS
    • shadcn/ui component library
    • Dark/Light/System theme support
    • Collapsible sidebar navigation
    • Advanced search functionality
    • Toast notifications
    • Confirmation dialogs
    • Loading states and skeletons

  • ⚡ Real-time Communication

    • WebSocket integration with Socket.io
    • Real-time dashboard updates
    • Live activity log updates
    • Instant media library updates
    • Notification system
    • Room-based subscriptions

  • 💾 Caching & Performance

    • Redis caching layer
    • Client-side image caching
    • Media list caching
    • Cache invalidation strategies
    • Optimized API calls
    • Lazy loading and code splitting

  • 🔔 Notification System

    • Real-time notifications
    • Unread count tracking
    • Notification dropdown
    • Mark as read functionality

  • ⚙️ Project Settings

    • Logo management (Main, Header, Footer)
    • Social media links configuration
    • SEO & Meta tags management
    • Contact & support information
    • General project information

  • 📈 System Analytics

    • System health monitoring
    • Error tracking and logging
    • Cache statistics
    • Docker status
    • Top processes monitoring
    • Log viewer with filtering

  • 👥 Account Sharing

    • Share account access with other users
    • Send and receive access invitations
    • Request access to other accounts
    • Manage shared access permissions
    • View account sharing activity
    • Access level control (view, edit, full)
    • Real-time notifications for sharing events

🔧 Technical Features

  • Next.js 15.1+: App Router, Server Components, API Routes
  • React 19.2: Latest React features with concurrent rendering
  • TypeScript 5.0: Full type safety across the application
  • Prisma ORM: Type-safe database access with PostgreSQL
  • Socket.io: Real-time bidirectional communication
  • Tailwind CSS 3.4: Utility-first CSS framework
  • shadcn/ui: Beautiful, accessible component library
  • Redis: Caching and session management
  • Winston: Professional logging system
  • Recharts: Beautiful chart library
  • Axios: HTTP client for API calls
  • ioredis: Redis client for Node.js

🎨 UI Components

  • Layout Components: Navbar, Sidebar, Footer, MainLayout
  • Form Components: Input, Textarea, Select, OTP Input, Country Selector
  • Data Display: Card, Badge, Avatar, Tabs, Charts
  • Feedback: Toast, Dialog, Confirm Dialog, Loading States
  • Media: MediaPicker, FolderManager, CachedImage
  • Navigation: Side Panel, Dropdown Menu
  • Authentication: PageGuard, StatusGuard, PermissionGuard

🏗️ Architecture

System Architecture

┌───────────────────────────────────────────────────────────────┐
│                    Client Browser                             │
│                    (React 19 + Next.js 15)                    │
└────────────────────────────┬──────────────────────────────────┘
                              │
                              ▼
┌────────────────────────────────────────────────────────────────┐
│                    Next.js Application                         │
│                    (Port 3000)                                 │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │  Client-Side Features:                                   │  │
│  │  - React Components (Client Components)                  │  │
│  │  - Context Providers (Auth, Theme, i18n, WebSocket)      │  │
│  │  - Hooks (useApiCall, usePermissions, useToast)          │  │
│  │  - Real-time WebSocket Client                            │  │
│  │  - Client-side Caching (Media, Images)                   │  │
│  └──────────────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │  Server-Side Features:                                   │  │
│  │  - API Routes (Next.js API Routes)                       │  │
│  │  - Server Components                                     │  │
│  │  - Database Access (Prisma)                              │  │
│  │  - Redis Caching                                         │  │
│  │  - WebSocket Server (Socket.io)                          │  │
│  │  - Authentication Middleware                             │  │
│  │  - Permission Checking                                   │  │
│  └──────────────────────────────────────────────────────────┘  │
└────────────────────────────┬───────────────────────────────────┘
                              │
                ┌─────────────┴─────────────┐
                ▼                           ▼
┌──────────────────────────┐   ┌──────────────────────────┐
│   PostgreSQL Database    │   │   Redis Cache            │
│   (Port 5432)            │   │   (Port 6379)            │
│   - User Data            │   │   - Session Storage      │
│   - Permissions          │   │   - Media Cache          │
│   - Activity Logs        │   │   - API Response Cache   │
│   - Groups               │   │   - Token Blacklist      │
│   - Media                │   │   - Rate Limiting        │
│   - Notifications        │   │                          │
│   - Account Sharing      │   │                          │
└──────────────────────────┘   └──────────────────────────┘
                │
                ▼
┌──────────────────────────┐
│   pgAdmin                │
│   (Port 5050)            │
│   - Database Management  │
│   - Query Interface      │
│   - Visual Schema Editor │
└──────────────────────────┘
                │
                ▼
┌──────────────────────────┐
│   Google Cloud Storage   │
│   (Media & Static Files) │
│   - User Uploads         │
│   - Generated Content    │
│   - Static Assets        │
└──────────────────────────┘

Request Flow

1. User Action (Click, Form Submit, etc.)
   │
   ├─► Client Component
   │   ├─► Context (Auth, Theme, i18n)
   │   ├─► Custom Hooks (useApiCall, usePermissions)
   │   └─► API Service Call
   │
   ├─► Next.js API Route (/api/*)
   │   ├─► Authentication Middleware
   │   ├─► Permission Check
   │   ├─► Request Validation
   │   ├─► Business Logic
   │   ├─► Database Operations (Prisma)
   │   ├─► Cache Management (Redis)
   │   ├─► WebSocket Event Emission
   │   └─► Response Formatting
   │
   ├─► WebSocket Update (Real-time)
   │   └─► Client Receives Update
   │       └─► UI Updates Automatically
   │
   └─► Response
       ├─► Success/Error Handling
       ├─► Toast Notification
       └─► UI State Update

Component Architecture

App Layout
├── Providers (Auth, Theme, i18n, WebSocket, Toast)
├── MainLayout
│   ├── Navbar (Collapsible, Search, Theme Toggle)
│   ├── Sidebar (Navigation, Appearance Settings)
│   ├── TopNav (User Menu, Notifications)
│   └── Content Area
│       ├── PageGuard (Authentication Check)
│       ├── PermissionGuard (Permission Check)
│       └── Page Content
│           ├── Dashboard (Charts, Statistics)
│           ├── Users (List, Create, Edit, Delete)
│           ├── Media (Library, Upload, Manage)
│           ├── Activity (Logs, Filtering)
│           ├── Settings (Profile, Project, System)
│           └── Admin (Access Control, Analytics)
└── Footer

🛠️ Tech Stack

Frontend Framework

  • Next.js 15.1.5: React framework with App Router
  • React 19.2.0: UI library with concurrent features
  • TypeScript 5.0: Type-safe JavaScript

Styling & UI

  • Tailwind CSS 3.4: Utility-first CSS framework
  • shadcn/ui: High-quality React components
  • Lucide React: Beautiful icon library
  • Recharts 3.5: Charting library

State Management & Data

  • React Context API: Global state management
  • React Hooks: Custom hooks for data fetching
  • Axios: HTTP client
  • Prisma Client: Database ORM

Real-time & Communication

  • Socket.io Client 4.8: Real-time WebSocket communication
  • Socket.io Server: WebSocket server integration

Caching & Storage

  • Redis 7 (ioredis): Server-side caching (included in Docker setup)
  • Client-side Cache: Media and image caching
  • localStorage: Client-side persistence
  • Docker Volumes: Persistent data storage for database and cache

Authentication & Security

  • JWT (jsonwebtoken): Token-based authentication
  • bcryptjs: Password hashing
  • Session Management: Secure session handling

Database & ORM

  • PostgreSQL 16: Relational database (included in Docker setup)
  • Prisma 7.0: Next-generation ORM
  • Prisma Client: Type-safe database access
  • pgAdmin 4: Database management UI (included in Docker setup)

Utilities

  • Winston: Logging system
  • UUID: Unique identifier generation
  • Class Variance Authority: Component variants
  • clsx & tailwind-merge: Conditional class names

📦 Installation & Setup

Prerequisites

System Requirements:

  • OS: Linux (Ubuntu 20.04+), macOS, or Windows with WSL2
  • Docker: 20.10+ (recommended for easy setup)
  • Docker Compose: 2.0+ (for multi-container orchestration)
  • Node.js: 18.0 or higher (for local development without Docker)
  • npm: 9.0 or higher (for local development without Docker)
  • PostgreSQL: 16+ (included in Docker setup)
  • Redis: 7+ (included in Docker setup)

Development Tools:

  • Git 2.30+
  • Code editor (VS Code recommended)
  • Postman or similar API testing tool
  • Make (optional, for convenient commands)

Quick Start

Option 1: Docker (Recommended - Easiest Setup)

Step 1: Clone Repository

git clone <repository-url>
cd nextjs-frontend-starter

Step 2: Setup Environment

# Copy example environment file
cp example.env .env

# Edit .env file with your configuration (optional - defaults work)
nano .env

Step 3: Start All Services with Docker Compose

# Using Make (recommended)
make up

# Or using Docker Compose directly
docker compose up -d

This will automatically:

  • ✅ Start PostgreSQL database
  • ✅ Start Redis cache
  • ✅ Start Next.js application
  • ✅ Start pgAdmin (database management UI)
  • ✅ Run database migrations
  • ✅ Seed database with default data

Step 4: Access Application

Useful Commands:

make help           # Show all available commands
make logs           # View all service logs
make logs-app       # View app logs only
make db-shell       # Open PostgreSQL shell
make db-migrate     # Run Prisma migrations
make db-seed        # Seed the database
make shell          # Open app container shell
make down           # Stop all services
make clean          # Stop and remove volumes

Option 2: Local Development (Without Docker)

Step 1: Clone Repository

git clone <repository-url>
cd nextjs-frontend-starter

Step 2: Install Dependencies

npm install

Step 3: Setup Environment

# Copy example environment file
cp example.env .env

# Edit .env file with your configuration
nano .env

Required Environment Variables:

# Application
APP_MODE=development
APP_INTERNAL_PORT=3000

# API Configuration
NEXT_PUBLIC_API_URL=http://localhost:3000
API_INTERNAL_URL=http://localhost:3000

# Database (PostgreSQL)
DATABASE_HOST=localhost
DATABASE_NAME=postgres
DATABASE_USER=nextjs_db
DATABASE_PASSWORD=postgres123
DATABASE_PORT=5432
DATABASE_URL=postgresql://nextjs_db:postgres123@localhost:5432/postgres?schema=public

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_URL=redis://localhost:6379
REDIS_CACHE_ENABLED=true

# JWT
JWT_SECRET=your-secret-key
JWT_ALGORITHM=HS256
ACCESS_TOKEN_EXPIRY_MINUTES=60
SESSION_TOKEN_EXPIRY_MINUTES=10080
REFRESH_TOKEN_EXPIRY_MINUTES=43200

# Storage (Optional - for media uploads)
GOOGLE_STORAGE_BUCKET_NAME=your-bucket-name
STORAGE_BUCKET=your-bucket-name

# Media Access
MEDIA_ENABLE_ACCESS_KEY=true
MEDIA_ACCESS_KEY_LENGTH=32
MEDIA_REQUIRE_ACCESS_KEY_FOR_PUBLIC=false
MEDIA_ALLOW_ADMIN_ACCESS_WITHOUT_KEY=true

# pgAdmin (for Docker setup)
PGADMIN_EMAIL=admin@example.com
PGADMIN_PASSWORD=admin@123
PGADMIN_PORT=5050

Step 4: Setup Database

# Generate Prisma Client
npm run db:generate

# Push schema to database
npm run db:push

# Seed database with default data
npm run db:seed

Step 5: Start Development Server

# Development mode with hot reload
npm run dev

# Or start production build
npm run build
npm start

Step 6: Access Application

🚀 Quick Start

Docker Deployment (Recommended)

Start All Services:

# Using Make (recommended)
make up

# Or using Docker Compose directly
docker compose up -d

View Logs:

# All services
make logs

# Specific service
make logs-app
make logs-db
make logs-redis
make logs-pgadmin

# Or using Docker Compose
docker compose logs -f
docker compose logs -f app

Database Management:

# Open PostgreSQL shell
make db-shell

# Run migrations
make db-migrate

# Seed database
make db-seed

# Open Prisma Studio
make db-studio

# Reset database
make db-reset

Stop Services:

# Stop all services
make down

# Stop and remove volumes
make clean

# Or using Docker Compose
docker compose down
docker compose down -v

Access Points:

Local Development (Without Docker)

Development Mode:

# Install dependencies
npm install

# Setup environment
cp example.env .env
# Edit .env with your configuration

# Setup database (requires PostgreSQL running)
npm run db:generate
npm run db:push
npm run db:seed

# Start development server
npm run dev

Production Build:

# Build application
npm run build

# Start production server
npm start

# Or use PM2
npm run pm2:start

Development with Docker

Start in Development Mode:

# Start with development overrides
docker compose -f docker-compose.yaml -f docker-compose.dev.yaml up -d

# Or using Make
make up-dev

This enables:

  • Hot-reload for code changes
  • Development optimizations
  • Easier debugging

📚 Project Structure

nextjs-frontend-starter/
├── 📁 src/
│   ├── 📁 app/                          # Next.js App Router
│   │   ├── 📁 (auth)/                   # Authentication pages
│   │   │   ├── login/                   # Login page
│   │   │   ├── signup/                  # Signup page
│   │   │   ├── verify/                  # Email/Phone verification
│   │   │   ├── set-password/            # Set password
│   │   │   └── forgot-password/         # Password recovery
│   │   ├── 📁 api/                      # API Routes
│   │   │   ├── auth/                    # Authentication endpoints
│   │   │   ├── users/                   # User management
│   │   │   ├── dashboard/               # Dashboard statistics
│   │   │   ├── media/                   # Media management
│   │   │   ├── activity/                # Activity logs
│   │   │   ├── permissions/             # Permissions & groups
│   │   │   ├── settings/                # User settings
│   │   │   └── notifications/           # Notifications
│   │   ├── 📁 admin/                    # Admin pages
│   │   │   ├── users/                   # User management
│   │   │   ├── access-control/          # Permissions & groups
│   │   │   ├── project-settings/        # Project configuration
│   │   │   └── system-analytics/        # System monitoring
│   │   ├── dashboard/                   # Dashboard page
│   │   ├── media/                       # Media library
│   │   ├── activity/                    # Activity logs
│   │   ├── profile-settings/            # User profile settings
│   │   ├── notifications/               # Notifications page
│   │   ├── layout.tsx                   # Root layout
│   │   └── page.tsx                     # Home page
│   │
│   ├── 📁 components/                    # React Components
│   │   ├── 📁 auth/                     # Authentication components
│   │   │   ├── PageGuard.tsx            # Route protection
│   │   │   └── StatusGuard.tsx          # User status check
│   │   ├── 📁 layout/                   # Layout components
│   │   │   ├── MainLayout.tsx           # Main app layout
│   │   │   ├── Navbar.tsx               # Sidebar navigation
│   │   │   └── TopNav.tsx               # Top navigation bar
│   │   ├── 📁 dashboard/                 # Dashboard components
│   │   │   ├── ChartCard.tsx            # Chart container
│   │   │   ├── LineChart.tsx            # Line chart
│   │   │   ├── BarChart.tsx             # Bar chart
│   │   │   ├── PieChart.tsx             # Pie chart
│   │   │   └── AreaChart.tsx            # Area chart
│   │   ├── 📁 media/                     # Media components
│   │   │   ├── MediaPicker.tsx          # Media selection component
│   │   │   ├── FolderManager.tsx        # Folder management
│   │   │   └── CachedImage.tsx          # Optimized image component
│   │   ├── 📁 ui/                       # shadcn/ui components
│   │   │   ├── button.tsx               # Button component
│   │   │   ├── card.tsx                 # Card component
│   │   │   ├── input.tsx                # Input component
│   │   │   ├── dialog.tsx               # Dialog component
│   │   │   └── ...                      # More UI components
│   │   └── 📁 permissions/               # Permission components
│   │       ├── PermissionGuard.tsx      # Permission check
│   │       └── PermissionButton.tsx     # Permission-based button
│   │
│   ├── 📁 context/                      # React Context Providers
│   │   ├── AuthContext.tsx              # Authentication context
│   │   ├── ThemeContext.tsx             # Theme management
│   │   ├── I18nContext.tsx              # Internationalization
│   │   ├── WebSocketContext.tsx         # WebSocket connection
│   │   └── Provider.tsx                 # Combined providers
│   │
│   ├── 📁 hooks/                         # Custom React Hooks
│   │   ├── useApiCall.ts                # API call hook
│   │   ├── useAuth.ts                   # Authentication hook
│   │   ├── usePermissions.ts            # Permission checking
│   │   ├── useToast.ts                  # Toast notifications
│   │   └── useDebounce.ts               # Debounce utility
│   │
│   ├── 📁 services/                      # API Service Layer
│   │   ├── auth.service.ts              # Authentication service
│   │   ├── user.service.ts              # User service
│   │   ├── media.service.ts             # Media service
│   │   ├── dashboard.service.ts         # Dashboard service
│   │   ├── permission.service.ts        # Permission service
│   │   └── websocket.service.ts         # WebSocket service
│   │
│   ├── 📁 lib/                          # Utility Libraries
│   │   ├── 📁 api/                      # API utilities
│   │   │   ├── ApiService.ts            # API service class
│   │   │   └── ApiServiceFactory.ts    # API factory
│   │   ├── 📁 cache/                     # Caching utilities
│   │   │   ├── cache.ts                # Redis cache
│   │   │   ├── mediaCache.ts           # Media cache
│   │   │   └── imageCache.ts           # Image cache
│   │   ├── 📁 authenticate/             # Auth utilities
│   │   │   ├── helpers.ts              # Auth helpers
│   │   │   └── session-manager.ts      # Session management
│   │   ├── 📁 middleware/               # Middleware
│   │   │   ├── auth.ts                 # Auth middleware
│   │   │   └── permission-check.ts     # Permission middleware
│   │   └── 📁 multilingual/             # i18n utilities
│   │       └── i18n.ts                  # Translation loader
│   │
│   ├── 📁 models/                       # TypeScript Models
│   │   ├── user.model.ts               # User types
│   │   ├── media.model.ts              # Media types
│   │   ├── permission.model.ts          # Permission types
│   │   └── api.model.ts                # API response types
│   │
│   ├── 📁 locales/                      # Translation Files
│   │   ├── 📁 en/                       # English translations
│   │   │   ├── general.json            # General terms
│   │   │   ├── auth.json               # Auth terms
│   │   │   ├── dashboard.json          # Dashboard terms
│   │   │   └── ...                     # More modules
│   │   └── 📁 ar/                       # Arabic translations
│   │       └── ...                     # Same structure
│   │
│   └── 📁 types/                        # TypeScript Types
│       ├── axios.ts                    # Axios types
│       └── cache.d.ts                  # Cache types
│
├── 📁 prisma/                           # Prisma ORM
│   ├── schema.prisma                    # Database schema
│   ├── seed-defaults.js                 # Seed data
│   └── migrations/                     # Database migrations
│
├── 📁 scripts/                          # Helper Scripts
│   ├── init-db.sql                      # PostgreSQL initialization
│   └── pgadmin-servers.json             # pgAdmin server config
│
├── 📁 public/                           # Static Assets
│   └── uploads/                         # Uploaded media (local)
│
├── 📄 server.js                         # Custom Next.js server
├── 📄 start.sh                          # Startup script (auto migrations)
├── 📄 Makefile                          # Docker management commands
├── 📄 next.config.ts                    # Next.js configuration
├── 📄 tailwind.config.js                # Tailwind configuration
├── 📄 tsconfig.json                     # TypeScript configuration
├── 📄 package.json                      # Dependencies
├── 📄 docker-compose.yaml               # Docker Compose config
├── 📄 docker-compose.dev.yaml            # Development override
├── 📄 Dockerfile                        # Docker image
├── 📄 example.env                        # Environment variables template
└── 📄 README.md                         # This file

🎨 Key Features Explained

🔐 Authentication System

Multi-Token Architecture:

  • Access Token: Short-lived (1 hour) for API authentication
  • Session Token: Medium-lived (7 days) with full user data
  • Refresh Token: Long-lived (30 days) for token renewal

Features:

  • Login with password or OTP
  • Email/Phone verification
  • Password management (set, change, reset)
  • Secure session management
  • Token rotation on refresh

Usage Example:

import { useAuth } from "@context/AuthContext"

function MyComponent() {
  const { user, login, logout, isAuthenticated } = useAuth()
  
  if (!isAuthenticated) {
    return <LoginForm onLogin={login} />
  }
  
  return <div>Welcome, {user?.email}</div>
}

📊 Real-time Dashboard

Features:

  • Live statistics with WebSocket updates
  • Interactive charts (Line, Bar, Pie, Area)
  • User growth tracking
  • Analytics by multiple dimensions
  • Real-time data refresh

WebSocket Integration:

import { useWebSocket } from "@context/WebSocketContext"

function Dashboard() {
  const { onUserCreated, onUserUpdated, onDashboardStatsUpdate } = useWebSocket()
  
  useEffect(() => {
    onUserCreated(() => {
      // Refresh dashboard data
      refreshDashboard()
    })
  }, [])
}

📁 Media Management

Features:

  • Google Cloud Storage & Local Storage support
  • MediaPicker component for easy selection
  • Folder organization
  • Public/Private media with access keys
  • Image caching and optimization
  • Bulk operations

MediaPicker Usage:

import { MediaPicker } from "@components/media/MediaPicker"

function MyComponent() {
  const [pickerOpen, setPickerOpen] = useState(false)
  
  return (
    <>
      <Button onClick={() => setPickerOpen(true)}>
        Select Media
      </Button>
      <MediaPicker
        open={pickerOpen}
        onClose={() => setPickerOpen(false)}
        onSelect={(media) => {
          // Handle selected media
          console.log(media)
        }}
        mode="image"
        allowUrl={true}
        allowUpload={true}
      />
    </>
  )
}

🌍 Internationalization

Features:

  • English and Arabic support
  • RTL layout support
  • Dynamic language switching
  • Module-based translations

Usage:

import { useModuleI18n } from "@context/I18nContext"

function MyComponent() {
  const { t } = useModuleI18n("general")
  const { t: tAuth } = useModuleI18n("auth")
  
  return (
    <div>
      <h1>{t("welcome")}</h1>
      <button>{tAuth("login")}</button>
    </div>
  )
}

🔑 Permission System

Features:

  • Permission-based route guards
  • Component-level permission checks
  • User group management
  • Permission analytics

Usage:

import { PermissionGuard } from "@components/permissions/PermissionGuard"
import { usePermissions } from "@hooks/usePermissions"

function MyComponent() {
  const { hasPermission } = usePermissions()
  
  return (
    <PermissionGuard requirePermission="manage_users">
      <UserManagementPanel />
    </PermissionGuard>
  )
}

🔌 API Integration

API Service

The application uses a centralized API service for all HTTP requests:

import { createPublicApiService } from "@lib/api/ApiServiceFactory"

const apiService = createPublicApiService()

// GET request
const response = await apiService.get("/api/users")

// POST request
const response = await apiService.post("/api/users", { name: "John" })

// With authentication
const authApi = createPublicApiService({
  "X-Session-Token": sessionToken
})

Custom Hook for API Calls

import { useApiCall } from "@hooks/useApiCall"

function MyComponent() {
  const fetchUsers = useApiCall(
    async () => {
      return await userService.getUsers()
    },
    {
      onSuccess: (data) => {
        console.log("Users loaded:", data)
      },
      onError: (error) => {
        console.error("Error:", error)
      },
      showErrorToast: true,
    }
  )
  
  useEffect(() => {
    fetchUsers.execute()
  }, [])
  
  return (
    <div>
      {fetchUsers.loading && <Loader />}
      {fetchUsers.data && <UserList users={fetchUsers.data} />}
    </div>
  )
}

📱 Real-time Features

WebSocket Integration

Connection:

import { useWebSocket } from "@context/WebSocketContext"

function MyComponent() {
  const { 
    connected,
    subscribeToDashboard,
    onUserCreated,
    onMediaUpdated 
  } = useWebSocket()
  
  useEffect(() => {
    subscribeToDashboard()
    
    onUserCreated((user) => {
      console.log("New user created:", user)
    })
    
    onMediaUpdated((media) => {
      console.log("Media updated:", media)
    })
  }, [])
}

Available Events:

  • user:created - New user registered
  • user:updated - User profile updated
  • user:deleted - User deleted
  • media:created - New media uploaded
  • media:updated - Media updated
  • media:deleted - Media deleted
  • folder:created - Folder created
  • folder:updated - Folder updated
  • folder:deleted - Folder deleted
  • activity:new - New activity log
  • dashboard:stats:update - Dashboard statistics updated

🎯 Usage Examples

Creating a New Page

"use client"

import { MainLayout } from "@components/layout/MainLayout"
import { PageGuard } from "@components/auth/PageGuard"
import { PermissionGuard } from "@components/permissions/PermissionGuard"

export default function MyPage() {
  return (
    <PageGuard requireAuth>
      <PermissionGuard requirePermission="view_my_feature">
        <MainLayout
          title="My Page"
          description="Page description"
        >
          <div>
            {/* Your page content */}
          </div>
        </MainLayout>
      </PermissionGuard>
    </PageGuard>
  )
}

Using MediaPicker in Forms

import { MediaPicker } from "@components/media/MediaPicker"
import { useState } from "react"

function ProfileForm() {
  const [mediaPickerOpen, setMediaPickerOpen] = useState(false)
  const [logoUrl, setLogoUrl] = useState("")
  
  return (
    <>
      <Input 
        value={logoUrl}
        placeholder="Logo URL"
      />
      <Button onClick={() => setMediaPickerOpen(true)}>
        Select Logo
      </Button>
      
      <MediaPicker
        open={mediaPickerOpen}
        onClose={() => setMediaPickerOpen(false)}
        onSelect={(media) => {
          const url = typeof media === 'string' 
            ? media 
            : media.public_url
          setLogoUrl(url)
          setMediaPickerOpen(false)
        }}
        mode="image"
      />
    </>
  )
}

Using Toast Notifications

import { useToast } from "@hooks/useToast"

function MyComponent() {
  const { showSuccess, showError, showInfo } = useToast()
  
  const handleSave = async () => {
    try {
      await saveData()
      showSuccess("Data saved successfully!")
    } catch (error) {
      showError("Failed to save data")
    }
  }
}

🐳 Docker Deployment

Docker Compose Services

The project includes a complete Docker Compose setup with all required services:

Services:

  • app: Next.js application (Port 3000)
  • postgres: PostgreSQL 16 database (Port 5432)
  • redis: Redis 7 cache (Port 6379)
  • pgadmin: Database management UI (Port 5050)
  • nginx: Reverse proxy (Port 9080, optional)

Quick Start with Docker

# Start all services
make up
# or
docker compose up -d

# View logs
make logs
# or
docker compose logs -f

# Stop services
make down
# or
docker compose down

Docker Compose Configuration

The docker-compose.yaml includes:

  • Automatic database migrations on startup
  • Database seeding with default data
  • Health checks for all services
  • Volume persistence for data
  • Network isolation for security
  • Resource limits for production

Environment Variables

Key environment variables for Docker:

# Database (auto-configured for Docker)
DATABASE_HOST=postgres
DATABASE_NAME=postgres
DATABASE_USER=nextjs_db
DATABASE_PASSWORD=postgres123
DATABASE_PORT=5432
DATABASE_URL=postgresql://nextjs_db:postgres123@postgres:5432/postgres?schema=public

# Redis (auto-configured for Docker)
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_URL=redis://redis:6379

# pgAdmin
PGADMIN_EMAIL=admin@example.com
PGADMIN_PASSWORD=admin@123
PGADMIN_PORT=5050

# Migration & Seed settings
WAIT_FOR_DB=true
DB_WAIT_TIMEOUT=60
SKIP_MIGRATIONS=false
SKIP_SEED=false

Database Management with pgAdmin

Access pgAdmin:

  1. Open http://localhost:5050
  2. Login with:
    • Email: admin@example.com (or your PGADMIN_EMAIL)
    • Password: admin@123 (or your PGADMIN_PASSWORD)

Connect to Database:

  • The database server is pre-configured in pgAdmin
  • Server name: "Next.js Frontend DB"
  • Host: postgres (internal Docker network)
  • Port: 5432
  • Username: nextjs_db (or your DATABASE_USER)
  • Password: postgres123 (or your DATABASE_PASSWORD)

Build and Deploy

Build Docker Image:

# Build image
make build
# or
docker compose build

# Build for production (no cache)
make prod-build

Deploy to Production:

# Pull latest images and deploy
make prod-deploy
# or
docker compose pull
docker compose up -d --build
docker compose exec app npx prisma migrate deploy

View Service Status:

# Check container status
make status
# or
docker compose ps

# Check health
make health

Development with Docker

Start in Development Mode:

# With hot-reload and development optimizations
make up-dev
# or
docker compose -f docker-compose.yaml -f docker-compose.dev.yaml up -d

Access Container Shell:

# App container
make shell
# or
docker compose exec app sh

# PostgreSQL container
make shell-postgres
# or
docker compose exec postgres sh

# Redis container
make shell-redis
# or
docker compose exec redis sh

Database Operations

Run Migrations:

# Production migrations
make db-migrate
# or
docker compose exec app npx prisma migrate deploy

# Development migrations
make db-migrate-dev
# or
docker compose exec app npx prisma migrate dev

Seed Database:

make db-seed
# or
docker compose exec app npx prisma db seed

Open Prisma Studio:

make db-studio
# or
docker compose exec app npx prisma studio

Reset Database:

make db-reset
# or
docker compose exec app npx prisma migrate reset --force

Cleanup

Stop and Remove:

# Stop services
make down

# Stop and remove volumes (clean slate)
make clean

# Remove images
make clean-images

# Full cleanup (prune everything)
make prune

Automatic Database Setup

The start.sh script automatically handles database setup on container startup:

Features:

  • ✅ Waits for database to be ready (configurable timeout)
  • ✅ Runs Prisma migrations automatically
  • ✅ Seeds database with default data (if empty)
  • ✅ Generates Prisma Client if needed
  • ✅ Handles errors gracefully with retries

Environment Variables:

# Database wait settings
WAIT_FOR_DB=true              # Wait for database (default: true)
DB_WAIT_TIMEOUT=60            # Wait timeout in seconds (default: 60)

# Migration & seed settings
SKIP_MIGRATIONS=false         # Skip migrations (default: false)
SKIP_SEED=false               # Skip seeding (default: false)
FORCE_SEED=false              # Force seed even if data exists (default: false)

Manual Control:

# Skip migrations on startup
SKIP_MIGRATIONS=true docker compose up -d

# Skip seeding on startup
SKIP_SEED=true docker compose up -d

# Force seed even if data exists
FORCE_SEED=true docker compose up -d

Production Deployment

Recommended Production Setup:

  1. Use external PostgreSQL (managed database service)
  2. Use external Redis (managed cache service)
  3. Configure environment variables for production
  4. Enable Nginx reverse proxy (optional)
  5. Set up SSL/TLS certificates
  6. Configure backups for database
  7. Set up monitoring and logging

Start with Nginx:

make up-nginx
# or
docker compose --profile with-nginx up -d

Database Connection

From Host Machine:

# Connect to PostgreSQL
psql -h localhost -p 5432 -U nextjs_db -d postgres

# Or using Docker
docker compose exec postgres psql -U nextjs_db -d postgres

Connection String:

postgresql://nextjs_db:postgres123@localhost:5432/postgres

From Application (Docker Network):

postgresql://nextjs_db:postgres123@postgres:5432/postgres

📝 Available Scripts

NPM Scripts

# Development
npm run dev              # Start development server
npm run build            # Build for production
npm start                # Start production server

# Database
npm run db:generate      # Generate Prisma Client
npm run db:push          # Push schema to database
npm run db:seed          # Seed database
npm run db:studio        # Open Prisma Studio
npm run db:migrate       # Run migrations

# PM2 (Process Manager)
npm run pm2:start        # Start with PM2
npm run pm2:stop         # Stop PM2 process
npm run pm2:restart      # Restart PM2 process
npm run pm2:logs         # View PM2 logs

# Linting & Formatting
npm run lint             # Run ESLint
npm run format           # Format code with Prettier

Make Commands (Docker Management)

The project includes a comprehensive Makefile for convenient Docker management:

# Docker Commands
make build               # Build Docker images
make up                  # Start all services
make up-dev              # Start in development mode
make up-nginx            # Start with Nginx reverse proxy
make down                # Stop all services
make restart             # Restart all services
make logs                # View all service logs
make logs-app            # View app logs only
make logs-db             # View database logs only
make logs-redis          # View Redis logs only
make logs-pgadmin        # View pgAdmin logs only

# Database Commands
make db-shell            # Open PostgreSQL shell
make db-migrate          # Run Prisma migrations
make db-migrate-dev      # Run development migrations
make db-seed             # Seed the database
make db-reset            # Reset database (migrate + seed)
make db-studio           # Open Prisma Studio
make db-generate         # Generate Prisma Client
make db-push             # Push schema to database

# Utility Commands
make shell               # Open bash shell in app container
make shell-postgres      # Open shell in postgres container
make shell-redis         # Open shell in redis container
make status              # Show container status
make health              # Check service health

# Cleanup Commands
make clean               # Stop services and remove volumes
make clean-images        # Remove Docker images
make prune               # Clean up all Docker resources

# Development Commands
make dev                 # Start local development server
make install             # Install dependencies
make lint                # Run linter
make format              # Format code

# Production Commands
make prod-build          # Build for production (no cache)
make prod-up             # Start production services
make prod-deploy         # Deploy to production

# Help
make help                # Show all available commands

Quick Reference:

Command Description
make up Start all services
make down Stop all services
make logs View logs
make db-shell Open database shell
make db-migrate Run migrations
make shell Open app container
make clean Clean up everything

🔒 Security Features

  • JWT Authentication: Secure token-based authentication
  • Password Hashing: bcrypt with configurable salt rounds
  • Token Blacklisting: Redis-based token invalidation
  • Permission Guards: Route and component-level protection
  • Input Validation: Server-side validation for all inputs
  • CORS Protection: Configurable CORS origins
  • Rate Limiting: Request throttling (via backend)
  • Secure Headers: Helmet.js security headers
  • Media Access Control: Access keys for private media

🎨 Theming

The application supports three theme modes:

  • Light Mode: Bright, clean interface
  • Dark Mode: Dark, eye-friendly interface
  • System Mode: Automatically follows system preference

Theme Switching:

import { useTheme } from "@context/ThemeContext"

function ThemeToggle() {
  const { theme, setTheme } = useTheme()
  
  return (
    <select value={theme} onChange={(e) => setTheme(e.target.value)}>
      <option value="light">Light</option>
      <option value="dark">Dark</option>
      <option value="dynamic">System</option>
    </select>
  )
}

📊 Performance Optimizations

  • Image Optimization: Next.js Image component with caching
  • Code Splitting: Automatic route-based code splitting
  • Lazy Loading: Dynamic imports for heavy components
  • Client-side Caching: Media and image caching
  • Server-side Caching: Redis caching for API responses
  • Optimistic Updates: Immediate UI updates with background sync
  • Debouncing: Debounced search and input handlers
  • Memoization: React.memo and useMemo for expensive computations

🧪 Testing

# Run tests (when implemented)
npm test

# Run tests in watch mode
npm test:watch

# Run tests with coverage
npm test:coverage

🔧 Troubleshooting

Docker Issues

Services won't start:

# Check if ports are already in use
netstat -tulpn | grep -E '3000|5432|6379|5050'

# Stop conflicting services or change ports in .env

Database connection errors:

# Check if database is ready
make health
# or
docker compose exec postgres pg_isready -U postgres

# View database logs
make logs-db

Migrations failing:

# Reset database and try again
make db-reset

# Or manually run migrations
make db-migrate

Volume permission issues:

# Fix permissions
sudo chown -R $USER:$USER ./volumes

Container won't start:

# Check logs
make logs

# Rebuild containers
make clean
make build
make up

Database Issues

Can't connect to database:

  1. Check if PostgreSQL container is running: docker compose ps
  2. Verify environment variables in .env
  3. Check database logs: make logs-db
  4. Try connecting manually: make db-shell

Migrations not running:

  1. Check SKIP_MIGRATIONS environment variable
  2. Manually run: make db-migrate
  3. Check Prisma schema: npx prisma validate

Seed data not loading:

  1. Check if database is empty: make db-shell then SELECT COUNT(*) FROM "User";
  2. Force seed: FORCE_SEED=true docker compose up -d
  3. Manually seed: make db-seed

pgAdmin Issues

Can't access pgAdmin:

  1. Check if pgAdmin is running: docker compose ps pgadmin
  2. Verify port 5050 is not in use
  3. Check logs: make logs-pgadmin
  4. Verify credentials in .env file

Can't connect to database in pgAdmin:

  1. Use postgres as hostname (Docker network)
  2. Port: 5432
  3. Username: postgres (or your DATABASE_USER)
  4. Password: postgres123 (or your DATABASE_PASSWORD)

Redis Issues

Redis connection errors:

# Check if Redis is running
docker compose ps redis

# Test Redis connection
docker compose exec redis redis-cli ping

# View Redis logs
make logs-redis

Application Issues

App won't start:

  1. Check logs: make logs-app
  2. Verify environment variables
  3. Check database connection
  4. Rebuild: make clean && make build && make up

Build errors:

# Clean build
make clean
make build

# Check for TypeScript errors
npm run lint

📄 License

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

🙏 Acknowledgments

Built with amazing open-source technologies:

Made with ❤️ using modern web technologies

This project is free to use, modify, and distribute for any purpose without restrictions.