Overload documentation

Overload is a workout logger, not a workout library. It is the complete Flutter source for an Android and iOS app that records sets in a gym: weight, reps, rest, personal records, progress over time.

The distinction matters commercially. Almost every fitness app on this marketplace is a preset-routine library with bundled demonstration videos, GIFs and photographs. Overload ships zero media assets. There is no video to license, no image rights to verify, and nothing to re-source when you publish under your own brand. The exercise catalogue is 590 text-only records from a public-domain dataset, bundled as one JSON file.

It is built for an intermediate lifter training three to five times a week, on bad gym connectivity, one-handed, between sets. Logging a set is one tap. The app works fully offline.

What it is not

Stated plainly here rather than discovered after purchase:

• No exercise videos, GIFs, images or illustrations — text records only.
• No preset training programmes or content library. Three minimal starter routines are offered during onboarding and are obviously editable.
• No AI or automated coaching.
• No web or desktop build. Android and iOS only.
• No backend code. Firebase only — there are no Cloud Functions and no server to deploy.
• No trainer/client, gym-management or admin roles.
• No Apple Health, Health Connect or wearable sync.
• No nutrition or calorie tracking, no social feed.
• English only. There is no localisation layer, no intl and no ARB files.
• No Firebase, RevenueCat or AdMob account, and no Play Console or Apple Developer membership. These are third-party services with their own pricing — some of them paid — and you sign up for each yourself. Read Third-party services and their costs before you buy.
• No design source files. The Overload icon and splash ship for both platforms, but they are drawn from geometry by a Python script rather than authored in Illustrator or Figma — you change two colour constants and re-run it. There is no .ai or .fig to open.

Every screen below is a real screenshot from the app, in roughly the order you meet them. Nothing here is a mockup or a render. The content is the output of the bundled demo seeder — about 13 weeks of plausible training history — which is what your own build looks like once you have run Demo data.

• Complete Flutter source for one app targeting Android and iOS.
• 590-exercise catalogue as a bundled JSON asset, public domain, licence archived in LICENSES/.
• firestore.rules — restrictive security rules, plus firestore.indexes.json.
• A rules test harness under tools/rules_test for the Firebase emulator.
• RevenueCat subscriptions and AdMob, both fully wired, both optional, shipping with test credentials so the app runs before you configure anything.
• The Hearth design system — hand-authored light and dark themes, one palette file, a bundled type scale.
• Three starter routines as editable seed data.
• An in-app demo data seeder for filling a fresh install with 13 weeks of plausible history (debug builds only).
• 370 automated tests plus on-device integration tests that run against a real Firebase project.
• Buyer documentation: README.md, SETUP.md, REBRANDING.md, TROUBLESHOOTING.md.
• Six months of item support.

Logging a workout

• One-tap set logging. Last session’s numbers appear inline as ghost text; tapping the completion toggle on an empty row fills them in.
• Rest timer with a wall-clock deadline, so a timer backgrounded for two minutes returns correct. Fires a local notification when the app is suspended.
• Sessions survive backgrounding and force-quit. A workout in progress is always resumable.
• Warm-up sets, drop sets and failure sets; per-set and per-session notes; optional RPE column.
• Supersets, exercise reordering mid-session, and adding an exercise on the fly.
• Automatic personal records on heaviest weight, best estimated 1RM (Epley) and session volume — announced the moment they happen.

Routines and exercises

• Routine builder with drag reorder, supersets, folders and per-exercise targets (sets, rep range, rest).
• 590 searchable, filterable movements — prefix-per-word search across name, muscle group and equipment.
• Custom exercises, merged into the same search as the seeded catalogue.
• Three starter routines offered at onboarding, plainly editable.

History and progress

• Session history with a calendar heatmap, editable past sessions, and repeat-a-workout.
• Per-exercise progress: estimated 1RM over time, heaviest set, per-session volume, and every record.
• Aggregate progress: sessions per week, weekly volume, volume by muscle group, and a training streak.
• Body metrics — bodyweight plus seven measurements, charted over real elapsed time.
• Plate calculator and warm-up ramp.
• CSV export of the full history, exported in kilograms with the unit named in the header.

