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

FolderWhat 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.mjsRebrands 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.

You can start before you have every key. Only Firebase and the storage keys are needed to sign in and play videos. To try purchases before you add payment keys, set 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.

AI-powered features in the item: Yes. They are optional, need your own OpenAI or Google Gemini API key, and stay off without one:

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)

Home
Home
For You feed
For You feed
Series page
Series page
Player
Player
Choose the ending
Choose the ending
Unlock an episode
Unlock an episode
Coin store
Coin store
VIP plans
VIP plans
Rewards and check-in
Rewards and check-in
My List
My List
Search
Search
Account
Account

Website

Website home
Home
Series page
Series page
Web player
Web player
VIP pricing
VIP pricing

Creator Studio (/studio)

Studio dashboard
Dashboard
Upload episodes
Upload episodes
Unlock pricing
Unlock pricing
Studio analytics
Analytics
Subtitles
Subtitles
Earnings
Earnings

Admin panel (/admin)

Admin dashboard
Dashboard
Series
Series
Users
Users
Coin packs
Coin packs
Payment gateways
Settings: payment gateways
Push notifications
Push notifications

2. Requirements

To run the server

To build the mobile app

Accounts you must create yourself

Third-party services and what they cost

These services are run by other companies, not by us, and you pay them directly. Each has its own pricing, free-tier limits, fees and terms, which can change at any time. You are responsible for every cost below. Check each pricing page before you go live, and set budget alerts where the provider offers them.
ServiceUsed forNeeded?Costs to expect
Firebase (Google)Sign-in, push notifications, Analytics, CrashlyticsRequiredFree 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.
RevenueCatApp Store and Google Play purchases of coins and VIPRequired to sell in the appFree 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 PlayPublishing the app, in-app purchasesRequired to sell in the appStore 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 AdMobRewarded, interstitial and app-open adsOptionalNo 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.
StripeWebsite card payments and VIP subscriptionsOptionalA 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.
PayPalWebsite paymentsOptionalA fee per payment, more across borders. Needs a PayPal business account.
RazorpayWebsite payments (India)OptionalA fee per payment. Needs an Indian business account that passes Razorpay's KYC checks.
FlutterwaveWebsite payments (Africa)OptionalA 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 othersVideos, posters and subtitles; every play streams HLS from itRequiredUsually 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 domainWebsite, API, worker, databaseRequiredMonthly hosting. Converting videos uses a lot of CPU, so upload-heavy platforms need more cores.
OpenAI or Google GeminiAI subtitles, translations, posters, SEO text, report second opinionsOptionalCharged per use (per minute of audio, per token, per image).
SMTP email providerStaff invites, password resets, emails to studiosOptionalMost have a free tier, then a price per email.
Vercel, managed PostgreSQL (optional hosting)Running the website without your own server (chapter 6)OptionalTheir 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.

  1. 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
  2. In .env, fill at least these values:
    KeyWhat to put
    POSTGRES_PASSWORDA long random password (run openssl rand -hex 24 to 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), or http://YOUR_SERVER_IP:9000 for a first test.
    NEXT_PUBLIC_FIREBASE_*, FIREBASE_*From chapter 4.
  3. Start everything:
    docker compose up -d --build
    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.
  4. 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/health shows {"ok":true,"db":"ok",…}.
  5. Make yourself the admin (chapter 7), then put it on your domain with HTTPS (chapter 5).
Port 3000, 9000 or 9001 already used by something else on the server? Set WEB_PORT, MINIO_PORT and MINIO_CONSOLE_PORT in .env (and use the new storage port in S3_PUBLIC_ENDPOINT).
Changed .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.

Firebase is a third-party service with its own pricing. Firebase is run by Google, not by us. It has its own plans and pricing structure (the free Spark plan and the pay-as-you-go Blaze plan), and some features used here can cost money as you grow, for example phone sign-in SMS messages, Authentication beyond the free monthly users, and Crashlytics/Analytics data exports. Prices and free limits can change at any time. You are responsible for any Firebase costs your project incurs. Check firebase.google.com/pricing before you go live, and set a budget alert in Google Cloud Billing.
  1. Go to the Firebase console → Add project. Give it your app name. Google Analytics: on.
  2. Build → Authentication → Get started → Sign-in method. Turn on: Anonymous (guest mode), Google, Phone, Email/Password (staff accounts) and Apple (see chapter 16).
  3. Authentication → Settings → Authorized domains: add your-domain.com.
  4. Project settings (gear) → General → Your apps → Add app → Web (name it "Website"). Copy the values from the firebaseConfig shown into deploy/.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:…"
  5. Project settings → Service accounts → Generate new private key. A JSON file downloads. Copy three values from it into deploy/.env:
    FIREBASE_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"
    Keep the \n as they are in the file. Keep this file secret.
  6. For the mobile app, install the FlutterFire CLI and connect the app (it registers the Android and iOS apps and writes their config files):
    dart 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.reelsaga
    Use your own app id here (see chapter 17 to change it first). Then copy the values into reelsaga_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 in android/app/google-services.json, ios/Runner/GoogleService-Info.plist, or in Project settings → Your apps.
  7. iOS Google sign-in: copy ios/Flutter/Firebase.xcconfig.example to ios/Flutter/Firebase.xcconfig and set GOOGLE_REVERSED_CLIENT_ID to the REVERSED_CLIENT_ID from GoogleService-Info.plist.
  8. Android Google and phone sign-in need your signing key fingerprints: run cd android && ./gradlew signingReport and 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.
Testing phone sign-in without SMS costs: Authentication → Sign-in method → Phone → Phone numbers for testing, add a number and a code.

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.

Use HTTPS for both addresses in production. A website on https cannot play videos from an http storage address (browsers block it), and the iOS app only allows https.

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.

  1. Create a PostgreSQL database (Neon, Supabase, Railway, or your own) and copy its connection string.
  2. Import reelsaga_web_nextjs into Vercel (Root directory: reelsaga_web_nextjs). Add every key of reelsaga_web_nextjs/.env.example under Settings → Environment Variables, with DATABASE_URL set to your database.
  3. Create the tables and the sample data once from your computer: in reelsaga_web_nextjs, put the same DATABASE_URL in .env, then pnpm install, pnpm prisma:migrate:deploy, pnpm first-run.
  4. 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-worker with the worker's .env filled 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:

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

  1. cd reelsaga_mobile_flutter, then copy .env.example to .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)
  2. Get the packages and run on a phone or emulator:
    flutter pub get
    flutter run
  3. Build for testing: flutter build apk --release (Android) or open ios/Runner.xcworkspace in Xcode (iOS).
  4. 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 build settings: 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.
Running the server on your own computer? The Android emulator reaches it at 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)

