🚀 Generate engaging, on-brand posts for LinkedIn, Twitter (X), Instagram, and Facebook in seconds — powered by Google Gemini AI.

🌐 Live Demo • ✨ Features • 🛠 Tech Stack • 🚀 Getting Started • 🗺 Roadmap

---

📖 Table of Contents

• 🎯 What Is PostPilot?
• 💡 Why PostPilot?
• ✨ Features
• 🎬 Live Demo
• 🛠 Tech Stack
• 🏗 Architecture
• 📁 Project Structure
• 🚀 Getting Started
• 🔐 Environment Variables
• 💾 Database Setup
• 📜 Available Scripts
• 🚢 Deployment
• ⚡ SEO & Performance
• 🔒 Security
• 🗺 Roadmap
• 👨‍💻 Author
• 📝 License

---

🎯 What Is PostPilot?

PostPilot is a chat-driven AI content writing tool built specifically for social media teams. Instead of forcing users through rigid forms, PostPilot uses a ChatGPT-style conversational interface where users describe what they want, and the AI returns a ready-to-publish post — complete with platform-specific tone, optimal length, and trending hashtags.

Core promise: From idea → published post in under 60 seconds ⚡

👥 Who It's For

User Type	Use Case
🚀 Founders & Solopreneurs	Build a consistent personal brand on LinkedIn without spending hours writing
📱 Social Media Managers	Manage multiple brand voices across platforms efficiently
🎨 Content Creators	Scale your output without sounding robotic
🏢 Small & Medium Businesses	Get pro-level content without hiring a full content team

---

💡 Why PostPilot?

❌ Problem	✅ PostPilot Solution
Writer's block & blank-page anxiety	AI generates first drafts in 5 seconds
Inconsistent brand voice across platforms	Tone presets — professional, casual, witty, inspirational, bold
Hours wasted summarising articles	Paste a URL — auto-extracts content with attribution
Low engagement from generic captions	Platform-tuned prompts for LinkedIn, Twitter, Instagram, Facebook
Expensive enterprise content tools	Free tier with 10 posts/month — no credit card required

---

✨ Features

🤖 AI Post Generation

💬 Conversational AI Generator ChatGPT-style interface Streaming responses (Server-Sent Events) Real-time token-by-token output Context-aware conversations	🎯 Multi-Platform Support LinkedIn (long-form professional) Twitter / X (punchy, viral) Instagram (emotive, visual) Facebook (community-focused)
🎨 Tone Control Professional Casual Witty Inspirational Bold	🔗 URL-to-Post Magic Paste any article link Auto-extracts via Mozilla Readability Generates post with attribution Saves hours of summarising

📚 Content Library

• 📝 Pre-built templates — 7 categories (Product Launch, Milestones, Lessons, Announcements, Engagement, Personal Brand, Tips)
• 🔍 Post history with full-text search & platform filters
• ⭐ Favorites system for your best posts
• 📋 One-click copy with visual feedback
• 🔄 Regenerate & remix any post with new tone

📊 User Dashboard

• 📈 Usage stats — posts generated, plan tier, remaining quota
• 🕐 Recent posts preview
• ⚡ Quick-action CTAs to jump into the generator
• 💾 Conversation history — rename, pin, revisit

🔐 Authentication & Account

• 🔑 Supabase Auth — Email/password + Google OAuth
• 👤 Auto-provisioned profiles via Postgres triggers
• 💳 Plan tiers — Free (10/month), Pro, Team
• ⚛️ Atomic credit consumption — race-condition-safe billing
• ⚙️ Settings page — profile, theme, account management

👑 Admin Panel

• 🛡️ Admin dashboard at /admin
• 👥 User management — promote, suspend, adjust limits
• 🔒 RLS-protected — only admin role users
• 📊 Audit logs

🎨 UX Polish

• 🌗 Dark / Light / System theme via next-themes
• 📱 Mobile-first responsive — 44px touch targets, no horizontal overflow
• ✨ Page transitions with Framer Motion
• 🎓 Onboarding tour for first-time users
• 📊 Top progress bar on route changes
• 🔔 Toast notifications
• 🎮 Konami-code easter egg
• 🎉 Confetti on milestones

---

🎬 Live Demo

🌐 postpilot-io.vercel.app

---

🛠 Tech Stack

Frontend

Next.js 16

React 19

TypeScript 5

Tailwind 4

Framer Motion

Backend & Data

Supabase

Postgres

Gemini AI

Vercel

Complete Stack

Category	Technologies
Framework	Next.js 16 (App Router, Server Components, Streaming)
UI Library	React 19, shadcn/ui, Radix UI
Language	TypeScript 5 (strict mode)
Styling	Tailwind CSS 4, Framer Motion 12, Lucide Icons
Backend	Supabase (Auth, Postgres, RLS, Real-time)
AI	Google Gemini 2.5 Flash Lite + Flash (fallback)
Content Extraction	Mozilla Readability + jsdom
Auth	@supabase/ssr (cookie-based SSR)
Analytics	Vercel Analytics + Speed Insights
Tooling	ESLint 9, Yarn 4 (Berry), Webpack

