Set up your school, step by step.

Welcome

Thank you for buying Learnova. 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

What it looks like

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. Lesson videos, thumbnails, files and certificates 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.

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

Instructor dashboard (/instructor)

Admin panel (/admin)

Requirements

To run the server

• A Linux server (VPS) with at least 2 CPU cores, 4 GB RAM and 40 GB disk (more disk for many videos). Ubuntu 24.04 is used in this guide.
• Docker with the Compose plugin (install guide).
• A domain name, for example your-domain.com, with two DNS records pointing at the server: your-domain.com and storage.your-domain.com.

To build the mobile app

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

Third-party services (accounts you will create)

• Firebase (required: sign-in and push).
• Optional, when you want them: RevenueCat (Plus subscriptions in the apps), Stripe / PayPal / Razorpay / Paystack / Flutterwave (website payments), any OpenAI-compatible AI provider (study buddy and transcripts), any SMTP email provider.

What each service costs

Prices change, so check each provider's pricing page before you launch. This is how each one charges, so you know what grows with your school.

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 learnova-1.0.0.zip root@YOUR_SERVER_IP:, then on the server:

   apt install -y unzip
   unzip learnova-1.0.0.zip
   cd learnova/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 (run openssl rand -hex 24 to make one).
   APP_URL	Your website address, e.g. https://your-domain.com.
   MEDIA_SIGNING_SECRET	Another random value (openssl rand -hex 24).
   S3_ACCESS_KEY_ID / S3_SECRET_ACCESS_KEY	A user name and a long password you choose for the built-in MinIO storage.
   S3_PUBLIC_ENDPOINT	The 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 (courses, instructors, learning paths, Plus plans, pages, FAQ and a year of sample sales), so every screen has content.
4. Check it: open http://YOUR_SERVER_IP:3000. You should see the home page with the sample courses. 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).

Firebase setup

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

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: Email/Password (learners and staff), Google, Anonymous (guest browsing) and Apple (see chapter 18).
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-----\n(your key)\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 learnova_mobile_flutter
   flutterfire configure --project your-project --platforms android,ios \
     --android-package-name com.yourcompany.learnova --ios-bundle-id com.yourcompany.learnova

   Use your own app id here (see chapter 24 to change it first). Then copy the values into learnova_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 sign-in needs 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.

Put it online (VPS, HTTPS)

The Docker stack listens on port 3000 (website) and 9000 (storage). Put a web server with free HTTPS in front of both. Caddy is the easiest:

apt install -y caddy
cat > /etc/caddy/Caddyfile <<'EOF'
your-domain.com {
  reverse_proxy localhost:3000
}
storage.your-domain.com {
  reverse_proxy localhost:9000
}
EOF
systemctl reload caddy

Then in deploy/.env set APP_URL="https://your-domain.com" and S3_PUBLIC_ENDPOINT="https://storage.your-domain.com", and run docker compose up -d. Caddy gets the certificates by itself.

Already use Traefik or Nginx? Point your-domain.com at port 3000 and storage.your-domain.com at port 9000 in the same way. Close ports 3000, 9000 and 9001 in your firewall once the proxy works (ufw allow 22,80,443/tcp && ufw enable). The MinIO console (port 9001) is for you only; reach it through an SSH tunnel: ssh -L 9001:localhost:9001 root@YOUR_SERVER_IP.

Backups

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

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

Other hosting (Vercel, cloud storage)

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

Website on Vercel

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 learnova_web_nextjs into Vercel (Root directory: learnova_web_nextjs). Add every key of learnova_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 learnova_web_nextjs, put the same DATABASE_URL in .env, then pnpm install, pnpm prisma:migrate:deploy, pnpm first-run.
4. The worker (video conversion, transcripts, push, reminders) needs ffmpeg and runs all the time, so it cannot run on Vercel. Run it on any small server with Docker: cd learnova_worker && docker build -t learnova-worker . && docker run -d --restart unless-stopped --env-file .env learnova-worker with the worker's .env filled from .env.example.

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, 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 (instructors upload straight to the bucket, and the website plays from it).