Platform

• Offline-first. Firestore local persistence is enabled with an unlimited cache; logging works with no signal and syncs when one returns.
• Anonymous-first auth. The app signs in anonymously on launch, so there is always an account. Creating a real one links the credential and preserves the same uid — data is never migrated or copied, so it cannot be lost.
• Email/password, Google and Apple sign-in. Account deletion in-app, which both stores require.
• Kilograms and pounds. Weights are always stored in kilograms; the setting affects display and input only.
• Light and dark themes, dark by default, plus six selectable accent colours.

Project layout

lib/
  main.dart                       app entry, Firebase init, offline persistence
  config/
    app_config.dart               THE config file — name, AdMob IDs, RevenueCat, flags
    routes.dart                   GoRouter: every route and the redirect gate
    providers.dart                app-wide Riverpod providers
    theme/
      app_theme.dart              public entry point
      app_palette.dart            the only file containing hex values
      app_color_scheme.dart       hand-authored Material 3 ColorSchemes
      app_typography.dart         the type scale
      app_spacing.dart            spacing, radius, motion
      overload_colors.dart        ThemeExtension for domain colours
  core/
    utils/  widgets/              shared helpers and widgets
  data/
    models/                       freezed models mirroring the Firestore shapes
    repositories/                 one per collection — the only Firestore callers
    services/                     auth, purchases, ads, notifications, CSV export
  features/
    <feature>/
      presentation/               screens and widgets
      providers/                  Riverpod providers for that feature
assets/
  data/exercises.json             590 movements, text only
  data/starter_routines.json      three editable starter routines
  google_fonts/                   bundled type, five weights
firestore.rules                   security rules — deploy these
firestore.indexes.json
tools/rules_test/                 emulator test harness for the rules
test/                             370 unit and widget tests
integration_test/                 on-device tests against a real Firebase project

Stack

Design invariants

These are the rules the codebase holds itself to. Breaking one is where bugs come from, so they are worth knowing before you edit.

• Widgets never touch Firestore. Widget → provider → repository, one direction. The classes in lib/data/repositories/ are the only Firestore callers.
• Weights are always stored in kilograms. The kg/lb setting affects display and input only and must never mutate a stored value.
• Hex literals live only in app_palette.dart. Everything else reads from the ColorScheme or from the OverloadColors theme extension, which is what makes a rebrand a one-file change.
• The seeded exercise catalogue is local, not in Firestore. It is identical for every user, so per-account copies would cost reads for nothing. Only custom exercises are stored per user.
• Generated code is committed. *.freezed.dart and *.g.dart are in the repository, against the usual Dart convention, so the project compiles from a fresh clone without anyone first discovering build_runner. Re-run codegen and commit the output when you change a model.
• Anything rendering aligned numbers uses a metric text style carrying tabular figures, so weight and rep columns do not twitch as digits change.
• English only. User-facing strings are plain literals in the widget that renders them.

Toolchain

# Confirm your Flutter version
flutter --version        # expect 3.47.2

# Install the Firebase tooling
npm install -g firebase-tools
dart pub global activate flutterfire_cli

firebase login

Create a Firebase project

1. 01
   Create a project in the Firebase console.
2. 02
   Under Build → Authentication → Sign-in method, enable Anonymous (required — the app signs in anonymously on launch), plus Email/Password, and Google and Apple if you want them.
3. 03
   Under Build → Firestore Database, create a database. Choose a region close to your users; it cannot be changed later.

Connect the app to your project

cd overload
flutter pub get

flutterfire configure \
  --project=your-project-id \
  --platforms=android,ios

That command writes three files, all deliberately gitignored:

.example files ship next to the last two so you can see the expected shape.

Deploy the security rules

This is the step reviewers check and the one most commonly skipped. A Firestore database created in test mode is open to the world and expires after 30 days.

cp firebase.json.example firebase.json    # if you do not already have one
firebase use --add                        # select your project

firebase deploy --only firestore:rules,firestore:indexes

Run it

flutter devices
flutter run -d <device-id>

On first launch the app signs in anonymously and takes you through onboarding: training goal, experience, units, and an offer to install the three starter routines. All of it is skippable.