---

🏗 Architecture

┌─────────────────────────────────────────────────────────────┐
│                     🌐 Browser (React 19)                   │
│   Landing • Auth • Dashboard • Chat • History • Templates   │
└──────────────────────────┬──────────────────────────────────┘
                           │ HTTPS
┌──────────────────────────▼──────────────────────────────────┐
│              ⚡ Next.js 16 (App Router · Vercel)            │
│  ┌─────────────────┐  ┌──────────────────────────────────┐  │
│  │ Server          │  │ Route Handlers (/api/*)          │  │
│  │ Components      │  │  • /chat   (SSE stream)          │  │
│  │ + Metadata API  │  │  • /scrape (URL → article)       │  │
│  │ + sitemap/robot │  │  • /posts, /usage, /stats        │  │
│  │ + OG image      │  │  • /admin/users                  │  │
│  └────────┬────────┘  └────────────┬─────────────────────┘  │
└───────────┼────────────────────────┼────────────────────────┘
            │                        │
   ┌────────▼────────┐    ┌──────────▼──────────┐
   │  🗄️ Supabase    │    │   🤖 Google Gemini  │
   │  • Postgres     │    │   • 2.5 Flash Lite  │
   │  • Auth (OAuth) │    │   • 2.5 Flash (fb)  │
   │  • RLS policies │    │   • Streaming       │
   │  • SQL funcs    │    └─────────────────────┘
   └─────────────────┘

🔄 Data Flow: Single Post Generation

1. 👤 User types a prompt in the chat UI
2. 🔐 POST /api/chat validates auth, checks can_user_generate RPC
3. 🔗 If URL detected → scrapeArticle() enriches prompt with article context
4. 💾 User message persisted to messages table
5. 🌊 Gemini streams tokens via TransformStream as Server-Sent Events
6. ✅ On completion → assistant message saved with parsed post_data JSONB
7. ⚛️ consume_post_credit atomically charges one credit
8. 🎨 Client renders post card with copy / regenerate / save actions

---

📁 Project Structure

postpilot/
├── 📂 src/
│   ├── 📂 app/                    # Next.js App Router
│   │   ├── 📂 (app)/              # Authenticated app routes
│   │   │   ├── dashboard/
│   │   │   ├── generate/          # 💬 Chat-based AI generator
│   │   │   ├── history/
│   │   │   ├── templates/
│   │   │   └── settings/
│   │   ├── 📂 (auth)/             # Login & signup
│   │   ├── 📂 (legal)/             # Privacy & Terms
│   │   ├── 📂 admin/              # 👑 Admin panel
│   │   ├── 📂 api/                # Route handlers
│   │   │   ├── chat/              # 🌊 Streaming AI endpoint
│   │   │   ├── scrape/            # 🔗 URL → article extractor
│   │   │   ├── conversations/
│   │   │   ├── posts/
│   │   │   ├── stats/
│   │   │   ├── usage/
│   │   │   └── admin/users/
│   │   ├── auth/callback/
│   │   ├── layout.tsx
│   │   ├── page.tsx
│   │   ├── manifest.ts
│   │   ├── opengraph-image.tsx
│   │   ├── robots.ts
│   │   └── sitemap.ts
│   ├── 📂 components/
│   │   ├── chat/
│   │   ├── landing/
│   │   ├── auth/
│   │   ├── admin/
│   │   ├── seo/
│   │   ├── shared/
│   │   └── ui/
│   ├── 📂 lib/
│   │   ├── ai/                    # 🤖 Gemini client & prompts
│   │   ├── auth/
│   │   ├── scrape/
│   │   ├── supabase/
│   │   ├── hooks/
│   │   ├── types/
│   │   ├── utils/
│   │   ├── templates.ts
│   │   └── motion.ts
│   └── proxy.ts
├── 📂 supabase/
│   └── migrations/                # SQL migrations
├── 📂 public/
├── next.config.ts
├── tsconfig.json
└── package.json

---

🚀 Getting Started

Prerequisites

• ✅ Node.js 20+
• ✅ Yarn 4 (Berry) — see .yarnrc.yml
• ✅ Supabase project — supabase.com
• ✅ Google AI Studio API key — aistudio.google.com

1️⃣ Clone the Repository

git clone https://github.com/mzstudiospk/PostPilot.git
cd PostPilot

2️⃣ Install Dependencies

yarn install

3️⃣ Configure Environment Variables

Create .env.local in the project root (see Environment Variables below).

4️⃣ Run Database Migrations

supabase db push

Or manually apply each SQL file from supabase/migrations/ in order via the Supabase SQL Editor.

5️⃣ Start Development Server

yarn dev

🎉 Open http://localhost:3000 in your browser.

---

🔐 Environment Variables

Create .env.local with the following:

# 🗄️ Supabase
NEXT_PUBLIC_SUPABASE_URL=https://YOUR-PROJECT.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=YOUR-ANON-KEY
SUPABASE_SERVICE_ROLE_KEY=YOUR-SERVICE-ROLE-KEY

# 🤖 Google Gemini AI
GEMINI_API_KEY=YOUR-GEMINI-API-KEY

# 🌐 App
NEXT_PUBLIC_APP_URL=http://localhost:3000

⚠️ Never commit .env.local — it's gitignored. The SUPABASE_SERVICE_ROLE_KEY bypasses RLS and must only be used server-side.

---

💾 Database Setup

The supabase/migrations/ directory contains every schema change in chronological order:

Migration	Purpose
phase4_auth_setup	profiles table, RLS policies, signup trigger, waitlist
phase5_ai_generator	posts table for generated content
phase5_posts_grants	Privilege grants for posts
chat_conversations	conversations + messages for chat history
admin_panel	Admin role and audit
atomic_post_credit	consume_post_credit() SQL function (race-safe billing)
landing_stats	Public landing-page stats view
messages_update_policy	Update policy hardening
scrape_rate_limit	Per-user rate limiting on URL scraping

🔒 All user-owned tables enforce Row-Level Security. Authenticated users can only read/write their own data.

---

📜 Available Scripts

yarn dev        # 🔥 Start dev server (Webpack)
yarn build      # 📦 Production build
yarn start      # 🚀 Run the built app
yarn lint       # 🔍 Run ESLint

---

🚢 Deployment

Vercel (Recommended)

1. 📤 Push the repo to GitHub
2. 🔗 Import it into Vercel
3. 🔐 Add environment variables from Environment Variables
4. 🚀 Deploy — Vercel auto-detects Next.js 16

🌐 Custom domain: Configure in Vercel → Project → Settings → Domains, then update NEXT_PUBLIC_APP_URL.

Other Platforms

Works on any Node.js 20+ host:

• Render
• Railway
• Fly.io
• AWS / GCP / Azure

yarn build && yarn start

---

⚡ SEO & Performance

✅ Lighthouse-Ready

• AVIF / WebP image optimization
• Font preloading with next/font
• Compressed responses
• No x-powered-by header

✅ Crawl-Friendly

• Dynamic sitemap.xml
• Optimized robots.txt
• Canonical URLs on every page

✅ Rich Previews

• Open Graph + Twitter Card metadata
• Dynamic OG image (1200×630)
• JSON-LD SoftwareApplication + Organization schema

✅ Accessibility

• 44px touch targets
• Semantic HTML, ARIA labels
• Keyboard navigation
• Focus rings + prefers-reduced-motion respected

✅ Mobile-First

• Hamburger drawer
• No horizontal overflow at 375px
• Body-scroll lock when menus open

✅ Targeted Keywords

• AI social media post generator
• AI LinkedIn post generator
• AI Twitter/Instagram caption generator
• Free AI content writing tool
• Social media AI for SMBs

---

🔒 Security

🛡️ Row-Level Security on every user-owned table 🔐 Server-side auth with @supabase/ssr — no tokens in client storage ⚛️ Atomic credit charging prevents free-tier abuse 🚦 Rate-limited URL scraping prevents /api/scrape abuse 🔐 Security headers:

• X-Frame-Options
• X-Content-Type-Options
• Referrer-Policy
• Permissions-Policy

✅ Input validation on every API route 🚫 No powered-by leakage 🚫 No source maps in production 🔑 Service-role key isolated to server-only modules

---

🗺 Roadmap

• 💳 Stripe billing integration (Pro & Team checkout)
• 🏢 Multi-brand workspaces (one user → many brand voices)
• 📤 Direct publishing (LinkedIn / Twitter / Buffer / Hootsuite)
• 🎨 AI image generation for post visuals
• 📊 Post performance analytics
• 👥 Team collaboration (comments, approvals, scheduled queues)
• 🌐 Browser extension for one-click post generation
• 📱 Mobile app (iOS + Android)
• 🌍 Multi-language support (Urdu, Arabic, Spanish)
• 🎙️ Voice-to-post feature

---

👨‍💻 Author

Muhammad Zeeshan

Senior React Native Developer & Founder @ MZ Studios

🇵🇰 Multan, Pakistan • 🌍 Working Globally

Built with ❤️ by MZ Studios

Apps That Work. Businesses That Grow.

---

📝 License

This project is proprietary. All rights reserved by MZ Studios and the project owner.

For licensing inquiries, please contact: [email protected]

---

⭐ Show Your Support

If you find PostPilot useful, please consider:

• ⭐ Star this repository
• 🐛 Report bugs via Issues
• 💡 Suggest features via Discussions
• 🔄 Share with your network

---

🚀 Built With