Setup & Deployment Guide

Flutter · Firebase · iOS · Android — complete instructions for macOS and Windows.

Mac — Required Tools

macOS 12 (Monterey) or later is recommended. Install all tools listed below before beginning — having everything ready avoids interruptions mid-setup.

Windows — Required Tools

Windows users can build and deploy the Android app and admin panel. iOS builds require macOS — Windows cannot build for iOS.

1. Install Flutter SDK (Mac)

Flutter is the core framework used to build both the Coduo mobile app and the web-based admin panel.

1. Check your Mac chip type

   Click the Apple menu → About This Mac. Note whether you see Apple M1/M2/M3 (ARM) or Intel. Download the matching Flutter SDK ZIP.

2. Download Flutter SDK

   Visit flutter.dev/docs/get-started/install/macos and download the ZIP for your chip type. Extract it to ~/development/flutter.

3. Add Flutter to PATH

   Open Terminal (Cmd+Space → Terminal). Edit your shell config file with the command below, add the export line, then save.

   nano ~/.zshrc
   
   export PATH="$PATH:$HOME/development/flutter/bin"
   
   # Save: Ctrl+O → Enter → Ctrl+X
   source ~/.zshrc

4. Verify Flutter installation

   Close and reopen Terminal. Run the command below. You should see green checkmarks for the installed tools.

   flutter doctor

   Tip: A successful flutter doctor run shows green checkmarks for every installed tool — that confirms Flutter is correctly installed.

2. Install Xcode (Mac)

Xcode is required to build iOS apps, run the iOS simulator, and submit to the App Store. It also installs essential Command Line Tools used by Flutter.

1. Install Xcode from the Mac App Store

   Open the App Store on your Mac. Search for “Xcode”. Click Get / Install. This is a large download (~12–14 GB) — allow 30–60 minutes on a good connection.

2. Accept the Xcode license

   Once installed, open Xcode and accept the license agreement, or run this command in Terminal:

   sudo xcodebuild -license accept

3. Configure Xcode Command Line Tools

   Run this command in Terminal to point Flutter at the correct Xcode version:

   sudo sh -c 'xcode-select -s /Applications/Xcode.app/Contents/Developer && xcodebuild -runFirstLaunch'

4. Install CocoaPods

   CocoaPods manages iOS dependencies for Flutter. Run in Terminal:

   sudo gem install cocoapods
   pod --version

3. Install Android Studio (Mac)

Android Studio provides the Android SDK, emulator, and Gradle build tools needed to build the Coduo Android app on macOS.

1. Download Android Studio

   Go to developer.android.com/studio — download the macOS .dmg file. Open the .dmg and drag Android Studio to your Applications folder.

2. First launch setup

   Open Android Studio. The Setup Wizard will appear — select Standard installation. Allow all SDK components to download (~2 GB).

3. Accept Android SDK licenses

   In Terminal, run:

   flutter doctor --android-licenses
   
   # Type "y" and press Enter for each licence prompt

4. Install required NDK

   In Android Studio: SDK Manager → SDK Tools → NDK (Side by side) → check version 27.1.12297006 → Apply.

5. Create an Android emulator

   In Android Studio: Tools → Device Manager → Create Device. Choose Pixel 8, select API 34, click Finish.

6. Verify full setup

   Run the command below — all items should show a checkmark.

   flutter doctor -v

4. Firebase Setup (Mac)

Firebase is the backend powering Coduo — handling authentication, database, file storage, cloud functions, and push notifications.

1. Create a Firebase project

   Go to console.firebase.google.com. Sign in with your Google account. Click Add Project, enter a project name, then click Create Project.

2. Enable required Firebase services

   In your new Firebase project, enable these services from the left sidebar:

   Authentication  → Get Started → Enable Email/Password + Google Sign-In
   
   Firestore Database → Create Database → Production mode → choose your region
   
   Storage → Get Started → Production mode
   
   Hosting → Get Started (required for admin panel deployment)
   
   Functions → Upgrade to Blaze (pay-as-you-go) plan — required for Cloud Functions

3. Open Project Settings

   Click the gear icon beside “Project Overview” in the left sidebar, then click Project Settings to register your apps.

4. Register your Android app

   Project Settings → Add App → Android icon. Package name: com.coduo.apps. Click Register App. Download google-services.json → place in:

   lms_app/android/app/google-services.json

5. Register your iOS app

   Project Settings → Add App → iOS icon. Bundle ID: com.coduo.apps. Click Register App. Download GoogleService-Info.plist → place in:

   lms_app/ios/Runner/GoogleService-Info.plist

6. Register the web app (admin panel)

   Project Settings → Add App → Web icon. App nickname: Coduo Admin. Check “Also set up Firebase Hosting”. Click Register app. Copy the firebaseConfig object shown.

7. Install the Firebase CLI and log in

   Run the commands below. The login command opens a browser — sign in with your Google account.

   npm install -g firebase-tools
   
   firebase login
   # This opens a browser window — sign in with your Google account
   
   firebase use YOUR_PROJECT_ID

