BookraftAI Documentation

A self-hostable AI book generation platform with KDP-ready PDF export, four payment gateways, and an admin panel — built on Next.js 16 and Express 5.

📖 Overview

BookraftAI is a full-stack web application that turns a short brief into a finished, print-ready book. It ships as two services:

• frontend/ — Next.js 16 (App Router) + React 19 + Tailwind v4 UI.
• backend/ — Express 5 API on Node 18+ with MongoDB via Mongoose.

Buyers self-host both services. End users supply their own AI provider keys (OpenRouter, optionally OpenAI), so you don't pay for their inference. Books are billed via a credit system charged through Stripe, PayPal, Razorpay, or Dodo Payments.

Landing page

Drop 01-landing.png into assets/screenshots/

✅ Requirements

📦 Installation

1. Unzip and install dependencies

cd bookraft-ai/backend
npm install

cd ../frontend
npm install

2. Configure environment files

cd backend
cp .env.example .env
# Edit .env — set MONGODB_URI and JWT_SECRET at minimum

cd ../frontend
cp .env.example .env.local
# Defaults to http://localhost:5001/api — change for production

3. Start in development

# Terminal 1 — backend on :5001
cd backend
npm run dev

# Terminal 2 — frontend on :3000
cd frontend
npm run dev

Open http://localhost:3000.

🚀 First run

1. Sign up at /signup — the very first user is automatically promoted to admin.
2. Open Settings → paste an OpenRouter API key. Optionally add an OpenAI key.
3. Open Admin → Settings → set the Support Email. Add Contact Information and Social Links if you want them on the public Contact page.
4. Open Admin → Plans → create one or more credit bundles.
5. Open Admin → Payment Gateways → enable any combination of Stripe, PayPal, Razorpay, Dodo and paste keys.
6. Generate your first book from /library → New book.

First run — creating your first book from the Library

Drop 06-new-book.png into assets/screenshots/

⚙️ Backend environment variables

🎛️ Frontend environment variables

🎨 Branding & rebrand checklist

BookraftAI is designed to be rebranded in minutes. All user-facing branding is centralised in one constants file:

frontend/lib/branding.ts

Edit these constants:

• APP_NAME — used in metadata, footer, legal pages, and admin labels.
• APP_TAGLINE — homepage / footer tagline.
• SUPPORT_EMAIL, LEGAL_EMAIL, PRIVACY_EMAIL — defaults shown on legal pages and as the deactivated-page fallback. The admin can also override the support email at runtime via Admin → Settings.

Then swap these visual assets:

• frontend/public/logo_light.png and logo_dark.png — header / footer logo.
• frontend/public/images/ — landing page artwork.
• frontend/app/favicon.ico — browser tab icon.

Optionally, update the package names:

• frontend/package.json → "name"
• backend/package.json → "name"

✉️ Email / SMTP setup

The public Contact form (POST /api/contact) and the deactivated-account "Contact Support" link both use the admin-configured Support Email. To deliver Contact messages, configure SMTP in backend/.env:

SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=mailer@example.com
SMTP_PASS=your-smtp-password
SMTP_FROM="Your Brand <mailer@example.com>"

🤖 AI models

BookraftAI does not bundle inference. End users plug in their own keys via /settings:

If a user has no OpenAI key, image generation falls back to OpenRouter (which silently ignores the requested size — OpenRouter returns square images regardless of trim). Users can also force all image traffic through OpenRouter via the forceOpenRouterForImages flag in their settings.

Settings → bring-your-own-key for OpenRouter and OpenAI

Drop 13-user-settings-byok.png into assets/screenshots/

💳 Payment gateways

Four gateways are integrated. Admins enable any combination via Admin → Payment Gateways. Keys are stored in MongoDB, not in env vars, so they're shared across backend instances.

Webhook URLs follow the pattern https://<your-api-host>/api/payments/<gateway>/webhook. Configure them in each gateway's dashboard so plan purchases get marked as completed and credits are granted.

Admin → Payment Gateways — enable Stripe, PayPal, Razorpay, or Dodo

Drop 17-admin-gateways.png into assets/screenshots/

🔐 Google OAuth