users/{uid}
  displayName, email, units, theme, accentColor,
  onboardingComplete, showRpe, isPro, createdAt

users/{uid}/exercises/{id}          custom exercises only — the 590 seeded live in assets
users/{uid}/routines/{id}
users/{uid}/sessions/{id}           status: active | completed | discarded
users/{uid}/records/{exerciseId}    denormalised, so a PR check mid-set is one read
users/{uid}/measurements/{id}

Why it is shaped this way

• Everything lives under users/{uid}. The data model is deliberately single-user — there is no gym-management or trainer/client seam — which makes the security rule simple and the audit trivial.
• Records are denormalised on purpose. Checking whether a set is a personal record happens mid-workout, so it must be one document read rather than a scan over history.
• Sessions carry a status. Discarded sessions are stored as discarded and never appear in history or in any aggregate.

The rules

firestore.rules restricts every path to request.auth.uid == uid with a deny-all fallthrough. Clients cannot write isPro — the subscription state is mirrored onto the profile for instant UI, but RevenueCat remains the source of truth and the rules forbid a client granting itself Pro.

A test harness for the Firebase emulator ships under tools/rules_test, and integration_test/app_test.dart asserts the deny cases against a real project on a device.

Every integration below is optional and degrades cleanly. A fresh clone with nothing configured runs, logs workouts, and does not crash or show a broken screen. That is a hard requirement of the codebase, not an accident.

Pro is not a wall in front of logging. Everything core is free: unlimited routines, unlimited history, and the aggregate progress view. Pro removes ads and unlocks CSV export and the per-exercise charts.

The gate is defined in one place, in FreeTier inside lib/config/app_config.dart:

abstract final class FreeTier {
  static const int? maxFreeRoutines = null;   // null = unlimited
  static const int? freeHistoryDays = null;   // null = all of it
  static const bool csvExportRequiresPro = true;
  static const bool advancedChartsRequirePro = true;
}

The capped model is fully implemented and simply switched off. Set maxFreeRoutines to 3 and freeHistoryDays to 30 and the allowance logic starts enforcing again with no other change — which is why they are nullable rather than sentinel numbers.

Configuring it

1. 01
   Create a RevenueCat project and connect your Play Console and App Store Connect apps.
2. 02
   Create products in each store first. RevenueCat surfaces store products; without them the paywall renders with nothing to sell.
3. 03
   Create an entitlement identified exactly pro, and an offering named default with your monthly and annual packages.
4. 04

   Pass the public SDK keys at build time:

   terminalCopy

   flutter run \
     --dart-define=REVENUECAT_ANDROID_KEY=goog_xxxxx \
     --dart-define=REVENUECAT_IOS_KEY=appl_xxxxx

Restore purchases

The paywall includes a restore action. This is an App Store requirement, not a nicety — an app that sells a subscription without one is rejected.

The app ships with Google’s official test unit IDs and works without an AdMob account. Replace them in three places before release:

1. 01
   AdMobConfig in lib/config/app_config.dart — banner and interstitial unit IDs.
2. 02
   android/app/src/main/AndroidManifest.xml — the com.google.android.gms.ads.APPLICATION_ID meta-data. The SDK reads the app ID from the manifest and crashes at startup if it is absent.
3. 03
   ios/Runner/Info.plist — the GADApplicationIdentifier key.

AdMobConfig.usingTestIds exists so you cannot ship test ads to production by forgetting a step. Set it to false once you have replaced the IDs.

Where ads appear

• Never during an active workout. Banners are shown on non-session screens only.
• One interstitial on workout completion, frequency-capped by AdMobConfig.interstitialCooldown (four hours by default).
• Nothing at all for Pro users.

There are no seeded accounts and no demo credentials — the app is anonymous-first, so it creates an account for you on launch, and there is no server or user table to seed.

To fill a fresh install with realistic content, use the in-app seeder:

1. 01
   Run a debug build.
2. 02
   Open More → Settings and scroll to Demo data.
3. 03
   Tap to seed. It writes roughly 13 weeks of history to your own account.