8. Update Firebase options in code

   The Firebase configuration is stored in firebase_options.dart. Use the FlutterFire CLI (recommended) to auto-generate it:

   # Install FlutterFire CLI
   dart pub global activate flutterfire_cli
   
   # Configure for mobile app
   cd lms_app
   flutterfire configure --project=YOUR_PROJECT_ID
   
   # Configure for admin panel
   cd ../lms_admin
   flutterfire configure --project=YOUR_PROJECT_ID

9. Update the admin auth service

   Open lms_admin/lib/services/auth_service.dart and update the project ID:

   static const String _projectId = 'YOUR_PROJECT_ID';  // ← change this

10. Update Firebase Hosting targets

    Open .firebaserc and update with your project and site names:

    {
      "projects": {
        "default": "YOUR_PROJECT_ID"
      },
      "targets": {
        "YOUR_PROJECT_ID": {
          "hosting": {
            "admin": ["YOUR_ADMIN_SITE_NAME"],
            "public": ["YOUR_PUBLIC_SITE_NAME"]
          }
        }
      }
    }

A. Mobile App — Theme & Colours

All mobile app colours are centralised in a single theme file. You only need to edit this one file to retheme the entire app — every screen updates automatically.

lms_app/lib/configs/app_config.dart

Current Colour Palette

These are the default Coduo colours. Change any hex value to retheme the app:

How to Change the Primary Colour

1. Open the config file

   Open lms_app/lib/configs/app_config.dart in your code editor.

2. Change the appThemeColor hex value

   Find the appThemeColor constant and update the hex code. All elements using this colour update automatically.

   // In lms_app/lib/configs/app_config.dart
   static const Color appThemeColor = Color(0xFF0D1B2A);  // ← change this hex
   
   // Example: Change to Blue Indigo theme
   static const Color appThemeColor  = Color(0xFF1A237E);
   static const Color appAccentColor = Color(0xFF283593);

3. Also update the Admin Panel theme

   Open lms_admin/lib/configs/mwaghavul_theme.dart and update the matching colours to keep brand consistency.

4. Hot reload or rebuild

   Save the file. If running in debug mode, press r in Terminal to hot reload and see changes instantly.

   # Quick test in debug mode:
   cd lms_app
   flutter run
   # Then press "r" in Terminal to hot reload after colour changes

App Name — Where to Change It

The app name appears on the splash screen, app bar, and home screen icon label. Update it in three places:

// 1. Flutter config
// lms_app/lib/configs/app_config.dart
static const String appName = 'Coduo';  // ← change here

// 2. Android label
// lms_app/android/app/src/main/AndroidManifest.xml
android:label="Coduo"

// 3. iOS display name
// lms_app/ios/Runner/Info.plist
<key>CFBundleDisplayName</key>
<string>Coduo</string>

B. Mobile App — Logo & Launcher Icon

The app has two separate image assets: the logo (shown inside the app UI) and the launcher icon (shown on the device home screen).

File Locations

lms_app/assets/images/logo.png        ← UI logo (splash, sidebar, headers)
lms_app/assets/images/logo_dark.png   ← White logo for dark backgrounds
lms_app/assets/images/icon.png        ← Home screen launcher icon
lms_admin/assets/images/logo.png      ← Admin panel sidebar logo
lms_admin/web/favicon.png             ← Admin panel browser tab icon
lms_admin/web/icons/Icon-192.png      ← Admin panel PWA icon
lms_admin/web/icons/Icon-512.png      ← Admin panel PWA icon (large)

Part 1 — Replace the App Logo

1. Prepare your logo image

   Requirements: PNG format with transparent background. Minimum 512×512px (1024×1024px recommended). Can be rectangular (e.g. horizontal logo with text).

2. Copy your logo file

   Run the commands below to copy your logo into the correct location:

   # Mac / Linux:
   cp your-logo.png lms_app/assets/images/logo.png
   cp your-logo.png lms_app/assets/images/logo_dark.png
   cp your-logo.png lms_admin/assets/images/logo.png
   
   # Windows:
   copy your-logo.png lms_app\assets\images\logo.png
   copy your-logo.png lms_app\assets\images\logo_dark.png
   copy your-logo.png lms_admin\assets\images\logo.png

3. Verify the asset path is registered

   Open lms_app/pubspec.yaml and confirm the assets section includes:

   flutter:
     assets:
       - assets/images/

4. Test the logo

   Run the app and check the splash screen and navigation bar for your new logo.

   cd lms_app && flutter run

Part 2 — Replace the Launcher Icon (Home Screen)

1. Prepare your icon image

   Requirements: PNG format, exactly 1024×1024px square. No rounded corners (the OS adds them). No text — icons must be readable at 48×48px.

2. Copy the icon file

   # Mac / Linux:
   cp your-icon.png lms_app/assets/images/icon.png
   
   # Windows:
   copy your-icon.png lms_app\assets\images\icon.png

