Brainrush

01Welcome

Thank you for buying Brainrush. This guide is written for beginners: follow the chapters in order and you will have the server, the website and the app running under your own name and keys.

What is in the download

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: players, questions, games, coins, leagues. Question pictures, sounds and avatars live in S3-compatible storage (MinIO in the Docker stack, or Amazon S3, Cloudflare R2…). Firebase is used only for sign-in and push notifications.

Screenshots

The main screens, so you know what you are setting up. The names, photos and numbers are demo data; yours replace them.

Mobile app (iOS and Android)

Website

Admin panel (/admin)

02Requirements

To run the server

• A Linux server (VPS) with at least 2 CPU cores, 4 GB RAM and 20 GB disk. Ubuntu 24.04 is used in this guide.
• Docker with the Compose plugin (install guide).
• A domain name, for example your-domain.com, with a DNS record pointing at the server.

To build the mobile app

• Flutter 3.44 or newer (Dart 3.12; install), Android Studio for Android, a Mac with Xcode for iOS.
• Node.js 22 or newer for the rename tool, and pnpm (npm i -g pnpm) if you run the website without Docker.

Third-party services (accounts you will create)

• Firebase (required: sign-in and push).
• Optional, when you want them: RevenueCat (in-app purchases), Google AdMob (ads), an AI key from Anthropic, OpenAI or Google Gemini (question generator), any SMTP email provider.

03Quick start (Docker)

This gets the whole server running on your VPS in about 15 minutes. Sign-in needs the Firebase keys from chapter 4; you can do this chapter first and add them after.

1. Copy the kit to the server, for example with scp brainrush-1.0.0.zip root@YOUR_SERVER_IP:, then on the server:

   apt install -y unzip
   unzip brainrush-1.0.0.zip
   cd brainrush/deploy
   cp .env.example .env
   nano .env

2. In .env, fill at least these values:

   Key	What to put
   POSTGRES_PASSWORD	A long random password, letters and digits only (run openssl rand -hex 24 to make one).
   S3_SECRET_ACCESS_KEY	Another random value (at least 8 characters) for the built-in file storage.
   APP_URL	Your website address, e.g. https://your-domain.com (for a first test: http://YOUR_SERVER_IP:3000).
   NEXT_PUBLIC_FIREBASE_*, FIREBASE_*	From chapter 4.

3. Start everything:

   docker compose up -d

   The first build takes 5–10 minutes. Each start creates or updates the database tables, then loads the badges and coin packs.
4. Open APP_URL in a browser. The first visit opens the install wizard: your admin account, the app name and the sample quizzes (chapter 7). APP_URL/api/v1/health shows {"ok":true,…}.
5. Put it on your domain with HTTPS (chapter 5).

04Firebase setup

Firebase handles sign-in (guest, Google, Apple, email) and push notifications. Your data stays in your own database.

1. Go to the Firebase console → Add project. Give it your app name.
2. Build → Authentication → Get started → Sign-in method. Turn on: Anonymous (guest play), Google, Email/Password (players and staff) and Apple (see chapter 15).
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:…"

   The website reads these when it starts, so a restart (docker compose up -d) is enough after a change.
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. Add the mobile apps: Project settings → Your apps → Add app, once for Android and once for iOS, with your app id (for example com.yourcompany.brainrush; see chapter 16 to change it first). Download google-services.json and GoogleService-Info.plist: you only need to copy values out of them (the app does not use the files themselves). Or run flutterfire configure, which does the same and prints the values.
7. Put the values in brainrush_mobile_flutter/.env:

   Key in the app's .env	Where to find it
   FIREBASE_PROJECT_ID, FIREBASE_MESSAGING_SENDER_ID, FIREBASE_STORAGE_BUCKET	Project settings → General (project id, project number, storage bucket)
   FIREBASE_ANDROID_API_KEY, FIREBASE_ANDROID_APP_ID	google-services.json: api_key.current_key and mobilesdk_app_id
   FIREBASE_IOS_API_KEY, FIREBASE_IOS_APP_ID, FIREBASE_IOS_BUNDLE_ID, FIREBASE_IOS_CLIENT_ID	GoogleService-Info.plist: API_KEY, GOOGLE_APP_ID, BUNDLE_ID, CLIENT_ID
   GOOGLE_SERVER_CLIENT_ID	Authentication → Sign-in method → Google → Web SDK configuration → Web client ID (Google sign-in on Android)