First admin and sample data

Create your own admin account (it makes the Firebase email account when it does not exist yet):

cd learnova/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 learnova_web_nextjs && pnpm admin:create you@example.com. Invite more staff from Admin → Roles & staff (chapter 19).

The sample data

The first start fills an empty database with sample categories, courses with lessons and quizzes, instructors, learners, learning paths, coupons, Plus plans, pages, FAQ and a year of sample sales, so you can see every screen working (dashboards, earnings, reports). Sample lessons play one short original clip until you upload real videos. When you are ready to go live:

• Unlist or archive the sample courses in Admin → Courses, and remove the sample instructors in Admin → Instructors, or keep them as placeholders while your own instructors upload.
• Check Plans & Plus, Coupons, Pages & FAQ (terms, privacy, refund policy) and Settings and edit them for your business.
• To start from a completely empty database instead, run docker compose down -v (this deletes all data and videos), set SEED_SALES_HISTORY=false in .env to skip the sample sales, then docker compose up -d again.

Setup check

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

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

Use pnpm run doctor, not pnpm doctor (that one is pnpm's own check of your pnpm install).

Run the mobile app

1. cd learnova_mobile_flutter, then copy .env.example to .env (the download already has one with empty values) and set:

   API_BASE_URL=https://your-domain.com
   APP_NAME=Learnova
   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).

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

Learnova Plus in the apps (RevenueCat)

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

Learners buy single courses, and can subscribe to Learnova Plus for every Plus course, unlimited AI questions, offline downloads and certificates. Inside the iOS and Android apps, Plus is sold through the App Store and Google Play with RevenueCat in between. The server is told about every purchase and gives access; the app never decides access itself.

1. Create the subscriptions in App Store Connect and Google Play Console (one subscription group) with these ids, or your own (the ids are stored with each plan in Admin → Plans & Plus): learnova_plus_monthly, learnova_plus_yearly, learnova_plus_student.
2. In RevenueCat: create a project, add your iOS and Android apps, import the products, create an entitlement plus with the Plus products, and an offering default (current) with the Plus packages.
3. App keys: RevenueCat → Project → API keys → the public SDK keys. In learnova_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) and REVENUECAT_WEBHOOK_SECRET (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_SECRET.

Single courses and learning paths are paid in the app with the same checkout as the website: wallet, bank transfer, or the gateways from chapter 11, whose payment page opens in the browser. Courses bought on the website open in the app too. A share of each month's Plus revenue is paid to instructors by minutes watched; set the share in Admin → Settings → Learnova Plus.

Website payments

On the website, learners pay for courses, learning paths and Plus with any gateway you set up. Each gateway appears at checkout when its keys are set; switch them on or off in Admin → Settings → Payment gateways (the Configure button shows which keys are set and the webhook address to copy).

PayPal, Razorpay, Paystack and Flutterwave take one-time payments, so Plus bought with them is a pass for one period that the learner renews by buying again. Every payment is credited once, even when the return page and the webhook both arrive. Refunds from Admin → Orders go back through the same gateway; learners ask for refunds from their order page, within the window you set.

Currency and tax

• Admin → Settings → Currency & tax: the checkout currency and whether prices include tax (EU, UK, AU style) or tax is added at checkout (US style).
• Add a tax rule per country, US state or Canadian province (and one "European Union" rule as a fallback for EU countries). Checkout uses the most specific active rule for the billing address, shows it on the receipt, and the Reports → Tax / VAT tab totals it.

Push notifications

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: learnova_all and learnova_<language>. Send campaigns from Admin → Push notifications to everyone, Plus members, a course's learners, or one learner, now or scheduled. Learners also get pushes for replies, live-class reminders and announcements, and can turn each kind off in the app.
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).

Video lessons and storage

Instructors upload lesson videos in Instructor → Courses → Curriculum. The file goes straight to your storage; the worker then makes streaming versions (1080p down to 360p, HLS) and a poster, and the lesson plays in the app and on the website with signed links that expire. Learners with Plus can download lessons for offline viewing in the app. Lesson files (PDFs, code) and assignment uploads are stored the same way.