3. Generate platform-specific icons

   This one command generates all required sizes for both Android and iOS automatically:

   cd lms_app
   flutter pub run flutter_launcher_icons
   
   # Expected output:
   # Successfully generated launcher icons for Android
   # Successfully generated launcher icons for iOS

C. Admin Panel — Theme, Colours & Logo

The admin panel has its own theme file, separate from the mobile app. Update both to keep a consistent brand look.

Admin Theme File Locations

lms_admin/lib/configs/mwaghavul_theme.dart   ← admin colour constants
lms_admin/lib/configs/app_config.dart        ← admin app name + background colours
lms_admin/lib/configs/assets_config.dart     ← logo file paths

1. Open the admin theme file

   Open lms_admin/lib/configs/mwaghavul_theme.dart in your code editor.

2. Change colour values

   Update the colour constants. The primaryGreen constant controls the sidebar, buttons, and key UI elements.

   // lms_admin/lib/configs/mwaghavul_theme.dart
   static const Color primaryGreen   = Color(0xFF0D1B2A);  // ← main brand colour
   static const Color secondaryGreen = Color(0xFF1B3A5C);  // ← secondary colour

3. Update the admin app name

   Open lms_admin/lib/configs/app_config.dart:

   static const String appName = 'Coduo Admin Panel';  // ← change this

4. Rebuild and deploy the admin panel

   cd lms_admin
   flutter clean && flutter pub get
   flutter build web --release
   cd ..
   firebase deploy --only hosting:admin
   
   # Clear your browser cache after deploy:
   # Mac:     Cmd + Shift + R
   # Windows: Ctrl + Shift + R

5. Admin Panel Deployment (Mac)

The Coduo admin panel is a Flutter Web app. Build it locally and deploy it to Firebase Hosting so it is accessible from any browser.

1. Set the Firebase project

   From your project root in Terminal:

   firebase use YOUR_PROJECT_ID
   firebase projects:list   # verify

2. Create Firebase Hosting sites

   firebase hosting:sites:create YOUR_APP_admin
   firebase hosting:sites:create YOUR_APP_public

3. Build the admin panel

   cd lms_admin
   flutter pub get
   flutter build web --release
   cd ..

4. Deploy to Firebase Hosting

   firebase deploy --only hosting:admin

5. Grant yourself admin access

   After deploying, you need to create the first admin user. See Section 12 — First Admin User for full instructions. Quick method: Firebase Console → Firestore → create collection admin_users → Document ID: your UID → Field: email (string) = your email address.

6. Deploy Cloud Functions

   Set required API secrets then deploy:

   firebase functions:secrets:set GROQ_API_KEY
   firebase functions:secrets:set STRIPE_SECRET_KEY
   firebase functions:secrets:set PAYSTACK_SECRET_KEY
   firebase functions:secrets:set JUDGE0_API_KEY
   firebase functions:secrets:set JUDGE0_API_URL
   
   cd functions
   npm install
   npm run build
   cd ..
   firebase deploy --only functions

D. Running the App on a Physical Device

You can run and test the Coduo mobile app directly on a physical Android or iOS device connected to your computer via USB. This is always preferred over an emulator for testing payments, push notifications, and performance.

Android Device — Mac & Windows

1. Enable Developer Options on your phone

   On your Android phone: Settings → About Phone → tap “Build Number” 7 times rapidly. You will see “You are now a developer!”

2. Enable USB Debugging

   Settings → Developer Options → turn on “USB Debugging”. A dialog may appear on the phone — tap “Allow”.

3. Connect via USB

   Connect your phone to your computer with a USB cable. On the phone, if prompted, select “File Transfer” or “MTP” mode (not “Charging only”).

4. Verify Flutter sees the device

   flutter devices
   
   # Example output:
   # 2 connected devices:
   # Pixel 8 (mobile) • R3CX123456 • android-arm64 • Android 14
   # Chrome (web)     • chrome      • web-javascript • Google Chrome

5. Run the app on your device

   cd lms_app
   flutter run
   
   # If multiple devices connected, specify:
   flutter run -d DEVICE_ID

iOS Device — Mac Only

1. Connect your iPhone via USB

   Connect your iPhone to your Mac. A prompt will appear on iPhone asking “Trust This Computer?” — tap Trust.

2. Verify Flutter sees the device

   Run flutter devices — you should see your iPhone listed.

3. Open in Xcode first (one-time setup)

   Before the first run on a real device, open Xcode to configure signing:

   open lms_app/ios/Runner.xcworkspace
   
   # In Xcode:
   # Runner → Signing & Capabilities → select your Team
   # Xcode will provision the device automatically

4. Run the app on your iPhone

   cd lms_app
   flutter run
   
   # First run on a new device may take several minutes
   # Your phone must remain unlocked during installation

E. Running the Admin Panel on Chrome (Local Dev)

You can run the admin panel locally in Chrome without deploying to Firebase. This is the fastest way to develop and test admin panel changes.

Mac — Run Admin Panel on Chrome