8. iOS: copy ios/Flutter/Keys.xcconfig.example to ios/Flutter/Keys.xcconfig (the download already has one) and set GOOGLE_REVERSED_CLIENT_ID (the REVERSED_CLIENT_ID from GoogleService-Info.plist) and FIREBASE_ENCODED_APP_ID (your GOOGLE_APP_ID with the colons turned into dashes, e.g. 1:123:ios:abc → app-1-123-ios-abc).
9. Android Google sign-in needs your signing key fingerprints: run cd brainrush_mobile_flutter/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.

05Your domain and HTTPS

Easiest: the stack can get a free certificate for you with Caddy. Point your domain's DNS at the server, open ports 80 and 443, then in deploy/.env set DOMAIN="your-domain.com" and APP_URL="https://your-domain.com", and start with the https profile:

docker compose --profile https up -d

Already use Nginx, Traefik or Caddy on the server? Point your-domain.com at port 3000 (WEB_PORT), set APP_URL, run docker compose up -d, and leave the https profile off. Close port 3000 in your firewall once the proxy works (ufw allow 22,80,443/tcp && ufw enable).

Backups

cd brainrush/deploy
docker compose exec postgres pg_dump -U brainrush brainrush | gzip > backup-$(date +%F).sql.gz

Run it daily with cron and copy the files off the server. Uploaded pictures and sounds are in the minio-data Docker volume; back it up too, or use a cloud bucket (next chapter).

06Other hosting

Website on Vercel (or any Node host)

Costs: Vercel and managed database providers are third-party services with their own pricing; you are responsible for any hosting costs.

1. Create a PostgreSQL database (Neon, Supabase, Railway, or your own) and copy its connection string.
2. Import brainrush_web_nextjs into Vercel (Root directory: brainrush_web_nextjs). Add the keys of brainrush_web_nextjs/.env.example under Settings → Environment Variables, with DATABASE_URL set to your database and the S3_* keys set to a cloud bucket.
3. Create the tables once from your computer: in brainrush_web_nextjs, put the same DATABASE_URL in .env, then run pnpm install, pnpm prisma:migrate:deploy and pnpm prisma:seed --base. Then open your site: the install wizard does the rest.
4. The worker (battle clock, contest payouts, leagues, daily quizzes, pushes) runs all the time, so it cannot run on Vercel. Run it on any small server: cd brainrush_web_nextjs && pnpm install && pnpm worker with the same .env (use a process manager such as pm2 or systemd), or with Docker using deploy/docker-compose.yml's worker service.

Cloud storage instead of MinIO

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 and S3_SECRET_ACCESS_KEY. Keep the bucket private: files are served through your API. Without any S3_* key (outside Docker), uploads go to a local uploads/ folder.

07First admin and sample quizzes

The first visit to your site opens the install wizard (/install). It asks for:

• the app name (set your support email later in Admin → Settings),
• your name, email and password: this makes your super admin account (it creates the Firebase email account for you),
• whether to load the sample quizzes: 14 categories, about 830 questions in all six question types, daily quizzes, articles and badges. Keep them while you test; you can delete or edit any of it later.

Then sign in at https://your-domain.com/admin. Invite more staff from Admin → Roles (roles: super admin, content editor, moderator, finance). The wizard only runs while no super admin exists.

08Setup check

Open Admin → Setup check: it lists every key, says which are missing, and tests each connection (database, storage, Firebase sign-in, push, purchases, email, AI, worker) with a clear message. The same check runs in a terminal:

docker compose run --rm migrate pnpm run doctor     # Docker
cd brainrush_web_nextjs && pnpm run doctor          # without Docker

09Run the mobile app

1. cd brainrush_mobile_flutter. The download has a .env with empty values (a copy of .env.example). Set:

   API_BASE_URL=https://your-domain.com
   APP_NAME=Brainrush
   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 → keep Automatically manage signing on and choose your own Team. Xcode then creates the certificates and profiles for your bundle id. Do this on the All tab so Debug, Release and Profile use the same team.

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). Without the Firebase values the app shows a setup screen that says what is missing.

10In-app purchases (RevenueCat)

Costs: RevenueCat is a third-party service with its own pricing plans; you are responsible for any RevenueCat costs.

The app sells coin packs (consumables) and "Remove ads" (non-consumable) through the App Store and Google Play, with RevenueCat in between. The server is told about every purchase and adds the coins; 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 id of each pack is set in Admin → Coin Packs & IAP):
   • Coins (consumable): br.coins.500, br.coins.1200, br.coins.3000, br.coins.6500
   • Remove ads (non-consumable): br.removeads