The seeded history is built to look like real training rather than generated data: progression curves with plateaus and deload weeks, sessions that were missed, weights a gym can actually load, plus bodyweight and measurement history so every chart has something in it. Clearing it removes only what the seeder wrote and leaves your own sessions alone.

Two files carry almost everything: lib/config/app_config.dart and lib/config/theme/app_palette.dart.

Identifiers

Change the identifiers first, then re-run flutterfire configure.

Colour

The design system is called Hearth: dark-first, warm, built to be read at arm’s length on a dim gym floor. Light is tuned separately rather than derived by inverting dark.

Every hex value in the app is in lib/config/theme/app_palette.dart. Nothing else contains one. Change the accent there and it propagates through both themes.

Typography

Five weights of Plus Jakarta Sans are bundled under assets/google_fonts/. Runtime fetching is disabled, so the app never makes a network request for a font and a missing weight throws loudly instead of silently falling back. Adding a weight to the scale means adding the file.

Starter routines

Edit assets/data/starter_routines.json. Every exercise id must resolve against assets/data/exercises.json — there is a test that fails loudly if one does not.

The style guide screen

Debug builds carry a design-system reference screen listing every colour, type style and component the theme defines, reachable from Settings → Design system. It is the fastest way to check a rebrand in one scroll. It is compiled out of release builds.

Android

Generate a keystore and create android/key.properties:

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

# android/key.properties  — never commit this file
storePassword=…
keyPassword=…
keyAlias=upload
storeFile=/absolute/path/to/upload-keystore.jks

flutter build appbundle --release \
  --dart-define=REVENUECAT_ANDROID_KEY=goog_xxxxx

iOS

Open ios/Runner.xcworkspace in Xcode, set your team and bundle identifier, add the Sign in with Apple capability if you offer it, then:

flutter build ipa --release \
  --dart-define=REVENUECAT_IOS_KEY=appl_xxxxx

1. 01
   Replace the identifiers in android/app/build.gradle.kts and ios/Runner.xcodeproj, then re-run flutterfire configure.
2. 02
   Replace AppConfig.supportEmail, privacyPolicyUrl and termsUrl — they ship as example.com placeholders.
3. 03
   Replace the AdMob unit IDs in AppConfig, AndroidManifest.xml and Info.plist, then set AdMobConfig.usingTestIds = false.
4. 04
   Supply RevenueCat keys via --dart-define in your release command.
5. 05
   Deploy the Firestore rules and indexes. Verify a signed-in user cannot read another user’s documents.
6. 06
   Enable Anonymous sign-in in the Firebase console, plus every provider whose button you keep.
7. 07
   Replace the app icon and splash artwork — the Overload mark ships. Edit the colour constants in tools/icon/generate_icon.py, re-run it, then dart run flutter_launcher_icons and dart run flutter_native_splash:create.
8. 08
   Confirm no keystore, key.properties, or Firebase config file is committed.
9. 09
   Run flutter analyze (expect zero issues) and flutter test (expect 370 passing).
10. 10
    Build a release on both platforms from a clean checkout before submitting.

Every version published so far. Updates are free for the life of the item.

Six months of item support is included with your purchase, per the CodeCanyon standard: answering questions about how the item works, help with defects, and updates for bugs.

Support does not include your Firebase, RevenueCat, AdMob or store accounts, the fees any of those services charge you, your hosting, or customisation work. We walk you through setup; we cannot supply the accounts or pay their bills. See Third-party services and their costs.

Before writing in, check TROUBLESHOOTING.md in the download — it covers the errors people actually hit, including the missing firebase_options.dart on a fresh clone, iOS build failures in the ads SDK, permission-denied errors from undeployed rules, and paywalls with nothing to sell.

Licence

Sold under the standard Envato Regular and Extended licences. The bundled exercise dataset is public domain; its provenance and licence are archived in LICENSES/. Every third-party dependency is listed with its licence in README.md.

What support covers

• Six months of support from purchase, extendable at checkout
• Support covers bugs in the template and questions about how it is put together
• It does not cover custom feature work, third-party API changes or store review outcomes
• The Regular licence covers one free end product. Charging users for the app itself needs the Extended licence