1. Open Google Cloud Console → APIs & Services → Credentials.
2. Create an OAuth 2.0 Client ID of type Web application.
3. Authorised redirect URI: {SERVER_URL}/api/auth/google/callback (e.g. https://api.yourdomain.com/api/auth/google/callback).
4. Copy the Client ID and Client Secret into backend/.env as GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET.
5. Restart the backend. The "Sign in with Google" button on /login activates automatically.

If both env vars are unset, the route returns 503 cleanly and the button is hidden.

🛠 Admin panel

Pages under /admin/* are gated to users with role: "admin":

Admin panel — users, plans, gateways, purchases, analytics, settings

Drop 14-admin-home.png into assets/screenshots/

📝 Book workshop

The workshop at /book/[id] is a tabbed editor:

Workshop → Content — stream, regenerate, and rewrite pages

Drop 08-workshop-content.png into assets/screenshots/

📄 KDP-ready PDF export

PDF export runs entirely in the browser via jsPDF — manuscripts never leave the user's device during export. Three export modes:

• Full book — cover + interior in one file.
• Interior only — for KDP's separate manuscript upload.
• Cover only — for KDP's cover upload form.

Trim sizes (6×9", 8.5×11", custom), margins, bleed (0.125"), paper type, interior color, page numbering position/font/color/start-offset, and per-page background images are all configurable in the workshop's Details tab.

Workshop → Export — KDP-ready full book / interior / cover PDFs

Drop 12-workshop-export.png into assets/screenshots/

⚡ VPS install (recommended)

BookraftAI ships with two interactive Bash scripts under setup/ that take a fresh Ubuntu VPS to a live, SSL-secured deployment in under 15 minutes:

Prerequisites

• A fresh Ubuntu VPS with SSH access (1 GB RAM minimum, 2 GB recommended).
• Two subdomains you control — one for the frontend (e.g. app.example.com) and one for the API (e.g. api.example.com).
• Your OpenRouter API key (used as the workspace-level fallback for AI generation; end users can override in /settings).
• Optional: OpenAI key, Google OAuth credentials, SMTP credentials. The script prompts for these but accepts blanks.

Step 1 — Clone the project on your VPS

cd /opt
git clone https://github.com/your-username/bookraft-ai.git
cd bookraft-ai

If you uploaded the CodeCanyon zip instead of cloning, scp or rsync it to /opt/bookraft-ai/ and unzip in place.

Step 2 — Run the installer

sudo bash setup/setup.sh

You'll see an interactive menu. Choose 1) Complete Installation. The script will:

1. Install Node.js 20, MongoDB 7 (official repo), and PM2 — skipping anything already installed, so it's safe to re-run.
2. Prompt for your frontend domain (e.g. app.example.com) and backend domain (e.g. api.example.com). Enter them without http://.
3. Prompt for the MongoDB URI — accept the default mongodb://localhost:27017/bookraft-ai to use the local Mongo it just installed.
4. Prompt for Google OAuth (skip with blank values to hide the Google button), OpenRouter, OpenAI (optional), and SMTP (optional — only required if you want the public Contact form to deliver).
5. Generate a strong JWT_SECRET via openssl rand -base64 48.
6. Install backend and frontend dependencies and build the frontend.

Step 3 — Point your DNS

At your DNS provider, add two A records pointing to your VPS's public IPv4:

app.example.com    A    <vps-ipv4>
api.example.com    A    <vps-ipv4>

Wait until both resolve before continuing. Verify from the VPS itself:

dig +short app.example.com @1.1.1.1
dig +short api.example.com @1.1.1.1
# both should print your VPS IP

Step 4 — Run the deployment wizard

sudo bash setup/deploy.sh

The script will:

1. Confirm DNS is pointing at the server.
2. Install Nginx and Certbot.
3. Write Nginx vhosts at /etc/nginx/sites-available/bookraft-api and /etc/nginx/sites-available/bookraft-ui, then enable them. The API vhost includes proxy_buffering off and 3600-second timeouts so live SSE page-streaming works without chunking.
4. Install backend dependencies and start the API under PM2 as bookraft-api.
5. Start the Next.js frontend under PM2 as bookraft-ui on port 3051.
6. Save the PM2 process list and configure it to auto-start on reboot.
7. Optionally run certbot --nginx for both subdomains, then patch SERVER_URL, CLIENT_URL, and NEXT_PUBLIC_API_URL in the env files to https:// and rebuild the frontend.

At the end you'll see:

🚀 DEPLOYMENT SUCCESSFUL!
  Frontend URL: https://app.example.com
  Backend API:  https://api.example.com

Step 5 — Bootstrap the first admin

Visit https://app.example.com/signup and sign up. The first account is auto-promoted to admin. Then:

1. Settings → paste your OpenRouter key (and OpenAI key if you want strict image trim sizes).
2. Admin → Plans → create at least one credit bundle.
3. Admin → Payment Gateways → enable Stripe, PayPal, Razorpay, and/or Dodo Payments. Configure webhooks on each gateway dashboard to https://api.example.com/api/payments/<gateway>/webhook.
4. Admin → Settings → set Support Email and any contact/social links.

If you later need to enable Google sign-in, set the redirect URI in Google Cloud Console to:

https://api.example.com/api/auth/google/callback

…then add the Client ID and Secret to backend/.env (or re-run setup.sh → option 2) Update Application Configuration), and restart with pm2 restart bookraft-api.

Useful PM2 commands

pm2 list                          # show all processes
pm2 logs bookraft-api             # tail backend logs
pm2 logs bookraft-ui              # tail frontend logs
pm2 restart bookraft-api          # restart backend after .env change
pm2 restart bookraft-ui           # restart frontend (after `npm run build`)
pm2 monit                         # interactive monitor

Updating to a newer version

cd /opt/bookraft-ai
# Replace source: git pull, or upload the new CodeCanyon zip and unzip in place

cd backend  && npm install && cd ..
cd frontend && npm install && npm run build && cd ..

pm2 restart bookraft-api bookraft-ui

If env variables changed in the new release, run sudo bash setup/setup.sh → 2) Update Application Configuration to merge them without overwriting your existing values.

Rolling back

Both scripts write timestamped .bak.YYYYMMDD_HHMMSS backups of any env file they touch. To roll back to a previous configuration:

ls backend/.env.bak.*
cp backend/.env.bak.20260101_120000 backend/.env
pm2 restart bookraft-api

🌐 Deployment

If you can't use the VPS scripts above (e.g. you're deploying to Vercel/Railway, Render, a managed Kubernetes cluster, or a different distro), the platform deploys cleanly as two standard Node apps. The settings below apply to any host.

Frontend

Standard Next.js 16 deployment. Recommended: Vercel.

• Set NEXT_PUBLIC_API_URL to your backend's public origin + /api.
• Run npm run build in CI to catch type errors before promoting.

Backend

Any Node 18+ host (Render, Railway, Fly.io, a $6 VPS, etc.). Required environment:

• NODE_ENV=production — enables fail-fast on missing/placeholder JWT_SECRET.
• MONGODB_URI, JWT_SECRET, CLIENT_URL, SERVER_URL.

Persistent uploads

🛡 Security checklist before going live

• Set NODE_ENV=production. The backend will refuse to boot with the placeholder JWT_SECRET.
• Generate a strong JWT_SECRET (e.g. node -e "console.log(require('crypto').randomBytes(48).toString('base64'))").
• Lock down the first-admin path: sign up before the URL is publicly known, or pre-seed an admin user.
• Set MongoDB to require authentication and bind to a private network.
• Configure HTTPS (the included Helmet middleware sets sane security headers; HSTS is on by default).
• Configure rate limiting at the proxy/CDN as well — the bundled express-rate-limit covers /api/users/login, /api/users/signup, and /api/contact at the app layer.
• Rotate any AI provider keys you used during development.
• Review CORS — by default only CLIENT_URL can call the API.

🩺 Troubleshooting

"Server is healthy" but requests fail with CORS

Set CLIENT_URL in backend/.env to the exact origin of your frontend (no trailing slash). Restart the backend.

Google sign-in returns 503

Both GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET must be set. Restart after editing .env.

Image generation returns square images at the wrong size

OpenRouter's chat-completions image modality silently ignores the size parameter. To get the trim size you asked for, add an OPENAI_API_KEY in user Settings — the server will route image calls through OpenAI's strict /v1/images/generations.

Contact form returns 503 "not configured"

Either the admin Support Email or the SMTP env vars are missing. Set both: Admin → Settings → Support Email, and SMTP_HOST/SMTP_PORT/SMTP_USER/SMTP_PASS in backend/.env.

Generated images disappear after server restart

You're on an ephemeral filesystem. Mount a persistent volume to backend/uploads/ or change the storage backend.

Backend refuses to boot in production with "JWT_SECRET is missing or set to the placeholder"

This is the intended safeguard. Set a strong unique JWT_SECRET in your production environment.

📜 Third-party licenses

BookraftAI bundles or depends on the following open-source projects. All are CodeCanyon-compatible (MIT, ISC, Apache 2.0, OFL):

• Sora font — SIL Open Font License (OFL)
• Lucide Icons, React Icons — ISC / MIT
• shadcn/ui, Radix UI, Tailwind CSS, Framer Motion — MIT
• Next.js, React — MIT
• Express, Mongoose, Passport, Helmet, express-rate-limit, Joi, Nodemailer — MIT
• jsPDF — MIT
• OpenAI Node SDK — Apache 2.0
• Stripe, Razorpay, Dodo Payments SDKs — MIT / Apache 2.0

🗒 Changelog

See CHANGELOG.md in the project root for the full version history.

v1.0.0 — Initial release

• Two AI book engines (text + image-page), 23 book types, workshop editor, KDP-ready PDF export.
• Bring-your-own-key AI integration (OpenRouter + optional OpenAI).
• Email + Google OAuth auth, JWT sessions.
• Pay-per-credit billing with Stripe, PayPal, Razorpay, Dodo Payments.
• Admin panel: users, plans, gateways, purchases, settings, analytics.
• Centralised branding constants for fast rebranding.
• Contact form with Nodemailer SMTP delivery.
• Helmet + rate limiting on auth and contact endpoints.
• Production safeguard: backend refuses to boot with the placeholder JWT secret.

💬 Support

For installation help, bugs, and feature questions, contact us via your CodeCanyon item's Comments tab or the Support tab on the item page.