Harmonia Documentation

Feature Walkthrough

A plain-language tour of what the app does, so you can find your way around before touching any code. Nothing in this section needs programming knowledge — the technical setup starts at section 1.

First launch

• Splash screen — your logo and tagline while the app loads its settings from the backend. If you turned on maintenance mode or a forced update in the admin panel, the listener sees that message here instead.
• Sign in or skip — e-mail and password, Google, Facebook or Apple. Listeners can tap Skip and browse as a guest; the app asks them to sign in when they try something that needs an account, such as liking a song.
• Music taste — after the first sign-in, listeners pick genres and artists they like. This shapes their Home feed and recommendations, and can be changed later in Settings.
• Home — the listener lands on the Home tab.

The four main tabs

Listening

• Mini player and full player — a mini player follows the listener through the app; tapping it opens the full player with artwork, seek bar, shuffle and repeat.
• Up next and lyrics — reorder the queue, read synced lyrics, open full-screen lyrics and share a lyric card.
• Listening tools — sleep timer, playback speed, equalizer (Android), crossfade, volume normalisation and autoplay of similar songs.
• Anywhere — background playback with lock-screen controls, Chromecast, Android Auto and an Android home-screen widget.
• Offline — Premium listeners download songs and albums and play them without a connection.

Free and Premium

You decide which songs, albums and playlists are Premium. Free listeners see Premium content locked and hear ads; Premium listeners get ad-free listening, downloads and Premium-only content. Premium is sold as a subscription through Google Play Billing (see section 11).

Settings

Profile and photo, your devices (sign any device out remotely), music taste, manage subscription, playback options, audio quality, push notifications, theme (light, dark or system), language (English or Bangla), clear cache, legal pages, credits, sign out and delete account.

What you control from the admin panel

Almost everything listeners see is managed in the browser, without rebuilding the app: songs, albums, artists, playlists, shorts, home sections, banners, moods and genres, Premium plans and the Premium screen text, ads, push notifications, app version and maintenance mode, legal links, app users and staff accounts. The full list is in section 14.

Third-Party Services and Costs

Harmonia is self-hosted: you receive the full source code, with no licence keys and nothing payable to us. Some features connect to outside services that are not included in the purchase.

How the Pieces Connect (Architecture)

Harmonia is three projects that talk to one backend. Only the backend talks to the database and holds secrets; the app and the admin panel never connect to PostgreSQL or R2 credentials directly.

1. Prerequisites

Use these versions for the smoothest build. The app was built and tested with the versions marked "tested".

Server size

The backend, PostgreSQL and the admin panel can run together on one Linux server (Ubuntu 22.04 or 24.04 LTS recommended). Audio and images are stored in Cloudflare R2, not on the server, so the disk only needs room for the code, the database and temporary files during uploads.

CPU matters most when you upload songs, because FFmpeg converts each one into three stream qualities. Building the admin panel (npm run build) needs about 1.5 GB of free RAM; on a 2 GB server add swap first. A shared hosting plan (cPanel without SSH and Node.js) is not enough; you need a VPS or cloud server with SSH access.

2. Environment Setup

Select your operating system to see the setup steps.

Open and run the app

cd Flutter-App
flutter pub get
flutter run

Generated code (models and translations) is already included. Regenerate it only after you change models or translation files:

dart run build_runner build --delete-conflicting-outputs
flutter gen-l10n

3. Change Package Name and Bundle ID

Every app needs a unique identifier, for example com.yourcompany.music. Change it before you set up Firebase, because Firebase apps are registered by this identifier.

Android

iOS

• Open ios/Runner.xcworkspace in Xcode.
• Select the Runner target > Signing & Capabilities, choose your Team and enter your Bundle Identifier.
• Do the same for the RunnerTests target (use <your bundle id>.RunnerTests).

4. Firebase Setup

Firebase provides sign-in and push notifications.

Step 1: Create a Firebase project

• Open the Firebase console and click Create a project. Enter a name and accept the terms.
• Choose whether to enable Gemini and Google Analytics (neither is needed by Harmonia), then click Create project.

Step 2: Connect the app (recommended: FlutterFire CLI)

The FlutterFire CLI registers your Android and iOS apps and writes all config files for you.

npm install -g firebase-tools
firebase login
dart pub global activate flutterfire_cli
cd Flutter-App
flutterfire configure --project=<your-firebase-project-id>

Select android and ios, and confirm the package name and bundle ID from section 3. The command updates:

• lib/firebase_options.dart
• android/app/google-services.json
• ios/Runner/GoogleService-Info.plist
• firebase.json

Manual alternative

• In the Firebase console click Add app > Android, enter your package name, download google-services.json and place it in android/app/.
• Click Add app > Apple, enter your bundle ID, download GoogleService-Info.plist and drag it into Runner/ in Xcode (tick "Copy items if needed").
• Run flutterfire configure once anyway, or update the values in lib/firebase_options.dart by hand — the app reads its Firebase settings from that file.

Step 3: Enable sign-in methods

• Open Build > Authentication > Sign-in method.
• Enable Email/Password, and the social providers you want (configured in section 5).

Step 4: Service account for the backend