1. Navigate to the admin panel folder, then install dependencies

   Only needed the first time or after updating packages:

   cd lms_admin
   flutter pub get
   flutter run -d chrome
   
   # Chrome opens automatically at http://localhost:PORT

2. Hot reload during development

   While running, press these keys in Terminal:

   r   → hot reload  (applies code changes instantly)
   R   → hot restart (full widget rebuild)
   q   → quit

6. Android Keystore & Play Store Upload (Mac)

Every Android app must be signed with a keystore before it can be uploaded to the Google Play Store. Back up your keystore — if you lose it, you cannot update your app.

1. Generate a keystore

   Run this command from inside the lms_app/ directory. Replace values with your own:

   keytool -genkey -v \
     -keystore android/your-app-release.jks \
     -alias your-app \
     -keyalg RSA \
     -keysize 2048 \
     -validity 10000 \
     -dname "CN=Your Name, OU=Mobile, O=Your Company, L=City, ST=State, C=US" \
     -storepass YOUR_STORE_PASSWORD \
     -keypass YOUR_KEY_PASSWORD

   Note: Save your keystore file and passwords in a secure place (e.g. a password manager). If you lose them, you cannot update your app on the Play Store.
2. Configure key.properties

   Open lms_app/android/key.properties and fill in your values:

   storePassword=YOUR_STORE_PASSWORD
   keyPassword=YOUR_KEY_PASSWORD
   keyAlias=your-app
   storeFile=../your-app-release.jks

3. Change the package name (if needed)

   The default package is com.coduo.apps. To change it:

   cd lms_app
   dart run change_app_package_name:main com.yourcompany.yourapp
   
   # Then update app_config.dart:
   static const String androidPackageName = 'com.yourcompany.yourapp';

4. Build the release AAB

   Google Play requires an Android App Bundle (.aab), not an APK:

   cd lms_app
   flutter build appbundle --release
   
   # Output file:
   # lms_app/build/app/outputs/bundle/release/app-release.aab

5. Upload to Play Console

   Go to play.google.com/console → your app → Release → Production → Create new release → Upload the .aab file.

6. Add SHA-1 to Firebase

   Get your SHA-1 fingerprint and add it to Firebase for Google Sign-In:

   keytool -list -v \
     -keystore lms_app/android/your-app-release.jks \
     -alias your-app \
     -storepass YOUR_STORE_PASSWORD
   
   # Copy the SHA-1 value
   # Firebase Console → Project Settings → Android app → Add fingerprint → paste SHA-1

7. iOS Build & App Store Upload (Mac)

iOS builds require a Mac and an Apple Developer account. Follow these steps to build and submit Coduo to the App Store.

1. Register your Bundle ID

   Go to developer.apple.com/account → Certificates, Identifiers & Profiles → Identifiers → + → App IDs. Bundle ID: com.coduo.apps. Enable: Push Notifications, Sign In with Apple.

2. Create the app in App Store Connect

   Go to appstoreconnect.apple.com → My Apps → + → New App. Platform: iOS. Bundle ID: select yours. Click Create.

3. Set up signing in Xcode

   Open lms_app/ios/Runner.xcworkspace in Xcode (not .xcodeproj). Runner → Signing & Capabilities → check Automatically manage signing → select your Team.

4. Install CocoaPods dependencies

   cd lms_app/ios
   pod install
   
   # If errors:
   pod repo update && pod install --repo-update

5. Build the iOS app

   Run from the lms_app directory:

   cd lms_app
   flutter build ipa --release
   
   # Output:
   # lms_app/build/ios/ipa/Runner.ipa

6. Upload to App Store Connect

   In Xcode Organizer: select your archive → Distribute App → App Store Connect → Upload → keep defaults → Upload.

7. Submit for review

   App Store Connect → your app → App Store tab → + Version → fill in screenshots and description → Build → + → select your build → Add for Review.

8. Set up APNs for push notifications

   Apple Developer → Certificates → + → Apple Push Notification service. Upload the .p8 key to Firebase: Project Settings → Cloud Messaging → APNs Authentication Key.

Required App Store Assets

1. Install Flutter SDK (Windows)

Flutter is the core framework used to build both the Coduo mobile app and the admin panel.

1. Download Flutter SDK

   Visit flutter.dev/docs/get-started/install/windows and download the Flutter SDK ZIP for Windows. Extract it to C:\flutter.

2. Add Flutter to System PATH

   Open Start → System Properties → Environment Variables. Under System Variables, select Path → Edit → New → Add: C:\flutter\bin. Click OK on all dialogs.

3. Verify Flutter installation

   Open a new Command Prompt or PowerShell window and run:

   flutter --version
   flutter doctor

4. Install Android Studio

   Download from developer.android.com/studio. Run the installer and complete the Setup Wizard. In SDK Manager: Android 14.0 (API 36), NDK 27.1.12297006, Build-Tools 36.

5. Accept Android licenses

   flutter doctor --android-licenses

2. Install Node.js 22 & Firebase CLI (Windows)