2. In RevenueCat: create a project, add your iOS and Android apps and import the products. The app buys products by id, so no offering or entitlement is needed.
3. App keys: RevenueCat → Project → API keys → the public SDK keys. In brainrush_mobile_flutter/.env: REVENUECAT_APPLE_KEY and REVENUECAT_GOOGLE_KEY.
4. Server keys in deploy/.env: REVENUECAT_SECRET_KEY (a secret API key) and REVENUECAT_WEBHOOK_AUTH (any long random value).
5. RevenueCat → Integrations → Webhooks → add https://your-domain.com/api/v1/webhooks/revenuecat with the Authorization header value equal to REVENUECAT_WEBHOOK_AUTH.

The website does not sell coins: players buy them in the app, and the same balance shows on the website.

11Push notifications

Costs: Firebase Cloud Messaging is free; Apple needs your paid Apple Developer Program membership for the APNs key.

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. Every app joins the topic brainrush_all, and the server also sends to each player's own devices (battle invites, contest results, streak reminders, league results). Send your own messages from Admin → Notifications, now or scheduled.

12Ads (Google AdMob)

Costs: AdMob is a third-party Google service with its own terms and revenue share; you are responsible for any costs of using it.

The app has three ad types: rewarded (watch an ad to earn coins), interstitial (between games) and banner. Players who bought "Remove ads" see no interstitials or banners.

1. In AdMob, add your Android and iOS apps and create one ad unit of each type you want.
2. In brainrush_mobile_flutter/.env set ADMOB_ANDROID_APP_ID and the unit ids ADMOB_ANDROID_REWARDED_ID, ADMOB_ANDROID_INTERSTITIAL_ID, ADMOB_ANDROID_BANNER_ID, ADMOB_IOS_REWARDED_ID, ADMOB_IOS_INTERSTITIAL_ID, ADMOB_IOS_BANNER_ID.
3. The iOS app id goes in ios/Flutter/Keys.xcconfig: ADMOB_IOS_APP_ID=ca-app-pub-…~….
4. 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 in deploy/.env).
5. Control ads in Admin → Ads: on or off, coins per rewarded ad, rewarded ads per day, an interstitial every N games, banners on or off.

Google's test ad ids never send verification callbacks. So without your own rewarded ad ids, "Watch an ad" shows "No ad available right now", while interstitials and banners keep showing Google's test ads. For local testing only, AD_REWARDS_MODE="demo" on the server accepts rewarded ads without Google's callback — never use it on a live server, because anyone could claim the coins.

Other rewards are checked on the server too. Referral codes work only for signed-in players (not guests) in their first 7 days, only with the code of an older active player, never in a circle, and both sides are paid only after the new player's first real quiz (5 correct answers), with at most 20 paid invites per player and 5 per day. A guest's progress can be merged into an account only with the guest's own sign-in token, and each account takes in one guest only. Quiz coins are scored by the server from its own answer key.

When Google's confirmation is late or never comes

• Late (usually a second or two, sometimes longer): the app waits up to 10 seconds. If Google's callback arrives after that, the view is kept as confirmed-but-unpaid, and the worker pays it within a minute, once, inside the daily limit, with an inbox message "Your ad reward arrived".
• The app went offline right after the ad: the same worker step pays it when Google's callback reaches your server.
• Never (for example the callback URL is wrong, or test ad ids are used): nothing is paid, and the player sees "Google hasn't confirmed this ad yet". Check Admin → Setup check and the ad unit's Verify URL button in AdMob. Confirmed views older than a day are not paid.

Other networks join through AdMob mediation, set up in your AdMob account.

13AI question generator

Costs: Anthropic, OpenAI and Google Gemini charge per use (per token) on their own pricing pages; Gemini has a free tier with limits. The monthly quota in Admin → Settings → AI caps how many questions the generator writes.

Admin → AI Generator writes new questions for any topic, level and question type; you review them before they go live. Set one of ANTHROPIC_API_KEY, OPENAI_API_KEY or GEMINI_API_KEY in deploy/.env, or paste a key in Admin → Settings → AI. Without a key the page says "add your key", and you can still write questions by hand or import a CSV.

14Email

Costs: your SMTP provider's pricing applies; most have a free monthly allowance, then a fee per email.

Staff invites and password resets 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, emails are written to the server log instead (docker compose logs web), which is handy while testing. Player password resets are sent by Firebase.