The backend verifies sign-ins and sends push notifications with a Firebase service account: Project settings > Service accounts > Generate new private key. You will paste this JSON into the backend's .env in section 13.

5. Social Sign-In and Push Notifications

The login screen shows Google, Facebook and Apple buttons on both platforms. Configure the ones you want; to hide a button, remove it from lib/feature/auth/presentation/widgets/social_media_buttons.dart.

Google

• Enable Google in Firebase Authentication.
• Android: add your SHA-1 and SHA-256 fingerprints in Project settings > Your apps > Android. Add the debug key, your upload key and, after publishing, the App signing key from Play Console. Get local fingerprints with cd android && ./gradlew signingReport. Download google-services.json again afterwards.
• iOS: download GoogleService-Info.plist again (it now contains CLIENT_ID and REVERSED_CLIENT_ID). In Xcode, open Runner > Info > URL Types, add a URL type and paste the REVERSED_CLIENT_ID value as the URL scheme.

Facebook

• Create an app at Meta for Developers and add the Facebook Login product.
• In Firebase, enable Facebook with your Meta app ID and app secret, and copy the OAuth redirect URI that Firebase shows into the Meta app's Valid OAuth Redirect URIs.
• Android: in android/app/src/main/res/values/strings.xml replace YOUR_FACEBOOK_APP_ID and YOUR_FACEBOOK_CLIENT_TOKEN (Meta app > Settings > Basic / Advanced). Add your package name and key hashes in the Meta app's Android settings.
• iOS: add these to ios/Runner/Info.plist: FacebookAppID, FacebookClientToken, FacebookDisplayName, a URL scheme fb<APP_ID> under CFBundleURLTypes, and LSApplicationQueriesSchemes with fbapi and fb-messenger-share-api. See the flutter_facebook_auth iOS guide.

Apple

• Enable Apple in Firebase Authentication.
• iOS: in Xcode, Signing & Capabilities > + Capability > Sign in with Apple. Xcode creates Runner.entitlements for you.
• Android uses Apple's web flow. Create a Services ID in your Apple Developer account and set it, plus your redirect URL, in lib/feature/auth/data/datasources/auth_remote_data_source.dart (clientId and redirectUri). Follow the sign_in_with_apple Android setup. If you do not need Apple sign-in on Android, hide the button there instead.

Push notifications

• Android: works once google-services.json is in place.
• iOS: in Xcode add the Push Notifications capability (Background Modes for audio, fetch and remote notifications are already set in Info.plist). Create an APNs key in your Apple Developer account and upload it in Firebase: Project settings > Cloud Messaging > Apple app configuration.
• For "Everyone" campaigns the app subscribes every device to one FCM topic, and the backend sends to it. The default is harmonia. Give your deployment its own topic name and set it in both places:
  • App: broadcastTopic in lib/core/service/push_notification/push_notification_service.dart
  • Backend: FCM_BROADCAST_TOPIC in .env

  // Flutter-App/lib/core/service/push_notification/push_notification_service.dart
  static const String broadcastTopic = 'mymusic';
  
  # Backend/.env
  FCM_BROADCAST_TOPIC=mymusic

6. Change App Name

Tip: search the lib/ folder for Harmonia to find every occurrence.

7. App Icon, Splash and Colours

App icon

• Android: replace the files in android/app/src/main/res/mipmap-*/ (adaptive icon: mipmap-anydpi-v26/ic_launcher.xml). The easiest way is Android Studio: right-click res > New > Image Asset.
• iOS: replace the images in ios/Runner/Assets.xcassets/AppIcon.appiconset/, or drop a 1024×1024 image onto the AppIcon set in Xcode.
• Optional: generate both at once with the flutter_launcher_icons package.

Splash screen

• The native launch background colour is splash_background in android/app/src/main/res/values/colors.xml (and LaunchImage on iOS).
• The animated splash (logo, wordmark and tagline) is drawn in lib/feature/splash/presentation/splash_screen.dart.

Brand colours

The brand colours are in lib/core/theme/src/theme_extension/src/colors/semantic.dart. Flutter writes colours as 0xAARRGGBB: FF (fully opaque) followed by the normal hex code. The default brand green is #1DDA63:

// lib/core/theme/src/theme_extension/src/colors/semantic.dart
static const Color primary = Color(0xFF1DDA63);        // brand green #1DDA63
static const Color darkBackground = Color(0xFF020E28); // dark theme page #020E28
static const Color darkSurface = Color(0xFF0B1B3D);    // dark cards #0B1B3D

Example: to use orange #FF6B00 as your brand colour, change the first line to Color(0xFFFF6B00), then stop the app and run it again (hot reload does not update const colours).

• Theme wiring that uses these colours is in lib/core/theme/theme.dart.
• Page colours that follow light and dark mode are in lib/core/theme/palette.dart. Dark is the default theme; listeners can switch in Settings.

8. Connect the App to Your Backend

Open lib/core/network/constants/api_endpoint.dart and set your backend's public address:

static const String apiHost = 'https://your-domain.com';   // change to e.g. https://api.yourdomain.com