1. Download nvm-windows

   Go to github.com/coreybutler/nvm-windows/releases and download nvm-setup.exe. Run the installer.

2. Install Node.js 22

   Open a new terminal and run:

   nvm install 22
   nvm use 22
   node --version   # should show v22.x.x

3. Install Firebase CLI

   npm install -g firebase-tools
   firebase login

3. Android Keystore & Play Store (Windows)

The keystore process on Windows is the same as Mac, but uses Windows path separators.

1. Generate keystore

   Open PowerShell in the lms_app directory and run:

   keytool -genkey -v `
     -keystore android\your-app-release.jks `
     -alias your-app `
     -keyalg RSA -keysize 2048 -validity 10000 `
     -dname "CN=Your Name, OU=Mobile, O=Your Company, L=City, ST=State, C=US" `
     -storepass YOUR_STORE_PASSWORD `
     -keypass YOUR_KEY_PASSWORD

2. Configure key.properties

   Open lms_app\android\key.properties and fill in your values (use backslash for Windows paths):

   storePassword=YOUR_STORE_PASSWORD
   keyPassword=YOUR_KEY_PASSWORD
   keyAlias=your-app
   storeFile=..\your-app-release.jks

3. Build the release AAB

   cd lms_app
   flutter build appbundle --release

8. AI Configuration (Groq, Gemini, OpenAI, Judge0)

Coduo uses AI for three features: AI Code Review, AI Tutor Chat (“Ask Cody”), and Error Explanation. Code execution is powered by Judge0. You do not need all providers — Groq alone is sufficient for most use cases.

AI Provider Chain

The system tries providers in this order. If one fails or is not configured, it falls back to the next:

1. Groq       (fastest, free tier — recommended starting point)
2. Gemini     (Google, generous free tier)
3. OpenAI     (most capable, paid)
4. Rule-based fallback (always works, no LLM — no keys needed)

Groq Setup (Recommended — Start Here)

Groq is the fastest and has a generous free tier (14,400 requests/day).

1. Get API key

   Go to console.groq.com → Sign up / log in → API Keys → Create API Key. Copy the key (starts with gsk_...).

2. Set the secret

   firebase functions:secrets:set GROQ_API_KEY
   # Paste your key when prompted
   firebase deploy --only functions

Gemini Setup (Google AI — Free Fallback)

1. Get API key

   Go to aistudio.google.com → Get API key → Create API key. Copy the key (starts with AIza...).

2. Set the secret

   firebase functions:secrets:set GEMINI_API_KEY
   firebase deploy --only functions

Judge0 Setup (Code Execution)

Judge0 executes learner code in a sandboxed environment. Use RapidAPI for the easiest setup.

1. Subscribe on RapidAPI

   Go to rapidapi.com/judge0-official/api/judge0-ce → Sign up → Subscribe to the Basic plan (free: 100 requests/day). Copy your RapidAPI Key.

2. Set secrets

   firebase functions:secrets:set JUDGE0_API_KEY
   # Paste your RapidAPI key
   
   firebase functions:secrets:set JUDGE0_API_URL
   # Paste: https://judge0-ce.p.rapidapi.com
   
   firebase deploy --only functions

Verify AI Is Working

firebase functions:log --only reviewCode

# In the app: Log in as Pro user → open a coding challenge
# → write code → tap 'AI Review' → should see feedback in 2-5 seconds

AI Configuration Quick Reference

9. Payment Configuration

Coduo supports three payment methods: Stripe (cards), Paystack (Africa/global), and Bank Transfer (manual verification). You can enable any combination.

Stripe Setup

1. Create a Stripe account

   Go to stripe.com → Start now. Complete account verification (business details, bank account). Activate your account for live payments.

2. Get API keys

   Stripe Dashboard → Developers → API keys. Copy the Publishable key (pk_live_...) and Secret key (sk_live_...).

3. Set the secret key in Firebase

   firebase functions:secrets:set STRIPE_SECRET_KEY
   # Paste sk_live_... or sk_test_...
   firebase deploy --only functions

4. Update the publishable key in the app

   Open lms_app/lib/services/payment_service.dart:

   static const String stripePublishableKey = 'pk_live_YOUR_KEY_HERE';

5. Set up the webhook

   Stripe Dashboard → Developers → Webhooks → Add endpoint. URL: https://YOUR_REGION-YOUR_PROJECT.cloudfunctions.net/stripeWebhook. Events: payment_intent.succeeded, payment_intent.payment_failed. Copy the Signing secret (whsec_...) and set it:

   firebase functions:secrets:set STRIPE_WEBHOOK_SECRET
   # Paste whsec_...
   firebase deploy --only functions

Paystack Setup (Africa/Global)

1. Create a Paystack account

   Go to paystack.com → Create free account. Complete business verification.

2. Get API keys

   Paystack Dashboard → Settings → API Keys & Webhooks. Copy Public Key (pk_live_...) and Secret Key (sk_live_...).

3. Set the secret key

   firebase functions:secrets:set PAYSTACK_SECRET_KEY
   firebase deploy --only functions

