ShowcaseAI Documentation

Overview #

ShowcaseAI is a self-hosted SaaS platform for creating AI-generated marketing media — videos, images, voiceovers, avatars, and ad copy — sold on the CodeCanyon / Envato marketplace.

Users generate content by describing what they want or uploading a product photo. Behind the scenes the platform orchestrates three external AI services to produce talking-avatar videos, product showcase clips, images, cloned voices, and written ad copy. Usage is metered with a credit balance that users top up via Stripe.

Core capabilities

• Video generation — talking-avatar videos (lip-synced), product showcase, product-avatar, fashion/try-on, and AI ad videos.
• Image generation — text-to-image, product shoots, avatar imagery, and avatar+product compositing.
• Voice — text-to-speech in many voices, plus custom voice cloning.
• AI copywriting — ad scripts, marketing/sales copy, and a multi-variant Ad Copy Studio.
• Brand Kits — reusable brand identity applied across generations.
• Ad Localizer — recreate a talking-avatar video in many languages.
• Community — social feed with posts, likes, and comments.
• Billing — credit ledger + Stripe credit-pack purchases.
• Admin — users, analytics, preset prompts, avatar templates, community moderation, credit packs, and a Settings screen where all provider keys are entered (no file editing needed).

Architecture #

Two independent applications in one package (the backend/ and frontend/ folders), communicating over HTTP.

How a request flows