• Use the origin only — no trailing slash and no /api/v1; the app adds that itself.
• Use https in production.
• For local testing on an emulator use http://10.0.2.2:7001 (Android emulator) or your computer's LAN IP (real device).
• Plain http:// only works in debug builds. Release builds are HTTPS-only: Android allows cleartext traffic only in android/app/src/debug/AndroidManifest.xml, and iOS allows only local-network addresses (NSAllowsLocalNetworking). Your production apiHost and media URLs (R2) must use https://.

Privacy policy, terms, support e-mail, store links, minimum app version and maintenance mode are not in the app code. They come from the backend and are edited on the admin panel's App config page.

A privacy policy template that matches the app's features is included at Flutter-App/docs/privacy-policy.md. Replace the [PLACEHOLDERS] with your details, remove the parts for features you turned off, have it checked for your countries, publish it at a public URL and paste that URL into App config. Google Play, the App Store and Meta all require one.

9. Languages

The app ships with English and Bangla. By default it follows the phone's language when it is supported, otherwise English. Listeners can choose in Settings > Appearance > Language.

• All on-screen text is in lib/l10n/app_en.arb (the template) and lib/l10n/app_bn.arb.
• Generated code goes to lib/l10n/gen/ (configured in l10n.yaml).

What a language file looks like

Each language is one JSON file of "key": "text" pairs. The keys are the same in every file; only the text changes. Entries starting with @ describe placeholders and exist only in the English template. Here is part of the existing English file and its Bangla counterpart:

// lib/l10n/app_en.arb  (template)
{
  "@@locale": "en",
  "appName": "Harmonia",
  "settingsTitle": "Settings",
  "settingsLanguage": "Language",
  "settingsClearCacheSubtitle": "{size} used by images and temporary files",
  "@settingsClearCacheSubtitle": {
    "placeholders": { "size": { "type": "String" } }
  }
}

// lib/l10n/app_bn.arb  (existing Bangla)
{
  "@@locale": "bn",
  "appName": "হারমোনিয়া",
  "settingsTitle": "সেটিংস",
  "settingsLanguage": "ভাষা",
  "settingsClearCacheSubtitle": "ছবি আর অস্থায়ী ফাইলে {size} জায়গা নিচ্ছে"
}

A new Spanish file lib/l10n/app_es.arb should contain the same keys, "@@locale": "es", and keep every {placeholder} exactly as in English:

// lib/l10n/app_es.arb  (new)
{
  "@@locale": "es",
  "appName": "Harmonia",
  "settingsTitle": "Ajustes",
  "settingsLanguage": "Idioma",
  "settingsClearCacheSubtitle": "{size} usados por imágenes y archivos temporales"
}

Check: flutter gen-l10n finishes without errors and lists no untranslated keys for es. Any key you leave out falls back to English.

Add a language

• Copy app_en.arb to app_xx.arb (for example app_es.arb), set "@@locale": "xx", delete the @ description entries and translate the values.
• Add 'xx' to supportedLanguages in lib/core/settings/app_settings_cubit.dart:

  static const supportedLanguages = ['en', 'bn', 'es'];

• Add the language to the options list in the language tile of lib/feature/profile/presentation/profile/pages/profile_page.dart:

  final options = <String?, String>{null: l10n.settingsLanguageSystem, 'en': 'English', 'bn': 'বাংলা', 'es': 'Español'};

• Run flutter gen-l10n.
• If the language uses a new script, add a font fallback in lib/core/theme/app_fonts.dart.

Remove a language

Delete its ARB file, remove it from supportedLanguages and the language tile, then run flutter gen-l10n.

Catalogue content (song titles, playlist names and so on) is shown as entered in the admin panel.

10. AdMob

The package contains only Google's official AdMob test IDs (publisher ca-app-pub-3940256099942544, listed in Google's test ads guide). Ads show as "Test Ad" and earn nothing. No publisher ID of ours is included anywhere.

The four ad unit test IDs are written to the database the first time the backend starts (Backend/src/modules/subscriptions/premium.defaults.ts). After that, change them on the admin panel's Ads page; editing the defaults file later has no effect on an existing database.

App IDs (in the app)

Ad unit IDs (in the admin panel)

Banner and interstitial unit IDs are not in the app. Set them on the admin panel's Ads page, separately for Android and iOS, together with how often interstitials appear (every N songs, minimum interval). The app reads them from GET /api/v1/ads/config at launch, so you can change them without a new release.

Premium listeners never see ads.

11. Premium Subscriptions (Google Play)

iOS and App Store review

Apple requires digital subscriptions sold inside an iOS app to use Apple In-App Purchase (App Review Guideline 3.1.1). Harmonia's backend verifies Google Play purchases only, so on iOS the app must not offer a way to buy Premium. Choose one approach before you submit to the App Store:

Suggested App Review notes for approach A and B:

Harmonia is free to use on iOS. The iOS app has no in-app purchases and no
links or references to buying anything elsewhere. Some content is
unlocked for accounts that an administrator grants access to; the demo
account below has this access so you can review every feature.
Demo account: review@your-domain.com / your-password

If App Review still asks for a purchase mechanism, reply in Resolution Center: the iOS app does not sell digital content, access is granted by the service operator, and there are no purchase calls to action in the app. Then either remove the remaining Premium wording on iOS or implement approach C.