4. Update the public key in the app

   Open lms_app/lib/services/paystack_service.dart:

   static const String paystackPublicKey = 'pk_live_YOUR_KEY_HERE';

5. Set up the webhook

   Paystack Dashboard → Settings → API Keys & Webhooks. Webhook URL: https://YOUR_REGION-YOUR_PROJECT.cloudfunctions.net/paystackWebhook

Bank Transfer Setup

Bank transfer allows users to pay via direct bank transfer and upload proof of payment for admin verification.

Configure bank details in the Admin Panel → Payment Settings → Bank Transfer, or set directly in Firestore payment_configuration/bank_transfer:

{
  "enabled": true,
  "bank_name": "First Bank",
  "account_number": "1234567890",
  "account_name": "Your Company Name",
  "instructions": "Transfer the exact amount and upload your receipt.",
  "expiry_hours": 48
}

10. Social Login Configuration

Coduo supports Google, Facebook, and Apple Sign-In. Google Sign-In is already integrated — you just need to add your SHA-1 fingerprint. Facebook and Apple require additional setup.

Google Sign-In

1. Get SHA-1 fingerprint

   # From lms_app directory:
   keytool -list -v \
     -keystore android/your-app-release.jks \
     -alias your-app \
     -storepass YOUR_STORE_PASSWORD

2. Add SHA-1 to Firebase

   Firebase Console → Project Settings → Android app → Add fingerprint → paste SHA-1. Download the updated google-services.json and replace lms_app/android/app/google-services.json.

3. Add iOS reversed client ID

   Open lms_app/ios/Runner/Info.plist and add your reversed client ID (found in GoogleService-Info.plist as REVERSED_CLIENT_ID):

   <key>CFBundleURLTypes</key>
   <array>
     <dict>
       <key>CFBundleURLSchemes</key>
       <array>
         <string>com.googleusercontent.apps.YOUR_CLIENT_ID</string>
       </array>
     </dict>
   </array>

Apple Sign-In

Apple Sign-In is required by Apple if your app offers any other social login on iOS.

1. Enable in Apple Developer

   developer.apple.com → Certificates, Identifiers & Profiles → Identifiers → select your App ID → enable Sign In with Apple → Save.

2. Create a Service ID

   Identifiers → + → Services IDs. Enable Sign In with Apple. Configure: Domains: YOUR_PROJECT.firebaseapp.com. Return URLs: https://YOUR_PROJECT.firebaseapp.com/__/auth/handler

3. Create a key

   Keys → + → enable Sign In with Apple → Configure → select Primary App ID → Register → Download the .p8 file → note the Key ID.

4. Enable in Firebase

   Firebase Console → Authentication → Sign-in method → Apple → Enable. Enter Services ID, Team ID, Key ID, and contents of the .p8 file.

5. Add capability in Xcode

   Open Runner.xcworkspace → Runner → Signing & Capabilities → + Capability → Sign In with Apple.

11. AdMob Configuration

Coduo integrates Google AdMob for banner and interstitial ads. Premium users automatically see no ads (controlled via show_ads_to_premium: false in Firestore).

1. Create an AdMob account

   Go to admob.google.com → Sign in → complete account setup (country, payment info).

2. Create apps in AdMob

   AdMob Console → Apps → Add app → select Android → App name: Coduo → Add app. Repeat for iOS. Copy both App IDs (format: ca-app-pub-XXXXXXXXXXXXXXXX~XXXXXXXXXX).

3. Create ad units

   For each platform: Apps → select app → Ad units → Add ad unit → select Banner or Interstitial → name it → copy the Ad Unit ID.

4. Update the Android App ID

   Open lms_app/android/app/src/main/AndroidManifest.xml:

   <meta-data
     android:name="com.google.android.gms.ads.APPLICATION_ID"
     android:value="ca-app-pub-YOUR_ANDROID_APP_ID"/>

5. Update the iOS App ID

   Open lms_app/ios/Runner/Info.plist:

   <key>GADApplicationIdentifier</key>
   <string>ca-app-pub-YOUR_IOS_APP_ID</string>

6. Configure ad units in the Admin Panel

   Admin Panel → Settings → AdMob Settings. Enter your ad unit IDs for each placement (Home Banner, Challenge Interstitial, Rewarded Ad — for both Android and iOS).

Test Ad Unit IDs (Use During Development)

12. Creating the First Admin User

After deploying the admin panel, you need to create the first admin account. There is no default admin — you must create one manually.

Method 1 — Using the Setup Script (Recommended)

1. Get a service account key

   Firebase Console → Project Settings → Service accounts → Generate new private key. Download the JSON file. Save it as service-account.json in the project root.

2. Run the setup script

   nvm use 22
   node create_first_admin.js
   
   # The script prompts for:
   # - Admin email address
   # - Admin password (min 8 characters)
   # - Admin display name

Method 2 — Manual Setup via Firebase Console

