A modern, multi‑theme blogging platform
Type‑safe · Modular · i18n · Production‑ready
Features · Themes · Tech Stack · Structure · Quick Start
maddyBlog is an open‑source blogging platform with a multi‑theme engine, drag‑drop header/footer builder, Persian/English i18n, and AI integration. Built with Next.js 16, TypeScript, and PostgreSQL — every module is decoupled, type‑safe, and production‑ready.
✦ 9 themes · Visual header/footer builder · AI content tools · i18n ✦
| 🎨 Multi‑Theme Engine | 9 themes (default, Madelin, Zoomg, Zoomji, DigiTech, GameVerse, PersonalBlog, NewsWire, EduPro) with runtime switching |
| 🧩 Header/Footer Builder | Drag‑drop visual builder with 14 element types, per‑theme configs, color customization |
| ✍️ Rich‑Text Editor | Tiptap‑powered with slash commands, image upload, live preview, autosave |
| 🔐 Auth System | JWT (jose) with httpOnly cookies, bcrypt, role‑based (USER / ADMIN) |
| 🏷️ Categories & Tags | Organize content with PostTag many‑to‑many |
| 💬 Nested Comments | Threaded discussions with reply trees + in‑memory rate limiting + @mentions |
| 🌐 i18n | Persian (RTL) / English (LTR) with message files, admin UI in Persian |
| 🤖 AI Integration | Content generation via Anthropic, Gemini, Ollama providers |
| 🔍 Full‑Text Search | PostgreSQL to_tsvector / to_tsquery across title + content |
| 📈 Trending Algorithm | views × 0.6 + comments × 0.4 + recency boost |
| ❤️ Reactions | Like / Fire / Clap with toggle per user |
| 🔖 Bookmarks | Save posts for later |
| 👁️ View Tracking | Granular PostView analytics (visitorHash, referrer, userAgent) |
| 📊 Analytics Dashboard | recharts charts, traffic sources, top posts table, daily stats |
| 🎬 Stories & Slides | Instagram‑style stories + hero slides with scheduling and ordering |
| 📧 Newsletter | Email subscription with rate limiting |
| 👥 Follow System | Follow/unfollow with unique constraints + activity feed |
| 🔔 Notifications | Follow, comment, reaction, mention, publish — with admin bell + polling |
| 📰 Activity Feed | Timeline of followed users' actions |
| 👤 Profile Pages | /users/[username] with bio, avatar, post list |
| 🎛️ Admin Dashboard | Full admin panel: posts, comments, users, themes, media, plugins, settings |
| 🖼️ Media Library | Upload, browse, copy URL, delete — grid view |
| 🐳 Docker | Multi‑stage Alpine build + docker‑compose with PostgreSQL 16 |
| 🚀 CI/CD | GitHub Actions — lint → typecheck → build on push/PR |
| Theme | Vibe | Directory |
|---|---|---|
| Default | Clean, minimalist | default |
| Madelin | Modern, feminine | madelin |
| Zoomg | Gaming, bold | zoomg |
| Zoomji | Tech, vibrant | zoomji |
| DigiTech | Digital, futuristic | digitech |
| GameVerse | Dark, immersive | gameverse |
| PersonalBlog | Clean card‑based | personalblog |
| NewsWire | News portal style | newswire |
| EduPro | Educational, structured | edupro |
All themes share a responsive layout, support dynamic header/footer customization, and can be switched live from the admin panel.
📦 All themes are published on the maddyblog-themes repo — install via the admin Marketplace tab.
🧩 All plugins are published on the maddyblog-plugins repo — install via the admin Marketplace tab.
| Layer | Technology |
|---|---|
| 🎨 Frontend | Next.js 16 · TypeScript 5.x · React 19 · TailwindCSS |
| ⚙️ Backend | REST API Routes + Server Components |
| 🗄️ Database | PostgreSQL · Prisma ORM v7 (driver adapters) |
| ✍️ Editor | Tiptap (Slash commands, image upload, live preview) |
| ✅ Validation | Zod v4 |
| 🔐 Auth | JWT via jose · bcryptjs · httpOnly cookies |
| 🌐 i18n | Custom provider with message files (fa/en) |
| 🤖 AI | Anthropic · Gemini · Ollama providers |
| 📊 Charts | recharts |
| 🧹 Dev Tools | ESLint · Prettier · Husky · lint‑staged · Vitest |
| 🐳 Deploy | Docker · docker‑compose · GitHub CI |
maddyBlog/
├── prisma/ # Schema, migrations & seed
├── src/
│ ├── app/
│ │ ├── (admin)/ # Admin dashboard (15 pages)
│ │ ├── api/ # 25+ REST endpoints
│ │ ├── posts/ # Public blog pages
│ │ ├── categories/ # Category pages
│ │ ├── tags/ # Tag pages
│ │ ├── search/ # Search page
│ │ └── users/ # Profile pages
│ ├── components/
│ │ ├── admin/ # Admin UI (Header, Sidebar, etc.)
│ │ ├── blog/ # PostCard, CommentForm, SearchBar
│ │ ├── editor/ # Tiptap editor, toolbar, slash commands
│ │ ├── header-footer/ # Dynamic header/footer renderer + elements
│ │ ├── shared/ # ImageSlider, StoriesBar
│ │ ├── social/ # FollowButton, NotificationBell, ActivityFeed
│ │ ├── ui/ # Reusable UI primitives
│ │ └── seo/ # StructuredData (JSON‑LD)
│ ├── themes/ # 9 theme packages (100+ components)
│ │ ├── default/
│ │ ├── madelin/
│ │ ├── zoomg/
│ │ ├── zoomji/
│ │ ├── digitech/
│ │ ├── gameverse/
│ │ ├── personalblog/
│ │ ├── newswire/
│ │ └── edupro/
│ ├── features/ # Domain modules (auth, post, comment)
│ ├── services/ # Business logic (analytics, search, etc.)
│ ├── lib/ # prisma, jwt, errors, logger, ai providers
│ ├── i18n/ # i18n provider + message loading
│ └── cli/ # Developer CLI tool
├── messages/ # i18n JSON files (fa.json, en.json)
├── tests/ # Vitest unit tests
├── docs/ # Architecture docs
├── public/ # Static assets
└── .github/ # CI workflows & templates
# clone
git clone https://github.com/Maddyrampant/maddyBlog.git
cd maddyBlog
# install
npm install
# setup env
cp .env.example .env
# generate prisma client
npx prisma generate
# run migrations (needs PostgreSQL)
npx prisma migrate dev
# seed (optional)
npm run seed
# start
npm run devNeeds a PostgreSQL instance — set
DATABASE_URLin.env
DATABASE_URL=postgresql://user:password@localhost:5432/maddyblog
JWT_SECRET=your-super-secret-key-change-in-production
NEXT_PUBLIC_APP_URL=http://localhost:3000
LOG_LEVEL=info| command | does |
|---|---|
npm run dev |
start development server |
npm run build |
production build |
npm run lint |
lint all files |
npm run typecheck |
TypeScript type checking |
npm run test |
run Vitest tests |
npm run seed |
seed database |
npm run db:studio |
open Prisma Studio |
npm run dev:cli |
developer CLI tool |
MIT — see LICENSE
built with love by a girl who codes
Maddyrampant © 2026