15Sign-in methods

• Guest: Firebase Anonymous. Turn guest play on or off in Admin → Settings. A guest who signs in later keeps their coins and progress. The website's shared-quiz links use guest play for "Play in browser — no sign-up".
• Google: on in Firebase; Android needs the SHA fingerprints and GOOGLE_SERVER_CLIENT_ID, iOS needs GOOGLE_REVERSED_CLIENT_ID (chapter 4).
• Apple (required by Apple when you offer Google sign-in on iOS): Apple Developer → your app id → enable Sign in with Apple. In Firebase → Authentication → Apple, turn it on (for iOS only, the bundle id is enough).
• Email and password: players can create an account with email on the app and website; staff sign in at /admin with the account the wizard or an invite made.

16Rebrand: name, app id, colour

One command changes the app name everywhere (app, website, admin, emails, push topic), the Android application id and iOS bundle id, the brand colour (with its lighter and darker shades), the website font and the icons:

cd brainrush
node tools/rename.mjs --name "QuizNova" --id com.mycompany.quiznova --color "#2563EB" --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 brainrush_mobile_flutter
flutter pub get
dart run flutter_launcher_icons
dart run flutter_native_splash:create

then add the Firebase apps for the new app id (chapter 4) and rebuild the website (docker compose up -d --build). The folder names (brainrush_mobile_flutter and so on) stay as they are; people never see them. The app name shown inside the running app and website comes from Admin → Settings → App name too.

By hand: the app's colours are in brainrush_mobile_flutter/lib/theme/br_colors.dart (a light and a dark set) and the website's in brainrush_web_nextjs/src/app/globals.css (--br-primary and friends).

17Logo, icon and fonts

• Icons inside the app: Phosphor Icons (bold), bundled as a font in assets/fonts/Phosphor-Bold.ttf. Every icon the app uses is listed once in lib/theme/app_icons.dart, so you can swap one there.
• App icon: replace the 1024×1024 PNGs in brainrush_mobile_flutter/assets/icon/: icon.png (full square, no transparency), and for Android's round and squircle icons icon_foreground.png (your symbol on a transparent background, inside the middle two thirds) and icon_background.png. Then run dart run flutter_launcher_icons.
• Logo in the app and launch screen: assets/images/logo.png (512×512). The launch screen colour is under flutter_native_splash: in pubspec.yaml; run dart run flutter_native_splash:create after a change.
• Website icons: replace brainrush_web_nextjs/src/app/icon.png (256×256) and apple-icon.png (180×180).
• App fonts: Bricolage Grotesque (words) and Space Mono (numbers, timers and labels). Put your .ttf files in assets/fonts/, list them under fonts: in pubspec.yaml, and change the family names in lib/theme/app_theme.dart. Check the font's licence allows apps.
• Website fonts: --font in the rename tool swaps Bricolage Grotesque for another Google Font; Space Mono for numbers is set in brainrush_web_nextjs/src/app/layout.tsx (next/font/google).

18Basic edits

Permission texts (iOS)

iOS shows these when the app first asks. Change them in brainrush_mobile_flutter/ios/Runner/Info.plist; keep them honest and specific, or App Review rejects the build.

19Question bank: categories, CSV import, AI and reports

Each question belongs to a subcategory and a level. A level is played with questions per level picked at random from its pool, so put more questions in a level than are played (for example 15–20 for 10 played) for variety.

• Types: multiple choice (2–4 options), true/false, image (a picture plus options), audio (a sound plus options), maths (a formula plus options) and guess the word (the player builds the answer from letter tiles).
• CSV import (Admin → Questions → Import, up to 5,000 rows): download the template from that page, fill one row per question, and upload. The page checks every row and shows the problems before anything is saved.
• Pictures and sounds: upload them in the question editor (stored in your S3 storage).
• AI generator (Admin → AI Generator): pick a subcategory, level, difficulty and question types; drafts wait for a person to approve, edit or reject them (AI chapter).
• Bulk tools (Admin → Questions): select many questions to publish, unpublish or delete at once; drag categories into the order players see in Admin → Categories → Reorder.
• Players can report a wrong question; reports land in Admin → Reports with the reason and how often the question is answered right, so you fix the worst first.

20Game modes, step by step

Every mode is played against the server's clock and answer key: the app shows questions, the server decides what is right and what it pays. The table says how each mode plays and where you change it.

Progress: XP, streaks, leagues and badges