1. Create a user in Firebase Auth

   Firebase Console → Authentication → Users → Add user. Enter email and password. Click Add user. Copy the User UID shown.

2. Add to the admin_users collection

   Firestore → admin_users collection → Add document. Document ID: paste the User UID. Add fields:

   name:       "Admin User"         (string)
   email:      "admin@yourapp.com"  (string)
   role:       "admin"              (string)
   created_at: (use server timestamp)

3. Verify login

   Open the admin panel URL → log in with the email and password you created → you should see the admin dashboard.

User Roles

13. Firestore Rules & Indexes

Firestore security rules control who can read and write data. Deploy them before going live.

1. Deploy security rules

   From the project root:

   firebase deploy --only firestore:rules

2. Deploy indexes

   Firestore indexes are required for complex queries (multiple where clauses, orderBy on different fields).

   firebase deploy --only firestore:indexes

3. Deploy storage rules

   firebase deploy --only storage
   
   # Or deploy everything at once:
   firebase deploy --only firestore:rules,firestore:indexes,storage

Common Index Error

If you see this error in the app:

The query requires an index. You can create it here: https://console.firebase.google.com/...

→ Click the link — it takes you directly to the index creation page.
→ Wait 2-5 minutes for the index to build after creating it.

14. Troubleshooting

Admin Panel Issues

Splash Screen Stuck / Never Loads

Access Denied After Login

Admin Panel Shows Wrong Firebase Data

// Check lms_admin/lib/services/auth_service.dart:
static const String _projectId = 'YOUR_CORRECT_PROJECT_ID';

Mobile App Issues

flutter pub get Fails

flutter clean
flutter pub get

# If still failing:
flutter pub cache repair
flutter pub get

Android Build Fails — NDK Version

iOS Build Fails — CocoaPods

cd lms_app/ios
pod repo update
pod install --repo-update

Google Sign-In Fails on Android

Cause: SHA-1 fingerprint not added to Firebase. Follow the steps in Section 10 — Social Login to add your SHA-1 fingerprint.

Firebase Functions Issues

Functions Deploy Fails

cd functions
nvm use 22
npm run build   # check for TypeScript errors first
firebase deploy --only functions

Secret Not Found Error

firebase functions:secrets:list   # see what's set
firebase functions:secrets:set MISSING_SECRET_NAME
firebase deploy --only functions

Useful Debug Commands

# Check Flutter environment
flutter doctor -v

# Check connected devices
flutter devices

# View Firebase function logs
firebase functions:log

# Check Firebase project
firebase projects:list
firebase use

# Verify secrets
firebase functions:secrets:list

# View Android logs
adb logcat | grep flutter

Commands Quick Reference

Mac Terminal Commands

flutter doctor                         # check Flutter setup
flutter pub get                        # install Flutter packages
flutter run                            # run app on connected device
flutter run -d chrome                  # run admin panel on Chrome
flutter build appbundle --release      # build Android AAB
flutter build ipa --release            # build iOS IPA
flutter build web --release            # build admin panel (in lms_admin/)
firebase deploy --only hosting:admin   # deploy admin panel
firebase deploy --only functions       # deploy Cloud Functions
firebase deploy                        # deploy everything at once

Windows PowerShell Commands

flutter doctor
flutter build appbundle --release
flutter build web --release
firebase deploy --only hosting:admin
firebase deploy --only functions
firebase deploy

Key URLs

Setup Checklist

Use this checklist to track your setup progress. Complete each item in order before proceeding to the next section.

Environment Setup

• Flutter SDK installed and verified (flutter doctor shows green)
• Android Studio installed with SDK & emulator configured
• Xcode installed and license accepted (Mac only)
• CocoaPods installed (Mac only)
• Node.js 22 installed via nvm
• Firebase CLI installed and logged in
• Project dependencies installed (flutter pub get in lms_app and lms_admin)

Firebase Setup

• Firebase project created
• Authentication enabled (Email/Password + Google)
• Firestore database created (Production mode)
• Firebase Storage enabled
• Firebase Hosting configured (admin + public sites)
• Firebase Blaze plan enabled (required for Functions)
• Android app registered — google-services.json placed
• iOS app registered — GoogleService-Info.plist placed
• firebase_options.dart updated in lms_app and lms_admin

Branding

• App name updated in app_config.dart, AndroidManifest.xml, and Info.plist
• Primary colour updated in app_config.dart and mwaghavul_theme.dart
• Logo placed at assets/images/logo.png (both apps)
• App icon placed at assets/images/icon.png (1024×1024px)
• flutter pub run flutter_launcher_icons run
• Package name changed from com.coduo.apps (Android + iOS)

Deployment

• Firestore security rules deployed
• Firestore indexes deployed
• Admin panel built and deployed to Firebase Hosting
• First admin user created
• Cloud Functions dependencies installed and deployed

API Keys & Configuration