Step 1: Create the subscription in Play Console

• Upload a build to a testing track first (Play Console only allows products once the app has the billing permission, which Harmonia already declares).
• Open Monetize with Play > Products > Subscriptions and create a subscription, for example product ID premium_single.
• Add a base plan (for example monthly, auto-renewing, 1 month) and set prices.
• Optional: add a free-trial offer (for example free-trial-7-days).
• Add your testers under Settings > License testing so test purchases are free.

Step 2: Add the plan in the admin panel

Open Premium plans and create a plan. Fill in the platforms (android), payment provider (google_play), the product ID, base plan ID and optional offer ID — they must match Play Console exactly. Name, features, trial text, tag, colour and button text control how the plan looks in the app. The price shown to listeners always comes from Google Play.

The texts on the Premium screen (title, benefits, trial offer) are edited on the same page under Premium page settings.

Step 3: Let the backend verify purchases

The app sends every purchase to the backend, which confirms it with Google before unlocking Premium. Set up the Google Play service account and real-time notifications as described in section 13, step 7.

How Premium works

• Mark songs, albums or playlists as Premium in the admin panel. A song inside a Premium album is Premium everywhere.
• Free listeners see Premium items with a lock and cannot play or download them.
• Premium listeners get ad-free listening, offline downloads and Premium content. When Premium ends, downloads are removed from the device.
• Restore purchases on the Premium tab restores an existing subscription on a new device.

12. Build and Release

Version number

Android reads versionCode and versionName from android/app/build.gradle.kts (these override pubspec.yaml). Increase versionCode for every upload. iOS uses version in pubspec.yaml.

Android: create an upload keystore

macOS / Linux:

keytool -genkey -v -keystore ~/upload-keystore.jks -keyalg RSA -keysize 2048 -validity 10000 -alias upload

Windows:

keytool -genkey -v -keystore %userprofile%\upload-keystore.jks -storetype JKS -keyalg RSA -keysize 2048 -validity 10000 -alias upload

Android: key.properties

Create android/key.properties:

storePassword=<password from previous step>
keyPassword=<password from previous step>
keyAlias=upload
storeFile=<full path to upload-keystore.jks>

android/app/build.gradle.kts already reads this file in its signingConfigs block. If key.properties is missing, release builds are signed with the debug key so they still build — Google Play will not accept those.

Android: build

flutter build apk --release          # APK for direct install / testing
flutter build appbundle --release    # App Bundle for Google Play

The App Bundle is created at build/app/outputs/bundle/release/app-release.aab. Upload it in Play Console.

iOS: build