RevenueCat is a mandatory third-party account for in-app purchases. The app sells through RevenueCat's SDK (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.

  1. 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
    Bonus coins and "first top-up doubled" are added by the server, not by the store product.
  2. In RevenueCat: create a project, add your iOS and Android apps, import the products, create an entitlement vip with the three VIP products, an offering default (current) with the VIP packages, and an offering coins with the coin products.
  3. 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.
  4. Server keys in deploy/.env: REVENUECAT_API_KEY (a secret API key, v1) and REVENUECAT_WEBHOOK_SECRET (any long random value).
  5. 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.
  6. RevenueCat → Integrations → Webhooks → add https://your-domain.com/api/v1/webhooks/revenuecat with the Authorization header value equal to REVENUECAT_WEBHOOK_SECRET.
Demo mode. With 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.

App Store rule: no web payments for digital goods inside the iOS app. Apple's App Review Guidelines (3.1.1 and 3.1.3) restrict selling digital goods, such as coins, episode unlocks and VIP subscriptions, through web payments inside an iOS app: the iOS app must sell them with Apple's in-app purchase, and must not link to, open or point viewers to the website's checkout, except where Apple's rules for a storefront explicitly allow it. The app follows this: it sells coins and VIP only through in-app purchases (RevenueCat) and never opens the website checkout; a VIP plan bought on the website can only be managed or cancelled from the app. The gateways below are for your website. Keep it this way if you change the app. Google Play's payments policy has similar rules for Android.

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.

GatewayKeysWebhook URL and events
Stripe (cards, wallets; VIP as a real subscription)STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECREThttps://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".
PayPalPAYPAL_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_SECREThttps://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_HASHhttps://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).

  1. Android works once Firebase is set up (chapter 4).
  2. 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.
  3. The app registers each signed-in device and joins two topics: reelsaga_all and reelsaga_<language> (for example reelsaga_es). Send campaigns from Admin → Push to everyone, a language, a series' followers, or one user, now or scheduled.
  4. The topic prefix is PUSH_TOPIC_PREFIX; it must be the same in deploy/.env and 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.

  1. In AdMob, add your Android and iOS apps and create one ad unit of each type you want.
  2. In reelsaga_mobile_flutter/.env set ADMOB_ANDROID_APP_ID and the unit ids ADMOB_ANDROID_REWARDED, ADMOB_ANDROID_INTERSTITIAL, ADMOB_ANDROID_APP_OPEN, ADMOB_IOS_REWARDED, ADMOB_IOS_INTERSTITIAL, ADMOB_IOS_APP_OPEN.
  3. The iOS app id goes in ios/Flutter/Firebase.xcconfig: ADMOB_IOS_APP_ID=ca-app-pub-…~….
  4. Your app ids replace placeholders; no ids of ours are included. AndroidManifest.xml reads ${admobAppId}, filled from ADMOB_ANDROID_APP_ID in the app's .env by android/app/build.gradle.kts; Info.plist reads $(ADMOB_IOS_APP_ID) from ios/Flutter/Firebase.xcconfig. Until you set them, the build uses Google's public sample app ids (ca-app-pub-3940256099942544~3347511713 for Android, ca-app-pub-3940256099942544~1458002511 for iOS, in build.gradle.kts and ios/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.
  5. 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 keep AD_REWARDS_MODE="ssv" (the default) and list your rewarded ad unit ids in ADMOB_REWARDED_AD_UNITS, comma-separated (the same ids as ADMOB_ANDROID_REWARDED and ADMOB_IOS_REWARDED in the app). Callbacks for any other ad unit pay nothing, and until it is set no rewarded ad pays (Admin → Setup flags it).
  6. 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.
How rewarded ads are protected. The app never decides a reward on its own. Each rewarded ad carries a one-time code and the viewer's id as AdMob server-side verification data. When the viewer earns the reward, Google calls your server's /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 happensWhat 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 confirmsThe 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

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.plistWhen iOS shows itText in the download
NSUserTrackingUsageDescriptionApp 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.
NSPhotoLibraryUsageDescriptionChoosing a profile photo or a screenshot for a support messageChoose a photo for your profile or attach a screenshot to your feedback.
NSCameraUsageDescriptionTaking a profile photoTake 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.

19. Basic edits

I want to change…Where
Coin packs, prices, bonus, first top-up, default unlock priceAdmin → Coin Packs
VIP plans, trial days, benefitsAdmin → VIP Plans
Episode prices and free episodes of a seriesStudio → Pricing (creators), Admin → Series
Daily check-in rewards, streak restoreAdmin → Rewards
Home banners and railsAdmin → Banners & Rails
Terms, privacy, delete account, about, helpAdmin → CMS Pages
Genres, tags and languagesAdmin → Genres & Tags, Admin → Languages
App versions (force update), maintenance mode, guest mode, support linksAdmin → Settings → App config
App texts and translationsreelsaga_mobile_flutter/lib/l10n/app_en.arb and app_es.arb (English and Spanish), then run flutter gen-l10n
Website textsThe 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).

Studio dashboard
Studio → Dashboard
My Series
Studio → My Series

Step 1. Apply and get approved

  1. 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).
  2. 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.
  3. While the application waits, /studio shows its status, and the creator can already add a payout method. After approval, /studio opens the dashboard.

Step 2. Create a series

  1. 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.
  2. Add a poster (2:3, PNG/JPG/WebP), or press Generate with AI when an AI image key is set (chapter 14).
  3. The series is a draft: changes save automatically and viewers can't see it yet.
Series form
Studio → My Series → a series (the same form as New series)
Upload episodes
Studio → Upload

Step 3. Upload the episodes

  1. 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.
  2. The file name sets the episode: ep05_dorm_party.mp4 becomes episode 5, "Dorm Party". Files without a number are added after the last episode.
  3. 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.
  4. Studio → Episodes shows every episode; drag a row (or use Alt + arrow keys) to change the order.
Episode order
Studio → Episodes
Unlock pricing
Studio → Pricing

Step 4. Set the unlock prices

  1. Studio → Pricing, pick the series.
  2. Free episodes: the first N episodes are free for everyone (0 to 50). Viewers hit the paywall at episode N + 1.
  3. 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.
  4. Bundle discount: the discount (0 to 50%) when a viewer unlocks all remaining episodes at once.
  5. 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)

Step 6. Publish

  1. Publish the episodes: on Studio → Upload, Publish ready publishes every episode whose video is ready.
  2. Send the series for review: open it in Studio → My Series and press Submit for review. Its status becomes In review.
  3. 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.
  4. 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.
Admin series editor
Admin → Series → a series (status)
Studio analytics
Studio → Analytics

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

  1. 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.
  2. Studio → Interactive, pick the series, then in Choice settings:
    FieldWhat it does
    Choice episodeThe episode where viewers choose.
    PromptThe question on screen, e.g. "Should she open the letter?" (3–200 characters).
    Appears atWhen the question appears in the choice episode, as minutes:seconds (for example 1:41).
    TimerHow long viewers have to choose (5–60 seconds).
    If no voteThe 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 EpWhere both paths continue; it must come after the last path episode. Leave it empty when the paths are two different endings.
    Other path priceCoins to also watch the path the viewer didn't choose (0–500; 0 = free). The suggested default is Admin → Coin Packs → Alt ending price.
  3. 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.
  4. The Votes so far panel shows how viewers chose. Admin → Settings → App config → Interactive episodes turns the feature off everywhere.
