QuillStack 📝

A Modern MERN Stack Blogging Platform with Studio Ghibli-Inspired Design

Live Demo · Report Bug · Request Feature

---

📖 Table of Contents

• About
• Features
• Tech Stack
• Screenshots
• Getting Started
  • Prerequisites
  • Installation
  • Environment Variables
• Project Structure
• API Documentation
• Deployment
• Future Enhancements
• Contributing
• License
• Contact
• Acknowledgments

---

🌟 About

QuillStack is a feature-rich, full-stack blogging platform built with the MERN stack and TypeScript. Inspired by the whimsical aesthetics of Studio Ghibli, it offers a delightful user experience with a warm, inviting interface in both light and dark themes.

This project serves as a comprehensive portfolio piece, demonstrating modern web development practices, including authentication, authorization, file uploads, rich text editing, and responsive design.

Key Highlights:

• 🎨 Studio Ghibli-inspired design system with custom light/dark themes
• 📝 Rich text editor powered by Tiptap
• 🔐 Secure JWT-based authentication with refresh tokens
• 🖼️ Image upload and management via Cloudinary
• 👨‍💼 Comprehensive admin dashboard for content management
• 📱 Fully responsive design across all devices
• ⚡ Optimized performance with compression and rate limiting
• 🛡️ Security-first approach with Helmet.js and input validation

---

✨ Features

For Users

• 📖 Browse Blogs: Explore published blog posts with pagination
• 🔍 Search & Filter: Find blogs by title or content
• 📄 Blog Details: Read full blog posts with formatted content
• 🌓 Theme Switching: Toggle between light, dark, and system themes
• 📱 Responsive Design: Seamless experience across all devices

For Admins

• 📊 Dashboard: Overview of site statistics and metrics
• ✍️ Blog Management: Create, edit, and delete blog posts
• 🖼️ Image Uploads: Upload and manage blog banner images via Cloudinary
• 👥 User Management: View and manage registered users
• 💬 Comment Moderation: Review and manage blog comments
• 📝 Rich Text Editor: Tiptap-powered WYSIWYG editor with:
  • Multiple heading levels
  • Text formatting (bold, italic, strikethrough)
  • Lists (ordered, unordered, task lists)
  • Blockquotes and code blocks
  • Links and horizontal rules
  • Tables
• 📋 Draft System: Save blogs as drafts before publishing

Security & Performance

• 🔒 Secure Authentication: JWT-based auth with HTTP-only cookies
• 🛡️ Authorization: Role-based access control (Admin/User)
• ⚡ Rate Limiting: Protection against brute-force attacks
• 🗜️ Compression: Gzip compression for faster load times
• 🧹 Input Sanitization: XSS protection with DOMPurify
• 🔐 Password Hashing: Bcrypt for secure password storage
• 🌐 CORS Protection: Whitelisted origins only

---

🛠️ Tech Stack

Frontend

• Framework: React 19
• Language: TypeScript 5.9
• Routing: React Router 7
• Styling: Tailwind CSS 4 with custom Ghibli-inspired theme
• UI Components: shadcn/ui (Radix UI primitives)
• Rich Text Editor: Tiptap 3
• Form Handling: React Hook Form with Zod validation
• HTTP Client: Axios
• Animations: Motion (Framer Motion)
• Notifications: Sonner
• Build Tool: Vite 7

Backend

• Runtime: Node.js
• Framework: Express 5
• Language: TypeScript 5.9
• Database: MongoDB with Mongoose
• Authentication: JWT (jsonwebtoken)
• File Upload: Multer + Cloudinary
• Validation: Express Validator
• Security: Helmet.js, bcryptjs
• Logging: Winston
• Rate Limiting: express-rate-limit
• Compression: compression middleware

DevOps & Tools

• Package Manager: pnpm 10
• Deployment: Render (Free Tier)
• Version Control: Git
• Runtime Execution: tsx (for TypeScript)

---

📸 Screenshots

Admin Dashboard

Comprehensive admin dashboard with metrics

---

🚀 Getting Started

Prerequisites

• Node.js (v18 or higher)
• pnpm (v10.24.0)
• MongoDB (local or Atlas)
• Cloudinary account (for image uploads)

Installation

1. Clone the repository

   git clone https://github.com/KeepSerene/quill-stack-blog-site-mern.git
   cd quill-stack-blog-site-mern
   

2. Install dependencies

   pnpm install
   

3. Install backend dependencies

   cd backend
   pnpm install
   

4. Install frontend dependencies

   cd ../frontend
   pnpm install
   cd ..
   

Environment Variables

Backend (.env)

Create a .env file in the backend directory:

# Server Configuration
PORT=3000
NODE_ENV=development

# Client URL (for CORS)
CLIENT_URL=http://localhost:5173

# Database
DB_URI=mongodb://localhost:27017/quill-stack-db
# Or use MongoDB Atlas:
# DB_URI=mongodb+srv://username:password@cluster.mongodb.net/quill-stack-db

# JWT Secrets (generate strong random strings)
JWT_ACCESS_SECRET=your-super-secret-access-key-min-32-chars
JWT_REFRESH_SECRET=your-super-secret-refresh-key-min-32-chars
JWT_ACCESS_EXPIRES_IN=1h
JWT_REFRESH_EXPIRES_IN=1w