AI study buddy and transcripts

Learners ask the AI study buddy about a lesson; instructors get draft answers in Q&A and quiz question drafts; the worker writes lesson transcripts. Set AI_API_KEY (and AI_BASE_URL for a provider other than OpenAI — Gemini, OpenRouter and Groq offer OpenAI-compatible URLs), and optionally AI_MODEL. For transcripts set SUBTITLE_PROVIDER=openai (any Whisper-compatible API). Free learners get a daily number of AI questions (Admin → Settings → Learnova Plus); Plus members have no limit. Without a key, the AI buttons say "add your key".

Live classes

Instructors schedule live sessions in Instructor → Live classes with a meeting link (Zoom, Google Meet, Teams…; a default link is set once in Instructor → Settings → Integrations). Booked learners see the session in the app and on the website, get a reminder before it starts (the time is set in Admin → Settings → Live classes), and join with one tap. Cohort courses sell seats for a scheduled run.

Email

Receipts, refund decisions, instructor application and course review results, staff invites, password resets and contact-form messages 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). Set the sender name and address in Admin → Settings → Email (SMTP) and press Send test email. Without SMTP_HOST, emails are written to the server log instead (docker compose logs web), which is handy while testing.

Sign-in methods

• Email and password: on in Firebase. Learners sign up, verify and reset their password from the app or website.
• Google: on in Firebase; Android needs the SHA fingerprints, iOS needs GOOGLE_REVERSED_CLIENT_ID (chapter 4).
• Guest: Firebase Anonymous. Learners browse and preview without an account; turn it on or off in Admin → Settings → General. A guest who signs up keeps their progress.
• Apple (required by Apple when you offer Google sign-in on iOS): Apple Developer → your app id → enable Sign in with Apple. In Firebase → Apple provider, add your Services ID, Team ID, Key ID and the .p8 key. On the server set APPLE_TEAM_ID, APPLE_KEY_ID, APPLE_CLIENT_ID (your bundle id) and APPLE_PRIVATE_KEY so account deletion also revokes the Apple sign-in, as Apple requires. Set NEXT_PUBLIC_AUTH_APPLE=true to show it on the website too.
• Staff sign in with email and password at /admin/login. Two-step verification uses an authenticator app (Google Authenticator, 1Password, Authy…). To offer it: in the Google Cloud console upgrade Firebase Authentication to Identity Platform, then turn on TOTP in Firebase → Authentication → Sign-in method → Multi-factor authentication. Each staff member then opens the account menu (top right) in the admin → Two-step verification, scans the QR code and enters a code; from then on sign-in asks for a 6-digit code after the password. To make it compulsory set ADMIN_REQUIRE_MFA=true once everyone is enrolled. Someone who loses their phone: a super admin opens them in Admin → Roles & staff and presses Reset under Two-step verification.

Staff and roles

Admin → Roles & staff lists your team. Invite someone by email and pick a role; they get a link to choose a password (valid 72 hours, and you can resend it). Built-in roles: Super admin (everything, the only role that manages staff), Content reviewer, Support, Finance and Marketing. Open a role to tick, per area (courses, orders, payouts, settings…), what it may view, create, edit, delete and approve, or create your own roles. The admin menu only shows the areas a role can open. Every change made in the admin is recorded in Admin → Audit log.

Instructors apply from the website (/teach); you approve them in Admin → Instructors and set their revenue share. Their courses wait in Admin → Courses → In review until you approve them (or turn on "Publish new courses without review" in Settings → Learning & payouts).

Instructor studio: publish a course step by step

Every instructor works in the studio at /instructor on the website. This is the whole path from an empty course to one learners can buy.

