Headpat CMS - Next.js

A modern, full-featured Content Management System built with Next.js, TypeScript, and SQLite. Features user authentication, content management, media uploads, email notifications, and a comprehensive admin panel.

🚀 Features

• User Management: Registration, authentication, email verification, password reset
• Content Management: Articles, pages, projects, and resources with rich text editing
• Media Management: File uploads, image handling, and media library
• Admin Panel: Comprehensive dashboard with user management, content oversight, and system configuration
• Email System: Built-in email notifications with multiple template support
• Security: Session-based authentication, password hashing, activity logging
• Modern UI: Responsive design with Tailwind CSS

📁 Project Structure

├── app/                    # Next.js App Router
│   ├── admin/             # Admin panel pages and components
│   ├── api/               # API routes for backend functionality
│   ├── auth/              # Authentication pages (login, register, etc.)
│   ├── blog/              # Blog/articles pages
│   ├── pages/             # CMS pages
│   ├── profile/           # User profile management
│   ├── projects/          # Projects showcase
│   └── resources/         # Resources section
├── components/            # Reusable React components
│   ├── admin/             # Admin-specific components
│   ├── auth/              # Authentication components
│   ├── common/            # Shared components
│   ├── editor/            # Rich text editor components
│   ├── forms/             # Form components
│   ├── layout/            # Layout components
│   ├── media/             # Media management components
│   ├── ui/                # UI components
│   └── users/             # User management components
├── db/                    # Database files
├── lib/                   # Utility libraries and configurations
│   ├── email/             # Email service and templates
│   └── users/             # User management utilities
├── public/                # Static assets
├── scripts/               # Database migration and seeding scripts
└── tests/                 # Test files

⚡ Quick Setup

Prerequisites

• Node.js 18+
• npm or yarn
• MailHog (optional, for local email testing)

Installation

1. Clone the repository

   git clone <repository-url>
   cd headpat-nextjs
   

2. Install dependencies

   npm install
   

3. Environment setup

   cp .env.example .env
   

   Edit .env with your configuration:

   NODE_ENV=development
   SESSION_SECRET=your-secure-secret-key
   NEXT_PUBLIC_BASE_URL=http://localhost:3000
   
   # Email configuration (see Email Configuration section below)
   SMTP_HOST=localhost
   SMTP_PORT=1025
   SMTP_FROM=noreply@headpat-nextjs.local
   

4. Initialize database

   npm run migrate:seed
   

5. Start development server

   npm run dev
   

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

Default Admin Access

After seeding the database, you can log in with:

• Username: admin
• Password: admin123

⚠️ Important: Change the default admin password immediately after first login.

📧 Email Configuration

The application supports multiple email configurations for different environments:

Local Development with MailHog (Recommended)

MailHog is the easiest way to test emails locally without sending real emails.

1. Download and run MailHog:

   • Download from: https://github.com/mailhog/MailHog/releases
   • Or if you have Go installed: go install github.com/mailhog/MailHog@latest
   • Run: ./MailHog.exe (or MailHog on macOS/Linux)

2. Configure environment variables:

   SMTP_HOST=localhost
   SMTP_PORT=1025
   SMTP_USER=
   SMTP_PASS=
   SMTP_FROM=noreply@headpat-nextjs.local
   SMTP_SECURE=false
   

3. Access MailHog web interface: http://localhost:8025

All emails sent by the application will be captured by MailHog and viewable in the web interface.

Alternative: Mailtrap (Cloud-based testing)

For cloud-based email testing:

SMTP_HOST=smtp.mailtrap.io
SMTP_PORT=2525
SMTP_USER=your_mailtrap_user
SMTP_PASS=your_mailtrap_pass
SMTP_FROM=noreply@headpat-nextjs.local
SMTP_SECURE=false

Production SMTP

For production, configure with your email provider:

SMTP_HOST=your-smtp-host.com
SMTP_PORT=587
SMTP_USER=your-email@domain.com
SMTP_PASS=your-app-password
SMTP_FROM=noreply@yourdomain.com
SMTP_SECURE=true

Email Features

The system sends emails for:

• ✅ Welcome emails for new users
• ✅ Email verification during registration
• ✅ Password reset requests
• ✅ Password change notifications
• ✅ User import notifications (admin-created accounts)

🛠️ Available Scripts

Command	Description
npm run dev	Start development server
npm run build	Build for production
npm run start	Start production server
npm run lint	Run ESLint
npm run migrate	Run database migrations
npm run seed	Seed database with sample data
npm run migrate:seed	Run migrations and seed data
npm run reset-dev	Reset database and restart dev server

🔧 Key Technologies

• Framework: Next.js 15 with App Router
• Language: TypeScript
• Database: SQLite with Knex.js
• Styling: Tailwind CSS
• Editor: TipTap (rich text editing)
• Email: Nodemailer
• Authentication: Session-based with bcrypt
• File Uploads: Multer with Sharp for image processing

🏗️ Development

Database Management

• Migrations: Located in scripts/migrate.ts
• Seeding: Located in scripts/seed.ts
• Database file: db/database.sqlite3

API Structure

RESTful API endpoints are organized under /app/api/:

• /api/auth/* - Authentication endpoints
• /api/admin/* - Admin-only endpoints
• /api/users/* - User management
• /api/articles/* - Content management
• /api/media/* - File uploads and media

Adding New Features

1. Create API routes in /app/api/
2. Add corresponding UI components in /components/
3. Create pages in appropriate /app/ directories
4. Update database schema via migrations if needed

📝 License

This project is private and proprietary.

---

For more detailed documentation, see the docs/ directory and individual component README files.