• GROQ_API_KEY set (minimum recommended for AI)
• JUDGE0_API_KEY and JUDGE0_API_URL set
• STRIPE_SECRET_KEY and publishable key configured (if using Stripe)
• PAYSTACK_SECRET_KEY and public key configured (if using Paystack)
• Bank transfer details configured (if using)
• Google Sign-In SHA-1 fingerprint added to Firebase
• AdMob App IDs added to AndroidManifest.xml and Info.plist
• AdMob ad unit IDs configured in admin panel

Store Submission

• Android keystore generated and backed up securely
• key.properties configured with keystore details
• Android AAB built (flutter build appbundle --release)
• Google Play Console account created ($25 one-time fee)
• App listing completed with screenshots and description
• iOS bundle ID registered in Apple Developer portal
• App created in App Store Connect
• iOS IPA built (flutter build ipa --release)
• APNs key uploaded to Firebase for push notifications

App Features Overview

Mobile App — Learning Experience

• Structured Learning Tracks — tiered curriculum (Beginner → Intermediate → ML/AI) with modules and lessons
• 4 Exercise Types — concept cards, coding exercises, fill-in-the-blank, multiple choice
• Real Code Execution — Judge0 integration; runs Python, JavaScript, SQL, and more
• Test Case Validation — per-exercise test cases with pass/fail feedback and detailed results
• Skill Assessment Onboarding — adaptive quiz places users at the right level on first launch
• Daily Coding Challenges — one challenge per day with countdown timer and 7-day history
• Offline Mode — lessons cached locally; full offline reading with sync on reconnect
• PDF Library — in-app PDF reader for reference materials and ebooks
• Spaced Repetition System — flashcard-style review queue for coding concepts

AI Features

• AI Code Reviewer — Groq-powered code review with line-by-line comments and rating
• AI Error Explanation — one-tap AI explanation of runtime/compile errors in plain English
• AI Tutor Chat (“Ask Cody”) — in-lesson conversational AI tutor with lesson context awareness
• AI-Powered Recommendations — ML-based lesson recommendations based on performance history

Gamification

• Streak System — daily streak tracking with fire animation and milestone celebrations
• Streak Freeze — purchase freeze tokens to protect streak on missed days
• Hearts / Lives System — 5 hearts per session; deducted on wrong answers
• XP & Levelling — XP awarded for lessons, exercises, challenges, and daily challenges
• Gems (Virtual Currency) — earn gems; spend in the Gem Shop
• 40+ Achievements & Badges — across 7 categories with animated unlock celebration
• League / Division System — Bronze → Silver → Gold → Diamond weekly leagues
• Weekly XP Reset — league XP resets every Sunday with promotions/demotions
• Cosmetics System — unlock avatar frames, profile themes, and visual customisations

Social & Leaderboards

• 4-Tab Leaderboard — Weekly, All Time, League, and Following tabs
• Visual Podium — top 3 users on animated gold/silver/bronze podium
• Follow / Friend System — follow other users; Following tab shows friends' weekly XP
• Public Profile Screen — view any user's stats, badges, completed tracks, and activity
• Coding Clubs / Groups — create and join coding clubs with shared challenges
• Portfolio Builder — auto-generated PDF portfolio of completed tracks and skills

Payments & Monetisation

• Stripe Integration — card payments with 3D Secure support
• Paystack Integration — card and bank payments for African markets
• Bank Transfer — manual bank transfer with admin verification workflow
• Multi-Currency Support — USD, NGN, GHS and configurable exchange rates
• Subscription Plans — configurable free/pro/premium tiers with feature gates
• Purchase History — full transaction history with receipt viewer and PDF export

Admin Panel

• Live Dashboard — total users, revenue, active learners, lesson completions
• Track, Lesson & Challenge Manager — full content CRUD with ordering
• Exercise Builder — per-exercise test cases, hints, XP reward, language selection
• User Management — searchable user list, role assignment, export to CSV
• Transaction Management — full transaction list with status filter and bank transfer verification
• Push Notification Sender — send FCM notifications to all users or segments
• Revenue Analytics — period-based revenue charts with payment method breakdown
• Daily Challenge Manager — calendar view for scheduling with bulk create/edit
• Cosmetics Manager — create/edit cosmetic items with gem prices and rarity

Technical

• Flutter 3.x — single codebase for Android and iOS
• Firebase Backend — Firestore, Auth, Storage, FCM, App Check
• Riverpod State Management — reactive, testable state
• Hive Offline Cache — lessons and preferences cached locally
• 11 Languages — English, Arabic, Spanish, French, German, Hindi, Hebrew, Indonesian, Japanese, Portuguese, Chinese
• RTL Support — full right-to-left layout for Arabic and Hebrew
• Dark / Light Mode — system-aware with manual override
• Custom Coding Keyboard — extra toolbar row with brackets, operators, indent/dedent
• Syntax Highlighting — Python, JavaScript, SQL with theme-aware colour schemes

Licensing

Support & Contact

Coduo is an independent developer product. Please read this documentation carefully before reaching out for support.

We also offer freelance hire and customisation services. If you need the app customised for your specific use case, send a detailed description of your requirements to longsblack33@gmail.com.