1. New course. Studio → Courses → New course. Give it a title and a subject; it starts as a draft only you can see.
2. Details. Subtitle, description, what learners will learn, requirements, level, language, captions. Upload a thumbnail (the cover photo, 1280×720 or larger) and, if you like, a short promo video.
3. Curriculum. Add sections, then lessons in each: Video (upload the file; the worker turns it into streaming quality levels and writes the transcript when AI is set up), Article, Quiz (questions, the right answers, a pass mark), Assignment (a brief, a due date, points) or Live (a session in a cohort). Drag to reorder. Tick Free preview on a lesson anyone may watch before buying. Attach downloadable files to any lesson.
4. Pricing. Set the price, an optional sale price with an end date, and whether the course is part of Learnova Plus. Instructors can also make coupons for their own courses.
5. Submit for review. The checklist on the course page must be complete first: at least 5 lessons, every video processed, a thumbnail, a subtitle and a description. The course then waits in Admin → Courses → In review.
6. Review. An admin approves it (it goes live in the catalogue) or requests changes with notes; the instructor fixes and submits again. To skip review on your own school, turn on "Publish new courses without review" in Admin → Settings → Learning & payouts.

Certificates

A learner gets a certificate automatically when they have completed every lesson of a course that offers one, and passed its final quiz if it has one. Finishing every course in a learning path adds a path certificate. Each certificate has an id like LNV-2026-04217 and a public page at /verify/<id> with a QR code, so an employer can check it.

• Designs: Admin → Certificates → Templates. Pick the default template, its colours, signature name and title.
• Revoke: Admin → Certificates, open one and revoke it. The verify page then says it was revoked.
• Pass mark: Admin → Settings → Learning & payouts → "Certificate pass mark" (70% by default) is the starting pass mark for new quizzes.

Earnings, the Plus pool and payouts

Instructors earn in two ways. All amounts are kept in whole cents, so totals always add up.

1. New earnings are on hold for the refund window (30 days by default), then become available.
2. The instructor sets a payout method in Studio → Settings and requests a payout once the available balance reaches the minimum ($50 by default).
3. An admin with the payouts permission marks it paid (after sending the money), puts it on hold, or rejects it in Admin → Payouts. Every step is in the audit log.

Admin panel tour

The admin panel is at /admin. Across the top are the modules; under them, the pages of the current module. Press ⌘K (Ctrl+K on Windows) anywhere to jump to a course, learner or order.

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 learnova
node tools/rename.mjs --name "MyAcademy" --id com.mycompany.myacademy --color "#0EA5E9" --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 learnova_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 (learnova_mobile_flutter and so on) stay as they are; they are never shown to users.

By hand: the brand colours are in learnova_mobile_flutter/lib/core/theme/app_colors.dart (app) and learnova_web_nextjs/src/app/globals.css (website, --brand, --brand-soft, --brand-ink); the app name is APP_NAME in the app's .env and NEXT_PUBLIC_APP_NAME on the server; the name in emails, receipts and certificates is Admin → Settings → General → Platform name.

Logo, icon and fonts

• App icon and splash: replace the PNGs in learnova_mobile_flutter/assets/icon/ (1024×1024: icon_ios.png without transparency, icon_android.png, icon_foreground.png for Android adaptive icons, icon_splash.png), then run dart run flutter_launcher_icons and dart run flutter_native_splash:create. The splash and adaptive-icon background colours are in flutter_native_splash.yaml and pubspec.yaml.
• Website icons: replace learnova_web_nextjs/src/app/icon.png (512×512), apple-icon.png (180×180) and favicon.ico. The logo mark next to the name is src/components/shared/logo.tsx.
• App fonts: the app uses three families: Fraunces for headings and big numbers (display), Instrument Sans for everything else (family) and IBM Plex Mono for small labels and counters (mono). To change one, put your .ttf files in assets/fonts/, list them under fonts: in pubspec.yaml, and change the matching name at the top of lib/core/theme/app_text.dart. Check the font's licence allows apps.
• Website fonts: --font in the rename tool changes the interface font (Instrument Sans); the heading serif, the mono labels and the handwriting used for learner notes are the other next/font/google imports in learnova_web_nextjs/src/app/layout.tsx.