# Admin Emails (comma-separated)
ADMIN_EMAILS=admin@example.com,another@example.com

# Cloudinary Configuration
CLOUDINARY_CLOUD_NAME=your-cloud-name
CLOUDINARY_API_KEY=your-api-key
CLOUDINARY_API_SECRET=your-api-secret

# Logging
WINSTON_LOG_LEVEL=info

Frontend (.env)

Create a .env file in the frontend directory:

# API Base URL
VITE_API_BASE_URL=http://localhost:3000/api/v1

Running the Application

Development Mode

1. Start the backend server

   cd backend
   pnpm dev
   

2. Start the frontend dev server (in a new terminal)

   cd frontend
   pnpm dev
   

3. Open your browser

   • Frontend: http://localhost:5173
   • Backend: http://localhost:3000

Production Build

# Build both frontend and backend
pnpm build

# Start the production server
pnpm start

---

📁 Project Structure (Tentative!)

quill-stack/
├── backend/
│   ├── src/
│   │   ├── configs/          # Configuration files
│   │   ├── controllers/      # Request handlers
│   │   │   └── v1/
│   │   │       ├── auth/     # Authentication controllers
│   │   │       ├── blogs/    # Blog controllers
│   │   │       ├── comments/ # Comment controllers
│   │   │       ├── likes/    # Like controllers
│   │   │       ├── users/    # User controllers
│   │   │       └── views/    # View controllers
│   │   ├── lib/              # Utility libraries
│   │   │   ├── cloudinary.ts # Cloudinary integration
│   │   │   ├── jwt.ts        # JWT utilities
│   │   │   ├── mongoose.ts   # MongoDB connection
│   │   │   └── winston.ts    # Logging configuration
│   │   ├── middlewares/      # Express middlewares
│   │   │   ├── authenticate.middleware.ts
│   │   │   ├── authorize.middleware.ts
│   │   │   ├── upload.middleware.ts
│   │   │   └── validation-errors.middleware.ts
│   │   ├── models/           # Mongoose schemas
│   │   │   ├── User.ts
│   │   │   ├── Blog.ts
│   │   │   ├── Comment.ts
│   │   │   ├── Like.ts
│   │   │   └── View.ts
│   │   ├── routes/           # API routes
│   │   │   └── v1/
│   │   │       ├── auth.route.ts
│   │   │       ├── blogs.route.ts
│   │   │       ├── comments.route.ts
│   │   │       ├── likes.route.ts
│   │   │       ├── users.route.ts
│   │   │       ├── views.route.ts
│   │   │       └── index.ts
│   │   ├── @types/           # TypeScript type definitions
│   │   └── server.ts         # Express app entry point
│   ├── package.json
│   └── tsconfig.json
├── frontend/
│   ├── public/
│   │   ├── favicon.svg
│   │   └── screenshots/      # App screenshots
│   ├── src/
│   │   ├── components/       # React components
│   │   │   ├── ui/           # shadcn/ui components
│   │   │   └── ...           # Custom components
│   │   ├── layouts/          # Layout components
│   │   │   ├── Root.tsx
│   │   │   └── Admin.tsx
│   │   ├── pages/            # Page components
│   │   │   ├── auth/         # Authentication pages
│   │   │   ├── users/        # User pages
│   │   │   ├── admins/       # Admin pages
│   │   │   └── errors/       # Error pages
│   │   ├── routes/           # React Router configuration
│   │   │   ├── actions/      # Form actions
│   │   │   ├── loaders/      # Data loaders
│   │   │   └── router.ts
│   │   ├── lib/              # Utilities
│   │   │   └── api/          # API client setup
│   │   ├── types/            # TypeScript types
│   │   ├── index.css         # Global styles
│   │   └── main.tsx          # App entry point
│   ├── index.html
│   ├── package.json
│   ├── tsconfig.json
│   └── vite.config.ts
├── package.json              # Root package.json
└── README.md

---

📡 API Documentation

Base URL

• Development: http://localhost:3000/api/v1
• Production: https://quill-stack.onrender.com/api/v1

Authentication Endpoints

Method	Endpoint	Description	Auth Required
POST	/auth/register	Register a new user	No
POST	/auth/login	Login user	No
POST	/auth/refresh-token	Refresh access token	Yes (Cookie)
POST	/auth/logout	Logout user	Yes

Blog Endpoints

Method	Endpoint	Description	Auth Required	Role
GET	/blogs	Get all published blogs	No	-
GET	/blogs/:slug	Get blog by slug	No	-
POST	/blogs	Create a new blog	Yes	Admin
PUT	/blogs/:slug	Update blog by slug	Yes	Admin
DELETE	/blogs/:slug	Delete blog by slug	Yes	Admin

User Endpoints

Method	Endpoint	Description	Auth Required	Role
GET	/users	Get all users	Yes	Admin
GET	/users/current	Get current user	Yes	User/Admin
GET	/users/:userId	Get user by ID	Yes	Admin
PUT	/users/current	Update current user	Yes	User/Admin
DELETE	/users/current	Delete current user	Yes	User/Admin
DELETE	/users/:userId	Delete user by ID	Yes	Admin
GET	/users/:userId/blogs	Get blogs by user	Yes	User/Admin

Comment Endpoints

| Method | Endpoint | Description |