ReelSaga
Short drama streaming app: a Flutter app for iOS and Android, a Next.js website with a Creator Studio and an Admin panel, and a video worker. You add your own keys; everything else is ready.
1. Welcome
Thank you for buying ReelSaga. This guide is written for beginners: follow the chapters in order and you will have the server, the website and the app running with your own name and keys.
What is in the download
| Folder | What it is |
|---|---|
reelsaga_mobile_flutter/ | The mobile app (Flutter, iOS and Android). Viewers watch episodes, unlock them with coins, buy VIP, earn rewards. |
reelsaga_web_nextjs/ | One Next.js app that is the website, the Creator Studio (/studio), the Admin panel (/admin) and the API the mobile app uses (/api/v1). |
reelsaga_worker/ | Background jobs: turns uploaded videos into streaming (HLS) files, sends push campaigns, makes AI subtitles, releases scheduled episodes. |
deploy/ | The Docker stack: website + worker + PostgreSQL database + MinIO file storage, started with one command. |
tools/rename.mjs | Rebrands the whole kit (name, app id, colour, font, icon) in one command. |
docs/ | This documentation (HTML and PDF). |
How the parts fit
The mobile app and the website both talk to the same server (the Next.js app). All data lives in your PostgreSQL database. Videos, posters and subtitles live in S3-compatible storage (MinIO in the Docker stack, or Amazon S3, Cloudflare R2, Backblaze B2…). Firebase is used only for sign-in, push notifications, Analytics and Crashlytics.
DEMO_PURCHASES="true": purchases then run in demo mode (coins and VIP are granted without payment and labelled DEMO); keep it "false" on a live server. Without their keys, AI features say "add your key", emails are not sent, and the app shows no ads.AI disclosure
AI tools used to create this item: Yes.
- Source code: Yes. Written with the help of an AI coding assistant (Claude, by Anthropic). We reviewed, edited and tested all of it: the Flutter app passes
flutter analyzewith no issues, and the server has automated tests. - Documentation: Yes. Drafted with the same AI assistant, then checked step by step against the running product.
- Graphics: Yes. The screen designs and the app icon were made with the help of AI design tools. The preview images and the cover are screenshots of the real, running app. No photo or video is AI-generated: the six demo episode videos are real footage from Pexels by Alexander Mass (Pexels License), shown on the demo only and not in the download; episode posters are frames from those videos, and series covers are colour gradients.
AI-powered features in the item: Yes. They are optional, need your own OpenAI or Google Gemini API key, and stay off without one:
- Subtitles: episode subtitles from speech-to-text (OpenAI Whisper or Gemini) in the Creator Studio.
- Translation: subtitle translation, and translation of CMS pages in the Admin panel.
- Poster art: poster images generated with OpenAI in the Creator Studio.
- SEO copy: a URL slug and meta description for series pages.
- Report review: a second opinion on user reports for moderators.
Everything these features produce is AI-generated, can contain mistakes, and should be reviewed before you publish it. The AI provider is a third-party service with its own pricing; you are responsible for its costs.
How to turn the AI features on: chapter 14.
Screenshots
The main screens, so you know what you are setting up. The sample series, users and numbers are demo data; yours replace them.
Mobile app (iOS and Android)
Website
Creator Studio (/studio)
Admin panel (/admin)
2. Requirements
To run the server
- A Linux server (VPS) with at least 2 CPU cores, 4 GB RAM and 40 GB disk (more disk for many videos). Ubuntu 24.04 is used in this guide.
- Docker with the Compose plugin (install guide).
- A domain name, for example
your-domain.com, with two DNS records pointing at the server:your-domain.comandstorage.your-domain.com.
To build the mobile app
- Flutter 3.44 or newer (install), Android Studio with Android SDK 36 for Android, a Mac with Xcode 26 for iOS, and your own Apple Developer team for signing.
- Node.js 22 or newer and pnpm 11 (
npm i -g pnpm) if you run the website without Docker or use the rename tool.
Accounts you must create yourself
- Firebase (Google): sign-in and push. Required.
- RevenueCat: required to sell coins and VIP inside the mobile app. The app uses RevenueCat's SDK (
purchases_flutter) for App Store and Google Play purchases, so you register your own RevenueCat account, accept RevenueCat's terms of service, and put your own RevenueCat keys in the app and on the server (chapter 10). Without it the app runs, but its coin store and VIP page say purchases are unavailable. - Apple Developer Program and Google Play Console: to publish the app and sell in it.
- Your own server and domain, and storage for the videos (MinIO on the server, or a cloud bucket).
- Optional: Google AdMob (ads), Stripe, PayPal, Razorpay or Flutterwave (website payments), OpenAI or Google Gemini (AI), an SMTP email provider.
Third-party services and what they cost
| Service | Used for | Needed? | Costs to expect |
|---|---|---|---|
| Firebase (Google) | Sign-in, push notifications, Analytics, Crashlytics | Required | Free Spark plan with limits. Phone sign-in SMS are charged per message, and Authentication beyond the free monthly active users (or with multi-factor) needs the pay-as-you-go Blaze plan. Push messages (Cloud Messaging) have no per-message charge. |
| RevenueCat | App Store and Google Play purchases of coins and VIP | Required to sell in the app | Free up to a monthly revenue limit, then a percentage of the revenue it tracks, or a paid plan. You need your own account and accept RevenueCat's terms. |
| Apple App Store / Google Play | Publishing the app, in-app purchases | Required to sell in the app | Store commission on every in-app sale (15% or 30% depending on your programme), Apple's yearly developer fee, Google's one-time registration fee. |
| Google AdMob | Rewarded, interstitial and app-open ads | Optional | No fee, but you need your own AdMob publisher account (Google reviews it and needs your payment and tax details). Google keeps its share of ad revenue and pays you the rest. |
| Stripe | Website card payments and VIP subscriptions | Optional | A fee per successful payment (a percentage plus a fixed amount), more for international cards and currency conversion; disputes cost extra. Needs a verified business account in a supported country. |
| PayPal | Website payments | Optional | A fee per payment, more across borders. Needs a PayPal business account. |
| Razorpay | Website payments (India) | Optional | A fee per payment. Needs an Indian business account that passes Razorpay's KYC checks. |
| Flutterwave | Website payments (Africa) | Optional | A fee per payment, varying by country and method. Needs a verified business account. |
| Video storage and streaming: MinIO on your server, or Amazon S3, Cloudflare R2, Backblaze B2 and others | Videos, posters and subtitles; every play streams HLS from it | Required | Usually your biggest cost as you grow. MinIO is free software but uses your server's disk and bandwidth; cloud storage charges for stored GB, requests and outgoing traffic (some providers have no egress fee). Every upload is stored as up to three HLS quality levels plus an MP4 of each for downloads, so plan for several times the size of the original files. Traffic grows with every viewer and every minute watched; a CDN in front of the bucket helps. |
| Server (VPS) and domain | Website, API, worker, database | Required | Monthly hosting. Converting videos uses a lot of CPU, so upload-heavy platforms need more cores. |
| OpenAI or Google Gemini | AI subtitles, translations, posters, SEO text, report second opinions | Optional | Charged per use (per minute of audio, per token, per image). |
| SMTP email provider | Staff invites, password resets, emails to studios | Optional | Most have a free tier, then a price per email. |
| Vercel, managed PostgreSQL (optional hosting) | Running the website without your own server (chapter 6) | Optional | Their own plans and usage pricing. |
3. Quick start (Docker)
This gets the whole server running on your VPS in about 15 minutes. You need the Firebase keys from chapter 4 for sign-in; you can do this chapter first and add them after.
- Copy the kit to the server, for example with
scp reelsaga-1.0.1.zip root@YOUR_SERVER_IP:, then on the server:apt install -y unzip unzip reelsaga-1.0.1.zip cd reelsaga/deploy cp .env.example .env nano .env - In
.env, fill at least these values:Key What to put POSTGRES_PASSWORDA long random password (run openssl rand -hex 24to make one).APP_URLYour website address, e.g. https://your-domain.com.MEDIA_SIGNING_SECRETAnother random value ( openssl rand -hex 24).S3_ACCESS_KEY_ID/S3_SECRET_ACCESS_KEYA user name and a long password you choose for the built-in MinIO storage. S3_PUBLIC_ENDPOINTThe address phones and browsers reach the storage on: https://storage.your-domain.com(see chapter 5), orhttp://YOUR_SERVER_IP:9000for a first test.NEXT_PUBLIC_FIREBASE_*,FIREBASE_*From chapter 4. - Start everything:
The first build takes 5–10 minutes. On the first start the database tables are created and sample data is loaded (10 series, coin packs, VIP plans, pages), so every screen has content.docker compose up -d --build - Check it: open
http://YOUR_SERVER_IP:3000. You should see the home page with the sample series.http://YOUR_SERVER_IP:3000/api/v1/healthshows{"ok":true,"db":"ok",…}. - Make yourself the admin (chapter 7), then put it on your domain with HTTPS (chapter 5).
WEB_PORT, MINIO_PORT and MINIO_CONSOLE_PORT in .env (and use the new storage port in S3_PUBLIC_ENDPOINT)..env? Run docker compose up -d again. Changed a NEXT_PUBLIC_… value? These are built into the website, so run docker compose up -d --build.4. Firebase setup
Firebase handles sign-in (Google, Apple, phone, guest, and email for staff) and push notifications. Your data stays in your own database.
- Go to the Firebase console → Add project. Give it your app name. Google Analytics: on.
- Build → Authentication → Get started → Sign-in method. Turn on: Anonymous (guest mode), Google, Phone, Email/Password (staff accounts) and Apple (see chapter 16).
- Authentication → Settings → Authorized domains: add
your-domain.com. - Project settings (gear) → General → Your apps → Add app → Web (name it "Website"). Copy the values from the
firebaseConfigshown intodeploy/.env:NEXT_PUBLIC_FIREBASE_API_KEY="…apiKey…" NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN="your-project.firebaseapp.com" NEXT_PUBLIC_FIREBASE_PROJECT_ID="your-project" NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET="your-project.firebasestorage.app" NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID="…" NEXT_PUBLIC_FIREBASE_APP_ID="1:…:web:…" - Project settings → Service accounts → Generate new private key. A JSON file downloads. Copy three values from it into
deploy/.env:
Keep theFIREBASE_PROJECT_ID="your-project" FIREBASE_CLIENT_EMAIL="firebase-adminsdk-xxxx@your-project.iam.gserviceaccount.com" FIREBASE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nMIIE…\n-----END PRIVATE KEY-----\n"\nas they are in the file. Keep this file secret. - For the mobile app, install the FlutterFire CLI and connect the app (it registers the Android and iOS apps and writes their config files):
Use your own app id here (see chapter 17 to change it first). Then copy the values intodart pub global activate flutterfire_cli cd reelsaga_mobile_flutter flutterfire configure --project your-project --platforms android,ios \ --android-package-name com.yourcompany.reelsaga --ios-bundle-id com.yourcompany.reelsagareelsaga_mobile_flutter/.env(FIREBASE_ANDROID_API_KEY,FIREBASE_ANDROID_APP_ID,FIREBASE_IOS_API_KEY,FIREBASE_IOS_APP_ID,FIREBASE_IOS_CLIENT_ID,FIREBASE_MESSAGING_SENDER_ID,FIREBASE_PROJECT_ID): you find them inandroid/app/google-services.json,ios/Runner/GoogleService-Info.plist, or in Project settings → Your apps. - iOS Google sign-in: copy
ios/Flutter/Firebase.xcconfig.exampletoios/Flutter/Firebase.xcconfigand setGOOGLE_REVERSED_CLIENT_IDto theREVERSED_CLIENT_IDfromGoogleService-Info.plist. - Android Google and phone sign-in need your signing key fingerprints: run
cd android && ./gradlew signingReportand add the SHA-1 and SHA-256 under Project settings → Your apps → Android → Add fingerprint. Add the fingerprints of your upload key and of Google Play's app signing key too when you publish.
5. Put it online (VPS, HTTPS)
The Docker stack listens on port 3000 (website) and 9000 (storage). Put a web server with free HTTPS in front of both. Caddy is the easiest:
apt install -y caddy
cat > /etc/caddy/Caddyfile <<'EOF'
your-domain.com {
reverse_proxy localhost:3000
}
storage.your-domain.com {
reverse_proxy localhost:9000
}
EOF
systemctl reload caddy
Then in deploy/.env set APP_URL="https://your-domain.com" and S3_PUBLIC_ENDPOINT="https://storage.your-domain.com", and run docker compose up -d. Caddy gets the certificates by itself.
Already use Traefik or Nginx? Point your-domain.com at port 3000 and storage.your-domain.com at port 9000 in the same way. Close ports 3000, 9000 and 9001 in your firewall once the proxy works (ufw allow 22,80,443/tcp && ufw enable). The MinIO console (port 9001) is for you only; reach it through an SSH tunnel: ssh -L 9001:localhost:9001 root@YOUR_SERVER_IP.
Backups
cd reelsaga/deploy
docker compose exec postgres pg_dump -U reelsaga reelsaga | gzip > backup-$(date +%F).sql.gz
Run it daily with cron and copy the files off the server. Videos are in the minio-data Docker volume; back it up too, or use a cloud bucket (next chapter).
6. Other hosting (Vercel, cloud storage)
Costs: Vercel, managed databases and cloud storage are third-party services with their own pricing; you are responsible for any hosting costs (cost overview).
Website on Vercel
Vercel has its own pricing: its free Hobby plan is for personal, non-commercial projects, so a live business usually needs a paid plan. You pay Vercel and your database provider directly.
- Create a PostgreSQL database (Neon, Supabase, Railway, or your own) and copy its connection string.
- Import
reelsaga_web_nextjsinto Vercel (Root directory:reelsaga_web_nextjs). Add every key ofreelsaga_web_nextjs/.env.exampleunder Settings → Environment Variables, withDATABASE_URLset to your database. - Create the tables and the sample data once from your computer: in
reelsaga_web_nextjs, put the sameDATABASE_URLin.env, thenpnpm install,pnpm prisma:migrate:deploy,pnpm first-run. - The worker (video conversion, push, subtitles) needs ffmpeg and runs all the time, so it cannot run on Vercel. Run it on any small server with Docker:
cd reelsaga_worker && docker build -t reelsaga-worker . && docker run -d --restart unless-stopped --env-file .env reelsaga-workerwith the worker's.envfilled from.env.example.
Cloud storage instead of MinIO
Costs: cloud buckets charge for storage, requests and outgoing traffic; video streaming makes the traffic part grow quickly with your audience.
Any S3-compatible bucket works. Set S3_ENDPOINT (empty for Amazon S3; for Cloudflare R2 https://<account>.r2.cloudflarestorage.com), S3_REGION, S3_BUCKET, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, and leave S3_PUBLIC_ENDPOINT empty. Keep the bucket private, and add a CORS rule that allows GET and PUT from your domain (the Studio uploads straight to the bucket, and the website plays from it).
7. First admin and sample data
Create your own admin account (it makes the Firebase email account when it does not exist yet):
cd reelsaga/deploy
docker compose run --rm migrate pnpm admin:create you@example.com
It prints a link: open it to choose your password, then sign in at https://your-domain.com/admin/login. (You can also put the password after the email; it then shows on screen and in your shell history.) Without Docker: cd reelsaga_web_nextjs && pnpm admin:create you@example.com. Invite more staff from Admin → Roles & Staff (roles: super admin, content manager, finance, moderator, support, read-only).
The sample data
The first start fills an empty database with sample series, studios, viewers, coin packs, VIP plans, pages and 90 days of sample sales, so you can see every screen working. Sample episodes play one short original clip until you upload real ones. When you are ready to go live:
- Delete the sample series in Admin → Series and the sample studios in Admin → Creators, or keep them as placeholders while you upload.
- Check Coin Packs, VIP Plans and CMS Pages (terms, privacy, delete account) and edit them for your business.
- Want the sample catalogue without the 90 days of sample sales (so your money reports start at zero)? Run
docker compose down -v(this deletes all data and videos), addSEED_SALES_HISTORY=falseto.env, thendocker compose up -dagain. The sample series and studios still load; remove them as described above.
8. Setup check
Open Admin → Setup: it lists every key, says which are missing, and tests each connection (database, storage, Firebase, push, payments, email, AI, ads report) with a clear message. The same check runs in a terminal:
docker compose run --rm migrate pnpm run doctor # Docker
cd reelsaga_web_nextjs && pnpm run doctor # without Docker
9. Run the mobile app
cd reelsaga_mobile_flutter, then copy.env.exampleto.env(the download has no.env: the app does not build until you create it) and set:API_BASE_URL=https://your-domain.com APP_NAME=ReelSaga FIREBASE_… (from chapter 4)- Get the packages and run on a phone or emulator:
flutter pub get flutter run - Build for testing:
flutter build apk --release(Android) or openios/Runner.xcworkspacein Xcode (iOS). - iOS signing: the Xcode project ships with Automatic signing and no team or provisioning profile set. Open
ios/Runner.xcworkspace→ select Runner → Signing & Capabilities → tick Automatically manage signing (already on) and choose your own Team. Xcode then creates the certificates and profiles for your bundle id. Do this for the Debug, Release and Profile configurations (the All tab).
android/app/build.gradle.kts sets compileSdk = 36, targetSdk = 36 and minSdk = 24 explicitly. Google Play requires a recent target SDK; when Google raises it, change both numbers there.http://10.0.2.2:3000 and the iOS simulator at http://localhost:3000. Release builds need an https address.The app reads every setting from .env: no keys live in Dart code. After changing .env, stop the app and run it again (hot reload does not reload .env).
10. In-app purchases (RevenueCat)
purchases_flutter), which is run by RevenueCat, Inc., not by us. Each buyer of this item must register their own RevenueCat account, accept RevenueCat's terms of service, and supply their own RevenueCat keys (steps 3 and 4 below); no keys of ours are included. Costs: RevenueCat is free up to a monthly revenue limit, then charges a share of the revenue it tracks or a paid plan (revenuecat.com/pricing), on top of Apple's and Google's store commission. Without RevenueCat the app still runs, but it can't sell coins or VIP.The app sells coin packs (consumables) and VIP (subscriptions) through the App Store and Google Play, with RevenueCat in between. The server is told about every purchase and gives the coins or VIP; the app never decides a balance itself.
- Create the products in App Store Connect and Google Play Console with these ids (or your own; the ids are stored with each pack and plan in Admin → Coin packs / VIP plans):
- Coins (consumable):
reelsaga_coins_300,reelsaga_coins_600,reelsaga_coins_1200,reelsaga_coins_2500,reelsaga_coins_6500,reelsaga_coins_13000 - VIP (auto-renewing, one subscription group):
reelsaga_vip_weekly,reelsaga_vip_monthly,reelsaga_vip_yearly
- Coins (consumable):
- In RevenueCat: create a project, add your iOS and Android apps, import the products, create an entitlement
vipwith the three VIP products, an offeringdefault(current) with the VIP packages, and an offeringcoinswith the coin products. - App keys: RevenueCat → Project → API keys → the public SDK keys. In
reelsaga_mobile_flutter/.env:REVENUECAT_IOS_KEY,REVENUECAT_ANDROID_KEY,USE_REVENUE_CAT=true. - Server keys in
deploy/.env:REVENUECAT_API_KEY(a secret API key, v1) andREVENUECAT_WEBHOOK_SECRET(any long random value). - Test purchases (sandbox): purchases made with App Store sandbox or Google Play test accounts are ignored on a production server, so testers can't give themselves real coins or VIP. To test the store on your live server for a short time, set
REVENUECAT_ALLOW_SANDBOX="true", restart, test, then remove it. On your own computer (development) test purchases always count. - RevenueCat → Integrations → Webhooks → add
https://your-domain.com/api/v1/webhooks/revenuecatwith the Authorization header value equal toREVENUECAT_WEBHOOK_SECRET.
DEMO_PURCHASES="true" and no payment key set (RevenueCat, Stripe, PayPal, Razorpay or Flutterwave), purchases are granted without payment and labelled DEMO, so you can try every flow. It is off by default, so a live server never gives coins or VIP away; adding any payment key also switches to live mode.11. Website payments
Costs: each gateway takes a fee per payment and has its own account rules (business verification, supported countries); see the cost overview. Coins are credited only for payments the gateway confirms as paid, for at least the price of the pack or plan.
On the website, viewers buy coins and VIP with any gateway you turn on. Each gateway appears when its keys are set; switch them on or off in Admin → Settings → Payment gateways. Turn on Web coin checkout in Admin → Settings → App config to show the coin store on the website.
| Gateway | Keys | Webhook URL and events |
|---|---|---|
| Stripe (cards, wallets; VIP as a real subscription) | STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET | https://your-domain.com/api/v1/webhooks/stripe with events checkout.session.completed, checkout.session.async_payment_succeeded (bank debits and vouchers that complete later), invoice.paid, invoice.payment_failed, customer.subscription.updated, customer.subscription.deleted, charge.refunded and charge.dispute.created (refunds made in the Stripe Dashboard and card chargebacks). Turn on the Customer portal (Settings → Billing) for "Manage subscription". |
| PayPal | PAYPAL_CLIENT_ID, PAYPAL_CLIENT_SECRET, PAYPAL_MODE=live (anything else = sandbox) | None needed: the payment is confirmed when the buyer returns. |
| Razorpay (India) | RAZORPAY_KEY_ID, RAZORPAY_KEY_SECRET, RAZORPAY_WEBHOOK_SECRET | https://your-domain.com/api/v1/webhooks/razorpay, events payment_link.paid, refund.processed and payment.dispute.created, with the same secret. |
| Flutterwave (Africa) | FLUTTERWAVE_SECRET_KEY, FLUTTERWAVE_WEBHOOK_HASH | https://your-domain.com/api/v1/webhooks/flutterwave; set the same Secret hash in Flutterwave → Settings → Webhooks. |
PayPal, Razorpay and Flutterwave take one-time payments, so a VIP plan bought with them is a pass for one period (week, month or year) that the viewer renews by buying again. Every payment is credited once, even when the return page and the webhook both arrive. The pages a gateway sends the buyer back to must be pages of your own website (APP_URL); any other address is refused. Refunds from Admin → Transactions go back through the same gateway. A refund or chargeback made outside the admin is picked up by itself for the App Store and Google Play (through RevenueCat), Stripe and Razorpay; for PayPal and Flutterwave, open the payment in Admin → Transactions → Refund and tick Money already returned. Either way the coins or VIP and the studios' earnings from that payment are taken back (chapter 22, "Refunds and chargebacks").
12. Push notifications
Costs: Firebase Cloud Messaging has no per-message charge; it is part of your Firebase project (cost overview).
- Android works once Firebase is set up (chapter 4).
- iOS: in the Apple Developer site create an APNs key (Keys → +, Apple Push Notifications service), then upload it in Firebase → Project settings → Cloud Messaging → Apple app configuration.
- The app registers each signed-in device and joins two topics:
reelsaga_allandreelsaga_<language>(for examplereelsaga_es). Send campaigns from Admin → Push to everyone, a language, a series' followers, or one user, now or scheduled. - The topic prefix is
PUSH_TOPIC_PREFIX; it must be the same indeploy/.envand the app's.env(the rename tool keeps them equal).
13. Ads (Google AdMob)
Costs and account: AdMob is a Google service with its own terms. It has no fee, but you need your own AdMob publisher account, approved by Google with your payment and tax details; Google keeps its share of ad revenue and pays the rest to that account.
The app has three ad types: rewarded (watch an ad to unlock an episode or earn coins), interstitial (between free episodes) and app open (when the viewer comes back to the app). VIP members see none when "Hide all ads for VIP" is on.
- In AdMob, add your Android and iOS apps and create one ad unit of each type you want.
- In
reelsaga_mobile_flutter/.envsetADMOB_ANDROID_APP_IDand the unit idsADMOB_ANDROID_REWARDED,ADMOB_ANDROID_INTERSTITIAL,ADMOB_ANDROID_APP_OPEN,ADMOB_IOS_REWARDED,ADMOB_IOS_INTERSTITIAL,ADMOB_IOS_APP_OPEN. - The iOS app id goes in
ios/Flutter/Firebase.xcconfig:ADMOB_IOS_APP_ID=ca-app-pub-…~…. - Your app ids replace placeholders; no ids of ours are included.
AndroidManifest.xmlreads${admobAppId}, filled fromADMOB_ANDROID_APP_IDin the app's.envbyandroid/app/build.gradle.kts;Info.plistreads$(ADMOB_IOS_APP_ID)fromios/Flutter/Firebase.xcconfig. Until you set them, the build uses Google's public sample app ids (ca-app-pub-3940256099942544~3347511713for Android,ca-app-pub-3940256099942544~1458002511for iOS, inbuild.gradle.ktsandios/Flutter/Debug.xcconfig/Release.xcconfig) so the SDK starts, and the ad unit ids are empty, so no ads load. Google's sample ids earn nothing for anyone; replace them with your own before you publish. - Server-side verification (required for rewarded ads): in AdMob open each rewarded ad unit → Server-side verification → turn it on and set the callback URL to
https://your-domain.com/api/v1/ads/ssv(use Verify URL to test it). On the server keepAD_REWARDS_MODE="ssv"(the default) and list your rewarded ad unit ids inADMOB_REWARDED_AD_UNITS, comma-separated (the same ids asADMOB_ANDROID_REWARDEDandADMOB_IOS_REWARDEDin the app). Callbacks for any other ad unit pay nothing, and until it is set no rewarded ad pays (Admin → Setup flags it). - Control how often ads show in Admin → Ads: rewarded ads per day, coins per ad, cooldown, interstitial every N free episodes, app-open spacing in hours.
/api/v1/ads/ssv with a signed message; the server checks Google's signature (with Google's published keys) and that the view came from one of your own rewarded ad units (ADMOB_REWARDED_AD_UNITS), stores the confirmed view, and only then grants the coins, the episode unlock or the streak restore — once per confirmed view, within the daily limit and cooldown you set. A request without Google's confirmation gets nothing. Admin → Setup (and pnpm run doctor) shows the callback URL and how many confirmed views arrived.When Google's confirmation is late or never comes
Google's server-side verification callback usually reaches your server a second or two after the viewer earns the reward, but it can be late (a slow network, a timeout) or never come (the ad was not finished, server-side verification is not switched on for that ad unit). Viewers are never charged and a confirmed view is never lost. What the viewer sees:
| What happens | What the viewer sees |
|---|---|
| Google confirms within 10 seconds (the normal case) | The reward right away: the episode unlocks, the coins arrive, or the streak is restored. |
| Google confirms later (up to 24 hours) | The message "Google hasn't confirmed this ad yet. Your reward is added automatically when it does, and you'll get a notification." The claim waits on the server as pending. When the callback arrives, the server grants what the viewer asked for and sends an inbox notification ("Episode unlocked", "Streak restored" or "Your ad reward is in"). If that no longer applies (the episode was unlocked another way meanwhile), the viewer gets the rewarded-ad coins instead. |
| The app could not reach your server after the ad (offline, app closed) | "You're offline. If Google confirmed the ad, its coins are added to your wallet automatically." A view Google confirmed but the app never claimed is paid as rewarded-ad coins 10 minutes later, the next time the viewer opens the app or the website. |
| Google never confirms | The pending claim expires after 24 hours and nothing is granted. This is what happens to every rewarded ad when server-side verification is not switched on for the ad unit, so check Admin → Setup after launch: it shows the callback URL and how many confirmed views arrived. |
Tell viewers in your help pages (Admin → CMS Pages, FAQ) that a reward can take a moment to arrive.
Without rewarded ad ids in the app, the "Watch an ad" option shows "No ad available right now", and no other ads show. For local testing only, AD_REWARDS_MODE="demo" on the server accepts rewards without Google's callback (the app then shows a 15-second demo slot) — never use it on a live server, because anyone could claim rewards. Google's test ad ids (listed in .env.example) never send verification callbacks, so test them with AD_REWARDS_MODE="demo". Other networks (AppLovin, Meta, Unity…) join through AdMob mediation, set up in your AdMob account.
Ad revenue in the admin: the dashboard and Ads page read your earnings from the AdMob Reporting API. In Google Cloud, enable the AdMob API, create an OAuth client (type Web application, redirect URI https://developers.google.com/oauthplayground), then in the OAuth Playground (gear icon → Use your own OAuth credentials) authorise the scope https://www.googleapis.com/auth/admob.readonly with the Google account that owns your AdMob account and exchange the code for a refresh token. Set ADMOB_PUBLISHER_ID (pub-…, AdMob → Settings → Account information), ADMOB_CLIENT_ID, ADMOB_CLIENT_SECRET and ADMOB_REFRESH_TOKEN on the server to show 30-day ad revenue and eCPM on the dashboard and Ads page.
14. AI subtitles and text
Costs: OpenAI and Google Gemini charge you per use (minutes of audio, text, images) on your own account. AI output can be wrong: studios review AI subtitles before they go live when "Hold for studio review before live" is on.
Which parts of ReelSaga itself were made with AI tools: AI disclosure in chapter 1.
Creators can make subtitles automatically and the admin can draft text with AI. Set SUBTITLE_PROVIDER to openai or gemini and the matching OPENAI_API_KEY or GEMINI_API_KEY, in deploy/.env (used by both the website and the worker). Without a key, the AI buttons say "add your key" and manual subtitles still work.
15. Email
Costs: SMTP providers have their own plans; most include a free monthly amount.
Staff invites, password resets and support replies are sent by email. Set SMTP_HOST, SMTP_PORT (587, or 465 with SMTP_SECURE=true), SMTP_USER, SMTP_PASS from any provider (Amazon SES, Postmark, Mailgun, Brevo, your host). Without SMTP_HOST, nothing is sent: the server log (docker compose logs web) notes each email with its recipient and subject only, never its text, because invite and reset links let anyone sign in. Set up SMTP before you invite staff; your own first admin link comes from pnpm admin:create (chapter 7).
16. Sign-in methods
- Guest: Firebase Anonymous. Turn guest mode on or off in Admin → Settings → App config. A guest who signs in later keeps their coins, unlocked episodes, VIP and progress; their purchases and coin history move to the account, so refunds and store restores still find them. Deleting a guest account keeps its payment records (anonymised), like any deleted account.
- Google: on in Firebase; Android needs the SHA fingerprints, iOS needs
GOOGLE_REVERSED_CLIENT_ID(chapter 4). - Phone: on in Firebase; for iOS also upload the APNs key (chapter 12) so Firebase can verify the device silently.
- Apple (required by Apple when you offer Google sign-in on iOS): Apple Developer → your app id → enable Sign in with Apple. In Firebase → Apple provider, add your Services ID, Team ID, Key ID and the .p8 key. On the server set
APPLE_TEAM_ID,APPLE_KEY_ID,APPLE_CLIENT_ID(your bundle id) andAPPLE_PRIVATE_KEYso account deletion also revokes the Apple sign-in, as Apple requires. - Welcome coins (Admin → Rewards → Welcome coins, 300 by default) go once to each new account whose email address the sign-in provider verified: Google and Apple sign-ins, or a guest who links one of them. Guests and phone-only accounts get none, so throwaway accounts can't collect them; the app says "New here? Get 300 free coins with Google or Apple". Invite rewards also count only friends with a verified email.
- Staff sign in with email and password at
/admin/login. To require two-step verification: in Firebase turn on Authentication → Settings → SMS multi-factor authentication (it asks you to upgrade to Identity Platform), have every staff member add their phone from the account menu (top right) in the admin, then setADMIN_REQUIRE_MFA=true.
17. Rebrand: name, app id, colours
One command changes the app name everywhere (app, website, admin, emails, push topics, store product ids), the Android application id and iOS bundle id, the brand colour, the website font and the icons:
cd reelsaga
node tools/rename.mjs --name "MyFlix" --id com.mycompany.myflix --color "#7C3AED" --font "DM Sans" --icon my-icon-1024.png
Every option is optional, so you can run it again later for one change. Add --dry to see what would change. Afterwards:
cd reelsaga_mobile_flutter
flutter pub get
dart run flutter_launcher_icons
dart run flutter_native_splash:create
flutterfire configure --project your-project # Firebase files for the new app id
and rebuild the website (docker compose up -d --build). The folder names (reelsaga_mobile_flutter and so on) stay as they are; they are never shown to users.
Permission texts (iOS)
iOS shows these texts when the app asks for a permission. They are neutral (no product name) so you can ship them as they are; change the wording to match your app in reelsaga_mobile_flutter/ios/Runner/Info.plist (the keys below). App Store review reads them, so keep them honest and specific.
| Key in Info.plist | When iOS shows it | Text in the download |
|---|---|---|
NSUserTrackingUsageDescription | App Tracking Transparency, before personalised ads (app_tracking_transparency) | Allow tracking to see ads that are more relevant to you. Free episodes stay free either way. |
NSPhotoLibraryUsageDescription | Choosing a profile photo or a screenshot for a support message | Choose a photo for your profile or attach a screenshot to your feedback. |
NSCameraUsageDescription | Taking a profile photo | Take a photo for your profile if you choose to. |
For other languages, add InfoPlist.strings files in Xcode (Runner → Localizations). Android asks for notifications with the system's own text; the notification channel names ("Reminders", "New episodes and updates") are in lib/core/services/firebase/reminder_notification_service.dart. If you turn off ads entirely, remove the tracking text and the app_tracking_transparency package.
By hand: the brand colours are in reelsaga_mobile_flutter/lib/core/theme/app_colors.dart (app) and reelsaga_web_nextjs/src/app/globals.css (website, --rs-crimson); the app name is APP_NAME in the app's .env and NEXT_PUBLIC_APP_NAME on the server.
18. Logo, icon and fonts
- App icon and splash: replace the PNGs in
reelsaga_mobile_flutter/assets/icon/(1024×1024:icon_ios.pngwithout transparency,icon_android.png,icon_splash.png), then rundart run flutter_launcher_iconsanddart run flutter_native_splash:create. The splash background colour is influtter_native_splash.yaml. - Website icons: replace
reelsaga_web_nextjs/src/app/icon.png(512×512),apple-icon.png(180×180) andfavicon.ico. - App font: put your
.ttffiles inassets/fonts/, list them underfonts:inpubspec.yaml, and changefamilyinlib/core/theme/app_text.dart. Check the font's licence allows apps. - Website font:
--fontin the rename tool, or change thenext/font/googleimport inreelsaga_web_nextjs/src/app/layout.tsx.
19. Basic edits
| I want to change… | Where |
|---|---|
| Coin packs, prices, bonus, first top-up, default unlock price | Admin → Coin Packs |
| VIP plans, trial days, benefits | Admin → VIP Plans |
| Episode prices and free episodes of a series | Studio → Pricing (creators), Admin → Series |
| Daily check-in rewards, streak restore | Admin → Rewards |
| Home banners and rails | Admin → Banners & Rails |
| Terms, privacy, delete account, about, help | Admin → CMS Pages |
| Genres, tags and languages | Admin → Genres & Tags, Admin → Languages |
| App versions (force update), maintenance mode, guest mode, support links | Admin → Settings → App config |
| App texts and translations | reelsaga_mobile_flutter/lib/l10n/app_en.arb and app_es.arb (English and Spanish), then run flutter gen-l10n |
| Website texts | The page files in reelsaga_web_nextjs/src/app/(site)/ and src/components/site/ |
App translations: the texts are in lib/l10n/app_en.arb (English) and lib/l10n/app_es.arb (Spanish). After editing, run flutter gen-l10n to regenerate lib/l10n/gen/ (flutter run and flutter build do it too). To add a language, copy app_en.arb to app_xx.arb, translate every value (keep the keys), set "@@locale": "xx", run flutter gen-l10n (the generated list adds the locale to supportedLocales), then in Admin → Languages edit that language and turn on The app ships this translation. Only those languages appear as app languages (the website settings, push language topics and CMS translations follow them); every other live language is a subtitle language.
20. Creator Studio: publish a series step by step
The Creator Studio at https://your-domain.com/studio is where studios publish their series: production companies, independent creators, or your own team. A studio sees only its own series, numbers and money. This chapter walks once through the whole path, from the application to a published series. The screenshots are from the live demo (the read-only demo studio).
Step 1. Apply and get approved
- The creator signs in on your website (any method except guest) and opens
/studio. Without a studio they land on Publish on … (/studio/apply): studio name, country, contact email, website or social link, a few lines about their work, an optional sample clip, and the box I own or license all content I upload. The page shows the studio share you set (chapter 22). - The application appears in Admin → Creators under Pending. A content manager or super admin opens it, ticks the review checks (identity verified, rights declaration signed, sample approved) and presses Approve, or Reject with a reason (the applicant gets an email with the reason and can apply again). You can also skip the application: Admin → Creators → Invite creates an approved studio directly.
- While the application waits,
/studioshows its status, and the creator can already add a payout method. After approval,/studioopens the dashboard.
Step 2. Create a series
- Studio → My Series → New series. Fill the title, synopsis, 1 to 4 genres (the first is the main one), tags, planned number of episodes, release schedule and original language, and tick I own all rights to this series.
- Add a poster (2:3, PNG/JPG/WebP), or press Generate with AI when an AI image key is set (chapter 14).
- The series is a draft: changes save automatically and viewers can't see it yet.
Step 3. Upload the episodes
- Studio → Upload, pick the series at the top, then drag MP4 or MOV files onto the page (vertical 9:16 works best; up to 4 GB per file). Each file goes straight from the browser into your storage, so large files never pass through the website server.
- The file name sets the episode:
ep05_dorm_party.mp4becomes episode 5, "Dorm Party". Files without a number are added after the last episode. - When a file has arrived, the worker converts it to HLS streaming files in 1080p, 720p and 480p (rungs taller than your source are skipped), an MP4 copy of each for offline downloads, a poster frame and a short preview. The row shows Processing, then Ready; if a conversion fails it shows the reason.
- Studio → Episodes shows every episode; drag a row (or use Alt + arrow keys) to change the order.
Step 4. Set the unlock prices
- Studio → Pricing, pick the series.
- Free episodes: the first N episodes are free for everyone (0 to 50). Viewers hit the paywall at episode N + 1.
- Default price: coins to unlock each paid episode (30 to 120). Change single episodes in the table; a finale can cost up to 500 coins.
- Bundle discount: the discount (0 to 50%) when a viewer unlocks all remaining episodes at once.
- The You earn per unlock column shows what the studio receives per unlock at your coins-per-$1 rate and the studio's share (chapter 22). Press Save.
Viewers unlock a paid episode with coins, with a free episode pass, or by watching a rewarded ad (within the daily ad limit). VIP members watch series marked Included in VIP without unlocking (Admin → Series → the series → Included in VIP).
Step 5. Subtitles and an interactive ending (optional)
- Studio → Subtitles: upload
.srtor.vttfiles per episode and language, edit the lines in the editor, or press Generate AI subtitles (needs an AI key; AI subtitles wait for the studio's approval when Admin → Languages → Hold for studio review before live is on). - Studio → Interactive: let viewers choose how the story goes on (chapter 21).
Step 6. Publish
- Publish the episodes: on Studio → Upload, Publish ready publishes every episode whose video is ready.
- Send the series for review: open it in Studio → My Series and press Submit for review. Its status becomes In review.
- Staff review it in Admin → Series (filter In review), open it, check it and set the status to Ongoing (new episodes still coming), Published (complete), or Scheduled (coming soon). From that moment the series is on the website and in the app. Hidden takes it down again.
- To release an episode later instead of now, staff set its release time in Admin → Episodes (status Scheduled): the worker publishes it at that time, VIP members can watch it up to 24 hours early, and viewers who turned on the series' reminder bell get a push when the episode's reminder is on.
After publishing, Studio → Analytics shows views, viewers, how far viewers get, the share who pass the paywall, reminder subscribers, retention per episode and traffic sources; Earnings and Payouts are in chapter 22.
21. Choose the ending (interactive episodes)
A series can let viewers decide how the story continues. At a chosen moment of a choice episode, the player shows a question with two answers (path A and path B) and a countdown. Each path is a list of episodes; after a path ends, both paths meet again at the rejoin episode, or the story ends there when you set none. Viewers can also buy the path they didn't choose.
How a studio sets it up
- Upload all episodes of both paths like any other episodes (chapter 20). Example from the sample data (Crown of Ashes): episode 32 is the choice, path A is episodes 33–36, path B is episodes 37–40, and both continue at episode 41.
- Studio → Interactive, pick the series, then in Choice settings:
Field What it does Choice episode The episode where viewers choose. Prompt The question on screen, e.g. "Should she open the letter?" (3–200 characters). Appears at When the question appears in the choice episode, as minutes:seconds (for example 1:41).Timer How long viewers have to choose (5–60 seconds). If no vote The path that plays when the timer runs out (and for viewers who are not signed in). Path A / Path B: label and episodes (numbers) The answer text, and the episodes of that path in playing order. Path episodes must be later episodes of the same series, and each episode can be on one path only. Rejoin at Ep Where both paths continue; it must come after the last path episode. Leave it empty when the paths are two different endings. Other path price Coins to also watch the path the viewer didn't choose (0–500; 0 = free). The suggested default is Admin → Coin Packs → Alt ending price. - The Branch graph shows choice → path A / path B → rejoin. Press Publish branches. The series is marked interactive and appears on the app's Interactive tab and in the "Choose the ending" rail.
- The Votes so far panel shows how viewers chose. Admin → Settings → App config → Interactive episodes turns the feature off everywhere.
What the viewer sees
- At the "appears at" moment the question slides over the video with both answers and the countdown; the video keeps playing.
- The viewer taps an answer (one vote per viewer). When the timer runs out without a tap, the "if no vote" path is chosen. Website visitors who are not signed in watch the default path, and their vote is not counted.
- After voting, the screen shows how everyone voted so far (percent for A and B).
- "Next episode" now follows the chosen path: the path's first episode, then its next ones, then the rejoin episode. Episodes of the other path are skipped in the normal order (next episode and autoplay).
- Watch the other path · N coins unlocks every locked episode of the other path at once, for the other path price. It is charged once, even if tapped twice. It is free for VIP members when the series is included in VIP, and nothing is charged for episodes the viewer had already unlocked. Paid paths count for the studio's earnings like any unlock.
- Path episodes are paid episodes like the others: the free-episode count, prices, VIP and ad unlocks all apply.
22. Creator earnings and payouts
Studios earn a share of what viewers spend on their series. Every amount below comes from settings you control, and every payout is approved by your finance staff. The kit does not send money by itself: you pay studios with the provider they chose, then mark the payout paid.
Where you set the rules
| Setting | Where | Default |
|---|---|---|
| Default creator share % (for newly approved studios) | Admin → Settings → Payments → Creator earnings | 60% |
| One studio's share % | Admin → Creators → the studio → Revenue share (finance or super admin) | the default at approval |
| VIP pool % (part of VIP revenue shared with studios) | Admin → Settings → Payments → Creator earnings | 50% |
| Minimum payout | Admin → Settings → Payments → Creator earnings | $50.00 |
| Early payouts on/off, and the early payout fee | Admin → Settings → Payments → Creator earnings | on, $5.00 |
| Coins per $1 (the value of a coin) | Admin → Settings → Payments | 100 coins = $1 |
A change to a studio's share applies from the next statement; statements already written keep the share they were made with.
How a month's earnings are worked out
- Coin unlocks. The paid coins viewers spent that month on the studio's episodes (single unlocks, "unlock all" bundles, other-path purchases), divided by coins per $1. Only coins a viewer bought count. Bonus coins (welcome coins, check-in, rewarded ads, invites, coin-pack bonuses) earn the studio nothing, so free coins can never turn into payouts; when a purchase is paid partly with bonus coins, only its paid part counts (each unlock stores both). Episodes unlocked with a rewarded ad or a free pass, free episodes and VIP plays earn nothing here.
- VIP pool. Each subscriber's VIP payments that month (paid VIP purchases in the apps and on the website, without demo purchases, minus the tax recorded with them) × VIP pool %. A subscriber's part is shared only between the studios that subscriber watched, by their VIP plays: plays of paid episodes watched through VIP instead of unlocking them. One subscriber's money never pays for another subscriber's plays, so an account a studio controls can only move its own payment around, never the money other subscribers paid. A VIP play counts once per viewer, episode and day (replays add nothing), only from a paid VIP plan (not a free trial), and never from the studio's own account. The pool part of a subscriber who watched no VIP play that month stays with you.
- Net revenue = coin unlocks + the studio's part of the VIP pool. The studio earns its share % of the net.
Monthly statements and payouts
- On the 1st of each month at 02:30 UTC the worker settles the month that just ended: it writes one statement per studio that earned something (and catches up any of the last 12 months that has none). A statement is never rewritten; only a later refund or chargeback lowers it (see "Refunds and chargebacks"). Admin → Payouts → Settle last month runs the same thing at once.
- For each studio it adds up the unpaid balance: all statements (after refunds) minus all payouts and early payout fees. When the balance reaches the minimum payout and the studio has a payout method, it creates a pending payout for the whole balance. A smaller balance carries over to the next month.
- Finance staff open Admin → Payouts, open a payout to see the breakdown (coin unlocks, VIP pool, carried over) and where to send it, send the money with the studio's provider, then press Approve (or Approve all after paying them all). The payout is marked paid. Hold payout keeps a payout back with a reason the studio sees.
Refunds and chargebacks
Money that goes back to the buyer never stays in a studio's earnings. This applies to a refund in Admin → Transactions, and by itself to a refund by Apple or Google (RevenueCat), a refund in the Stripe Dashboard or a card chargeback (Stripe), and a Razorpay refund or dispute. For a PayPal or Flutterwave refund or chargeback, record it in Admin → Transactions → Refund with Money already returned ticked.
- Coin packs: the refunded coins still in the wallet are removed; if you choose to let the viewer keep them, they become bonus coins, which earn studios nothing. Refunded coins the viewer already spent are taken back from the unlocks they paid for (oldest first after the purchase), so those unlocks no longer earn the studio anything. A partial refund takes back the refunded share of the coins.
- VIP: VIP ends and the payment leaves the VIP pool.
- If that month was already settled, the studio's statement is lowered by what it earned from that money; Studio → Earnings shows it as "Refunds and chargebacks after settlement". If the studio was already paid, its balance goes below zero and the next payout waits until new earnings cover it.
- A chargeback counts as a refund as soon as it is opened, even if you win the dispute later; add the coins back in Admin → Users if you want.
Payout methods
- Studios choose Wise, PayPal or Bank transfer, a currency and their account (email, IBAN or account number), plus an optional legal name and tax ID, in Studio → Settings → Payout method (also possible while the application waits).
- The account and the tax ID are stored encrypted (AES-256-GCM) with a key made from
MEDIA_SIGNING_SECRET. Keep that value when you move servers; with a new one, saved payout details can't be read and studios enter them again. - The studio and most staff see only the last 4 characters. Super admins and finance staff see the full account in the payout detail, to send the money.
- To pay automatically instead (for example with the Wise or PayPal Payouts API), call your provider in
reelsaga_worker/src/jobs/payouts.ts, which runs after Approve.
Early payouts
When early payouts are on, a studio can ask for its money before the month is settled: Studio → Payouts → Request early payout. The available amount is the unpaid balance plus what the studio earned since its last statement. The request must be at least the minimum payout; the early payout fee is taken from the balance on top of the amount (with $60 available and a $5 fee, the most a studio can ask for is $55). It arrives in Admin → Payouts like any payout.
What studios see
- Studio → Earnings: a month's statement (or, for the current month, a live estimate) with coin unlocks, VIP pool, any refunds after settlement, the share % and the studio's share.
- Studio → Payouts: the available balance, the next scheduled payout, the payout history with status and hold reasons, and the early payout button.
- The Studio dashboard shows this month's earnings and a pending payout.
23. Every key, explained
"Where" says which .env file it goes in: Docker = deploy/.env (shared by website and worker in the Docker stack), website = reelsaga_web_nextjs/.env (without Docker), worker = reelsaga_worker/.env (without Docker), app = reelsaga_mobile_flutter/.env. Admin → Setup shows the same list with the live status of each key.
| Key | Required | Where | What it does |
|---|---|---|---|
| Database | |||
DATABASE_URL | Yes | website, worker | PostgreSQL connection string |
POSTGRES_DB | Yes | Docker | Database the Docker stack creates |
POSTGRES_USER | Yes | Docker | Database user for the Docker stack |
POSTGRES_PASSWORD | Yes | Docker | Database password for the Docker stack |
| App | |||
APP_URL | Yes | website, Docker | Public URL of the web app (links in emails, signed media) |
NEXT_PUBLIC_APP_NAME | — | website, Docker | Name shown in the web app |
NEXT_PUBLIC_IOS_APP_URL | — | website, Docker | App Store link for the website's Get the app buttons |
NEXT_PUBLIC_ANDROID_APP_URL | — | website, Docker | Google Play link for the website's Get the app buttons |
WEB_PORT | — | Docker | Host port the web container listens on |
| Storage | |||
MINIO_PORT | — | Docker | Host port of the built-in MinIO storage API (default 9000) |
MINIO_CONSOLE_PORT | — | Docker | Host port of the MinIO web console (default 9001) |
| App | |||
CORS_ORIGINS | — | website, Docker | Browser apps allowed to call /api/v1 |
PUSH_TOPIC_PREFIX | — | website, Docker, app | FCM topic prefix (<prefix>all, <prefix><language>); same as the server's |
| Firebase sign-in | |||
NEXT_PUBLIC_FIREBASE_API_KEY | Yes | website, Docker | Firebase web config |
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN | Yes | website, Docker | Firebase web config |
NEXT_PUBLIC_FIREBASE_PROJECT_ID | Yes | website, Docker | Firebase web config |
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET | — | website, Docker | Firebase web config |
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID | — | website, Docker | Firebase web config |
NEXT_PUBLIC_FIREBASE_APP_ID | Yes | website, Docker | Firebase web config |
NEXT_PUBLIC_FIREBASE_ADMIN_APP_ID | — | website, Docker | Optional second web app for the admin panel |
ADMIN_REQUIRE_MFA | — | website, Docker | Require two-step sign-in for staff |
| Firebase Admin + push | |||
FIREBASE_PROJECT_ID | Yes | website, worker, Docker, app | Firebase project id |
FIREBASE_CLIENT_EMAIL | Yes | website, worker, Docker | Service account e-mail |
FIREBASE_PRIVATE_KEY | Yes | website, worker, Docker | Service account private key |
| Secrets | |||
MEDIA_SIGNING_SECRET | Yes | website, Docker | Signs media URLs (openssl rand -hex 24) |
REVENUECAT_WEBHOOK_SECRET | — | website, Docker | Authorization header RevenueCat sends to the webhook |
| Payments | |||
REVENUECAT_API_KEY | — | website, Docker | RevenueCat secret API key (in-app purchases) |
STRIPE_SECRET_KEY | — | website, Docker | Stripe secret key (web checkout) |
STRIPE_WEBHOOK_SECRET | — | website, Docker | Stripe webhook signing secret |
PAYPAL_CLIENT_ID | — | website, Docker | PayPal REST app client id (web checkout) |
PAYPAL_CLIENT_SECRET | — | website, Docker | PayPal REST app secret |
PAYPAL_MODE | — | website, Docker | "live" for real money, anything else = sandbox |
RAZORPAY_KEY_ID | — | website, Docker | Razorpay key id (web checkout, India) |
RAZORPAY_KEY_SECRET | — | website, Docker | Razorpay key secret |
RAZORPAY_WEBHOOK_SECRET | — | website, Docker | Razorpay webhook secret (payment_link.paid) |
FLUTTERWAVE_SECRET_KEY | — | website, Docker | Flutterwave secret key (web checkout, Africa) |
FLUTTERWAVE_WEBHOOK_HASH | — | website, Docker | Flutterwave webhook secret hash (verif-hash header) |
DEMO_PURCHASES | — | website, Docker | "true" grants purchases without payment while no payment key is set (testing only) |
REVENUECAT_ALLOW_SANDBOX | — | website, Docker | "true" also credits App Store / Google Play test purchases (sandbox). Off in production: test purchases are ignored |
| Ads | |||
AD_REWARDS_MODE | — | website, Docker | "ssv" (default): rewarded ads pay only after AdMob server-side verification; "demo": testing only |
ADMOB_REWARDED_AD_UNITS | — | website, Docker | Your rewarded ad unit ids, comma-separated (the app's ADMOB_ANDROID_REWARDED and ADMOB_IOS_REWARDED): only their SSV callbacks pay |
ADMOB_PUBLISHER_ID | — | website, Docker | AdMob publisher id (pub-…): ad revenue in the admin |
ADMOB_CLIENT_ID | — | website, Docker | Google OAuth client id for the AdMob Reporting API |
ADMOB_CLIENT_SECRET | — | website, Docker | Google OAuth client secret for the AdMob Reporting API |
ADMOB_REFRESH_TOKEN | — | website, Docker | OAuth refresh token with the admob.readonly scope |
| Storage | |||
S3_ENDPOINT | — | website, worker | S3-compatible endpoint (empty for AWS S3) |
S3_REGION | — | website, worker, Docker | Bucket region |
S3_BUCKET | Yes | website, worker, Docker | Bucket for video, posters and subtitles |
S3_ACCESS_KEY_ID | Yes | website, worker, Docker | Storage access key |
S3_SECRET_ACCESS_KEY | Yes | website, worker, Docker | Storage secret key |
S3_PUBLIC_ENDPOINT | — | website, Docker | Storage address phones and browsers use (required with the Docker MinIO) |
S3_PUBLIC_URL | — | website, Docker | Public bucket / CDN base URL (leave empty for a private bucket) |
| Sign in with Apple | |||
APPLE_TEAM_ID | — | website, Docker | Token revocation at account deletion |
APPLE_KEY_ID | — | website, Docker | Token revocation at account deletion |
APPLE_CLIENT_ID | — | website, Docker | iOS bundle id |
APPLE_PRIVATE_KEY_PATH | — | website | Path to the .p8 key (or use APPLE_PRIVATE_KEY) |
APPLE_PRIVATE_KEY | — | website, Docker | The .p8 key contents |
| AI | |||
SUBTITLE_PROVIDER | — | website, worker, Docker | "openai" or "gemini" for AI subtitles |
OPENAI_API_KEY | — | website, worker, Docker | OpenAI key (subtitles, posters, SEO, translation) |
GEMINI_API_KEY | — | website, worker, Docker | Gemini key (subtitles, SEO, translation) |
| Worker | |||
WORKER_CONCURRENCY | — | worker | Parallel transcodes |
SMTP_HOST | — | website, Docker | SMTP server; empty = console mode |
SMTP_PORT | — | website, Docker | 587 (STARTTLS) or 465 (TLS) |
SMTP_USER | — | website, Docker | SMTP user |
SMTP_PASS | — | website, Docker | SMTP password |
SMTP_SECURE | — | website, Docker | "true" for port 465 |
| Mobile app | |||
API_BASE_URL | Yes | app | Your server; the app calls <url>/api/v1 |
APP_NAME | — | app | App name in the UI |
APP_STORE_ID | — | app | Rate-us and share links |
REVENUECAT_IOS_KEY | — | app | RevenueCat public iOS SDK key |
REVENUECAT_ANDROID_KEY | — | app | RevenueCat public Android SDK key |
USE_REVENUE_CAT | — | app | Use store purchases (false = demo) |
| Ads | |||
ADMOB_ANDROID_APP_ID | — | app | AdMob Android app id (Google's sample id when empty) |
ADMOB_ANDROID_REWARDED | — | app | AdMob Android rewarded unit (empty = no rewarded ads; a demo countdown with AD_REWARDS_MODE=demo) |
ADMOB_ANDROID_INTERSTITIAL | — | app | AdMob Android interstitial unit (empty = off) |
ADMOB_ANDROID_APP_OPEN | — | app | AdMob Android app-open unit (empty = off) |
ADMOB_IOS_REWARDED | — | app | AdMob iOS rewarded unit (empty = no rewarded ads; a demo countdown with AD_REWARDS_MODE=demo) |
ADMOB_IOS_INTERSTITIAL | — | app | AdMob iOS interstitial unit (empty = off) |
ADMOB_IOS_APP_OPEN | — | app | AdMob iOS app-open unit (empty = off) |
| Mobile app | |||
LINK_PRIVACY | — | app | Privacy policy URL |
LINK_TERMS | — | app | Terms URL |
LINK_SUPPORT | — | app | Support URL |
LINK_DELETE_ACCOUNT | — | app | Account deletion URL |
SUPPORT_EMAIL | — | app | Support e-mail |
LINK_TELEGRAM | — | app | Telegram link |
LINK_WHATSAPP | — | app | WhatsApp link |
SHOW_TELEGRAM | — | app | Show the Telegram link |
SHOW_WHATSAPP | — | app | Show the WhatsApp link |
FIREBASE_MESSAGING_SENDER_ID | Yes | app | Firebase config |
FIREBASE_STORAGE_BUCKET | — | app | Firebase config |
FIREBASE_WEB_API_KEY | — | app | Firebase web config (Flutter web) |
FIREBASE_WEB_APP_ID | — | app | Firebase web config (Flutter web) |
FIREBASE_WEB_AUTH_DOMAIN | — | app | Firebase web config (Flutter web) |
FIREBASE_ANDROID_API_KEY | Yes | app | Firebase Android config |
FIREBASE_ANDROID_APP_ID | Yes | app | Firebase Android config |
FIREBASE_IOS_API_KEY | Yes | app | Firebase iOS config |
FIREBASE_IOS_APP_ID | Yes | app | Firebase iOS config |
FIREBASE_IOS_CLIENT_ID | — | app | Google sign-in on iOS |
FIREBASE_IOS_BUNDLE_ID | — | app | iOS bundle id |
24. File structure
Mobile app (reelsaga_mobile_flutter/lib)
main.dart starts Firebase, loads .env, runs the app (short on purpose)
app.dart theme, language, router and app-wide listeners
components/ shared widgets (buttons, sheets, cards, tab bar) — names start with cc_
core/
constants/app_env.dart every .env value the app reads
router/ all routes (go_router)
theme/ colours, text styles, spacing
providers/ app-wide state (Riverpod): session, settings, push, wallet…
services/api/ the typed API client for your server (/api/v1) and its offline cache
services/ads/ AdMob rewarded / interstitial / app-open
services/purchases/ RevenueCat purchases (or demo mode)
services/firebase/ sign-in, notifications, analytics, remote config
domain/models/ data models parsed from the API
features/ one folder per area, each with pages/ widgets/ providers/
home discover watch unlock store subscription wallet rewards
library inbox profile account launch
l10n/ translations (parts/*.arb → app_en.arb, app_es.arb)
Lists and grids use the lazy .builder constructors, and state flows through Riverpod providers rather than long chains of widget parameters.
Server (reelsaga_web_nextjs/src)
app/(site)/ the public website (home, browse, series, watch, coins, account…)
app/studio/ Creator Studio pages
app/admin/ Admin panel pages
app/api/v1/[...path]/ the single API entry point; routes live in lib/server/handlers/
components/site|panel|ui website components, admin/studio components, base UI (shadcn)
lib/server/handlers/ every API route, by area: catalog, wallet, rewards, me, library, studio, admin… (chapter 26)
lib/server/ auth, router, payments (store.ts, gateways.ts), wallet, storage (media.ts), email, AI,
settings, setup check, creator earnings (creator-earnings.ts), choose-the-ending paths
(branches.ts), rewarded-ad verification (ad-rewards.ts), encryption of payout details
lib/api/schemas/ request validation (Zod)
database/prisma_client/ database schema (schema.prisma) and migrations (chapter 27)
database/seed/ sample data and the sample clip
scripts/ doctor, first-run, admin:create, seed:sales
tests/ API tests (Vitest)
Worker (reelsaga_worker/src)
index.ts job queue (pg-boss on your PostgreSQL)
jobs/transcode.ts uploaded video → HLS 1080p/720p/480p + an MP4 of each for downloads, poster, preview (ffmpeg)
jobs/subtitles.ts AI subtitles
jobs/push.ts push campaigns
jobs/release.ts scheduled episode releases (every minute)
jobs/earnings.ts monthly creator statements and payouts (1st of the month, chapter 22)
jobs/payouts.ts marks an approved payout paid (add your payout provider here)
ffmpeg.ts ffmpeg and ffprobe read local files only (protocol whitelist on every input)
jobs/revenue.ts, purge.ts series revenue for the admin lists (hourly), deleting accounts after the 30-day grace (daily)
To add your own API route or background job, follow chapter 25.
25. Extend it: a new API route and a new worker job
Two worked examples, each a complete change you can copy. They were tested on a fresh copy of this download.
Example 1: a new API route
Goal: GET /api/v1/creators/top, the studios with the most followers, for a "Top studios" list. Every API route is registered with route(method, path, handler) in a file under reelsaga_web_nextjs/src/lib/server/handlers/; the single entry point src/app/api/v1/[...path]/route.ts sends each request to the matching handler.
- Create
reelsaga_web_nextjs/src/lib/server/handlers/creators.ts:import { z } from "zod"; import { prisma } from "@/database/prisma_client/database"; import { json, parseQuery } from "@/lib/server/http"; import { route } from "@/lib/server/router"; const topQuery = z.object({ limit: z.coerce.number().int().min(1).max(50).default(10) }); /** The approved studios with the most followers. */ route("GET", "/creators/top", async ({ url }) => { const { limit } = parseQuery(url, topQuery); const rows = await prisma.creator.findMany({ where: { status: "approved" }, orderBy: { followers: "desc" }, take: limit, select: { id: true, name: true, followers: true, _count: { select: { series: true } } } }); return json({ items: rows.map((c) => ({ id: c.id, name: c.name, followers: c.followers, seriesCount: c._count.series })) }); }); - Register the file: add one line to
reelsaga_web_nextjs/src/lib/server/api.ts, next to the other handler imports:import "@/lib/server/handlers/creators"; - Need a signed-in user? Take
authfrom the handler arguments and callawait auth.user()(401 when signed out). For staff only:await auth.staff()for reads,await auth.staff(["finance"])for writes. For a studio's own data:const { creatorId } = await auth.creator(). Bodies are checked with Zod:const body = await parseBody(req, schema)answers 422 with the field errors when they don't match. - Add a test,
reelsaga_web_nextjs/src/tests/creators-top.test.ts:
Run it with a PostgreSQL database for tests (the tests make their own schema in it and delete it afterwards):import { describe, expect, it } from "vitest"; import { call } from "@/tests/api"; describe("top studios", () => { it("lists approved studios, most followers first", async () => { const r = await call<{ items: { name: string; followers: number }[] }>("GET", "/creators/top?limit=3"); expect(r.status).toBe(200); expect(r.data.items.length).toBeGreaterThan(0); const f = r.data.items.map((c) => c.followers); expect(f).toEqual([...f].sort((a, b) => b - a)); expect((await call("GET", "/creators/top?limit=500")).status).toBe(422); }); });cd reelsaga_web_nextjs TEST_DATABASE_URL="postgresql://user:password@localhost:5432/reelsaga_test" pnpm vitest run src/tests/creators-top.test.ts - Try it:
curl https://your-domain.com/api/v1/creators/top?limit=5. In the Flutter app, add a method next to the others inlib/core/services/api/reelsaga_api.dart.
src/database/prisma_client/schema.prisma, then run pnpm prisma:migrate:dev --name your_change in reelsaga_web_nextjs. It writes a migration under src/database/prisma_client/migrations/, which the Docker stack applies on its next start.Example 2: a new worker job
Goal: every night, delete notifications that viewers read more than 90 days ago. Background work runs in reelsaga_worker on a job queue (pg-boss) stored in your PostgreSQL database: a job can run on a schedule, or the website can send one with enqueue(name, data) from src/lib/server/jobs.ts.
- Create
reelsaga_worker/src/jobs/cleanup.ts:import { query } from "../db.ts"; const DELETE_READ = `DELETE FROM "notifications" WHERE "read" AND "created_at" < now() - make_interval(days => $1) RETURNING "id"`; /** Deletes notifications that were read more than `days` days ago; returns how many. */ export async function deleteOldNotifications(days = 90): Promise<number> { const rows = await query<{ id: string }>(DELETE_READ, [days]); return rows.length; } - In
reelsaga_worker/src/index.ts: import it, add the queue name toQUEUES, and register the job and its schedule next to the others insidemain():import { deleteOldNotifications } from "./jobs/cleanup.ts"; const QUEUES = [ // …the existing names… "delete-old-notifications" ] as const; // inside main(), after the other boss.work(...) calls: await boss.work("delete-old-notifications", async () => { const n = await deleteOldNotifications(); if (n) console.log(`[worker] deleted ${n} old notification(s)`); }); await boss.schedule("delete-old-notifications", "40 3 * * *"); // 03:40 UTC every day - Run it once by hand to check it, from
reelsaga_workerwith its.env(DATABASE_URL) in place:npx tsx --env-file=.env -e 'import("./src/jobs/cleanup.ts").then(async (m) => { console.log(await m.deleteOldNotifications()); process.exit(0); })' - Rebuild the worker:
docker compose up -d --build worker. The log shows the new queue in[worker] ready: ….
await enqueue("my-job", { id }) (from @/lib/server/jobs), and in the worker register boss.work<{ id: string }>("my-job", async (jobs) => { for (const j of jobs) await myJob(j.data); }).26. API reference (/api/v1)
Every route the server has (222 in total), made from the route files when this download was built. The mobile app and the website use the same API. Send JSON; answers are JSON. Signed-in calls send the Firebase ID token as Authorization: Bearer <token> (the app does this) or the website's session cookie. Errors look like {"error":{"code":"…","message":"…","fields":{…}}} with the matching HTTP status (401 signed out, 403 not allowed, 404 not found, 409 conflict, 422 invalid input, 402 not enough coins).
| Auth | Meaning |
|---|---|
| No | Public. |
| Optional | Public; a signed-in viewer gets their own state (unlocks, votes, progress) too. |
| Signed in | Any signed-in account, guests included unless the description says otherwise. |
| Creator (approved studio) | The owner of an approved studio; only their own series and money. |
| Staff (any role) | Any admin role, including the read-only demo admin. |
| Staff: … or super admin | Writes allowed for the listed roles and super admins; other staff get 403. |
| Signed by the provider | Webhooks and the AdMob callback: no user, but the provider's signature or secret is checked. |
| Method | Path | Auth | What it does |
|---|---|---|---|
| System and sign-in | |||
GET | /api/v1/health | No | Health check: the server is up and the database answers |
GET | /api/v1/ads/ssv | Signed by the provider | AdMob server-side verification callback (set it on every rewarded ad unit in AdMob) |
GET | /api/v1/config | No | The public app config: version rules, maintenance, ad, coin and check-in rules, the download limit and languages |
POST | /api/v1/auth/session | No | Exchange a Firebase ID token for the website's session cookie (14 days) |
POST | /api/v1/auth/demo-admin | No | Live demo only: sign in as the read-only demo admin (404 unless DEMO_ADMIN_PASSWORD is set) |
POST | /api/v1/auth/demo-studio | No | Live demo only: sign in to the demo studio (404 unless DEMO_ADMIN_PASSWORD is set) |
DELETE | /api/v1/auth/session | No | Sign out of the website (clears the session cookie) |
GET | /api/v1/media/:a/:b/:c | Signed link (expires) | Signed media |
GET | /api/v1/media/:a/:b/:c/:d | Signed link (expires) | Signed media |
GET | /api/v1/media/:a/:b/:c/:d/:e | Signed link (expires) | Signed media |
| Catalogue, player and comments | |||
GET | /api/v1/home | Optional | The home screen: live banners, genres and every enabled rail with its series |
GET | /api/v1/feed | Optional | The swipe feed, one card per series (For you, Following or Interactive tab), paged by cursor |
GET | /api/v1/series/:id | Optional | A series page: details, the next scheduled episode and, when signed in, the viewer's list, reminder, progress and access |
GET | /api/v1/series/:id/episodes | Optional | The episode grid with each episode's lock state for this viewer, in ranges of 30 |
GET | /api/v1/series/:id/related | No | Up to 6 series from the same genres, most viewed first |
GET | /api/v1/episodes/:id/play | Optional | Play an episode: a signed HLS link, subtitles and the next episode; a locked episode answers 402 with the unlock options |
PUT | /api/v1/episodes/:id/progress | Signed in | Save where the viewer is in an episode; finishing it counts one view per viewer |
PUT | /api/v1/episodes/:id/like | Signed in | Like an episode (once per viewer) |
DELETE | /api/v1/episodes/:id/like | Signed in | Take back the viewer's like of an episode |
GET | /api/v1/episodes/:id/comments | Optional | An episode's visible comments, newest first, with whether the viewer liked each one |
POST | /api/v1/episodes/:id/comments | Signed in | Post a comment (signed-in accounts, not guests) |
PUT | /api/v1/comments/:id/like | Signed in | One like per viewer: liking twice or unliking a comment you never liked changes nothing |
DELETE | /api/v1/comments/:id/like | Signed in | One like per viewer: liking twice or unliking a comment you never liked changes nothing |
GET | /api/v1/episodes/:id/share | No | A share link, title and image for an episode |
POST | /api/v1/reports | Signed in | Report an episode, comment, user or series to the moderators |
GET | /api/v1/genres | No | The active genres with their series counts |
GET | /api/v1/genres/:slug/series | No | A genre's series (popular, newest or top rated), paged by cursor |
GET | /api/v1/rankings | No | The top 20 series: most watched, trending, new or top rated |
GET | /api/v1/search | No | Search series by title, synopsis, tag or studio, with genre, status and feature filters |
GET | /api/v1/search/suggest | No | Type-ahead suggestions: matching series titles and tags |
GET | /api/v1/search/trending | No | Suggested searches: the tags and titles of this week's most played series |
| Library, history, reminders, notifications, help | |||
GET | /api/v1/library/watchlist | Signed in | The viewer's list (My list), sorted by date added, title or last update |
PUT | /api/v1/library/watchlist/:seriesId | Signed in | Add a series to the viewer's list |
DELETE | /api/v1/library/watchlist/:seriesId | Signed in | Remove a series from the viewer's list |
POST | /api/v1/library/watchlist/remove | Signed in | Remove several series from the viewer's list at once |
GET | /api/v1/library/continue | Signed in | Continue watching: up to 30 unfinished series with the episode and position to resume |
GET | /api/v1/library/downloads | Signed in | The viewer's downloaded episodes and the download limit (none for VIP) |
POST | /api/v1/library/downloads | Signed in | Download an episode the viewer can watch for offline viewing: a signed MP4 link, within the free download limit |
DELETE | /api/v1/library/downloads/:episodeId | Signed in | Remove a download record |
GET | /api/v1/history | Signed in | Watch history, newest first, paged by cursor |
DELETE | /api/v1/history | Signed in | Clear the viewer's watch history |
DELETE | /api/v1/history/:seriesId | Signed in | Remove one series from the watch history |
GET | /api/v1/reminders | Signed in | The series the viewer asked to be reminded about, with their next episode |
PUT | /api/v1/series/:id/reminder | Signed in | Turn on new-episode reminders for a series |
DELETE | /api/v1/series/:id/reminder | Signed in | Turn off new-episode reminders for a series |
GET | /api/v1/notifications | Signed in | The viewer's notifications by category, with the unread count |
POST | /api/v1/notifications/read | Signed in | Mark notifications read (by id, or all) |
GET | /api/v1/pages/:slug | No | A published CMS page such as the terms or privacy policy; ?lang= returns its translation when one exists |
GET | /api/v1/faq | No | The help centre questions and answers by category |
POST | /api/v1/support/messages | Optional | Send a message to support (guests too); staff answer it in Admin, Support |
POST | /api/v1/support/attachments | Signed in | A short-lived upload link for a screenshot to attach to a support message |
| Account | |||
GET | /api/v1/me | Signed in | Signing in again cancels a scheduled deletion: every client calls GET /me after sign-in |
POST | /api/v1/me/avatar | Signed in | A short-lived upload link for a profile photo; then PATCH /me with { avatarUrl: fileUrl } |
PATCH | /api/v1/me | Signed in | Update the profile: name, username, photo, genres, preferences and onboarding |
GET | /api/v1/me/preferences | Signed in | The viewer's app preferences (playback, downloads, notifications, language) |
PATCH | /api/v1/me/preferences | Signed in | Change app preferences; 1080p downloads need VIP |
POST | /api/v1/me/devices | Signed in | Register a device for push notifications |
POST | /api/v1/me/merge/preview | Signed in | Before a guest signs in to an existing account: what the guest and the account each hold |
POST | /api/v1/me/link | Signed in | Same as POST /me/merge/preview (the app's name for it) |
POST | /api/v1/me/merge | Signed in | Move a guest's coins, list, history and unlocks into the signed-in account (both, account only, or phone only) |
GET | /api/v1/me/export | Signed in | A signed link to download all of the viewer's data as JSON |
DELETE | /api/v1/me | Signed in | Real accounts are scheduled for deletion in 30 days; anonymous guests are deleted now, Firebase user included |
POST | /api/v1/me/apple/revoke | Signed in | Sign in with Apple revocation at account deletion (App Store rule) |
| Rewards and referrals | |||
GET | /api/v1/rewards | Signed in | The rewards page: the streak, the 7-day check-in week, the tasks and the wallet balance |
POST | /api/v1/rewards/check-in | Signed in | Check in for today and collect the day's bonus coins (plus the VIP daily bonus for VIP members) |
POST | /api/v1/rewards/streak/restore | Signed in | Restore a broken streak with coins or a rewarded ad, when the admin allows it |
POST | /api/v1/rewards/tasks/:code/claim | Signed in | Collect a finished task's coins (once per day or once ever, as the task says) |
POST | /api/v1/rewards/ad | Signed in | Collect the bonus coins for a rewarded ad that AdMob verified (pending while the callback is on its way) |
GET | /api/v1/referrals | Signed in | The viewer's invite link, code and invited friends; pays any referral that now qualifies |
POST | /api/v1/referrals/redeem | Signed in | A new account accepts a friend's invite |
| Wallet, unlocks, purchases and webhooks | |||
GET | /api/v1/episodes/:id/branch | Optional | A choice episode's prompt, the two paths, the vote split and, for the viewer, their vote and whether the other path can be bought |
POST | /api/v1/episodes/:id/branch/vote | Signed in | Choose a path (once per viewer); returns the episode that plays next |
POST | /api/v1/episodes/:id/branch/unlock-other | Signed in | "Watch the other path": one price unlocks every paid episode of the path the viewer did not pick |
POST | /api/v1/episodes/:id/unlock | Signed in | Unlock an episode with coins, a free episode pass or a rewarded ad (one request key per unlock) |
GET | /api/v1/series/:id/unlock-all | Signed in | The bundle price to unlock every remaining locked episode of a series |
POST | /api/v1/series/:id/unlock-all | Signed in | Unlocks every locked episode at the bundle discount; the price is split across the unlocks so studios earn from it |
GET | /api/v1/wallet | Signed in | The viewer's coin balance (paid and bonus), passes, expiring bonus and the last 3 transactions |
GET | /api/v1/wallet/transactions | Signed in | Coin history by type (top-ups, unlocks, rewards), paged by cursor |
GET | /api/v1/wallet/transactions/:id | Signed in | One of the viewer's coin transactions |
GET | /api/v1/wallet/unlocks | Signed in | The series the viewer unlocked episodes of, with episode and coin totals |
GET | /api/v1/store/coin-packs | Optional | Active coin packs (the website lists only packs set to show on web checkout) |
GET | /api/v1/store/vip-plans | No | Active VIP plans and the VIP benefits list |
POST | /api/v1/purchases/sync | Signed in | Asks RevenueCat for the subscriber and applies anything not credited yet |
POST | /api/v1/purchases/demo | Signed in | Demo purchases mode only: grants exactly what the store webhook would, without a payment |
POST | /api/v1/checkout | Signed in | Start a web checkout with Stripe, PayPal, Razorpay or Flutterwave; returns where to send the buyer |
POST | /api/v1/checkout/confirm | Signed in | PayPal, Razorpay and Flutterwave hand the buyer back with a query; this verifies it with the gateway and credits once |
GET | /api/v1/vip | Signed in | The viewer's VIP status and VIP billing history |
POST | /api/v1/vip/portal | Signed in | A Stripe billing portal link to manage a VIP subscription bought on the website |
POST | /api/v1/webhooks/revenuecat | Signed by the provider | RevenueCat purchase events (shared secret in the Authorization header): credits coins and VIP from the app stores |
POST | /api/v1/webhooks/razorpay | Signed by the provider | Razorpay payment events, checked with the webhook signature |
POST | /api/v1/webhooks/flutterwave | Signed by the provider | Flutterwave payment events, checked with the verif-hash secret |
POST | /api/v1/webhooks/stripe | Signed by the provider | Stripe events, checked with the signing secret: paid checkouts, renewals, failed payments, cancellations and refunds |
| Creator Studio | |||
POST | /api/v1/creator/application | Signed in | Apply to become a creator studio (signed-in accounts, not guests); staff review it in Admin, Creators |
GET | /api/v1/creator/application | Signed in | The status of the viewer's creator application (none, pending, approved, rejected, suspended) |
GET | /api/v1/studio/dashboard | Creator (approved studio) | The studio dashboard: this month's earnings and 30-day views, unlocks and followers against the period before, plus to-dos |
GET | /api/v1/studio/series | Creator (approved studio) | The studio's own series, last updated first |
GET | /api/v1/studio/series/:id | Creator (approved studio) | One of the studio's series with its genres, the studio's revenue share and coins per $1 |
POST | /api/v1/studio/series | Creator (approved studio) | Create a draft series |
PATCH | /api/v1/studio/series/:id | Creator (approved studio) | Edit a series: title, synopsis, genres, tags, schedule, language; submit: true sends it for review |
DELETE | /api/v1/studio/series/:id | Creator (approved studio) | Delete a draft or in-review series (a published one can only be hidden by an admin) |
POST | /api/v1/studio/uploads | Creator (approved studio) | A short-lived upload link for an episode video, poster, subtitle file or (for applicants) a sample clip |
POST | /api/v1/studio/uploads/:id/complete | Creator (approved studio) | Finish an upload: a video becomes an episode and starts transcoding; a poster or subtitle file is applied |
GET | /api/v1/studio/series/:id/episodes | Creator (approved studio) | A series' episodes with video status (and why a transcode failed), price, release and interactive choice |
PUT | /api/v1/studio/series/:id/episodes/order | Creator (approved studio) | Save a new episode order |
PATCH | /api/v1/studio/episodes/:id | Creator (approved studio) | Edit an episode: title, price, status, release time (publishing needs a finished video) |
PUT | /api/v1/studio/series/:id/pricing | Creator (approved studio) | Set a series' free episodes, default price, bundle discount and per-episode prices in coins |
GET | /api/v1/studio/series/:id/subtitles | Creator (approved studio) | The series' subtitle languages with their status and episode coverage |
POST | /api/v1/studio/series/:id/subtitles/generate | Creator (approved studio) | Queue AI subtitles for these languages (needs an AI provider key) |
GET | /api/v1/studio/episodes/:id/subtitles/:lang | Creator (approved studio) | An episode's subtitle cues in one language, for the editor |
PUT | /api/v1/studio/episodes/:id/subtitles/:lang | Creator (approved studio) | Save edited subtitle cues for an episode |
POST | /api/v1/studio/series/:id/subtitles/:lang/approve | Creator (approved studio) | Approve a reviewed AI subtitle language so viewers see it |
GET | /api/v1/studio/episodes/:id/branch | Creator (approved studio) | An episode's interactive choice (prompt, paths, rejoin, price) with its vote counts |
PUT | /api/v1/studio/episodes/:id/branch | Creator (approved studio) | Create or update an episode's interactive choice: prompt, timing, the two paths, rejoin and other-path price |
GET | /api/v1/studio/analytics | Creator (approved studio) | Studio analytics for a period: views, viewers, paywall conversion, reminders, episode retention and traffic sources |
GET | /api/v1/studio/earnings | Creator (approved studio) | A month's earnings: the settled statement when the settlement job has written one, otherwise a live estimate with the same maths (docs → Creator earnings and payouts) |
GET | /api/v1/studio/payouts | Creator (approved studio) | Payout history, the available and settled balance, the minimum, early payout rules and the next scheduled payout |
POST | /api/v1/studio/payouts/early | Creator (approved studio) | Takes the available balance before the month is settled, minus the early payout fee |
PUT | /api/v1/creator/payout-method | Signed in | Payout destination ("Set up payouts", "Change method") |
GET | /api/v1/studio/ai | Creator (approved studio) | Which AI tools are set up on this server (subtitles, text, images) |
POST | /api/v1/studio/series/:id/poster/generate | Creator (approved studio) | Generate a poster for a series with AI (needs an image provider key) |
GET | /api/v1/studio/profile | Creator (approved studio) | Studio settings: public studio profile shown on series pages and used for contact |
PATCH | /api/v1/studio/profile | Creator (approved studio) | Update the studio's public profile and contact details |
| Admin | |||
GET | /api/v1/admin/dashboard | Staff (any role) | The admin dashboard for a period: revenue, users, daily actives, VIP, coins sold, refund rate, open work and top series |
GET | /api/v1/admin/series | Staff (any role) | Every series with search and filters (status, genre, studio), paged |
GET | /api/v1/admin/series/:id | Staff (any role) | One series with its studio, genres and poster |
POST | /api/v1/admin/series | Staff: content manager or super admin | Create a series as the platform (house content) |
PATCH | /api/v1/admin/series/:id | Staff: content manager or super admin | Edit any series: details, studio, status, genres, free episodes, price, VIP, interactive, slug, badges |
DELETE | /api/v1/admin/series/:id | Staff: content manager or super admin | Delete a series and its episodes (type the title to confirm) |
GET | /api/v1/admin/ai/status | Staff (any role) | Which optional AI features this server can run (drives the "add your key" states) |
POST | /api/v1/admin/ai/seo | Staff: content manager or super admin | SEO card: slug + meta description from the buyer's AI key (409 ai_not_configured without one) |
POST | /api/v1/admin/uploads | Staff: content manager or super admin | Poster replace and bulk upload: presigned PUT, then complete (same pipeline as the studio) |
POST | /api/v1/admin/uploads/:id/complete | Staff: content manager or super admin | Finish an admin upload: a video becomes an episode and starts transcoding; a poster is applied |
GET | /api/v1/admin/episodes | Staff (any role) | A series' episodes with search and status filter |
POST | /api/v1/admin/episodes | Staff: content manager or super admin | Add an episode to a series (optionally queue AI subtitles) |
PATCH | /api/v1/admin/episodes/:id | Staff: content manager or super admin | Edit an episode: title, number, price, status, release time |
DELETE | /api/v1/admin/episodes/:id | Staff: content manager or super admin | Delete an episode |
PUT | /api/v1/admin/series/:id/episodes/order | Staff: content manager or super admin | Save a new episode order for a series |
POST | /api/v1/admin/episodes/price | Staff: content manager or super admin | Set one coin price on many episodes at once |
GET | /api/v1/admin/genres | Staff (any role) | List genres |
POST | /api/v1/admin/genres | Staff: content manager or super admin | Create a genre |
PATCH | /api/v1/admin/genres/:id | Staff: content manager or super admin | Update a genre |
DELETE | /api/v1/admin/genres/:id | Staff: content manager or super admin | Delete a genre |
PUT | /api/v1/admin/genres/order | Staff: content manager or super admin | Save the order of genres |
GET | /api/v1/admin/tags/popular | Staff (any role) | The 30 most used tags with their series counts |
POST | /api/v1/admin/tags/merge | Staff: content manager or super admin | Merge several tags into one across every series |
GET | /api/v1/admin/banners | Staff (any role) | List banners |
POST | /api/v1/admin/banners | Staff: content manager or super admin | Create a banner |
PATCH | /api/v1/admin/banners/:id | Staff: content manager or super admin | Update a banner |
DELETE | /api/v1/admin/banners/:id | Staff: content manager or super admin | Delete a banner |
PUT | /api/v1/admin/banners/order | Staff: content manager or super admin | Save the order of banners |
GET | /api/v1/admin/rails | Staff (any role) | The home screen rails with how many series each shows |
PATCH | /api/v1/admin/rails/:id | Staff: content manager or super admin | Edit a home rail: its title, its series, on or off |
PUT | /api/v1/admin/rails/order | Staff: content manager or super admin | Save the order of home rails |
GET | /api/v1/admin/creators | Staff (any role) | Creator studios and applications by status, with search |
GET | /api/v1/admin/creators/:id | Staff (any role) | A studio or application: details, review checks, series and payout method (last 4 only) |
PATCH | /api/v1/admin/creators/:id/share | Staff: finance or super admin | A studio's revenue share % |
POST | /api/v1/admin/creators/:id/approve | Staff: content manager or super admin | Approve a creator application (or reinstate a studio) |
POST | /api/v1/admin/creators/:id/suspend | Staff: content manager or super admin | Suspend a studio |
POST | /api/v1/admin/creators/:id/reject | Staff: content manager or super admin | Reject a creator application with a reason (the applicant gets an email) |
PATCH | /api/v1/admin/creators/:id/checks | Staff: content manager or super admin | Review checks: identity, rights declaration, sample guidelines |
POST | /api/v1/admin/creators/invite | Staff: content manager or super admin | Invite a studio directly: creates an approved studio with the default revenue share |
GET | /api/v1/admin/users | Staff (any role) | Users with search and filters (plan, sign-in, status), paged, plus today's active count |
GET | /api/v1/admin/users/export | Staff (any role) | Download every user as CSV |
GET | /api/v1/admin/users/:id | Staff (any role) | One user: profile, coins, VIP, spend, unlocks, recent coin activity and reports |
POST | /api/v1/admin/users/:id/coins | Staff: support, finance or super admin | Add or take away a user's coins with a reason (logged in the audit log) |
POST | /api/v1/admin/users/:id/ban | Staff: moderator or super admin | Ban a user, for good or until a date, with a reason |
POST | /api/v1/admin/users/:id/unban | Staff: moderator or super admin | Lift a user's ban |
GET | /api/v1/admin/coin-packs | Staff (any role) | List coin packs |
POST | /api/v1/admin/coin-packs | Staff: finance or super admin | Create a coin pack |
PATCH | /api/v1/admin/coin-packs/:id | Staff: finance or super admin | Update a coin pack |
DELETE | /api/v1/admin/coin-packs/:id | Staff: finance or super admin | Delete a coin pack |
PUT | /api/v1/admin/coin-packs/order | Staff: finance or super admin | Save the order of coin packs |
GET | /api/v1/admin/vip-plans/summary | Staff (any role) | VIP numbers: active members, monthly recurring revenue by plan, trial-to-paid and monthly churn |
GET | /api/v1/admin/vip-plans | Staff (any role) | List vip plans |
POST | /api/v1/admin/vip-plans | Staff: finance or super admin | Create a vip plan |
PATCH | /api/v1/admin/vip-plans/:id | Staff: finance or super admin | Update a vip plan |
GET | /api/v1/admin/reward-tasks | Staff (any role) | The reward tasks with how often each was claimed in the last 7 days |
PATCH | /api/v1/admin/reward-tasks/:code | Staff: super admin | Edit a reward task: title, coins, goal, on or off |
GET | /api/v1/admin/settings/:group | Staff (any role) | One settings group (app, ads, coins, rewards, payments, downloads, ai...) with its defaults filled in |
PUT | /api/v1/admin/settings/:group | Staff: super admin (payments and coins: finance too) | Save a settings group; each value is type- and range-checked |
GET | /api/v1/admin/transactions | Staff (any role) | Purchases with search and filters (gateway, status, coins or VIP), paged |
GET | /api/v1/admin/transactions/export | Staff (any role) | Download every purchase as CSV |
GET | /api/v1/admin/transactions/:id | Staff (any role) | One purchase with its user and coin transaction |
POST | /api/v1/admin/transactions/:id/refund | Staff: finance or super admin | Refunds a paid purchase (full or partial) |
GET | /api/v1/admin/payouts | Staff (any role) | Creator payouts by month and status, with the totals to pay |
GET | /api/v1/admin/payouts/:id | Staff (any role) | One payout: the studio, the breakdown and where to send it (the full account for finance staff only) |
POST | /api/v1/admin/payouts/settle | Staff: finance or super admin | Writes the monthly statements and creates the payouts now (the worker does it on the 1st of each month) |
POST | /api/v1/admin/payouts/:id/approve | Staff: finance or super admin | After you sent the money: approve a pending or held payout; the worker marks it paid |
POST | /api/v1/admin/payouts/:id/hold | Staff: finance or super admin | Hold a pending payout with a reason the studio sees |
POST | /api/v1/admin/payouts/approve-all | Staff: finance or super admin | Approve every pending payout (send the money first); the worker marks them paid |
GET | /api/v1/admin/reports | Staff (any role) | Reports by status with their counts |
GET | /api/v1/admin/reports/:id | Staff (any role) | The report, every report on the same item grouped by reason, and what the item is (episode poster, owner) |
POST | /api/v1/admin/reports/:id/ai-review | Staff: moderator or super admin | AI second opinion on a report (no key → 409 ai_not_configured → "add your key") |
POST | /api/v1/admin/reports/:id/resolve | Staff: moderator or super admin | Resolve a report: dismiss, remove the content, ban the user, warn or keep it in review |
GET | /api/v1/admin/push | Staff (any role) | Push campaigns, automations and the last 30 days' reach |
POST | /api/v1/admin/push | Staff: content manager or super admin | Send or schedule a push campaign to everyone, a segment, a series' followers or a language topic |
GET | /api/v1/admin/push/audiences | Staff (any role) | Audience picker: how many people each audience reaches right now |
POST | /api/v1/admin/push/test | Staff: content manager or super admin | "Send test": the message goes to the signed-in staff member's own devices only |
PATCH | /api/v1/admin/push/automations | Staff: content manager or super admin | Turn the automatic pushes on or off: cliffhanger, streak at risk, vote results |
GET | /api/v1/admin/pages | Staff (any role) | The CMS pages with how many translations each has |
GET | /api/v1/admin/pages/:slug | Staff (any role) | One CMS page with its translations |
POST | /api/v1/admin/pages/:slug/translate | Staff: content manager or super admin | Translates the page into every app language except English (AI key required; 409 ai_not_configured without) |
PUT | /api/v1/admin/pages/:slug | Staff: content manager or super admin | Create or update a CMS page (Markdown) |
GET | /api/v1/admin/faq | Staff (any role) | List faqs |
POST | /api/v1/admin/faq | Staff: content manager or super admin | Create a faq |
PATCH | /api/v1/admin/faq/:id | Staff: content manager or super admin | Update a faq |
DELETE | /api/v1/admin/faq/:id | Staff: content manager or super admin | Delete a faq |
GET | /api/v1/admin/languages | Staff (any role) | Languages with their app-text and subtitle coverage and the AI settings |
POST | /api/v1/admin/languages | Staff: super admin | Add a language |
PATCH | /api/v1/admin/languages/:code | Staff: super admin | Edit a language: live, strings done, order (English always stays live) |
GET | /api/v1/admin/staff | Staff (any role) | Staff members and the roles with what each can do |
POST | /api/v1/admin/staff/invite | Staff: super admin | Creates (or finds) the Firebase user, gives them the role, and emails a 72-hour invite link |
POST | /api/v1/admin/staff/:id/resend | Staff: super admin | Send a staff invite again (a new 72-hour link; super admin only) |
PATCH | /api/v1/admin/staff/:id | Staff: super admin | Change a staff member's role or turn their access on or off (super admin only) |
DELETE | /api/v1/admin/staff/:id | Staff: super admin | Remove someone from the staff (super admin only) |
GET | /api/v1/admin/audit | Staff (any role) | The audit log of staff actions, filtered by person or item, paged |
| Admin: setup, ads, sign-in help | |||
GET | /api/v1/admin/setup | Staff (any role) | Setup check: which keys are set and whether each service (database, storage, Firebase, payments, email) answers |
POST | /api/v1/admin/setup/test-email | Staff: super admin | Sends a test email to the signed-in staff member (super admin; the demo admin is read-only) |
POST | /api/v1/admin/auth/password-reset | No | Always 202 so the form never reveals who has an account |
GET | /api/v1/admin/auth/invite/:token | No | Turns a 72-hour staff invite token into a fresh Firebase reset code; 410 when it expired or was replaced |
GET | /api/v1/admin/ads/summary | Staff (any role) | Ad views and viewers in the last 30 days, plus AdMob revenue when its report key is set |
GET | /api/v1/admin/settings-status | Staff (any role) | Which server keys are present for each settings tab (never their values) |
27. Database (PostgreSQL)
All data lives in your PostgreSQL database; videos and images live in storage, and the tables only point to them. The schema is reelsaga_web_nextjs/src/database/prisma_client/schema.prisma (Prisma), and every change to it is a migration under migrations/. Money is stored in whole cents with a currency; coins are whole numbers; balances only change inside database transactions on the server.
The main tables and how they connect
creators.owner_id points to the studio owner in users; branch_votes also point to users.Every table
All 52 tables, made from schema.prisma when this download was built. Column names are as in the database (snake_case). "→" is a foreign key: the column on the left points to the table on the right.
| Table | What it holds | Keys | Points to |
|---|---|---|---|
| People | |||
users | Everyone who signs in: viewers (guest or account), studio owners and staff (staff_role). | PK id unique public_id unique firebase_uid unique username unique referral_code | — |
staff_roles | The staff roles and what each one may do (Admin → Staff). | PK code | — |
devices | Push notification tokens, one per device (Firebase Cloud Messaging). | PK id unique token | user_id → users |
creators | A creator studio or application: profile, review checks, revenue share and payout details (account and tax ID encrypted). | PK id unique owner_id | owner_id → users |
| Catalogue | |||
genres | Genres for the home screen, browse and search. | PK id unique slug | — |
series | A series: details, studio, status, pricing (free episodes, default price, bundle discount), VIP and interactive flags, counters. | PK id unique code unique slug | creator_id → creators |
series_genres | Which genres a series is in (one of them primary). | PK (series_id, genre_id) | series_id → series genre_id → genres |
episodes | An episode: number, price in coins (0 = free), status and release time, video and HLS location, counters. | PK id unique (series_id, number) | series_id → series |
episode_branches | A "choose the ending" choice on an episode: prompt, timing, the two paths (options), rejoin episode and other-path price. | PK id unique episode_id | episode_id → episodes |
branch_votes | Each viewer's choice on a branch, and whether they bought the other path. | PK (branch_id, user_id) | branch_id → episode_branches user_id → users |
subtitle_tracks | A subtitle language of a series: source (studio, AI, reviewed), coverage and status. | PK id unique (series_id, lang) | series_id → series |
comments | Viewer comments on episodes; moderators can hide them. | PK id | episode_id → episodes user_id → users |
comment_likes | One like per viewer and comment (PUT/DELETE /comments/:id/like); comments.likes is the running count. | PK (comment_id, user_id) | comment_id → comments user_id → users |
episode_likes | One like per viewer and episode; episodes.likes is the running count. | PK (episode_id, user_id) | episode_id → episodes user_id → users |
episode_completions | Viewers who finished an episode (PUT /episodes/:id/progress with completed): episodes.views counts each once. | PK (episode_id, user_id) | episode_id → episodes user_id → users |
rails | Home screen rails: kind (trending, new, continue watching...), title, order and hand-picked series. | PK id unique kind | — |
banners | Home screen banners with their target, audience and schedule. | PK id | — |
| Viewer library | |||
library_items | My list: the series a viewer saved. | PK (user_id, series_id) | user_id → users series_id → series |
watch_progress | Where each viewer is in each series (episode and position); also the watch history. | PK (user_id, series_id) | user_id → users series_id → series |
downloads | Episodes a viewer downloaded for offline viewing (they count toward the free limit). | PK (user_id, episode_id) | user_id → users episode_id → episodes |
reminders | New-episode reminders a viewer turned on for a series. | PK (user_id, series_id) | user_id → users series_id → series |
notifications | In-app notifications per viewer. | PK id | user_id → users |
| Money | |||
wallets | Each viewer's coins: paid and bonus balances and free episode passes. | PK user_id | user_id → users |
bonus_grants | Bonus coins expire 30 days after grant; spent oldest-first before paid coins. | PK id | user_id → users |
coin_transactions | Every coin movement (top-up, unlock, reward, refund, expiry), with an idempotency key so a retry never counts twice. | PK id unique purchase_id unique idempotency_key | user_id → users purchase_id → purchases |
unlocks | Episodes a viewer unlocked, how (coins, bundle, pass, ad, VIP, admin) and the coins paid; studio earnings are worked out from these. | PK (user_id, episode_id) | user_id → users episode_id → episodes |
ad_views | Rewarded ads watched, per viewer and purpose; the daily limit and cooldown are counted from these. | PK id | user_id → users |
ad_rewards | A rewarded ad Google confirmed through AdMob server-side verification (GET /api/v1/ads/ssv). The app claims it once, with the nonce it passed as SSV custom data; only then are coins, unlocks or streak restores granted. | PK id unique transaction_id | — |
ad_reward_claims | A rewarded-ad claim the app made before Google's confirmation reached the server. It waits here (status "pending") until the matching SSV callback arrives and is then granted, or it expires after 24 hours. | PK id unique nonce | user_id → users |
coin_packs | Coin packs for sale: coins, bonus, price, store product id, shown on web checkout or not. | PK id unique store_product_id | — |
vip_plans | VIP plans: interval, price, store product id and trial days. | PK id unique store_product_id | — |
subscriptions | A viewer's VIP subscription: plan, store, status and renewal dates. | PK id unique external_id | user_id → users plan_id → vip_plans |
purchases | Every store / gateway payment (admin). Credits are idempotent per externalId. | PK id unique code unique external_id | user_id → users |
| Rewards | |||
streaks | Each viewer's daily check-in streak. | PK user_id | user_id → users |
check_ins | Each daily check-in and the coins it gave. | PK (user_id, day) | user_id → users |
reward_tasks | Reward tasks (watch episodes, invite a friend, rewarded ad...) with goal, coins and how often they repeat. | PK code | — |
reward_claims | Which tasks a viewer collected, and for which period. | PK (user_id, task_code, period) | user_id → users task_code → reward_tasks |
referrals | Invites: who invited whom, and whether the reward was paid. | PK id unique referred_id | referrer_id → users referred_id → users |
| Creators' money, moderation, content, system | |||
payouts | A payout to a studio: period, amount, fee, method, status (pending, held, approved, paid) and breakdown. | PK id | creator_id → creators |
creator_earnings | A studio's monthly statement, written by the settlement job (worker settle-creator-earnings, 1st of each month, or Admin → Payouts → Settle last month). Net revenue by source and the studio's share at that month's share %. | PK (creator_id, period) | creator_id → creators |
reports | Reports from viewers about episodes, comments, users or series, and how staff resolved them. | PK id | reporter_id → users |
push_campaigns | Push campaigns sent or scheduled from Admin → Push. | PK id | — |
cms_pages | CMS pages such as the terms and the privacy policy (Markdown). | PK slug | — |
cms_page_translations | AI or hand translations of a CMS page; GET /pages/:slug?lang= falls back to the original. | PK (slug, lang) | — |
faqs | Help centre questions and answers. | PK id | — |
languages | Languages for app texts and subtitles: coverage and whether they are live. | PK code | — |
settings | Key/value settings by group (app, ads, coins, rewards, downloads, payments, ai, email); Admin edits them. | PK (group, key) | — |
support_messages | Messages to support from the app or the website. | PK id unique ticket | user_id → users |
uploads | Files studios and staff upload (video, poster, subtitle, sample clip) and their processing status. | PK id unique key | — |
audit_logs | Every staff action: who, what, which item and the data sent. | PK id | actor_id → users |
series_daily_stats | Plays per series per day and traffic source (studio dashboard, analytics). Incremented by GET /episodes/:id/play. | PK (series_id, day, source) | series_id → series |
vip_plays | One VIP play per viewer, episode and day: only the first counts toward series_daily_stats.vip_views. | PK (user_id, episode_id, day) | user_id → users episode_id → episodes |
docker compose exec postgres psql -U reelsaga reelsaga). Example, coins spent per series this month:
SELECT s.title, SUM(u.coins) AS coins
FROM unlocks u JOIN episodes e ON e.id = u.episode_id JOIN series s ON s.id = e.series_id
WHERE u.created_at >= date_trunc('month', now())
GROUP BY s.title ORDER BY coins DESC;28. Publish to the stores
You publish the app under your own developer accounts. Before you start: set your app id (chapter 17), your Firebase files (chapter 4), an https API_BASE_URL, and your privacy, terms and account deletion pages (Admin → CMS Pages; they are /privacy, /terms and /delete-account on your site — the stores ask for these links).
Google Play
- Create an upload key inside
android/app:cd reelsaga_mobile_flutter/android/app && keytool -genkey -v -keystore upload-keystore.jks -keyalg RSA -keysize 2048 -validity 10000 -alias upload. Back this file up and never share it. - Create
android/key.properties:
Without this file, release builds are signed with the debug key (fine for testing, refused by Play).storePassword=… keyPassword=… keyAlias=upload storeFile=upload-keystore.jks - Set the version in
pubspec.yaml(version: 1.0.0+1; raise the number after+for every upload), thenflutter build appbundle. - In Play Console: create the app, fill the store listing, content rating, data safety (the app collects account info, purchase history, device ids for ads and push, crash logs), and upload
build/app/outputs/bundle/release/app-release.aabto a testing track first. - Add the SHA-1/SHA-256 of Play's app signing key (Play Console → Test and release → App integrity) to Firebase.
App Store
- In the Apple Developer site, register your bundle id with Push Notifications, Sign in with Apple and In-App Purchase.
- Open
ios/Runner.xcworkspacein Xcode → Runner → Signing & Capabilities → choose your team (Automatic signing is already on; chapter 9). - In App Store Connect create the app, fill the listing and App Privacy, create the in-app purchases (chapter 10).
flutter build ipa, then uploadbuild/ios/ipa/*.ipawith the Transporter app, and send it to TestFlight first.
29. Updating
When a new version comes out, read the changelog, back up your database (chapter 5), then copy the new files over your copy, keeping your .env files, Firebase files and any changes you made. Run docker compose up -d --build: database changes are applied automatically on start. Using git for your copy makes this much easier: commit before you copy the update in, and review the differences.
30. FAQ and troubleshooting
Videos do not play / uploads fail
Check S3_PUBLIC_ENDPOINT: open https://storage.your-domain.com/minio/health/live in a browser; it must answer. With an https website the storage address must be https too. With a cloud bucket, check its CORS rule allows your domain.
An uploaded episode stays "processing"
The worker converts videos. Check it runs: docker compose logs worker. Studio → Upload shows the reason when a conversion fails.
Sign-in fails on the website
Add your domain under Firebase → Authentication → Settings → Authorized domains, and check all NEXT_PUBLIC_FIREBASE_* values, then rebuild (docker compose up -d --build).
Google sign-in fails on Android
Add the SHA-1 and SHA-256 of the key that signed the build to Firebase, then download the config again (flutterfire configure).
Purchases say DEMO
The server has DEMO_PURCHASES="true" and no payment key yet, so purchases are granted without payment. Add your RevenueCat or gateway keys (chapters 10–11), which switches to live purchases, and set DEMO_PURCHASES="false".
A rewarded ad says Google hasn't confirmed it yet
The reward waits for Google's server-side verification callback and arrives with a notification when it comes (chapter 13). If it never comes, switch on server-side verification for that rewarded ad unit in AdMob with your /api/v1/ads/ssv URL, and check Admin → Setup.
A studio has no payout this month
A payout is created only when the studio's unpaid balance reaches the minimum payout and the studio has a payout method (chapter 22). Smaller balances carry over. Admin → Payouts → Settle last month runs the monthly settlement at once.
Push campaigns do not arrive
iOS needs the APNs key in Firebase. Check PUSH_TOPIC_PREFIX is the same on the server and in the app, and that the phone allowed notifications. Admin → Setup tests the Firebase push connection.
The app shows "Can't reach the server"
API_BASE_URL in the app's .env must be your site's address (https, no /api/v1 at the end). Open https://your-domain.com/api/v1/health on the phone's browser.
I changed .env and nothing happened
Server: docker compose up -d (add --build for NEXT_PUBLIC_*). App: stop and run again.
Where are the logs?
docker compose logs -f web and docker compose logs -f worker. App crashes go to Firebase Crashlytics.
31. Credits and licences
ReelSaga is built on these open-source projects. Each keeps its own licence (mostly MIT, BSD-3 or Apache 2.0).
AI tools helped write the code and this documentation and design the screens and icon; see AI disclosure.
Mobile app
Flutter, flutter_riverpod, go_router, FlutterFire (firebase_core, firebase_auth, firebase_messaging, firebase_analytics, firebase_crashlytics, firebase_remote_config, firebase_app_check), google_sign_in, sign_in_with_apple, purchases_flutter (RevenueCat), google_mobile_ads, video_player, video_player_web_hls, hive_ce, http, flutter_dotenv, flutter_local_notifications, lucide_icons_flutter, shimmer, flutter_styled_toast, url_launcher, share_plus, in_app_review, package_info_plus, connectivity_plus, app_tracking_transparency, path_provider, wakelock_plus, image_picker, flutter_markdown_plus, shared_preferences, timezone, flutter_timezone, intl, flutter_launcher_icons, flutter_native_splash.
Website, Studio, Admin and worker
Next.js, React, Prisma, PostgreSQL, pg, pg-boss, Zod, Tailwind CSS, shadcn/ui, Base UI, Lucide icons, Sonner, next-themes, hls.js, react-markdown, Nodemailer, Firebase Admin SDK, AWS SDK for JavaScript, FFmpeg, MinIO, Docker.
Third-party services
Firebase, RevenueCat, Stripe, PayPal, Razorpay, Flutterwave, Google AdMob, OpenAI, Google Gemini, your SMTP email provider and your storage or hosting provider are separate companies, not part of this item. Each has its own pricing tiers and terms, and you are responsible for any costs from them. See Third-party services in chapter 2.
Licences of copied source code
The base UI components in reelsaga_web_nextjs/src/components/ui/ and src/lib/utils.ts are based on shadcn/ui (MIT License, Copyright (c) 2023 shadcn). Each of these files keeps an attribution header, and the full MIT licence text is in LICENSE.txt under "Third-party licenses". Packages installed with pnpm and pub keep their own licence files in their packages.
Fonts
Plus Jakarta Sans and JetBrains Mono, SIL Open Font License 1.1.
Content
The sample series texts, studio names, viewer names and the sample video clip are original and part of your licence. Pictures and videos on our live demo are for preview only and are not included in the download.
32. Changelog
1.0.1 (13 November 2026)
Security update: disabled, banned or removed staff lose admin access at once and their sessions are revoked; progress, views and ending votes only for episodes the viewer can watch; the feed keeps 1080p for VIP; emails are never written to the log; upload extensions come from the checked file type; iOS and Android build settings cleaned up; App Store payment rules added to the docs. Full list in CHANGELOG.md.
1.0.0
First release. See CHANGELOG.md in the download for the full list, including the changes made before release.
33. Support
Questions or a problem? Use the Support tab on the item page on CodeCanyon, with your purchase code, what you did, and what you saw (a screenshot and the output of pnpm run doctor help a lot). Support covers questions about the item, help with bugs, and help with the third-party services it uses as far as this documentation goes. It does not cover changes or new features you want to build; for that, or to have it installed for you, ask about our installation service on the item page.