Skip to content

README.md

Latest commit

 

History

History
207 lines (143 loc) · 6.49 KB

README.md

File metadata and controls

207 lines (143 loc) · 6.49 KB
TitleIQ

TitleIQ 🎯

AI-powered YouTube title & thumbnail optimization — maximize your CTR before every upload.

MIT License Node.js TypeScript React PRs Welcome

Features · Tech Stack · Getting Started · Deployment · Pricing

🚀 What is TitleIQ?

TitleIQ helps YouTube creators stop guessing and start optimizing. Paste your video title and thumbnail — and in seconds you get an AI-powered breakdown of your Click-Through Rate potential, with actionable rewrites and real competitor simulations.

✨ Features

🆓 Free Tier

Feature Description
Live CTR Score Analyzer Instantly scores your title across 4 dimensions: Curiosity Gap, Keyword Strength, Emotional Pull, and Title Length
Thumbnail Analyzer AI vision analysis for text readability, face impact, color contrast, and clutter score
Analysis History View and revisit all your past title and thumbnail analyses
A/B Compare Side-by-side comparison of two past analyses to identify the stronger performer

⚡ Pro Tier

Feature Description
Keyword Gap Fixer Identifies missing high-value keywords and auto-rewrites your title to include them
CTR Simulator Places your title against 4 real competitor titles in a simulated YouTube feed and predicts viewer click behavior
Unlimited Analyses No daily cap — analyze as many titles as you need

🛠 Tech Stack

Layer Technology
Frontend React 18, TypeScript, Vite, Tailwind CSS
Backend Node.js, Express, TypeScript
Database Neon (PostgreSQL)
AI Groq — Llama 3.3 70B + Llama Vision
Payments Razorpay
Email Resend
Security Helmet, JWT, HttpOnly Cookies

📁 Project Structure

TitleIQ/
├── client/                  # React frontend (Vite)
├── server/
│   └── src/
│       ├── routes/          # API route handlers
│       ├── services/        # AI, auth, and email services
│       ├── middleware/      # Auth, rate limiting, error handling
│       ├── prompts/         # AI prompt builders
│       ├── db/              # Database client & schema
│       └── data/            # Static competitor title data
├── shared/                  # Shared TypeScript types (client + server)
└── .env                     # Environment variables — never commit this!

🏁 Getting Started

Prerequisites

  • Node.js 18+
  • Neon PostgreSQL database
  • Groq API key
  • Resend API key
  • Razorpay account (test keys work for local dev)

1. Clone & Install

git clone https://github.com/Gaurav77Kumar/TitleIQ.git
cd TitleIQ
npm install        # installs dependencies for all workspaces

2. Configure Environment Variables

Create a .env file in the root directory:

# ── AI ─────────────────────────────────────────
GROQ_API_KEY=your_groq_api_key

# ── Database ────────────────────────────────────
DATABASE_URL=your_neon_postgresql_url

# ── Authentication ──────────────────────────────
JWT_SECRET=your_strong_secret_key          # min 32 characters recommended

# ── Email ───────────────────────────────────────
RESEND_API_KEY=your_resend_api_key

# ── Payments ────────────────────────────────────
RAZORPAY_KEY_ID=your_razorpay_key_id
RAZORPAY_KEY_SECRET=your_razorpay_secret
VITE_RAZORPAY_KEY_ID=your_razorpay_key_id  # exposed to the frontend via Vite



# ── Server ──────────────────────────────────────
PORT=3000
NODE_ENV=development

⚠️ Never commit .env to version control. It's already in .gitignore.

3. Run Database Migrations

cd server
npx tsx src/db/migrate.ts

4. Start Development Servers

# Backend  (runs on http://localhost:3000)
cd server && npm run dev

# Frontend (runs on http://localhost:5173, proxies API → :3000)
cd client && npm run dev

☁️ Deployment

Backend → Railway

Setting Value
Root directory server
Build command npm run build
Start command node dist/index.js

After deploy, set the CLIENT_URL environment variable in Railway to your Vercel frontend URL.

Frontend → Vercel

Setting Value
Root directory client
Framework preset Vite

Add all VITE_* environment variables in the Vercel dashboard.

💳 Pricing

Plan Price Analyses Features
Free ₹0/mo 10/day CTR Analyzer, Thumbnail Analyzer, History, A/B Compare
Pro ₹99/mo Unlimited Everything in Free + Keyword Gap Fixer + CTR Simulator

🔐 Security

  • Passwordless login via Email OTP (no passwords stored)
  • Auth tokens stored in HttpOnly Cookies (XSS-safe)
  • Helmet.js for HTTP security headers
  • Rate limiting on all API routes
  • JWT-signed sessions

🤝 Contributing

Pull requests are welcome! For major changes, please open an issue first to discuss what you'd like to change.

# Fork the repo, then:
git checkout -b feature/your-feature-name
git commit -m "feat: add your feature"
git push origin feature/your-feature-name
# Open a Pull Request

📄 License

MIT © 2025 TitleIQ