Basic edits

Every key, explained

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

File structure

Mobile app (learnova_mobile_flutter/lib)

main.dart                 starts Firebase, loads .env, runs the app (short on purpose)
app.dart                  theme, router and app-wide listeners
components/               shared widgets (buttons, sheets, cards, tab bar) — names start with cc_
core/
  constants/              every .env value the app reads, app-wide constants
  router/                 all routes (go_router)
  theme/                  colours, text styles, icons, spacing
  providers/              app-wide state (Riverpod): session, config, subscription, sync…
  services/api/           the typed API client for your server (/api/v1) and its offline cache
  services/firebase/      sign-in, notifications, analytics
  services/general/       RevenueCat purchases (or demo mode), reviews, sharing
domain/models/            data models parsed from the API
features/                 one folder per area, each with pages/ widgets/ providers/
  launch  auth  home  explore  course  commerce  learning  player
  study  live  progress  downloads  profile

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

Server (learnova_web_nextjs/src)

app/(site)/               the public website (home, courses, paths, checkout, library, orders, Plus…)
app/learn/                the full-screen course player
app/instructor/           Instructor dashboard pages
app/admin/                Admin panel pages
app/api/v1/[...path]/     the single API entry point; routes live in lib/server/handlers/
components/site|instructor|admin|panel|ui   website, dashboard and admin components, base UI (shadcn)
lib/server/handlers/      every API route, by area: catalog, learning, quiz, commerce, plus, engagement, ai,
                          instructor, admin, system
lib/server/               auth, payments (store.ts, gateways.ts, commerce.ts), storage (media.ts), email, AI,
                          certificates (pdf.ts), settings, setup check
lib/api/schemas/          request validation (Zod)
database/prisma_client/   database schema (schema.prisma) and migrations
database/seed/            sample data and the sample clip
scripts/                  doctor, first-run, admin:create, seed:sales
tests/                    API tests (Vitest); e2e/ has the browser smoke tests (Playwright)

Worker (learnova_worker/src)

index.ts                  job queue (pg-boss on your PostgreSQL) and schedules
jobs/transcode.ts         uploaded video → HLS 1080p–360p + MP4 + poster (ffmpeg)
jobs/transcript.ts        lesson transcripts (Whisper-compatible API)
jobs/push.ts              push campaigns and personal notifications
jobs/live.ts              live-class reminders
jobs/orders.ts            expires unpaid bank-transfer orders
jobs/plus-pool.ts         monthly Plus revenue share for instructors
jobs/badges.ts, purge.ts  achievement badges, clean-up

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

A worked example: a "course of the day" that the worker picks every morning and the app can read.

1. The API route

Routes live in learnova_web_nextjs/src/lib/server/handlers/, one file per area, and every file is imported once in src/lib/server/api.ts. Add to handlers/catalog.ts:

/** The course of the day, picked by the worker every morning. */
route("GET", "/course-of-the-day", async () => {
  const row = await prisma.setting.findUnique({ where: { group_key: { group: "daily", key: "course" } } });
  if (!row) throw errors.notFound("Course of the day");
  const [card] = await courseCards({ id: row.value as string });
  return json({ course: card ?? null });
});

It answers at GET /api/v1/course-of-the-day. Need a signed-in user? Start the handler with const user = await auth.user();. Staff only? await auth.staff("courses", "view") — the area and action match the permission grid in Admin → Roles & staff.

2. The worker job

Jobs live in learnova_worker/src/jobs/. Add "course-of-the-day" to the QUEUES list in learnova_worker/src/index.ts, write the job, and schedule it next to the others:

// learnova_worker/src/jobs/daily.ts
import { query } from "../db";

export async function pickCourseOfTheDay(): Promise<number> {
  const [c] = await query<{ id: string }>("SELECT id FROM courses WHERE status = 'published' ORDER BY random() LIMIT 1");
  if (!c) return 0;
  await query(
    `INSERT INTO settings ("group", key, value, updated_at) VALUES ('daily', 'course', $1::jsonb, now())
     ON CONFLICT ("group", key) DO UPDATE SET value = EXCLUDED.value, updated_at = now()`,
    [JSON.stringify(c.id)]
  );
  return 1;
}