1. The user clicks something in the browser (frontend, port 4001).
2. The frontend's API.request() helper sends an HTTP call to the backend at VITE_API_URL (e.g. http://localhost:5000/api/…), attaching the JWT token from the auth_token cookie in the Authorization: Bearer <token> header.
3. The backend authenticates the token (checkAuth middleware → req.user; /admin/* routes additionally pass checkAdmin), runs the controller, talks to MongoDB and/or an AI provider, and returns JSON.
4. For slow jobs (video/image), the backend returns immediately with a "processing" record; the provider later calls back (webhook) or is polled, and the record flips to "completed."

Technology Stack #

Backend backend/

Frontend frontend/

Project Structure #

The download contains two applications plus a quick-start README. Paths below are relative to the folder you unzipped.

README.md                          # Quick start
documentation.html      # This documentation (open in a browser)
testing-guide.html      # Step-by-step testing guide
backend/                           # Backend (Express + MongoDB)
├── server.js                # Entry — starts the HTTP server
├── package.json             # npm scripts (dev, start, setup, check…)
├── .nvmrc                   # Node.js 22 (nvm use)
├── .env.example             # Template for .env
├── .env                     # YOUR configuration — not in the package; created by npm run setup. Never share it
├── src/
│   ├── app.js               # Express app, security middleware, /api/health, Stripe webhook mount
│   ├── routes.js            # API route registry (all /api/* except /api/health and the Stripe webhook, which are in app.js)
│   ├── controllers/         # Request handlers (+ webhook/ subfolder)
│   ├── models/              # Mongoose schemas (26 models)
│   ├── helpers/             # CreditHelper, SettingsHelper, LlmHelper, UploadHelper, Middleware…
│   ├── lib/                 # AI providers: kieLib, tts, newportai, render, stripe
│   └── emailTemplates/      # resetPassword.html, userCreated.html
├── public/logo.png          # Logo shown in emails (served at <BACKEND_URL>/logo.png)
├── tmp/                     # Temporary upload files (cleaned automatically)
├── scripts/                 # setup, check, security-smoke (+ internal helpers)
├── seed/                    # Starter data loaded by npm run setup
└── deploy/
    ├── ecosystem.config.cjs # PM2 process file
    └── nginx.conf.example   # nginx reverse-proxy example

frontend/                          # Frontend (React 19 + Vite 7)
├── .nvmrc                   # Node.js 22 (nvm use)
├── .env.example             # Template for the VITE_* settings
├── .env                     # Your VITE_* settings — not in the package; created by npm run setup (backend)
├── vite.config.js           # Dev server (port 4001)
├── public/assets/images/    # favicon, logo and other static images
└── src/
    ├── routes/              # index / userRoutes / adminRoutes / authRoutes
    ├── pages/               # user/, admin/, user/create/, user/tool/, auth/
    ├── components/          # common/, avatars/, AiAds/, Popups/, profile/
    ├── store.js             # Zustand auth/user state
    └── utils/               # API.js (fetch wrapper), Helper.js

Backend npm scripts (run inside backend/)

Requirements & Technical Specifications #

What you need before installing. Items marked optional can be added later — the app starts without them and simply hides or disables the related feature.

Technical specifications

Installation & Running #

Install the backend first, then the frontend. The whole process takes about ten minutes. Run the commands in a terminal (on Windows: PowerShell or Command Prompt).

1 · Install the backend packages

$ cd backend
$ npm install

2 · Run the interactive installer

$ npm run setup

The installer does everything needed for a working first start:

1. Checks your Node.js version.
2. Creates backend/.env from backend/.env.example. The package contains no .env file — no database URL or secret is included. If backend/.env already exists, setup keeps it and only fills in the missing values.
3. Asks for the MongoDB connection string. Press Enter for a local MongoDB (mongodb://127.0.0.1:27017/showcaseai) or paste your own, for example an Atlas mongodb+srv://… URL (see how to get one). It also asks for the FRONTEND_URL (default http://localhost:4001) and the BACKEND_URL (default http://localhost:5000).
4. Generates a random JWT_SECRET and a random SETTINGS_ENCRYPTION_KEY and writes them into .env.
5. Creates frontend/.env from frontend/.env.example, with VITE_API_URL=<your BACKEND_URL>/api/, if it does not exist yet.
6. Connects to MongoDB.
7. Creates the admin account. It asks for the admin email (default admin@showcaseai.app), name and password. There is no default password: leave it empty and setup generates a strong random one and prints it once at the end — save it. Public demo passwords such as User@123# are refused.
8. Loads the starter data and one demo user — the demo user only when NODE_ENV is not production (see Admin Account & Starter Data). Content such as prompts and avatar templates is added by you afterwards (see Add your own content).
9. Prints the logins and the next steps.

Non-interactive mode (servers, scripts): npm run setup -- --yes asks no questions and uses the values already in .env, or the defaults. There is no default database URL in this mode: mongoDBURL must already be set in backend/.env, or you pass --mongo <url>. Without --admin-password it generates a random admin password and prints it once (save it); without --admin-email the admin is admin@showcaseai.app. Pass your own on a live server. Options:

Example:

$ npm run setup -- --yes --no-demo --mongo "mongodb://127.0.0.1:27017/showcaseai" \
    --admin-email you@example.com --admin-password "choose-a-strong-password" --admin-name "Your Name"

3 · Start the backend

$ npm run dev        # development (restarts on code changes)
$ npm start          # production

The API listens on http://localhost:5000. Check it is alive by opening http://localhost:5000/api/health in a browser — it answers {"status":"success","message":"ok"}.

4 · Install and start the frontend

Open a second terminal (leave the backend running):

$ cd frontend
$ npm install
$ npm run dev             # http://localhost:4001

frontend/.env was created by npm run setup, with VITE_API_URL=http://localhost:5000/api/ (your Backend URL + /api/), so it points at the backend. If the file is missing, the frontend still uses http://localhost:5000/api/; to change it, copy .env.example to .env and edit it. Open http://localhost:4001 in a browser.

5 · Log in and enter your provider keys

1. Log in with the admin account you created in step 2 — the email you entered (default admin@showcaseai.app) and the password you entered, or the generated one setup printed.
2. The AI features need two things. (a) Your own, paid provider keys entered in Admin → Settings: Kie.ai, AWS S3, Speechify and NewPortAI (see Third-party services & costs). (b) A public https BACKEND_URL (Admin → Settings → Site & Branding), because Kie.ai sends finished results to <BACKEND_URL>/api/kie/webhook. On localhost, videos, avatars and images stay "Processing". For local testing run a tunnel such as ngrok http 5000 and set BACKEND_URL to the https address it shows — see Why a public URL?.
3. Open Admin → Settings.
4. Enter your Kie.ai, Speechify and NewPortAI keys, your S3 storage details and (optionally) Stripe, email and stock-media keys. Click Save.
5. Click each Test button to confirm the key works. See Admin → Settings for every field.
6. Add your own content — prompts, avatar templates, community posts: Add your own content (manual).

6 · Verify the installation

$ cd backend
$ npm run check

npm run check verifies that .env is valid, the database connection works, an admin exists and the starter data is loaded. It lists which settings are configured (it never prints their values) and warns if BACKEND_URL is still localhost.

Admin Account & Starter Data #

There is one way to install: npm run setup. It creates the admin account and a small set of starter data for you — there is nothing to import by hand. After that, you change everything from the admin panel and add your own content. Visitors can register themselves on the sign-up page (/register), and admins can also create users in Admin → Users.

What npm run setup does

$ cd backend
$ npm install
$ npm run setup

1. Creates backend/.env from backend/.env.example (the package contains no .env file) and generates the two secrets.
2. Asks for your MongoDB connection string and site URLs (press Enter to accept the defaults), and creates frontend/.env pointing at your Backend URL.
3. Creates the admin account with the email, name and password you type. Leave the password empty to get a generated one, printed once at the end — save it. There is no default admin password.
4. Loads the starter data (Creator Studio models, community categories, credit packs, dropdown lists) and one demo user (not when NODE_ENV=production).
5. Prints the login details.

After setup — change whatever you want

Changing the admin login

There is exactly one admin account. Change it like this:

Edit the admin with MongoDB Compass

1. Install MongoDB Compass (free) from https://www.mongodb.com/products/tools/compass.
2. Click Add new connection, paste the mongoDBURL from backend/.env and connect.
3. Open your database (e.g. showcaseai) → the users collection.
4. Filter with { "role": "admin" }, click the pencil icon on the document, change email (lower-case) and/or name, then Update. Log in with the new email.

Locked out and email is not set up?

1. In a terminal inside backend, create a password hash (replace the password):

   $ node -e "console.log(require('bcryptjs').hashSync('MyNewPassword123', 10))"

2. In Compass, edit the admin document and replace the value of password with the printed text (it starts with $2), then Update.
3. Log in with the new password and change it again from Profile if you like.

Starting over (reset)

$ npm run setup -- --reset

Setup lists what will be deleted — every user account, video and image record, payment record, credit, setting and saved API key — and asks you to type the database name to confirm. Nothing is deleted unless you confirm. Then it installs everything fresh, exactly like the first time. Files already uploaded to S3 are not removed. Make a backup first if you might need the data (e.g. mongodump).

Logins after setup

Passwords are stored as bcrypt hashes. The demo user is for local testing only. Its password is public, so delete it in Admin → Users before you go live. It is never created when NODE_ENV=production is set in backend/.env (or with --no-demo).

Starter data (what setup creates)

Add your own content (manual) #

A fresh installation contains only the admin, one demo user, the AI model catalog, community categories, credit packs and dropdown lists. Everything below is added by you, from the admin panel, in a few minutes. Log in as the admin first.

Prompts Admin → Prompts

Preset prompts appear in the prompt picker of the studios so users can start from a ready-made idea. Until you add some, that picker is empty (users can still write their own prompt).

1. Open Admin → Prompts in the sidebar.
2. Use the filter at the top to choose the prompt type (Fashion Shoot Video, Product Shoot Video, Product Shoot Image, Product Avatar Image or Image To Avatar). The list shows only that type.
3. Click Add Prompt.
4. Choose the Prompt Type, type a Title and write the full Prompt text (all three are required).
5. Optional: under Reference Image click the box and choose a PNG, JPG or WEBP file (under 5 MB). Uploading needs S3 storage (Admin → Settings → Storage).
6. Click Submit. To change a prompt later use the edit (pencil) icon; Update Prompt saves it. The trash icon asks for confirmation and deletes it.

Avatar templates Admin → Product Avatar · Video Avatar

The ready-made avatars users pick in Avatar Studio. Product Avatar templates are used by the product/fashion avatar tools; Video Avatar templates by the talking-avatar tools. Both pages work the same way and both need S3 to be configured.

1. Open Admin → Product Avatar or Admin → Video Avatar.
2. Click Add Product Avatar Template / Add Video Avatar Template.
3. Fill in the details first: Full Name, Age Range, Ethnicity, Profession (the dropdown lists come from the starter data) and Gender, then Voice Type and Voice Name. Product Avatar templates also have an Avatar Type (Fashion Avatar or Product Avatar).
4. Click Save Details. The upload boxes (image, video, matted video, thumbnail) become active only after the details have been saved once.
5. Upload the files, then use the status switch in the list to publish or hide the template. Edit or delete it from the same list.

Community categories and posts Admin → Community Categories · Community

1. Admin → Community Categories lists the 4 starter categories. Click + Add Category, enter a Name (required), an optional description and an optional Icon SVG (paste SVG code), then save. Drag rows to change their order; use the pencil or trash icons to edit or delete.
2. Admin → Community opens the community feed. Click + Start Discussion, enter a Title, optional Description, pick a Category (required), add optional hashtags and up to 3 JPEG/PNG images, then post.
3. As admin you can also pin a post to the top of the feed or remove any post. Posts by your users appear here automatically.

Credit packs Admin → Credit Packs

Setup creates three example packs (Starter, Pro, Business). Adjust them to your own prices.

1. Open Admin → Credit Packs.
2. Click Add Credit Pack (or edit an existing pack).
3. Enter the Name, an optional description, the number of Credits and the Price; leave Currency as usd or change it; set a Sort Order; tick Mark as "Most Popular" to highlight a pack.
4. Click Create (or Update). Active packs appear on the users' Buy Credits page; real payments need the Stripe keys in Settings.

Provider keys Admin → Settings

1. Open Admin → Settings. The settings are split into groups (Site & Branding, AI Providers, Storage (AWS S3), Email / Notifications, Payments (Stripe), Credit Prices, Limits & Security, Stock Media); the links at the top jump to a group.
2. Paste the keys you have (see Keys & Credentials for where to get each one). Leave a field empty to keep its current value.
3. Click Save Settings at the bottom, then press the Test button next to each provider. Test checks the saved value, so save first.

Other things you may want to add

• Users and credits: Admin → Users (add users, give credits).
• Model prices: the example credit prices of the Creator Studio models live in the aimodelcatalogs collection (see Starter data).
• Brand kits, voices and generations are created by users in their own studios and need no admin setup.

Configuration (.env) #

Server settings live in backend/.env (backend) and frontend/.env (frontend). The package contains only the .env.example templates; npm run setup creates both .env files from them. Never commit or share them.

Backend — backend/.env

This file is not in the package. npm run setup creates it from backend/.env.example and fills in mongoDBURL, JWT_SECRET and SETTINGS_ENCRYPTION_KEY for you (once). It only holds what the server needs before it can start; everything else — site URLs, API keys, email, payments, storage, credit prices, session length, rate limits and upload limits — is managed in Admin → Settings.

Frontend — frontend/.env

npm run setup (in backend/) creates this file from frontend/.env.example if it does not exist yet, with VITE_API_URL set to your Backend URL + /api/. Without the file, the frontend uses http://localhost:5000/api/.

Sample images

The Create pages (Product Showcase, Product Avatar and AI Ads) offer four example product photos under Try Samples. The browser loads them from VITE_SAMPLE_MEDIA_BASE, which by default is the vendor-hosted sample-image CDN https://d3orgd3vfbg4nb.cloudfront.net. It is used only to display these example images; nothing else in the app depends on it. If you prefer to host the images yourself, upload four JPEG files to a bucket or web server you control using this path convention, then set VITE_SAMPLE_MEDIA_BASE to its base URL and rebuild the frontend:

<base>/assets/assets/sample-images/1.jpg … 4.jpg
<base>/assets/assets/sample-images/thumb/1.jpg … 4.jpg   # smaller thumbnails of the same images

Keys & Credentials — Step by Step #

Every value ShowcaseAI needs, what it is for, where it goes and exactly where to get it. Values marked .env go in backend/.env (most are written for you by npm run setup). Values marked Settings are entered in Admin → Settings after you log in — click Save, then the Test button next to the key.

Overview

1. MongoDB — mongoDBURL

The connection string of your database, including the database name. npm run setup asks for it and writes it to .env.

Option A — MongoDB on your own computer/server (free)

1. Install MongoDB Community Server from https://www.mongodb.com/try/download/community (on Windows tick "Install as a Service"; on Ubuntu follow the official apt instructions).
2. Use this connection string: mongodb://127.0.0.1:27017/showcaseai

Option B — MongoDB Atlas (cloud, free tier available)

1. Create an account at https://www.mongodb.com/cloud/atlas and create a cluster (the free M0 tier is fine to start).
2. Database Access → Add New Database User → choose a username and a password (avoid @ : / ? in the password, or URL-encode them).
3. Network Access → Add IP Address → add your server's public IP (use 0.0.0.0/0 only for a quick test).
4. Database → Connect → Drivers → copy the mongodb+srv://… string.
5. Replace <password> with your password and add the database name before the ?:

mongoDBURL=mongodb+srv://myuser:MyPassword123@cluster0.abcde.mongodb.net/showcaseai?retryWrites=true&w=majority

2. Secrets — JWT_SECRET and SETTINGS_ENCRYPTION_KEY

You don't need to do anything: npm run setup generates both and saves them in .env (they are empty in .env.example). Create one by hand only on a server where you prepare the .env yourself:

$ node -e "console.log(require('crypto').randomBytes(48).toString('base64url'))"

3. Site URLs — FRONTEND_URL, BACKEND_URL, VITE_API_URL

4. Kie.ai — KIE_API_KEY

Powers all image and video generation (Seedance, Kling, Veo, Grok, Nano Banana, Seedream, Flux, GPT Image…) and all AI text (scripts, ad copy, translations).

1. Sign up at https://kie.ai.
2. Open the API Key page in your Kie dashboard and create/copy your key.
3. Add credit to your Kie account (Billing) — generation fails without a balance.
4. Admin → Settings → AI Providers → paste into Kie API Key → Save → Test. The test shows your remaining Kie credit.

5. AWS S3 storage — AWS_REGION, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_S3_BUCKET

Every uploaded and generated file is stored in your S3 bucket. The files must be publicly readable because the AI providers download them by URL.

1. Sign in to https://console.aws.amazon.com → S3 → Create bucket. Pick a name (e.g. showcaseai-media) and a region (e.g. us-east-1). These are AWS_S3_BUCKET and AWS_REGION.
2. In the bucket → Permissions → Block public access → Edit → untick Block all public access → Save.
3. Same tab → Bucket policy → paste the policy below (replace the bucket name) → Save.
4. Same tab → Cross-origin resource sharing (CORS) → paste the CORS rules below (needed for video thumbnails in the browser).
5. IAM → Users → Create user (e.g. showcaseai) → Add permissions → Create inline policy → JSON → paste the IAM policy below.
6. Open the user → Security credentials → Create access key → "Application running outside AWS" → copy the Access key ID and Secret access key (the secret is shown only once).
7. Admin → Settings → Storage (AWS S3) → fill Region, Access Key ID, Secret Access Key and Bucket Name → Save → Test.

Bucket policy (public read):

{
  "Version": "2012-10-17",
  "Statement": [{
    "Sid": "PublicRead",
    "Effect": "Allow",
    "Principal": "*",
    "Action": "s3:GetObject",
    "Resource": "arn:aws:s3:::showcaseai-media/*"
  }]
}

CORS:

[{
  "AllowedOrigins": ["https://app.example.com", "http://localhost:4001"],
  "AllowedMethods": ["GET", "HEAD"],
  "AllowedHeaders": ["*"],
  "MaxAgeSeconds": 3600
}]

IAM policy (least privilege):

{
  "Version": "2012-10-17",
  "Statement": [
    { "Effect": "Allow", "Action": ["s3:PutObject", "s3:GetObject", "s3:DeleteObject"],
      "Resource": "arn:aws:s3:::showcaseai-media/*" },
    { "Effect": "Allow", "Action": ["s3:ListBucket"],
      "Resource": "arn:aws:s3:::showcaseai-media" }
  ]
}

Optional: AWS_S3_PUBLIC_URL = a CloudFront/CDN domain in front of the bucket (e.g. https://media.example.com). AWS_S3_ACL = public-read only if your bucket uses ACLs instead of a bucket policy (then also add s3:PutObjectAcl to the IAM policy). Otherwise leave both empty. Every file is stored under one folder in the bucket (AWS_S3_FOLDER, default showcaseai-cc), so a bucket shared with another project stays tidy.

6. Speechify — SPEECHIFY_API_KEY

Powers the voice library, text-to-speech, voice-overs and voice cloning.

1. Sign up for the Speechify API at https://console.sws.speechify.com.
2. Open API Keys → create a key → copy it.
3. Admin → Settings → AI Providers → Speechify API Key → Save → Test. The test also imports the Speechify voice library ("Imported N Speechify voices"). It is also imported automatically the first time someone opens the voice picker.

7. NewPortAI — NewPortAI_KEY

Powers lip-sync for talking-avatar videos and the Ad Localizer.

1. Sign up at https://www.newportai.com.
2. Open your dashboard → API Key → copy it, and add credit to your account.
3. Admin → Settings → AI Providers → NewPortAI Key → Save → Test.

8. Email — SMTP or Mandrill

Used for password-reset links and the optional welcome email when an admin adds a user. Choose one provider with the Send Mail Via switch (Admin → Settings → Email / Notifications).

SMTP (any email provider)

Then set Send Mail Via = SMTP, FROM_EMAIL (an address your provider allows you to send from, e.g. no-reply@example.com) and SUPPORT_EMAIL (shown in emails). Port 465 uses SSL automatically; 587 uses STARTTLS.

Mandrill (Mailchimp Transactional)

1. In Mailchimp open Transactional (Mandrill) → Settings → Add API key → copy it.
2. Under Domains add and verify your sending domain (DKIM/SPF records).
3. Admin → Settings → Email: Send Mail Via = Mandrill, paste Mandrill API Key, set From Email on the verified domain. If Mandrill fails and SMTP is also filled in, SMTP is used as a fallback.

9. Stripe — STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET (optional)

Needed only if you sell credit packs on the Buy Credits page.

1. Sign in at https://dashboard.stripe.com (use Test mode first).
2. Developers → API keys → reveal and copy the Secret key (sk_test_… / sk_live_…).
3. Developers → Webhooks → Add endpoint → URL https://api.example.com/api/payment/stripe/webhook → events checkout.session.completed and checkout.session.async_payment_succeeded → Add.
4. Open the endpoint → Signing secret → reveal and copy (whsec_…).
5. Admin → Settings → Payments (Stripe) → paste both → Save → Test. Then check your packs in Admin → Credit Packs.

Testing on your own computer: install the Stripe CLI and run stripe listen --forward-to localhost:5000/api/payment/stripe/webhook — it prints a whsec_… secret to use while it runs. Test card: 4242 4242 4242 4242, any future date, any CVC.

10. Stock media — PIXABAY_KEY, UNSPLASH_KEY, PEXELS_KEY (optional, free)

Enter them in Admin → Settings → Stock Media. Any provider without a key is simply not searchable.

11. Credit prices and limits

Nothing to obtain — just decide your prices. Admin → Settings → Credit Prices sets what every action costs (image, avatar, talking video, showcase video, AI Ads, voice clone, voice-over, Ad Localizer, AI text); the app shows users the current price. Admin → Settings → Limits & Security sets the login session length, rate limits, maximum upload size and when held credits are returned. See the full list with defaults.

12. Complete example files

backend/.env — on your computer (written by npm run setup)

mongoDBURL=mongodb://127.0.0.1:27017/showcaseai
JWT_SECRET=<generated by npm run setup>
SETTINGS_ENCRYPTION_KEY=<generated by npm run setup>
PORT=5000
NODE_ENV=development

backend/.env — on a live server

mongoDBURL=mongodb+srv://myuser:MyPassword123@cluster0.abcde.mongodb.net/showcaseai?retryWrites=true&w=majority
JWT_SECRET=<generated by npm run setup>
SETTINGS_ENCRYPTION_KEY=<generated by npm run setup>
PORT=5000
NODE_ENV=production

That's all — the site URLs, keys, email, payments, prices and limits are entered in Admin → Settings.

frontend/.env (rebuild the frontend after changing it)

VITE_API_URL=https://api.example.com/api/
VITE_APP_NAME=ShowcaseAI
VITE_TERMS_URL=https://example.com/terms
VITE_PRIVACY_URL=https://example.com/privacy

Admin → Settings #

One screen in the admin panel for every external key and site option. No file editing and no restart needed.

How it works

• Values are saved in MongoDB (collection sitedatas, key app_credentials). Secret values are encrypted with AES-256-GCM using SETTINGS_ENCRYPTION_KEY (or JWT_SECRET if that is not set).
• Precedence: value saved in Admin → Settings → otherwise the variable with the same name in backend/.env → otherwise empty.
• Changes apply immediately.
• Secrets are never sent back to the browser; they are shown as ••••••••. Leaving a secret field empty keeps the stored value.
• Keep SETTINGS_ENCRYPTION_KEY stable. If it changes, the saved secrets can no longer be decrypted and must be re-entered.

Groups and fields

URL fields accept a trailing slash or not. Number fields are validated (an invalid value is rejected with a message); an empty field uses the default shown. Reset next to a field removes the saved value; Remove deletes a saved secret.

Where to get each key

Step-by-step instructions for every key — MongoDB, Kie.ai, AWS S3 (bucket policy, CORS and IAM policy), Speechify, NewPortAI, SMTP/Mandrill, Stripe (including the webhook) and the stock media providers — are in Keys & Credentials — Step by Step.

Email behaviour

If Mandrill fails and SMTP is configured, SMTP is used as a fallback. If nothing is configured, emails are skipped and a warning ("Email not sent") is logged — the API keeps running.

Production Deployment #

A typical setup is one Linux server running the API under PM2 behind nginx, with the built frontend served as static files and HTTPS from Let's Encrypt.

1 · Build the frontend

$ cd frontend
# set VITE_API_URL=https://api.example.com/api/ in .env first (copy .env.example to .env if it is missing)
$ npm ci
$ npm run build      # output in dist/

Upload the contents of dist/ to your web root. The web server must send every unknown path to index.html (single-page-app fallback), otherwise refreshing a page such as /dashboard returns 404.

2 · Install and start the API

$ cd backend
$ cp .env.example .env                # then set NODE_ENV=production in .env
$ npm ci --omit=dev
$ npm run setup -- --yes --no-demo --mongo "<your MongoDB URL>" \
    --admin-email you@example.com --admin-password "<a strong password>" \
    --frontend-url https://app.example.com --backend-url https://api.example.com
  # ^ first install only. Skip it if the database is already set up.
$ npm install -g pm2
$ pm2 start deploy/ecosystem.config.cjs
$ pm2 save
$ pm2 startup                         # follow the printed command so PM2 starts on boot

The package contains no .env file. On a live server, copy backend/.env.example to backend/.env and set NODE_ENV=production in it before you run npm run setup. Setup keeps the existing file and fills in mongoDBURL and the secrets; with NODE_ENV=production it never creates the demo user. Add --mongo, --backend-url, --frontend-url and --admin-email / --admin-password as needed (see the options); without a password, setup prints a generated admin password once — save it.

The ecosystem file sets the working directory to backend and NODE_ENV=production. Useful commands: pm2 logs, pm2 restart all, pm2 status.

3 · Configure nginx

Start from deploy/nginx.conf.example and replace the domain names. It contains:

• An app domain (e.g. app.example.com) serving dist/ with try_files $uri $uri/index.html /index.html; for the SPA fallback.
• An API domain (e.g. api.example.com), or an /api path, proxying to http://127.0.0.1:5000 with client_max_body_size 100m, 300-second proxy timeouts and the X-Forwarded-For / X-Forwarded-Proto headers.

Then enable HTTPS with Let's Encrypt, for example:

$ sudo certbot --nginx -d app.example.com -d api.example.com

Single-server option

Instead of a separate web root, set SERVE_FRONTEND_DIST=../frontend/dist in backend/.env. The API then serves the frontend too, on the same domain. Build the frontend with VITE_API_URL=https://yourdomain.com/api/ and point nginx at the API only.

When SERVE_FRONTEND_DIST is set and dist/index.html exists, the API serves, in this order: /api/* (the API), the built static files, and finally index.html for every other non-API path (so React Router URLs survive a refresh). If dist/index.html is missing the API logs a warning and serves no frontend — run npm run build in frontend/ first.

4 · Final configuration

• Set FRONTEND_URL and BACKEND_URL to your real https domains.
• Configure the Stripe webhook (see Admin → Settings).
• Use your own admin login: change the password in Profile and the email in MongoDB Compass (see Changing the admin login).
• Rotate a secret only if it has been exposed, and only JWT_SECRET (generate a new value as shown in Secrets, paste it into .env and restart — everyone is logged out). Never change SETTINGS_ENCRYPTION_KEY on a live site (see Secrets – set once, never change); rotate provider keys in their own dashboards instead.
• Back up MongoDB regularly, and keep a copy of backend/.env somewhere safe.

Go-live checklist

Branding & Customisation #

Rename and rebrand the product without touching application code.

Email template variables

The templates can use these placeholders, which are replaced when an email is sent:

Authentication & Users #

JWT authentication with email and password — there is no social/OAuth login. Visitors can create their own account on the sign-up page (/register), and admins can create accounts in the admin panel. The first admin is created by the setup script (see Admin Account & Starter Data).

Creating users

• Self sign-up: /register (name, email, password). New accounts get the user role and start with no credits until an admin adds some or they buy a credit pack. Sign-ups are limited to 5 per hour per IP address.
• An admin opens Admin → Users → Add User and enters a name, email and password, plus an optional starting credit balance. The server always creates the account as a regular user (user role, active status).
• Deleted accounts: sign-up with the email of a deleted account is refused ("This email can't be used to register. Please contact the site administrator."). Only an admin can restore it, in Admin → Users → Add User with the same email; the account comes back with its previous data and credits ("Deleted account restored with its previous data").
• With the Send Email checkbox ticked, the user receives a welcome email containing a "set your password" link valid for 48 hours (the email never contains a plaintext password). Email must be configured for this.

Login

1. User submits email + password to POST /auth/login.
2. Backend finds the user, verifies the password with bcrypt, and rejects deleted and inactive accounts. Failed attempts are rate-limited (LOGIN_RATE_LIMIT, default 10 per 15 minutes per IP).
3. A JWT (HS256) is signed with JWT_SECRET, valid for the Login session length setting (SESSION_DAYS, 1–90 days, default 7), and returned with the user object (password removed). The browser keeps the auth_token cookie for at most 7 days, so a user stays signed in for the shorter of the two.
4. Frontend stores the token in the auth_token cookie (SameSite=Lax, Secure on https), then redirects: admin → /admin/dashboard, others → /dashboard.

Token handling

• Every API call sends Authorization: Bearer <token> (from the cookie).
• MiddlewareModule.checkAuth verifies the signature (algorithm pinned to HS256), loads the user, checks the user is still active and not deleted, and checks the token version. It sets req.user plus request context (source, storeId, domain from headers). Failures return HTTP 401 {"status":"error","errorCode":"InvalidToken"}.
• MiddlewareModule.checkAdmin runs after it on every /admin/* route and returns HTTP 403 {"errorCode":"Forbidden"} for non-admins.
• Session revocation: each user has a token version. Logout (POST /auth/logout), a password change (by the user or by an admin), and an admin deactivating or deleting a user all invalidate every existing token of that user immediately.
• On app load, ProtectedLayout calls GET /auth/get-auth-user to re-hydrate the session. Any 401 response clears the cookie and redirects to /login.

Password reset & password changes

• POST /auth/forgot-password emails a reset link with a random single-use token. Only its SHA-256 hash is stored; it expires after 1 hour. The response is identical whether or not the email exists (no account enumeration).
• POST /auth/reset-password takes { token, password }, sets the new hashed password and consumes the token.
• Changing the password on the profile page (/update-profile) requires the current password. Minimum password length is 8 characters.
• Forgot-password and reset-password requests share a limit of 5 per hour per IP. Sign-up has its own limit of 20 per hour per IP.

Roles & special flags

• role — user or admin. Enforced on the server for every /admin/* route; the frontend also redirects non-admins away from /admin/* pages. There is exactly one admin account (created by setup); roles cannot be changed afterwards.
• isSpecialUser — a "VIP" flag that grants effectively unlimited credits (returns a 10,000 balance and never deducts).
• status (active/inactive), isDeleted (soft delete), userSource (where the account originated: web for sign-ups, admin for accounts added in Admin → Users, setup or seed for the accounts created by npm run setup). A soft-deleted email cannot register again; only an admin can restore it from Admin → Users → Add User.
• An admin cannot deactivate or delete their own account, and the last admin cannot be removed.

Frontend access control

checkAccess() and applyAccessControl() in utils/Helper.js are the "pro feature" gate — currently set to unlock everything. They mark all menu items as available and remove "PRO/upgrade" badges.

The Credit System #

A ledger-based wallet. Every paid action costs credits; the balance is topped up by admin grants or Stripe purchases. All prices are calculated on the server — never taken from the browser.

The building blocks

Available balance = active credits (assigned) − used − currently reserved.

Admins assign credits when creating or editing a user (Admin → Users). Users see their balance in the sidebar and their history on the billing page.

How credits are spent: reserve → settle on success

Users are only charged for generations that succeed.

1. Reserve — before a paid provider is called, CreditHelper.reserve checks the balance and creates a CreditReservation (status RESERVED) inside the per-user lock. This lowers the available balance immediately, so parallel requests cannot overspend. If the provider rejects the job, the reservation is released at once.
2. Settle — when the provider reports success (Kie webhook, or NewPortAI polling), CreditHelper.settle consumes the reservation and records the charge. Duplicate callbacks find no reservation, so a job can never be charged twice.
3. Release — on failure the reservation is deleted with no charge.
4. Timeout — a background sweeper releases reservations whose provider never answered within RESERVATION_TTL_MIN (default 120 minutes) and marks the related media as failed ("Generation timed out. Your credits have been returned.").

Instant actions (AI text, saved text-to-speech, direct video-to-avatar upload) use CreditHelper.chargeNow, which checks and deducts in one locked step.

Where credits actually leave the account

Costs

All prices are set in Admin → Settings → Credit Prices (empty = default, 0 = free) and the app shows the current price to users. Creator Studio prices come from each model in the aimodelcatalogs collection.

AI Providers & Storage #

All AI work is delegated to three external services; media is stored on Amazon S3. Keys for all of them are entered in Admin → Settings.

Async Generation Flow #

Videos and images don't finish instantly. Here's the full lifecycle of a slow job.

Kie image / video

1. The controller calculates the price on the server and calls kieLib.generateImage/generateVideo.
2. kieLib first reserves the credits (CreditHelper.reserve). If the balance is too low, nothing is sent to Kie.
3. The job is sent to Kie with the callback URL <BACKEND_URL>/api/kie/webhook?token=…. If Kie rejects it, the reservation is released; if Kie accepts it, the Kie task id is attached to the reservation, a PredictionReplicate tracking row is created, and the task id is stored on the media record's renderData.renderServerId. Status = processing.
4. Kie calls back to POST /api/kie/webhook (kieController.ipn). Calls without a valid token are rejected with 401, and each task is claimed exactly once (duplicate or late callbacks are ignored):
   • Success → CreditHelper.settle charges the reserved credits, the result is re-uploaded to S3 and the record is marked completed.
   • Failure → the record is marked failed and the reservation is released (no charge).
5. For videos, completion is finalised through commonComplete.js (generalVideoComplete / avatarComplete). An avatar clip additionally feeds a follow-up NewPortAI lip-sync job.
6. If no callback ever arrives, the reservation sweeper returns the credits after RESERVATION_TTL_MIN and marks the record failed.

NewPortAI lip-sync

1. render.js reserves the talking-avatar price (CREDITS_TALKING_AVATAR, default 2) and starts a lip-sync task; the Ad Localizer does the same with its own per-language price.
2. newportai.js polls the task every 10 seconds (up to 15 minutes). On completion it uploads the video, marks the UserVideos record completed, and settles the reserved credits.

Feature Guide — Creative Studios #

Feature Guide — AI Ad Tools #

Feature Guide — Payments (Stripe) #

One-time credit packs, purchased through Stripe Checkout. Optional — without Stripe keys the rest of the app works normally. Setup steps: Admin → Settings → Payments.

The flow

1. Admin defines packs on /admin/credit-packs (name, credits, price, currency).
2. User opens /buy-credits, clicks Buy → backend creates a pending PaymentOrder + a Stripe Checkout session and redirects to Stripe.
3. User pays (test card 4242 4242 4242 4242). Stripe returns them to /payment-success.
4. Credits are granted by finalizeSession, triggered by both the Stripe webhook and the success-page verify call — made idempotent by the creditGranted flag so credits are never granted twice. Before granting, the paid amount, currency and session are checked against the stored order.

Architecture notes

• The webhook POST /api/payment/stripe/webhook is mounted specially in app.js with a raw body parser (before JSON parsing) so Stripe's signature can be verified. A valid signature (STRIPE_WEBHOOK_SECRET) is required; unsigned calls are refused.
• Webhook events used: checkout.session.completed and checkout.session.async_payment_succeeded.
• The Stripe client is lazily initialised — the app boots fine before keys are added; Buy Credits shows "Payments are not configured yet" until STRIPE_SECRET_KEY is saved in Admin → Settings (no restart needed).
• Users can only see their own payment orders.
• Models: CreditPack (what's for sale), PaymentOrder (audit trail + idempotency).

Feature Guide — Community & Projects #

Admin Panel #

Accessible to admin role accounts under /admin/*. Every admin API route is protected on the server: not logged in → 401, logged in but not an admin → 403.

The admin tasks you'll use most

1. Create a user — Admin sidebar → Users → Add User → name, email, password and an optional credit amount → Add User. Tick Send Email to send the welcome email with a link to set their own password.
2. Give a user credits — Admin sidebar → Users → find the user → Edit → enter an amount under Assign Credit → Update. The amount is added to the user's balance.
3. Set up something to sell — Admin sidebar → Credit Packs → Add Credit Pack → enter a name, credits, and price → Save. It then appears on the user's Buy Credits page.
4. Change a provider key — Admin sidebar → Settings → edit the field → Save → Test.

Data Models Reference #

26 Mongoose models. All use timestamps; most user-owned models share a platform sub-object and isDeleted/deletedAt soft-delete.

Users & Billing

Videos, Avatars & Images

Voice, Community & Content

API Reference #

All paths are prefixed /api. GET/POST = method; Auth = requires a valid token; Admin = requires a logged-in admin.

Common responses

System

Auth & Profile

Billing & Payments

Generation — Image, Video, Voice, LLM

New Feature Endpoints

Lists, Media, Community, Admin, Webhooks

Security & Hardening #

The protections built into ShowcaseAI, how to test them, and what you still need to do on your own server.

Access control

• Every /admin/* API route requires a logged-in admin: 401 when not logged in, 403 when not an admin. This includes the avatar-template and settings routes.
• /get-site-data requires a login and only returns the public lists (ethnicities, profession). Saved API keys can never be read through the API.
• Ownership is checked on every user resource: users can only view or delete their own media, voices, avatars, ad copies, brand kits and payment orders. Cloned voices can only be used by their owner.
• An admin cannot deactivate or delete themselves, and the last admin cannot be removed.

Sessions and passwords

• JWT signed with HS256 (algorithm pinned on verification), valid for SESSION_DAYS (default 7 days); the browser keeps the sign-in for at most 7 days.
• Per-user token version: logout, password change, and admin deactivation/deletion revoke all sessions of that user immediately. Inactive or deleted users cannot log in or use old tokens.
• Password reset uses a single-use random token; only its SHA-256 hash is stored and it expires after 1 hour. Welcome emails contain a 48-hour "set your password" link instead of a plaintext password.
• Minimum password length 8. Changing a password requires the current password. Forgot-password returns the same response for unknown emails (no account enumeration).

Request protection

• Rate limiting: failed logins 10 per 15 minutes per IP (LOGIN_RATE_LIMIT); forgot-password and reset-password 5 per hour (one shared limit); sign-up 20 per hour; voice previews 20 per minute; a global API limit (API_RATE_LIMIT, 1000 requests per 5 minutes per IP).
• Helmet security headers, a CORS allow-list (FRONTEND_URL), request body size limits, and generic error messages (no stack traces or internal errors are sent to clients).
• NoSQL injection: MongoDB operators are stripped from all request bodies, ids are validated, and user search text is escaped before it is used in a regular expression.

Credits and payments

• Prices are always calculated on the server (Creator Studio from the model catalog; text-to-speech from the script length), never taken from the browser.
• Credits are reserved atomically (per-user lock) before a paid provider is called and released automatically on failure. Stale reservations are released after RESERVATION_TTL_MIN. Duplicate provider callbacks cannot charge twice.
• Kie callbacks must carry a secret token (HMAC derived from WEBHOOK_SECRET, or from JWT_SECRET) and each task is processed only once.
• The Stripe webhook requires a valid signature; the amount, currency and session are checked against the order before credits are granted.

Files and outgoing requests

• Uploads: only image, video and audio files are accepted. The real file type is detected from the file content (magic bytes); HTML and SVG uploads are never stored. Storage keys are generated by the server inside the user's folder. Size limit MAX_UPLOAD_MB; temporary files are deleted.
• SSRF protection: when the server downloads a URL, only public http(s) addresses are allowed. Private, loopback, link-local and cloud-metadata IP addresses are blocked, also after redirects and DNS resolution. Downloads are limited in size (MAX_REMOTE_FILE_MB) and time. In production only https URLs are allowed unless ALLOW_HTTP_REMOTE_URLS=true.
• API keys saved in Admin → Settings are encrypted at rest (AES-256-GCM) and never sent back to the browser.

Frontend

• The login token is kept only in the auth_token cookie (SameSite=Lax, Secure on https) — not in sessionStorage.
• Automatic logout on any 401 response.
• Notification text is rendered as plain text (no HTML injection). Community category SVG icons are sanitised with DOMPurify (and on the server).
• External links open with noopener; a route error boundary shows a friendly error page instead of a blank screen.

Automated security checks

With the API running and setup finished, run from backend/:

$ SMOKE_ADMIN_PASSWORD="your-admin-password" npm run smoke                      # macOS / Linux, uses http://localhost:<PORT>
$ API_URL=http://localhost:5000 SMOKE_ADMIN_PASSWORD="…" npm run smoke     # explicit URL
> $env:SMOKE_ADMIN_PASSWORD="your-admin-password"; npm run smoke          # Windows PowerShell

npm run smoke runs scripts/security-smoke.js, which you can also start directly with node scripts/security-smoke.js. The script reads backend/.env, logs in as the admin (SMOKE_ADMIN_EMAIL, default admin@showcaseai.app, and SMOKE_ADMIN_PASSWORD — there is no default password, so you must set it to your admin password), creates a temporary test user and runs 33 checks — admin routes refused without login (401) and for normal users (403), saved keys never returned, NoSQL injection rejected, reset links single-use, tokens revoked after logout, users unable to delete other users' videos, client-supplied prices ignored, unsigned Kie/Stripe webhooks refused, HTML disguised as an image rejected, and login rate limiting. It prints a ✔/✖ line per check and a "passed / failed" summary. The temporary user and everything it created are deleted at the end; your real accounts are not touched.

Your hardening checklist

• NODE_ENV=production on the live server.
• Strong, unique JWT_SECRET and SETTINGS_ENCRYPTION_KEY (generated by npm run setup).
• HTTPS everywhere (frontend, API, webhooks).
• Restrict CORS to your real frontend origin.
• Use your own admin email and password (Changing the admin login).
• MongoDB with authentication enabled and network access restricted (Atlas IP allow-list or firewall).
• S3 IAM user with least privilege (see S3 setup).
• Keep dependencies updated (npm audit) and back up MongoDB regularly.

Troubleshooting #

Start with npm run check inside backend/ — it finds most configuration problems in seconds. Then look up the symptom below. The API terminal (or pm2 logs) always shows the underlying error.

Glossary #