Interactive endings editor
Studio → Interactive, while setting up a choice

What the viewer sees

Choose the ending in the app
The choice in the app
  1. At the "appears at" moment the question slides over the video with both answers and the countdown; the video keeps playing.
  2. 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.
  3. After voting, the screen shows how everyone voted so far (percent for A and B).
  4. "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).
  5. 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.
  6. 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

SettingWhereDefault
Default creator share % (for newly approved studios)Admin → Settings → Payments → Creator earnings60%
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 earnings50%
Minimum payoutAdmin → Settings → Payments → Creator earnings$50.00
Early payouts on/off, and the early payout feeAdmin → Settings → Payments → Creator earningson, $5.00
Coins per $1 (the value of a coin)Admin → Settings → Payments100 coins = $1

A change to a studio's share applies from the next statement; statements already written keep the share they were made with.

Creator earnings settings
Admin → Settings → Payments
Studio earnings
Studio → Earnings

How a month's earnings are worked out

  1. 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.
  2. 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.
  3. Net revenue = coin unlocks + the studio's part of the VIP pool. The studio earns its share % of the net.
Example. In May viewers spend 300 paid coins on a studio's episodes (100 coins per $1 → $3.00). One VIP subscriber paid $100 with $10 tax; the VIP pool is 50% → $45.00 from that subscriber, and 3 of their 4 VIP plays were this studio's episodes → $33.75. Net revenue $36.75 × the studio's 50% share = $18.38.
Amounts are what viewers paid. Apple's and Google's store commission, payment gateway fees and RevenueCat fees are not taken off first, so choose the share % and the VIP pool % with your own costs in mind.

Monthly statements and payouts

  1. 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.
  2. 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.
  3. 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.
Admin payouts
Admin → Payouts
Studio payouts
Studio → Payouts

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.

Payout methods

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

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.

KeyRequiredWhereWhat it does
Database
DATABASE_URLYeswebsite, workerPostgreSQL connection string
POSTGRES_DBYesDockerDatabase the Docker stack creates
POSTGRES_USERYesDockerDatabase user for the Docker stack
POSTGRES_PASSWORDYesDockerDatabase password for the Docker stack
App
APP_URLYeswebsite, DockerPublic URL of the web app (links in emails, signed media)
NEXT_PUBLIC_APP_NAME—website, DockerName shown in the web app
NEXT_PUBLIC_IOS_APP_URL—website, DockerApp Store link for the website's Get the app buttons
NEXT_PUBLIC_ANDROID_APP_URL—website, DockerGoogle Play link for the website's Get the app buttons
WEB_PORT—DockerHost port the web container listens on
Storage
MINIO_PORT—DockerHost port of the built-in MinIO storage API (default 9000)
MINIO_CONSOLE_PORT—DockerHost port of the MinIO web console (default 9001)
App
CORS_ORIGINS—website, DockerBrowser apps allowed to call /api/v1
PUSH_TOPIC_PREFIX—website, Docker, appFCM topic prefix (<prefix>all, <prefix><language>); same as the server's
Firebase sign-in
NEXT_PUBLIC_FIREBASE_API_KEYYeswebsite, DockerFirebase web config
NEXT_PUBLIC_FIREBASE_AUTH_DOMAINYeswebsite, DockerFirebase web config
NEXT_PUBLIC_FIREBASE_PROJECT_IDYeswebsite, DockerFirebase web config
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET—website, DockerFirebase web config
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID—website, DockerFirebase web config
NEXT_PUBLIC_FIREBASE_APP_IDYeswebsite, DockerFirebase web config
NEXT_PUBLIC_FIREBASE_ADMIN_APP_ID—website, DockerOptional second web app for the admin panel
ADMIN_REQUIRE_MFA—website, DockerRequire two-step sign-in for staff
Firebase Admin + push
FIREBASE_PROJECT_IDYeswebsite, worker, Docker, appFirebase project id
FIREBASE_CLIENT_EMAILYeswebsite, worker, DockerService account e-mail
FIREBASE_PRIVATE_KEYYeswebsite, worker, DockerService account private key
Secrets
MEDIA_SIGNING_SECRETYeswebsite, DockerSigns media URLs (openssl rand -hex 24)
REVENUECAT_WEBHOOK_SECRET—website, DockerAuthorization header RevenueCat sends to the webhook
Payments
REVENUECAT_API_KEY—website, DockerRevenueCat secret API key (in-app purchases)
STRIPE_SECRET_KEY—website, DockerStripe secret key (web checkout)
STRIPE_WEBHOOK_SECRET—website, DockerStripe webhook signing secret
PAYPAL_CLIENT_ID—website, DockerPayPal REST app client id (web checkout)
PAYPAL_CLIENT_SECRET—website, DockerPayPal REST app secret
PAYPAL_MODE—website, Docker"live" for real money, anything else = sandbox
RAZORPAY_KEY_ID—website, DockerRazorpay key id (web checkout, India)
RAZORPAY_KEY_SECRET—website, DockerRazorpay key secret
RAZORPAY_WEBHOOK_SECRET—website, DockerRazorpay webhook secret (payment_link.paid)
FLUTTERWAVE_SECRET_KEY—website, DockerFlutterwave secret key (web checkout, Africa)
FLUTTERWAVE_WEBHOOK_HASH—website, DockerFlutterwave 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, DockerYour 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, DockerAdMob publisher id (pub-…): ad revenue in the admin
ADMOB_CLIENT_ID—website, DockerGoogle OAuth client id for the AdMob Reporting API
ADMOB_CLIENT_SECRET—website, DockerGoogle OAuth client secret for the AdMob Reporting API
ADMOB_REFRESH_TOKEN—website, DockerOAuth refresh token with the admob.readonly scope
Storage
S3_ENDPOINT—website, workerS3-compatible endpoint (empty for AWS S3)
S3_REGION—website, worker, DockerBucket region
S3_BUCKETYeswebsite, worker, DockerBucket for video, posters and subtitles
S3_ACCESS_KEY_IDYeswebsite, worker, DockerStorage access key
S3_SECRET_ACCESS_KEYYeswebsite, worker, DockerStorage secret key
S3_PUBLIC_ENDPOINT—website, DockerStorage address phones and browsers use (required with the Docker MinIO)
S3_PUBLIC_URL—website, DockerPublic bucket / CDN base URL (leave empty for a private bucket)
Sign in with Apple
APPLE_TEAM_ID—website, DockerToken revocation at account deletion
APPLE_KEY_ID—website, DockerToken revocation at account deletion
APPLE_CLIENT_ID—website, DockeriOS bundle id
APPLE_PRIVATE_KEY_PATH—websitePath to the .p8 key (or use APPLE_PRIVATE_KEY)
APPLE_PRIVATE_KEY—website, DockerThe .p8 key contents
AI
SUBTITLE_PROVIDER—website, worker, Docker"openai" or "gemini" for AI subtitles
OPENAI_API_KEY—website, worker, DockerOpenAI key (subtitles, posters, SEO, translation)
GEMINI_API_KEY—website, worker, DockerGemini key (subtitles, SEO, translation)
Worker
WORKER_CONCURRENCY—workerParallel transcodes
Email
SMTP_HOST—website, DockerSMTP server; empty = console mode
SMTP_PORT—website, Docker587 (STARTTLS) or 465 (TLS)
SMTP_USER—website, DockerSMTP user
SMTP_PASS—website, DockerSMTP password
SMTP_SECURE—website, Docker"true" for port 465
Mobile app
API_BASE_URLYesappYour server; the app calls <url>/api/v1
APP_NAME—appApp name in the UI
APP_STORE_ID—appRate-us and share links
REVENUECAT_IOS_KEY—appRevenueCat public iOS SDK key
REVENUECAT_ANDROID_KEY—appRevenueCat public Android SDK key
USE_REVENUE_CAT—appUse store purchases (false = demo)
Ads
ADMOB_ANDROID_APP_ID—appAdMob Android app id (Google's sample id when empty)
ADMOB_ANDROID_REWARDED—appAdMob Android rewarded unit (empty = no rewarded ads; a demo countdown with AD_REWARDS_MODE=demo)
ADMOB_ANDROID_INTERSTITIAL—appAdMob Android interstitial unit (empty = off)
ADMOB_ANDROID_APP_OPEN—appAdMob Android app-open unit (empty = off)
ADMOB_IOS_REWARDED—appAdMob iOS rewarded unit (empty = no rewarded ads; a demo countdown with AD_REWARDS_MODE=demo)
ADMOB_IOS_INTERSTITIAL—appAdMob iOS interstitial unit (empty = off)
ADMOB_IOS_APP_OPEN—appAdMob iOS app-open unit (empty = off)
Mobile app
LINK_PRIVACY—appPrivacy policy URL
LINK_TERMS—appTerms URL
LINK_SUPPORT—appSupport URL
LINK_DELETE_ACCOUNT—appAccount deletion URL
SUPPORT_EMAIL—appSupport e-mail
LINK_TELEGRAM—appTelegram link
LINK_WHATSAPP—appWhatsApp link
SHOW_TELEGRAM—appShow the Telegram link
SHOW_WHATSAPP—appShow the WhatsApp link
FIREBASE_MESSAGING_SENDER_IDYesappFirebase config
FIREBASE_STORAGE_BUCKET—appFirebase config
FIREBASE_WEB_API_KEY—appFirebase web config (Flutter web)
FIREBASE_WEB_APP_ID—appFirebase web config (Flutter web)
FIREBASE_WEB_AUTH_DOMAIN—appFirebase web config (Flutter web)
FIREBASE_ANDROID_API_KEYYesappFirebase Android config
FIREBASE_ANDROID_APP_IDYesappFirebase Android config
FIREBASE_IOS_API_KEYYesappFirebase iOS config
FIREBASE_IOS_APP_IDYesappFirebase iOS config
FIREBASE_IOS_CLIENT_ID—appGoogle sign-in on iOS
FIREBASE_IOS_BUNDLE_ID—appiOS 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.

  1. 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 })) });
    });
  2. 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";
  3. Need a signed-in user? Take auth from the handler arguments and call await 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.
  4. Add a test, reelsaga_web_nextjs/src/tests/creators-top.test.ts:
    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);
      });
    });
    Run it with a PostgreSQL database for tests (the tests make their own schema in it and delete it afterwards):
    cd reelsaga_web_nextjs
    TEST_DATABASE_URL="postgresql://user:password@localhost:5432/reelsaga_test" pnpm vitest run src/tests/creators-top.test.ts
  5. Try it: curl https://your-domain.com/api/v1/creators/top?limit=5. In the Flutter app, add a method next to the others in lib/core/services/api/reelsaga_api.dart.