// learnova_worker/src/index.ts: import it at the top, then add after the other schedules
await every("course-of-the-day", "0 6 * * *", pickCourseOfTheDay, "course of the day picked");

Restart the worker (docker compose up -d --build worker). For a job the website starts instead of a schedule, call enqueue("your-queue", { … }) from src/lib/server/jobs.ts in the API and boss.work("your-queue", …) in the worker.

3. Show it in the app

Add a provider in lib/core/providers/data_providers.dart that reads ref.watch(apiClientProvider).get('/course-of-the-day'), and watch it in the Today page (lib/features/home/pages/home_page.dart) with ref.watch(...).

API reference

The website, the instructor studio, the admin panel and the mobile app all use one JSON API under /api/v1. The 293 routes, grouped by area. "Auth" says who may call it: Signed in needs a learner's Firebase ID token (Authorization: Bearer …, or the website session cookie); Instructor an approved instructor; Staff: area · action a staff role with that permission; Signed by the provider a payment provider's webhook signature.

Database (PostgreSQL)

All data lives in PostgreSQL, described in learnova_web_nextjs/src/database/prisma_client/schema.prisma and changed only through migrations (pnpm prisma:migrate:dev to make one, pnpm prisma:migrate:deploy to apply them; the Docker migrate service runs the second for you). Money is stored as whole cents with a currency. The 62 tables:

App permissions and store ids

The app asks for a permission only when the learner uses the feature. These are the texts the system shows; change them in the files named here before you publish (the stores reject vague texts).

Placeholder ids to replace

These ids are placeholders in the download. Replace each with your own before you publish.

The app has no ads, so there are no ad unit ids to set.

Publish to the stores

You publish the app under your own developer accounts. Before you start: set your app id (chapter 24), your Firebase files (chapter 4), an https API_BASE_URL, and your privacy, terms and account deletion pages (Admin → Pages & FAQ; the stores ask for these links).

Google Play

1. Create an upload key inside android/app: cd learnova_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, learning progress, device ids for push, crash logs; the "Delete account URL" is https://your-domain.com/delete-account, its text is in Admin → Pages), 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 Plus subscriptions (chapter 10).
4. flutter build ipa, then upload build/ios/ipa/*.ipa with the Transporter app, and send it to TestFlight first.

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.

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 lesson stays "processing"

The worker converts videos. Check it runs: docker compose logs worker. The curriculum editor 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).

Checkout says DEMO

No payment key is set yet. That is on purpose: add your gateway or RevenueCat keys (chapters 10–11).

A gateway does not show at checkout

Its keys are missing, or it is switched off in Admin → Settings → Payment gateways. Admin → Setup tests each gateway's keys.

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

Credits and licences

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.

Learnova 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, firebase_analytics, firebase_crashlytics, firebase_app_check), google_sign_in, sign_in_with_apple, purchases_flutter (RevenueCat), video_player, video_player_web_hls, hive_ce_flutter, http, flutter_dotenv, lucide_icons_flutter, shimmer, flutter_styled_toast, url_launcher, share_plus, in_app_review, package_info_plus, connectivity_plus, path_provider, wakelock_plus, image_picker, file_picker, flutter_markdown_plus, shared_preferences, intl, flutter_launcher_icons, flutter_native_splash.

Website, dashboards 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, pdf-lib, qrcode, Nodemailer, Firebase Admin SDK, FFmpeg, MinIO, Docker.

Fonts

Fraunces, Instrument Sans, IBM Plex Mono and Caveat (website notes), SIL Open Font License 1.1. The app bundles the first three with their licence files in learnova_mobile_flutter/assets/fonts/; the website loads them with next/font at build time.

Content

The sample course texts, quizzes, instructor and learner 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.

Changelog

1.0.0 — 2026-10-22

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

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.