• XP and levels: every game pays XP; levels unlock avatar frames (bronze, silver, gold, diamond).
• Streaks: one finished game a day keeps the streak. A streak freeze (bought with coins, up to 2 held) covers one missed day; a lost streak can be bought back the same day.
• Weekly leagues: every Monday players join a group of 30 in their tier (bronze → diamond). XP earned that week ranks them; on Sunday night the top move up and the bottom move down, and the worker pays the tier rewards. Daily and weekly boards pay the top three when they reset.
• Badges: earned for milestones (games, streaks, battles won, perfect levels…). Edit the list and the rules in Admin → Badges.

21Coins and fair play

Coins are the game's money, so every coin change is decided on the server, inside a database transaction, and written to the coin history (coin_tx). The app only shows the balance the server sends. These rules are on by default:

22Extend it: a new API route and a new worker job

Two small examples that follow the kit's own patterns. Make the change, run pnpm typecheck and pnpm test in brainrush_web_nextjs, then rebuild (docker compose up -d --build).

A new API route: a random fact for Home

1. Create brainrush_web_nextjs/src/lib/server/handlers/facts.ts:

   import { prisma } from "@/database/prisma_client/database";
   import { json } from "@/lib/server/http";
   import { route } from "@/lib/server/router";
   
   /** A random explanation from a live question, for a "Did you know?" card. */
   route("GET", "/facts/random", async ({ auth }) => {
     await auth.user(); // signed-in players only (guests count)
     const where = { status: "live" as const, explanation: { not: "" } };
     const count = await prisma.question.count({ where });
     const [q] = await prisma.question.findMany({ where, skip: Math.floor(Math.random() * Math.max(count, 1)), take: 1 });
     return json({ fact: q?.explanation ?? null });
   });

2. Register it with the others in src/lib/server/api.ts: add import "@/lib/server/handlers/facts";.
3. Call it from the app: ref.watch(apiGet('/facts/random')) gives you {fact: …} with loading and error states (see lib/pages/home/home_page.dart for the same pattern with /me/home).

A new worker job: a Sunday reminder

The worker (src/worker/index.ts) runs a list of timed tasks; only one worker runs them even if you start two. Add an entry to tasks:

{
  name: "sunday-reminder",
  everyMs: 3_600_000, // checks once an hour
  last: 0,
  run: async () => {
    const now = new Date();
    if (now.getUTCDay() !== 0 || now.getUTCHours() !== 17) return;
    // a scheduled campaign, as if made in Admin → Notifications; the "campaigns" task sends it within a minute
    await prisma.pushCampaign.create({ data: { title: "Leagues close tonight", body: "One more game could move you up a tier.", audience: "all", scheduledAt: now } });
  }
}

23Every key, explained

"Where" says which .env file it goes in: Docker = deploy/.env (website and worker in the Docker stack), website = brainrush_web_nextjs/.env (without Docker), app = brainrush_mobile_flutter/.env. Admin → Setup check shows the same list with the live status of each key.

24File structure

Mobile app (brainrush_mobile_flutter/lib)

main.dart            loads .env, starts Firebase, runs the app (short on purpose)
app.dart             theme, router and app-wide listeners
router.dart          every route (go_router) and the sign-in / setup gates
config/              .env values (app_env.dart) and Firebase options
api/                 the typed client for your server (/api/v1)
models/              data models parsed from the API
providers/           app-wide state (Riverpod): session, config, wallet, home…
services/            push, purchases (RevenueCat or demo), ads (AdMob), sounds, sign-in
theme/               colours (br_colors.dart), fonts and text styles
components/          shared widgets, names start with cc_ (buttons, cards, sheets, avatars…)
pages/               one folder per area: launch, auth, home, play, quiz, results, battle, compete,
                     leagues, exam, learn, create, store, profile, settings…
utils/               formatting and small helpers

Lists and grids use the lazy .builder constructors, and state flows through Riverpod providers rather than long chains of widget parameters.

Server (brainrush_web_nextjs/src)

app/(site)/               the public website (landing, play, leaderboard, contests, shared quizzes…)
app/(game)/quiz/          the full-screen quiz player
app/admin/                Admin panel pages
app/install/              the first-run wizard
app/api/v1/[...path]/     the single API entry point; routes live in lib/server/handlers/
components/site|play|panel|ui   website, quiz player, admin and base UI (shadcn) components
lib/server/handlers/      every API route by area: play, compete, social, me, admin…
lib/server/               games and scoring, battles, contests, leagues, exams, economy, purchases,
                          storage, email, AI, push, settings, setup check