Changing the database too? Edit 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.

  1. 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;
    }
  2. In reelsaga_worker/src/index.ts: import it, add the queue name to QUEUES, and register the job and its schedule next to the others inside main():
    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
  3. Run it once by hand to check it, from reelsaga_worker with 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); })'
  4. Rebuild the worker: docker compose up -d --build worker. The log shows the new queue in [worker] ready: ….
A job the website sends instead of a schedule: in a route handler call 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).

AuthMeaning
NoPublic.
OptionalPublic; a signed-in viewer gets their own state (unlocks, votes, progress) too.
Signed inAny 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 adminWrites allowed for the listed roles and super admins; other staff get 403.
Signed by the providerWebhooks and the AdMob callback: no user, but the provider's signature or secret is checked.
MethodPathAuthWhat it does
System and sign-in
GET/api/v1/healthNoHealth check: the server is up and the database answers
GET/api/v1/ads/ssvSigned by the providerAdMob server-side verification callback (set it on every rewarded ad unit in AdMob)
GET/api/v1/configNoThe public app config: version rules, maintenance, ad, coin and check-in rules, the download limit and languages
POST/api/v1/auth/sessionNoExchange a Firebase ID token for the website's session cookie (14 days)
POST/api/v1/auth/demo-adminNoLive demo only: sign in as the read-only demo admin (404 unless DEMO_ADMIN_PASSWORD is set)
POST/api/v1/auth/demo-studioNoLive demo only: sign in to the demo studio (404 unless DEMO_ADMIN_PASSWORD is set)
DELETE/api/v1/auth/sessionNoSign out of the website (clears the session cookie)
GET/api/v1/media/:a/:b/:cSigned link (expires)Signed media
GET/api/v1/media/:a/:b/:c/:dSigned link (expires)Signed media
GET/api/v1/media/:a/:b/:c/:d/:eSigned link (expires)Signed media
Catalogue, player and comments
GET/api/v1/homeOptionalThe home screen: live banners, genres and every enabled rail with its series
GET/api/v1/feedOptionalThe swipe feed, one card per series (For you, Following or Interactive tab), paged by cursor
GET/api/v1/series/:idOptionalA series page: details, the next scheduled episode and, when signed in, the viewer's list, reminder, progress and access
GET/api/v1/series/:id/episodesOptionalThe episode grid with each episode's lock state for this viewer, in ranges of 30
GET/api/v1/series/:id/relatedNoUp to 6 series from the same genres, most viewed first
GET/api/v1/episodes/:id/playOptionalPlay 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/progressSigned inSave where the viewer is in an episode; finishing it counts one view per viewer
PUT/api/v1/episodes/:id/likeSigned inLike an episode (once per viewer)
DELETE/api/v1/episodes/:id/likeSigned inTake back the viewer's like of an episode
GET/api/v1/episodes/:id/commentsOptionalAn episode's visible comments, newest first, with whether the viewer liked each one
POST/api/v1/episodes/:id/commentsSigned inPost a comment (signed-in accounts, not guests)
PUT/api/v1/comments/:id/likeSigned inOne like per viewer: liking twice or unliking a comment you never liked changes nothing
DELETE/api/v1/comments/:id/likeSigned inOne like per viewer: liking twice or unliking a comment you never liked changes nothing
GET/api/v1/episodes/:id/shareNoA share link, title and image for an episode
POST/api/v1/reportsSigned inReport an episode, comment, user or series to the moderators
GET/api/v1/genresNoThe active genres with their series counts
GET/api/v1/genres/:slug/seriesNoA genre's series (popular, newest or top rated), paged by cursor
GET/api/v1/rankingsNoThe top 20 series: most watched, trending, new or top rated
GET/api/v1/searchNoSearch series by title, synopsis, tag or studio, with genre, status and feature filters
GET/api/v1/search/suggestNoType-ahead suggestions: matching series titles and tags
GET/api/v1/search/trendingNoSuggested searches: the tags and titles of this week's most played series
Library, history, reminders, notifications, help
GET/api/v1/library/watchlistSigned inThe viewer's list (My list), sorted by date added, title or last update
PUT/api/v1/library/watchlist/:seriesIdSigned inAdd a series to the viewer's list
DELETE/api/v1/library/watchlist/:seriesIdSigned inRemove a series from the viewer's list
POST/api/v1/library/watchlist/removeSigned inRemove several series from the viewer's list at once
GET/api/v1/library/continueSigned inContinue watching: up to 30 unfinished series with the episode and position to resume
GET/api/v1/library/downloadsSigned inThe viewer's downloaded episodes and the download limit (none for VIP)
POST/api/v1/library/downloadsSigned inDownload an episode the viewer can watch for offline viewing: a signed MP4 link, within the free download limit
DELETE/api/v1/library/downloads/:episodeIdSigned inRemove a download record
GET/api/v1/historySigned inWatch history, newest first, paged by cursor
DELETE/api/v1/historySigned inClear the viewer's watch history
DELETE/api/v1/history/:seriesIdSigned inRemove one series from the watch history
GET/api/v1/remindersSigned inThe series the viewer asked to be reminded about, with their next episode
PUT/api/v1/series/:id/reminderSigned inTurn on new-episode reminders for a series
DELETE/api/v1/series/:id/reminderSigned inTurn off new-episode reminders for a series
GET/api/v1/notificationsSigned inThe viewer's notifications by category, with the unread count
POST/api/v1/notifications/readSigned inMark notifications read (by id, or all)
GET/api/v1/pages/:slugNoA published CMS page such as the terms or privacy policy; ?lang= returns its translation when one exists
GET/api/v1/faqNoThe help centre questions and answers by category
POST/api/v1/support/messagesOptionalSend a message to support (guests too); staff answer it in Admin, Support
POST/api/v1/support/attachmentsSigned inA short-lived upload link for a screenshot to attach to a support message
Account
GET/api/v1/meSigned inSigning in again cancels a scheduled deletion: every client calls GET /me after sign-in
POST/api/v1/me/avatarSigned inA short-lived upload link for a profile photo; then PATCH /me with { avatarUrl: fileUrl }
PATCH/api/v1/meSigned inUpdate the profile: name, username, photo, genres, preferences and onboarding
GET/api/v1/me/preferencesSigned inThe viewer's app preferences (playback, downloads, notifications, language)
PATCH/api/v1/me/preferencesSigned inChange app preferences; 1080p downloads need VIP
POST/api/v1/me/devicesSigned inRegister a device for push notifications
POST/api/v1/me/merge/previewSigned inBefore a guest signs in to an existing account: what the guest and the account each hold
POST/api/v1/me/linkSigned inSame as POST /me/merge/preview (the app's name for it)
POST/api/v1/me/mergeSigned inMove a guest's coins, list, history and unlocks into the signed-in account (both, account only, or phone only)
GET/api/v1/me/exportSigned inA signed link to download all of the viewer's data as JSON
DELETE/api/v1/meSigned inReal accounts are scheduled for deletion in 30 days; anonymous guests are deleted now, Firebase user included
POST/api/v1/me/apple/revokeSigned inSign in with Apple revocation at account deletion (App Store rule)
Rewards and referrals
GET/api/v1/rewardsSigned inThe rewards page: the streak, the 7-day check-in week, the tasks and the wallet balance
POST/api/v1/rewards/check-inSigned inCheck in for today and collect the day's bonus coins (plus the VIP daily bonus for VIP members)
POST/api/v1/rewards/streak/restoreSigned inRestore a broken streak with coins or a rewarded ad, when the admin allows it
POST/api/v1/rewards/tasks/:code/claimSigned inCollect a finished task's coins (once per day or once ever, as the task says)
POST/api/v1/rewards/adSigned inCollect the bonus coins for a rewarded ad that AdMob verified (pending while the callback is on its way)
GET/api/v1/referralsSigned inThe viewer's invite link, code and invited friends; pays any referral that now qualifies
POST/api/v1/referrals/redeemSigned inA new account accepts a friend's invite
Wallet, unlocks, purchases and webhooks
GET/api/v1/episodes/:id/branchOptionalA 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/voteSigned inChoose a path (once per viewer); returns the episode that plays next
POST/api/v1/episodes/:id/branch/unlock-otherSigned in"Watch the other path": one price unlocks every paid episode of the path the viewer did not pick
POST/api/v1/episodes/:id/unlockSigned inUnlock an episode with coins, a free episode pass or a rewarded ad (one request key per unlock)
GET/api/v1/series/:id/unlock-allSigned inThe bundle price to unlock every remaining locked episode of a series
POST/api/v1/series/:id/unlock-allSigned inUnlocks every locked episode at the bundle discount; the price is split across the unlocks so studios earn from it
GET/api/v1/walletSigned inThe viewer's coin balance (paid and bonus), passes, expiring bonus and the last 3 transactions
GET/api/v1/wallet/transactionsSigned inCoin history by type (top-ups, unlocks, rewards), paged by cursor
GET/api/v1/wallet/transactions/:idSigned inOne of the viewer's coin transactions
GET/api/v1/wallet/unlocksSigned inThe series the viewer unlocked episodes of, with episode and coin totals
GET/api/v1/store/coin-packsOptionalActive coin packs (the website lists only packs set to show on web checkout)
GET/api/v1/store/vip-plansNoActive VIP plans and the VIP benefits list
POST/api/v1/purchases/syncSigned inAsks RevenueCat for the subscriber and applies anything not credited yet
POST/api/v1/purchases/demoSigned inDemo purchases mode only: grants exactly what the store webhook would, without a payment
POST/api/v1/checkoutSigned inStart a web checkout with Stripe, PayPal, Razorpay or Flutterwave; returns where to send the buyer
POST/api/v1/checkout/confirmSigned inPayPal, Razorpay and Flutterwave hand the buyer back with a query; this verifies it with the gateway and credits once
GET/api/v1/vipSigned inThe viewer's VIP status and VIP billing history
POST/api/v1/vip/portalSigned inA Stripe billing portal link to manage a VIP subscription bought on the website
POST/api/v1/webhooks/revenuecatSigned by the providerRevenueCat purchase events (shared secret in the Authorization header): credits coins and VIP from the app stores
POST/api/v1/webhooks/razorpaySigned by the providerRazorpay payment events, checked with the webhook signature
POST/api/v1/webhooks/flutterwaveSigned by the providerFlutterwave payment events, checked with the verif-hash secret
POST/api/v1/webhooks/stripeSigned by the providerStripe events, checked with the signing secret: paid checkouts, renewals, failed payments, cancellations and refunds
Creator Studio
POST/api/v1/creator/applicationSigned inApply to become a creator studio (signed-in accounts, not guests); staff review it in Admin, Creators
GET/api/v1/creator/applicationSigned inThe status of the viewer's creator application (none, pending, approved, rejected, suspended)
GET/api/v1/studio/dashboardCreator (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/seriesCreator (approved studio)The studio's own series, last updated first
GET/api/v1/studio/series/:idCreator (approved studio)One of the studio's series with its genres, the studio's revenue share and coins per $1
POST/api/v1/studio/seriesCreator (approved studio)Create a draft series
PATCH/api/v1/studio/series/:idCreator (approved studio)Edit a series: title, synopsis, genres, tags, schedule, language; submit: true sends it for review
DELETE/api/v1/studio/series/:idCreator (approved studio)Delete a draft or in-review series (a published one can only be hidden by an admin)
POST/api/v1/studio/uploadsCreator (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/completeCreator (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/episodesCreator (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/orderCreator (approved studio)Save a new episode order
PATCH/api/v1/studio/episodes/:idCreator (approved studio)Edit an episode: title, price, status, release time (publishing needs a finished video)
PUT/api/v1/studio/series/:id/pricingCreator (approved studio)Set a series' free episodes, default price, bundle discount and per-episode prices in coins
GET/api/v1/studio/series/:id/subtitlesCreator (approved studio)The series' subtitle languages with their status and episode coverage
POST/api/v1/studio/series/:id/subtitles/generateCreator (approved studio)Queue AI subtitles for these languages (needs an AI provider key)
GET/api/v1/studio/episodes/:id/subtitles/:langCreator (approved studio)An episode's subtitle cues in one language, for the editor
PUT/api/v1/studio/episodes/:id/subtitles/:langCreator (approved studio)Save edited subtitle cues for an episode
POST/api/v1/studio/series/:id/subtitles/:lang/approveCreator (approved studio)Approve a reviewed AI subtitle language so viewers see it
GET/api/v1/studio/episodes/:id/branchCreator (approved studio)An episode's interactive choice (prompt, paths, rejoin, price) with its vote counts
PUT/api/v1/studio/episodes/:id/branchCreator (approved studio)Create or update an episode's interactive choice: prompt, timing, the two paths, rejoin and other-path price
GET/api/v1/studio/analyticsCreator (approved studio)Studio analytics for a period: views, viewers, paywall conversion, reminders, episode retention and traffic sources
GET/api/v1/studio/earningsCreator (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/payoutsCreator (approved studio)Payout history, the available and settled balance, the minimum, early payout rules and the next scheduled payout
POST/api/v1/studio/payouts/earlyCreator (approved studio)Takes the available balance before the month is settled, minus the early payout fee
PUT/api/v1/creator/payout-methodSigned inPayout destination ("Set up payouts", "Change method")
GET/api/v1/studio/aiCreator (approved studio)Which AI tools are set up on this server (subtitles, text, images)
POST/api/v1/studio/series/:id/poster/generateCreator (approved studio)Generate a poster for a series with AI (needs an image provider key)
GET/api/v1/studio/profileCreator (approved studio)Studio settings: public studio profile shown on series pages and used for contact
PATCH/api/v1/studio/profileCreator (approved studio)Update the studio's public profile and contact details
Admin
GET/api/v1/admin/dashboardStaff (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/seriesStaff (any role)Every series with search and filters (status, genre, studio), paged
GET/api/v1/admin/series/:idStaff (any role)One series with its studio, genres and poster
POST/api/v1/admin/seriesStaff: content manager or super adminCreate a series as the platform (house content)
PATCH/api/v1/admin/series/:idStaff: content manager or super adminEdit any series: details, studio, status, genres, free episodes, price, VIP, interactive, slug, badges
DELETE/api/v1/admin/series/:idStaff: content manager or super adminDelete a series and its episodes (type the title to confirm)
GET/api/v1/admin/ai/statusStaff (any role)Which optional AI features this server can run (drives the "add your key" states)
POST/api/v1/admin/ai/seoStaff: content manager or super adminSEO card: slug + meta description from the buyer's AI key (409 ai_not_configured without one)
POST/api/v1/admin/uploadsStaff: content manager or super adminPoster replace and bulk upload: presigned PUT, then complete (same pipeline as the studio)
POST/api/v1/admin/uploads/:id/completeStaff: content manager or super adminFinish an admin upload: a video becomes an episode and starts transcoding; a poster is applied
GET/api/v1/admin/episodesStaff (any role)A series' episodes with search and status filter
POST/api/v1/admin/episodesStaff: content manager or super adminAdd an episode to a series (optionally queue AI subtitles)
PATCH/api/v1/admin/episodes/:idStaff: content manager or super adminEdit an episode: title, number, price, status, release time
DELETE/api/v1/admin/episodes/:idStaff: content manager or super adminDelete an episode
PUT/api/v1/admin/series/:id/episodes/orderStaff: content manager or super adminSave a new episode order for a series
POST/api/v1/admin/episodes/priceStaff: content manager or super adminSet one coin price on many episodes at once
GET/api/v1/admin/genresStaff (any role)List genres
POST/api/v1/admin/genresStaff: content manager or super adminCreate a genre
PATCH/api/v1/admin/genres/:idStaff: content manager or super adminUpdate a genre
DELETE/api/v1/admin/genres/:idStaff: content manager or super adminDelete a genre
PUT/api/v1/admin/genres/orderStaff: content manager or super adminSave the order of genres
GET/api/v1/admin/tags/popularStaff (any role)The 30 most used tags with their series counts
POST/api/v1/admin/tags/mergeStaff: content manager or super adminMerge several tags into one across every series
GET/api/v1/admin/bannersStaff (any role)List banners
POST/api/v1/admin/bannersStaff: content manager or super adminCreate a banner
PATCH/api/v1/admin/banners/:idStaff: content manager or super adminUpdate a banner
DELETE/api/v1/admin/banners/:idStaff: content manager or super adminDelete a banner
PUT/api/v1/admin/banners/orderStaff: content manager or super adminSave the order of banners
GET/api/v1/admin/railsStaff (any role)The home screen rails with how many series each shows
PATCH/api/v1/admin/rails/:idStaff: content manager or super adminEdit a home rail: its title, its series, on or off
PUT/api/v1/admin/rails/orderStaff: content manager or super adminSave the order of home rails
GET/api/v1/admin/creatorsStaff (any role)Creator studios and applications by status, with search
GET/api/v1/admin/creators/:idStaff (any role)A studio or application: details, review checks, series and payout method (last 4 only)
PATCH/api/v1/admin/creators/:id/shareStaff: finance or super adminA studio's revenue share %
POST/api/v1/admin/creators/:id/approveStaff: content manager or super adminApprove a creator application (or reinstate a studio)
POST/api/v1/admin/creators/:id/suspendStaff: content manager or super adminSuspend a studio
POST/api/v1/admin/creators/:id/rejectStaff: content manager or super adminReject a creator application with a reason (the applicant gets an email)
PATCH/api/v1/admin/creators/:id/checksStaff: content manager or super adminReview checks: identity, rights declaration, sample guidelines
POST/api/v1/admin/creators/inviteStaff: content manager or super adminInvite a studio directly: creates an approved studio with the default revenue share
GET/api/v1/admin/usersStaff (any role)Users with search and filters (plan, sign-in, status), paged, plus today's active count
GET/api/v1/admin/users/exportStaff (any role)Download every user as CSV
GET/api/v1/admin/users/:idStaff (any role)One user: profile, coins, VIP, spend, unlocks, recent coin activity and reports
POST/api/v1/admin/users/:id/coinsStaff: support, finance or super adminAdd or take away a user's coins with a reason (logged in the audit log)
POST/api/v1/admin/users/:id/banStaff: moderator or super adminBan a user, for good or until a date, with a reason
POST/api/v1/admin/users/:id/unbanStaff: moderator or super adminLift a user's ban
GET/api/v1/admin/coin-packsStaff (any role)List coin packs
POST/api/v1/admin/coin-packsStaff: finance or super adminCreate a coin pack
PATCH/api/v1/admin/coin-packs/:idStaff: finance or super adminUpdate a coin pack
DELETE/api/v1/admin/coin-packs/:idStaff: finance or super adminDelete a coin pack
PUT/api/v1/admin/coin-packs/orderStaff: finance or super adminSave the order of coin packs
GET/api/v1/admin/vip-plans/summaryStaff (any role)VIP numbers: active members, monthly recurring revenue by plan, trial-to-paid and monthly churn
GET/api/v1/admin/vip-plansStaff (any role)List vip plans
POST/api/v1/admin/vip-plansStaff: finance or super adminCreate a vip plan
PATCH/api/v1/admin/vip-plans/:idStaff: finance or super adminUpdate a vip plan
GET/api/v1/admin/reward-tasksStaff (any role)The reward tasks with how often each was claimed in the last 7 days
PATCH/api/v1/admin/reward-tasks/:codeStaff: super adminEdit a reward task: title, coins, goal, on or off
GET/api/v1/admin/settings/:groupStaff (any role)One settings group (app, ads, coins, rewards, payments, downloads, ai...) with its defaults filled in
PUT/api/v1/admin/settings/:groupStaff: super admin (payments and coins: finance too)Save a settings group; each value is type- and range-checked
GET/api/v1/admin/transactionsStaff (any role)Purchases with search and filters (gateway, status, coins or VIP), paged
GET/api/v1/admin/transactions/exportStaff (any role)Download every purchase as CSV
GET/api/v1/admin/transactions/:idStaff (any role)One purchase with its user and coin transaction
POST/api/v1/admin/transactions/:id/refundStaff: finance or super adminRefunds a paid purchase (full or partial)
GET/api/v1/admin/payoutsStaff (any role)Creator payouts by month and status, with the totals to pay
GET/api/v1/admin/payouts/:idStaff (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/settleStaff: finance or super adminWrites the monthly statements and creates the payouts now (the worker does it on the 1st of each month)
POST/api/v1/admin/payouts/:id/approveStaff: finance or super adminAfter you sent the money: approve a pending or held payout; the worker marks it paid
POST/api/v1/admin/payouts/:id/holdStaff: finance or super adminHold a pending payout with a reason the studio sees
POST/api/v1/admin/payouts/approve-allStaff: finance or super adminApprove every pending payout (send the money first); the worker marks them paid
GET/api/v1/admin/reportsStaff (any role)Reports by status with their counts
GET/api/v1/admin/reports/:idStaff (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-reviewStaff: moderator or super adminAI second opinion on a report (no key → 409 ai_not_configured → "add your key")
POST/api/v1/admin/reports/:id/resolveStaff: moderator or super adminResolve a report: dismiss, remove the content, ban the user, warn or keep it in review
GET/api/v1/admin/pushStaff (any role)Push campaigns, automations and the last 30 days' reach
POST/api/v1/admin/pushStaff: content manager or super adminSend or schedule a push campaign to everyone, a segment, a series' followers or a language topic
GET/api/v1/admin/push/audiencesStaff (any role)Audience picker: how many people each audience reaches right now
POST/api/v1/admin/push/testStaff: 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/automationsStaff: content manager or super adminTurn the automatic pushes on or off: cliffhanger, streak at risk, vote results
GET/api/v1/admin/pagesStaff (any role)The CMS pages with how many translations each has
GET/api/v1/admin/pages/:slugStaff (any role)One CMS page with its translations
POST/api/v1/admin/pages/:slug/translateStaff: content manager or super adminTranslates the page into every app language except English (AI key required; 409 ai_not_configured without)
PUT/api/v1/admin/pages/:slugStaff: content manager or super adminCreate or update a CMS page (Markdown)
GET/api/v1/admin/faqStaff (any role)List faqs
POST/api/v1/admin/faqStaff: content manager or super adminCreate a faq
PATCH/api/v1/admin/faq/:idStaff: content manager or super adminUpdate a faq
DELETE/api/v1/admin/faq/:idStaff: content manager or super adminDelete a faq
GET/api/v1/admin/languagesStaff (any role)Languages with their app-text and subtitle coverage and the AI settings
POST/api/v1/admin/languagesStaff: super adminAdd a language
PATCH/api/v1/admin/languages/:codeStaff: super adminEdit a language: live, strings done, order (English always stays live)
GET/api/v1/admin/staffStaff (any role)Staff members and the roles with what each can do
POST/api/v1/admin/staff/inviteStaff: super adminCreates (or finds) the Firebase user, gives them the role, and emails a 72-hour invite link
POST/api/v1/admin/staff/:id/resendStaff: super adminSend a staff invite again (a new 72-hour link; super admin only)
PATCH/api/v1/admin/staff/:idStaff: super adminChange a staff member's role or turn their access on or off (super admin only)
DELETE/api/v1/admin/staff/:idStaff: super adminRemove someone from the staff (super admin only)
GET/api/v1/admin/auditStaff (any role)The audit log of staff actions, filtered by person or item, paged
Admin: setup, ads, sign-in help
GET/api/v1/admin/setupStaff (any role)Setup check: which keys are set and whether each service (database, storage, Firebase, payments, email) answers
POST/api/v1/admin/setup/test-emailStaff: super adminSends a test email to the signed-in staff member (super admin; the demo admin is read-only)
POST/api/v1/admin/auth/password-resetNoAlways 202 so the form never reveals who has an account
GET/api/v1/admin/auth/invite/:tokenNoTurns a 72-hour staff invite token into a fresh Firebase reset code; 410 when it expired or was replaced
GET/api/v1/admin/ads/summaryStaff (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-statusStaff (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

users wallets coin_transactions purchases subscriptions unlocks branch_votes series episodes episode_branches creator_earnings creators payouts
Each arrow points from the table that holds the reference to the table it points to (many → one). 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.

TableWhat it holdsKeysPoints to
People
usersEveryone 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_rolesThe staff roles and what each one may do (Admin → Staff).PK code—
devicesPush notification tokens, one per device (Firebase Cloud Messaging).PK id
unique token
user_id → users
creatorsA 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
genresGenres for the home screen, browse and search.PK id
unique slug
—
seriesA 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_genresWhich genres a series is in (one of them primary).PK (series_id, genre_id)series_id → series
genre_id → genres
episodesAn 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_branchesA "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_votesEach 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_tracksA subtitle language of a series: source (studio, AI, reviewed), coverage and status.PK id
unique (series_id, lang)
series_id → series
commentsViewer comments on episodes; moderators can hide them.PK idepisode_id → episodes
user_id → users
comment_likesOne 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_likesOne like per viewer and episode; episodes.likes is the running count.PK (episode_id, user_id)episode_id → episodes
user_id → users
episode_completionsViewers 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
railsHome screen rails: kind (trending, new, continue watching...), title, order and hand-picked series.PK id
unique kind
—
bannersHome screen banners with their target, audience and schedule.PK id—
Viewer library
library_itemsMy list: the series a viewer saved.PK (user_id, series_id)user_id → users
series_id → series
watch_progressWhere each viewer is in each series (episode and position); also the watch history.PK (user_id, series_id)user_id → users
series_id → series
downloadsEpisodes a viewer downloaded for offline viewing (they count toward the free limit).PK (user_id, episode_id)user_id → users
episode_id → episodes
remindersNew-episode reminders a viewer turned on for a series.PK (user_id, series_id)user_id → users
series_id → series
notificationsIn-app notifications per viewer.PK iduser_id → users
Money
walletsEach viewer's coins: paid and bonus balances and free episode passes.PK user_iduser_id → users
bonus_grantsBonus coins expire 30 days after grant; spent oldest-first before paid coins.PK iduser_id → users
coin_transactionsEvery 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
unlocksEpisodes 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_viewsRewarded ads watched, per viewer and purpose; the daily limit and cooldown are counted from these.PK iduser_id → users
ad_rewardsA 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_claimsA 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_packsCoin packs for sale: coins, bonus, price, store product id, shown on web checkout or not.PK id
unique store_product_id
—
vip_plansVIP plans: interval, price, store product id and trial days.PK id
unique store_product_id
—
subscriptionsA viewer's VIP subscription: plan, store, status and renewal dates.PK id
unique external_id
user_id → users
plan_id → vip_plans
purchasesEvery store / gateway payment (admin). Credits are idempotent per externalId.PK id
unique code
unique external_id
user_id → users
Rewards
streaksEach viewer's daily check-in streak.PK user_iduser_id → users
check_insEach daily check-in and the coins it gave.PK (user_id, day)user_id → users
reward_tasksReward tasks (watch episodes, invite a friend, rewarded ad...) with goal, coins and how often they repeat.PK code—
reward_claimsWhich tasks a viewer collected, and for which period.PK (user_id, task_code, period)user_id → users
task_code → reward_tasks
referralsInvites: 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
payoutsA payout to a studio: period, amount, fee, method, status (pending, held, approved, paid) and breakdown.PK idcreator_id → creators
creator_earningsA 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
reportsReports from viewers about episodes, comments, users or series, and how staff resolved them.PK idreporter_id → users
push_campaignsPush campaigns sent or scheduled from Admin → Push.PK id—
cms_pagesCMS pages such as the terms and the privacy policy (Markdown).PK slug—
cms_page_translationsAI or hand translations of a CMS page; GET /pages/:slug?lang= falls back to the original.PK (slug, lang)—
faqsHelp centre questions and answers.PK id—
languagesLanguages for app texts and subtitles: coverage and whether they are live.PK code—
settingsKey/value settings by group (app, ads, coins, rewards, downloads, payments, ai, email); Admin edits them.PK (group, key)—
support_messagesMessages to support from the app or the website.PK id
unique ticket
user_id → users
uploadsFiles studios and staff upload (video, poster, subtitle, sample clip) and their processing status.PK id
unique key
—
audit_logsEvery staff action: who, what, which item and the data sent.PK idactor_id → users
series_daily_statsPlays 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_playsOne 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
Custom reports: connect any SQL tool to the database (in the Docker stack: 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

  1. 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.
  2. Create android/key.properties:
    storePassword=…
    keyPassword=…
    keyAlias=upload
    storeFile=upload-keystore.jks
    Without this file, release builds are signed with the debug key (fine for testing, refused by Play).
  3. Set the version in pubspec.yaml (version: 1.0.0+1; raise the number after + for every upload), then flutter build appbundle.
  4. 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.aab to a testing track first.
  5. Add the SHA-1/SHA-256 of Play's app signing key (Play Console → Test and release → App integrity) to Firebase.

App Store

  1. In the Apple Developer site, register your bundle id with Push Notifications, Sign in with Apple and In-App Purchase.
  2. Open ios/Runner.xcworkspace in Xcode → Runner → Signing & Capabilities → choose your team (Automatic signing is already on; chapter 9).
  3. In App Store Connect create the app, fill the listing and App Privacy, create the in-app purchases (chapter 10).
  4. flutter build ipa, then upload build/ios/ipa/*.ipa with the Transporter app, and send it to TestFlight first.
Store rules to keep in mind: digital goods inside the app (coins, episodes, VIP subscriptions) must use in-app purchases, which the app does. App Store rules restrict selling them through web payments inside the iOS app, so never add a link or button from the app to the website's checkout (chapter 11); the website's payments are for the website. Apps with sign-in must offer account deletion (Profile → Account → Delete account, included) and, on iOS, Sign in with Apple when Google sign-in is offered.

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.