• Run cd ios && pod install && cd ..
• Open ios/Runner.xcworkspace, select your Team and bundle ID (section 3) and the capabilities from section 5.
• The minimum iOS version is 15.0, set in both the Xcode project and the Podfile. Nothing to change.
• Build the archive: flutter build ipa --release, then upload build/ios/ipa/*.ipa with Xcode's Organizer or the Transporter app.
• See Apple's distribution guide and Flutter's iOS deployment guide.

Test on a real device

• Android: enable USB debugging, connect the phone and run flutter run --release.
• iOS: connect the iPhone, trust the computer, select it in Xcode and press Run. Background audio, Chromecast and push notifications should be tested on real devices.
• Android Auto: test with the Desktop Head Unit.

13. Backend Setup (NestJS)

The backend lives in Backend/. It is a NestJS 11 + TypeORM API on PostgreSQL. The app and the admin panel talk only to this API.

Step 1: Install

cd Backend
npm ci

Install FFmpeg on the server

FFmpeg creates the low, normal and high stream qualities and measures loudness. It is not bundled with the package; install it with your system's package manager (free):

sudo apt update && sudo apt install -y ffmpeg     # Ubuntu / Debian
brew install ffmpeg                                # macOS (local testing)
ffmpeg -version                                    # check it works

The backend finds ffmpeg on the system PATH. If it is installed somewhere else, set its full path in .env: FFMPEG_PATH=/usr/local/bin/ffmpeg. Without FFmpeg the backend still runs and plays the original uploaded files; it just skips the extra stream qualities and loudness analysis and logs a warning.

Step 2: Create the database

createdb harmonia        # or create it in pgAdmin / your host's panel

Step 3: Configure .env

cp .env.example .env

Every variable is explained in .env.example. The important ones:

To encode the Firebase JSON as base64 on macOS/Linux: base64 -i service-account.json | tr -d '\n'

Step 4: First run and your admin account

npm run start:dev        # development, with auto-reload; API at http://localhost:7001/api/v1

What a successful first run looks like

This is the real output of npm run start:dev on an empty database, with only the database, JWT_SECRET and admin account set in .env (Firebase, R2 and Google Play not configured yet). About 200 lines that list modules and routes are shortened in the middle.

1. Found 0 errors: the TypeScript code compiled.
2. WARN FirebaseAdmin: normal until you add FIREBASE_SERVICE_ACCOUNT_JSON (section 4, step 4). App sign-in is not verified until then.
3. ERROR UploadsService "R2 not configured": shown in red but not fatal. The server keeps running; only file uploads fail until you complete step 6.
4. Seeded super admin: your ADMIN_EMAIL account was created. Sign in to the admin panel with it.
5. Created default …: default settings, Google's test ad IDs, sample Premium plans (development only) and app config were written to the database.
6. WARN FFmpeg: appears only if FFmpeg is not installed (see step 1).
7. Server running on http://localhost:7001: success. The API is ready.
8. The grey DeprecationWarning comes from the Nest CLI's file watcher, not from Harmonia, and can be ignored.

If the output stops with a red error before line 7, compare it with the troubleshooting list below. The most common causes are a wrong database password or port, and a database that does not exist yet.

Check it in the browser or terminal

$ curl -s "http://localhost:7001/api/v1/app/config?platform=android"
{"data":{"min_version":"1.0.0","latest_version":"1.0.0","store_url":null,"force_update_message":"Please update to the latest version to keep listening.","maintenance_mode":false,"maintenance_message":"We are doing some maintenance. Back shortly.","privacy_url":null,"terms_url":null,"support_email":null},"isArray":false,"path":"/api/v1/app/config","duration":"5ms","method":"GET"}

A JSON reply like this (wrapped in data) means the API, the database and the default settings all work. In development, open http://localhost:7001/api in your browser to see the interactive Swagger API docs:

• In development the tables are created automatically from the code. In production the server runs the database migrations in db/migrations/ on every start.
• When the admin_users table is empty, the server creates a super admin from ADMIN_EMAIL and ADMIN_PASSWORD. Use these to sign in to the admin panel.
• After your first login you can remove ADMIN_EMAIL and ADMIN_PASSWORD from .env; they are only used while no admin exists.
• Swagger API docs are available at http://localhost:7001/api when NODE_ENV is not production.

Step 5: Go live with PM2

npm ci
npm run build
npm install -g pm2
# edit cwd in prod.config.js, then:
pm2 start prod.config.js      # sets NODE_ENV=production
pm2 save && pm2 startup        # restart automatically after a reboot

Put nginx in front with HTTPS (for example with Let's Encrypt / certbot):

server {
    server_name api.yourdomain.com;
    client_max_body_size 250m;   # admin uploads: audio up to 60 MB, video up to 250 MB

    location / {
        proxy_pass http://127.0.0.1:7001;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

To update later: upload the new files, then npm ci && npm run build && pm2 restart harmonia-api. New migrations run automatically on start.

Step 6: Media storage (Cloudflare R2)

• In Cloudflare, open R2, create a bucket and connect a custom domain (for example cdn.yourdomain.com) under the bucket's settings, or enable its public r2.dev URL.
• Create an R2 API token with Object Read & Write on that bucket.
• Fill in CLOUDFLARE_R2_ENDPOINT (https://<account-id>.r2.cloudflarestorage.com), CLOUDFLARE_R2_ACCESS_KEY_ID, CLOUDFLARE_R2_SECRET_ACCESS_KEY, CLOUDFLARE_R2_BUCKET, CLOUDFLARE_R2_PUBLIC_URL (your public domain) and CLOUDFLARE_R2_PREFIX (a folder such as harmonia/).

Uploads from the admin panel are stored under <prefix>image/, <prefix>audio/ and <prefix>video/. Limits: images 10 MB, audio 60 MB, video 250 MB. Stream qualities created by ffmpeg go to <prefix>audio-variants/. Without R2 the upload endpoint answers 503 "Media storage is not configured"; you can still paste links to files hosted elsewhere (https only).

Step 7: Google Play (Premium)

A. Service account (purchase verification)

• Play Console > Setup > API access: link a Google Cloud project.
• In Google Cloud > IAM, create a service account and download a JSON key.
• Back in Play Console, invite the service account under Users and permissions and grant View financial data and Manage orders and subscriptions.
• Set GOOGLE_PLAY_PACKAGE_NAME (your app's package name) and GOOGLE_PLAY_SERVICE_ACCOUNT_JSON (JSON or base64). Until this is done, purchase verification answers 503.

B. Real-time developer notifications (recommended) — tell the backend about renewals, cancellations and refunds.

• Generate a secret: openssl rand -hex 24 and set it as GOOGLE_PLAY_RTDN_TOKEN.
• In Google Cloud Pub/Sub, create a topic (for example play-billing) and add google-play-developer-notifications@system.gserviceaccount.com as Pub/Sub Publisher.
• Create a push subscription on the topic with the endpoint
  https://api.yourdomain.com/api/v1/purchases/google/rtdn?token=<GOOGLE_PLAY_RTDN_TOKEN>
  (Pub/Sub cannot send custom headers, so the secret goes in the URL; the backend hides it in its logs.)
• Optional, stronger: enable authentication on the push subscription and set GOOGLE_PLAY_RTDN_AUDIENCE to the audience you configured.
• Play Console > Monetization setup > Real-time developer notifications: enter the full topic name and click Send test notification.

Without notifications, subscription changes are picked up when the app re-verifies and by an hourly expiry job. Refunds and revocations are always re-checked with Google before Premium is removed.

Step 8: Expiring audio links (optional)

By default, audio URLs on your R2 domain are permanent. To make them expire, deploy the included worker docs/media-signing-worker.js:

• Cloudflare > Workers & Pages > Create, paste the file and deploy.
• Worker Settings > Variables: add the secret MEDIA_URL_SIGNING_SECRET (a long random value) and the variable PROTECTED_PREFIXES, for example harmonia/audio/,harmonia/audio-variants/.
• Worker Triggers > Routes: add cdn.yourdomain.com/* (your R2 public domain).
• Set the same MEDIA_URL_SIGNING_SECRET in the backend .env (and optionally MEDIA_URL_TTL_SEC, default 43200 = 12 hours) and restart.

Images and videos stay public; protected audio needs a valid signature, which the backend adds automatically.

Troubleshooting

14. Admin Panel Setup (Next.js)

The admin panel lives in Admin-Panel/. It is a Next.js 15 web app that talks to the backend.

Step 1: Install and configure

cd Admin-Panel
npm ci
cp .env.example .env.local

Set NEXT_PUBLIC_API_URL to your backend including /api/v1:

NEXT_PUBLIC_API_URL=http://localhost:7001/api/v1          # local
NEXT_PUBLIC_API_URL=https://api.yourdomain.com/api/v1     # production

Step 2: Run

npm run dev        # http://localhost:3000

Start the backend first. A successful start looks like this (real output):

1. Ready: the admin panel is running at http://localhost:3000.
2. GET /login 200: your browser opened the sign-in page.
3. Environments: .env.local: your settings file was found. If this line is missing, the panel calls the default http://localhost:7001/api/v1.

Open http://localhost:3000. You should see the sign-in page:

After signing in you land on the Dashboard (see the admin panel tour below). On a new installation the numbers are 0 until you add songs. If sign-in fails with a network or CORS error, check that the backend is running and that CORS_ORIGINS in the backend's .env contains http://localhost:3000.

Step 3: Go live

npm ci
npm run build
# edit cwd in prod.config.js, then:
pm2 start prod.config.js     # runs "next start" on port 3000

Put nginx in front with HTTPS:

server {
    server_name admin.yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Then add https://admin.yourdomain.com to the backend's CORS_ORIGINS and restart the backend. Vercel also works: import the project, set NEXT_PUBLIC_API_URL in the project settings and deploy.

Roles

What you can manage

Admin panel tour

What each main page looks like, so you know your way around before you add content. Screenshots are from the demo with sample music.

Troubleshooting

15. API Reference

All endpoints live under https://api.yourdomain.com/api/v1. The full, always-current reference is the Swagger UI at /api on a development server. This section covers the conventions and the most important calls.

Conventions

• Requests and responses are JSON (uploads use multipart/form-data with a field named file).
• Unknown fields in request bodies are removed; invalid fields return 400 with a list of messages.
• IDs are UUIDs, except app user IDs (the Firebase UID) and Premium plan IDs (integers).
• Rate limits: 300 requests per minute per app install and 1500 per minute per IP by default (RATE_LIMIT_PER_MIN, RATE_LIMIT_IP_PER_MIN); admin login and password changes allow 10 per minute. Over the limit you get 429.

The response envelope

Successful responses are wrapped like this:

{
  "data": { ... },          // the actual result
  "isArray": false,
  "path": "/api/v1/songs/3f2c...",
  "duration": "12ms",
  "method": "GET"
}

Some older endpoints put their own { "status", "message", "data" } object inside data; the app and admin panel handle both forms.

Errors

// 400 validation error
{ "statusCode": 400, "timestamp": "2026-01-15T10:00:00.000Z", "path": "/api/v1/songs/create",
  "message": ["thumbnail must be an https URL", "title should not be empty"], "error": "Bad Request" }

// 404
{ "statusCode": 404, "timestamp": "...", "path": "/api/v1/songs/...", "message": "Song not found", "error": "Not Found" }

// 401 when a device was signed out remotely
{ "statusCode": 401, "timestamp": "...", "path": "...", "code": "DEVICE_REVOKED",
  "message": "This device was signed out from another device" }

Authentication

App users sign in with Firebase in the app. Every request sends the Firebase ID token and the install's device ID:

Authorization: Bearer <Firebase ID token>
x-device-id: <stable id per app install>

There is no separate register endpoint: the user record is created on the first authenticated request. Many read endpoints also work without a token (guest mode).

Admins log in with e-mail and password:

POST /api/v1/admin/auth/login
{ "email": "admin@yourdomain.com", "password": "your-password" }

// response (inside "data")
{ "access_token": "<JWT>", "expires_in": "24h",
  "admin": { "id": "uuid", "email": "admin@yourdomain.com", "name": "Super Admin",
             "role": "super_admin", "is_active": true, "last_login_at": "..." } }

Send the token as Authorization: Bearer <JWT> on admin requests. Other admin auth calls: GET /admin/auth/me and POST /admin/auth/change-password with { "current_password", "new_password" }.

Example: the Home feed

GET /api/v1/home?page=1&limit=10        (token optional)

{ "status": true, "message": "Home data fetched successfully",
  "pagination": { "page": 1, "limit": 10, "total": 7, "totalPages": 1, "isLastPage": true },
  "data": [
    { "title": "Banners", "type": "banner_carousel", "id": "banners",
      "items": [ { "id": "uuid", "title": "...", "image": "https://...", "redirectType": "playlist", "target_id": "uuid" } ] },
    { "title": "Top hits", "type": "song_horizontal_cards", "id": "uuid",
      "items": [ { "id": "uuid", "title": "...", "image": "...", "redirectType": "song", "is_premium": true,
                   "songs": [ { "id": "uuid", "title": "...", "artist": "...", "duration": 180,
                                "file_path": null, "audio_variants": null, "is_premium": true, "is_locked": true } ] } ] }
  ] }

Section types: banner_carousel, play_list_horizontal_cards, full_playlist_songs_horizontal_cards, song_horizontal_cards, artist_songs_horizontal_cards, horizontal_artist_list, shorts_horizontal_cards, recent_played_horizontal_cards, mood_chips_horizontal, genre_horizontal_cards.

Example: a song

GET /api/v1/songs/{id}        (token optional)

{ "id": "uuid", "title": "...", "artist": "Artist name", "featured": "Feat A",
  "thumbnail": "https://cdn.../cover.jpg", "duration": 215,
  "file_path": "https://cdn.../harmonia/audio/2026-10/x.mp3?exp=...&sig=...",
  "audio_qualities": ["low", "normal", "high"],
  "audio_variants": { "low": "https://...m4a", "normal": "...", "high": "..." },
  "variants_status": "ready",
  "lyrics": [ { "time": 0, "text": "First line" } ],
  "is_premium": false, "is_locked": false }

When a song is Premium and the caller is not, the response has "is_locked": true, "file_path": null and "audio_variants": null.

Example: search

GET /api/v1/search?q=love&limit=20&type=song

[ { "id": "uuid", "name": "Love Song", "type": "SONG", "image": "...", "artist": "...",
    "artist_id": "uuid", "duration": 200, "is_premium": false } ]

Also: GET /search/page?q=&offset=&limit= returns { "items": [...], "next_offset": 20 }, GET /search/suggest?q= and GET /search/trending.

Example: report playback

POST /api/v1/plays        (token optional, x-device-id recommended) → 202

{ "song_id": "uuid", "source_type": "playlist", "source_id": "uuid",
  "position_ms": 45000, "duration_ms": 215000, "completed": false, "platform": "android" }

A play counts after 30 seconds or when the song finishes. POST /plays/batch accepts { "events": [...] } with up to 200 events.

Example: verify a Google Play purchase

POST /api/v1/purchases/google/verify        (token required)

{ "purchase_token": "<from Google Play>", "product_id": "premium_single", "backend_plan_id": 1 }

// response
{ "is_premium": true, "status": "active", "platform": "android", "plan_id": 1,
  "product_id": "premium_single", "base_plan_id": "monthly",
  "expires_at": "2026-11-16T10:00:00.000Z", "auto_renew": true }

GET /me/entitlement returns the same object for the signed-in user.

Example: create a song (admin)

POST /api/v1/songs/create        (admin token, editor or super_admin)

{ "title": "My Song", "thumbnail": "https://cdn.yourdomain.com/.../cover.jpg",
  "file_path": "https://cdn.yourdomain.com/.../audio.mp3", "duration": 215,
  "artist_id": "uuid", "is_premium": false, "tags": "pop,summer",
  "lyric": [ { "time": 0, "text": "First line" } ],
  "audio_qualities": ["low", "normal", "high"],
  "credit": "Artist - Title", "license": "CC BY 4.0", "license_url": "https://...", "source_url": "https://..." }

title, thumbnail and file_path are required; thumbnail and file_path must be https URLs. Upload files first with POST /admin/uploads?kind=image|audio|video (returns { url, key, kind, mime, size }).

Endpoint groups

Every path below is relative to https://your-api/api/v1. The full, always-current list with request bodies is in Swagger at /api when NODE_ENV is not production.

Access: public (no token), optional (works for guests, richer when signed in), user (Firebase token), admin (any admin role), editor (editor or super admin), super (super admin).

16. Database Schema

PostgreSQL, managed with TypeORM. Tables are defined in src/modules/*/entities/*.entity.ts; production changes ship as migrations in db/migrations/ and run automatically when the server starts.

Conventions

• Most tables share id (uuid), createdAt, updatedAt and isDeleted (soft delete).
• App users are keyed by their Firebase UID (varchar(128)).
• Lists such as lyrics, audio variants and plan features are stored as jsonb.
• Search uses the pg_trgm extension, created automatically at start when the database user is allowed to; otherwise search falls back to simple matching.

Tables by area

Key tables

Enum values

Migrations

npm run migration:show       # list applied and pending migrations
npm run migration:run        # apply pending migrations manually
npm run migration:revert     # undo the last migration

A fresh production database is created entirely by the migrations on first start: 1793149601049-InitialSchema creates every table, index and foreign key of version 1.0.0. This has been tested on an empty PostgreSQL database with NODE_ENV=production.

CREATE TABLE IF NOT EXISTS migrations (id serial PRIMARY KEY, "timestamp" bigint NOT NULL, name varchar NOT NULL);
INSERT INTO migrations ("timestamp", name) VALUES (1793149601049, 'InitialSchema1793149601049');

Backups

pg_dump -Fc -d harmonia -f harmonia-$(date +%F).dump      # back up
pg_restore -d harmonia --clean harmonia-2026-01-15.dump      # restore

Schedule a daily backup (for example with cron) and keep copies off the server. Media files are in R2, so back up the bucket separately if needed.

17. FAQ and Common Build Errors

Before anything else

• Run flutter doctor and fix every item it reports.
• Run flutter clean then flutter pub get, and try again.

Flutter app

Backend and admin panel

See the troubleshooting tables in section 13 and section 14.

General questions

18. Support

Questions before or after purchase? Please use the Support tab on the CodeCanyon item page. All support is handled through the official Envato item support system.

We answer through the item's Support tab. Support covers bugs and questions about the included features; customisation and installation on your server are not part of item support.

Before you open a ticket

• Check the FAQ and common build errors and the Troubleshooting lists in sections 13 and 14.
• Make sure you are on the latest version (see the changelog).

What to include

A complete first message lets us answer in one reply instead of several:

More resources

• Live demo: the admin panel and Android demo app linked on the item page.
• Video tutorials: environment setup for Windows, macOS and Linux (section 2) and Firebase with Flutter (section 4).
• Flutter: docs.flutter.dev · NestJS: docs.nestjs.com · Next.js: nextjs.org/docs

19. Changelog

Version 1.0.0 (Initial Release)

• Initial release: Flutter app (Android and iOS), NestJS backend and Next.js admin panel.

AI disclosure: AI tools were used to assist with parts of this item (source code, documentation and preview graphics). All AI-assisted work was reviewed, edited and tested by the author.

20. Upgrading to a New Version

When a new version of Harmonia is released, download it from your CodeCanyon Downloads page and read its changelog first. Your songs, users, playlists, subscriptions and settings live in your PostgreSQL database and your R2 bucket, not in the code, so updating the code does not delete them.

Before you start

• Back up the database (see section 16, Backups):

  pg_dump -Fc -d harmonia -f harmonia-before-upgrade.dump

• Keep your own changes in Git, or note which files you edited, so you can carry them over.
• Never overwrite these files with the ones from the new package; they hold your settings:

  Project	Keep your copy of
  Backend	.env, prod.config.js if you changed the PM2 name or port, docs/media-signing-worker.js if you deployed a changed copy
  Admin panel	.env.local (or .env), prod.config.js if you changed it
  Flutter app	lib/firebase_options.dart, android/app/google-services.json, ios/Runner/GoogleService-Info.plist, android/key.properties and your keystore, lib/core/network/constants/api_endpoint.dart, app icons, strings.xml, Info.plist changes, AdMob app IDs

• Compare the new .env.example with your .env and add any new variables.

Carrying your own code changes forward

If you edited source files in the backend or admin panel (not only settings), do not copy the new version straight over them. The safest way is Git:

# one time, before your first customisation
cd Backend            # or Admin-Panel
git init && git add -A && git commit -m "Harmonia 1.0.0 original"
# ...make your changes and commit them as usual...

# when a new version arrives
git checkout -b upgrade
# copy the new package files over the folder (keep the files listed above)
git add -A && git commit -m "Harmonia 1.x.x original"
git checkout main && git merge upgrade      # Git combines both; fix any conflicts it lists

Files buyers commonly customise, and what to check after merging:

Without Git, compare your old folder and the new one with a diff tool (VS Code: right-click two files > Compare Selected) and re-apply your edits to the new files.

1. Backend

cd Backend
# copy the new files over your old folder, keeping your .env
npm ci
npm run build
pm2 restart harmonia-api

• Database changes are applied automatically. In production (NODE_ENV=production) the server runs every new migration in db/migrations/ when it starts. Each migration runs once; TypeORM records it in the migrations table.
• Migrations only add or change tables and columns. They keep your existing rows. If a release ever needs to change existing data, its changelog says so.
• Check what ran: npm run migration:show (applied ones are marked [X]). Run pending ones by hand with npm run migration:run.
• If something goes wrong: npm run migration:revert undoes the last migration, or restore the backup with pg_restore -d harmonia --clean harmonia-before-upgrade.dump, then go back to the old code.
• Development databases (NODE_ENV=development) update their tables from the code automatically and need no migration step.

2. Admin panel

cd Admin-Panel
# copy the new files over your old folder, keeping .env.local
npm ci
npm run build
pm2 restart harmonia-admin

The admin panel stores nothing itself; all data comes from the backend. Upgrade the backend first.

3. Flutter app

• Copy the new lib/, pubspec.yaml and assets/ over your project, then restore the files you customised (list above). If you use Git, commit first and review the diff.
• Run:

  flutter clean
  flutter pub get
  cd ios && pod install && cd ..
  flutter run

• Raise version: in pubspec.yaml (for example 1.0.1+2) and publish the update as in section 12. Listeners keep their downloads, likes and playlists because these are stored on the server and on their phone.
• Old app versions keep working with the new backend unless the changelog says otherwise. To make everyone update, raise the minimum version on the admin panel's App config page.