database/prisma_client/   database schema (schema.prisma) and migrations
database/seed/            the sample quizzes, badges and coin packs
worker/                   background jobs (pnpm worker)
scripts/doctor.ts         the setup check in a terminal
tests/                    API tests (Vitest); e2e/ has browser smoke tests (Playwright)

25API reference (181 routes)

The app, the website and the Admin panel all use the same JSON API under https://your-domain.com/api/v1. Signed-in calls send the Firebase ID token as Authorization: Bearer <token>; the server checks it and finds the player. Errors come back as {"error": {"code": "…", "message": "…"}} with a matching HTTP status. This table is generated from the route files when the download is built, so it lists exactly the routes the server has.

26Database (PostgreSQL)

All data lives in one PostgreSQL database, managed by Prisma. The schema is brainrush_web_nextjs/src/database/prisma_client/schema.prisma and every change ships as a migration in …/prisma_client/migrations/, applied by pnpm prisma:migrate:deploy (the Docker stack runs it on start). Never edit the tables by hand on a live server: add a field in schema.prisma, run pnpm prisma:migrate:dev --name your_change on your computer, and ship the new migration folder.

The 39 tables, generated from the schema:

27Publish to the stores

You publish the app under your own developer accounts. Before you start: set your app id (chapter 16), your Firebase values (chapter 4) and an https API_BASE_URL. The stores ask for a privacy policy link: https://your-domain.com/privacy; terms are at /terms. Players delete their account in the app (Profile → Settings → Account → Delete account).

Google Play

1. Create an upload key inside android/app: cd brainrush_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, game progress, purchase history, device ids for ads and push) 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, and 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.

28Updating

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

29FAQ and troubleshooting

The site opens the install wizard again

The wizard shows only while no super admin exists. If you see it on a site you already set up, the site is connected to an empty database: check DATABASE_URL / the POSTGRES_* values.

Sign-in fails on the website

Add your domain under Firebase → Authentication → Settings → Authorized domains, check the NEXT_PUBLIC_FIREBASE_* values, and restart (docker compose up -d).

Google sign-in fails on Android

Add the SHA-1 and SHA-256 of the key that signed the build to Firebase, and check GOOGLE_SERVER_CLIENT_ID is the Web client id.

Battles never find an opponent

Matchmaking and the battle clock run in the worker. Check it runs: docker compose logs worker; Admin → Setup check shows when it last answered. With few players, a bot joins after the wait set in Admin → Battles.

Purchases say DEMO

No RevenueCat key is set yet. That is on purpose: add your keys (chapter 10).

Push notifications do not arrive

iOS needs the APNs key in Firebase, and the phone must allow notifications. Admin → Setup check 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 in the phone's browser.

Images or sounds in questions do not load

Check the S3_* keys and Admin → Setup check → File storage. With a cloud bucket, the server needs read and write access to it.

I changed .env and nothing happened

Server: docker compose up -d. App: stop it and run it again.

Where are the logs?

docker compose logs -f web and docker compose logs -f worker.

30Credits

The services in Third-party services 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.

Brainrush is built on these open-source projects. Each keeps its own licence (mostly MIT, BSD-3 or Apache 2.0).

Mobile app

Flutter, flutter_riverpod, go_router, FlutterFire (firebase_core, firebase_auth, firebase_messaging), google_sign_in, sign_in_with_apple, purchases_flutter (RevenueCat), google_mobile_ads, audioplayers, flutter_dotenv, shared_preferences, http, intl, share_plus, url_launcher, package_info_plus, image_picker, qr_flutter, connectivity_plus, flutter_launcher_icons, flutter_native_splash.

Website, Admin, API and worker

Next.js, React, Prisma, PostgreSQL, pg, Zod, Tailwind CSS, shadcn/ui, Base UI, Phosphor Icons, Sonner, next-themes, qrcode, Nodemailer, Firebase JS SDK, Firebase Admin SDK, AWS SDK for JavaScript, MinIO, Caddy, Docker.

Fonts

Bricolage Grotesque and Space Mono, SIL Open Font License 1.1 (licence files in assets/fonts/). Phosphor Icons, MIT licence.

Content

The sample questions, explanations, articles, flag pictures, audio clips, sound effects, category names and player names are original and part of your licence.

31Changelog

1.0.0 — 2026-10-22

First release. See CHANGELOG.md in the download for the full list.

32Support

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.