​
Overview

This guide walks you through setting up your local development environment and running the FieldForce app for the first time.

​
Prerequisites

Before you begin, install the following tools:
ToolVersionNotes
Flutter SDK3.44.4 (pinned)Use FVM or download directly from flutter.dev
Dart SDKBundled with FlutterDo not install separately
MelosLatestMonorepo task runner
Android Studio or XcodeLatestNeeded for emulators and code signing
iOS builds require macOS. If you are on Linux or Windows you can still build for Android; iOS requires a Mac (or Codemagic CI — see the CI/CD guide).

​
1. Install Melos

Melos is the tool that coordinates commands across all packages in the workspace. 
dart pub global activate melos
Add the Dart pub global binaries to your PATH if not already there: 
export PATH="$PATH:$HOME/.pub-cache/bin"

​
2. Navigate to the mobile workspace

The Flutter workspace lives inside the monorepo: 
cd mobile/flutter
All commands below are run from this directory.

​
3. Install dependencies

dart pub get          # workspace-level dependencies
melos exec -- flutter pub get   # dependencies for every app and package

​
4. Run code generation

The project uses code generators (Freezed, Riverpod, slang). Generated files are committed to Git, so you normally don’t need to run this on first checkout — but if you see .freezed.dart or .g.dart files missing or out of date, run: 
melos run generate

​
5. Run the app

Config files live alongside the app. For local development, use the dev flavor: 
cd apps/fieldforce
flutter run --dart-define-from-file=config/dev.json
The dev.json file points to:
  • API_BASE_URL: your local Go backend
  • POWERSYNC_URL: your local PowerSync service
The backend must be running for auth and sync to work. Check the Go backend and PowerSync getting-started guides if you need to spin those up locally.
For a specific device, list connected devices first: 
flutter devices
flutter run --dart-define-from-file=config/dev.json -d <device-id>

​
6. Verify everything works

Once running, you should be able to:
  • See the login screen
  • Sign in with a dev account
  • See the tasks list (may be empty on a fresh database)
If you see sync errors, check that the PowerSync service is running and that POWERSYNC_URL in config/dev.json is correct.

​
Key daily commands

Run these from mobile/flutter/: 
# Check code style + DAG rules (always run before committing)
melos run analyze

# Run all tests
melos run test

# Regenerate code after changing a Freezed model, Riverpod provider, or slang locale
melos run generate

# Watch for changes and auto-regenerate (use during active development)
melos run generate:watch

​
Project structure at a glance

mobile/flutter/
  apps/
    fieldforce/           ← The main app you run
      config/
        dev.json          ← API URLs for local development
        staging.json
        prod.json
      lib/
        features/         ← App screens and logic (tasks/, auth/, home/)
        app.dart          ← App root (routing, theme, providers)
        main_dev.dart     ← Entry point for the dev flavor
  packages/
    core_models/          ← Shared types (Task, Result, AppFailure)
    core_network/         ← API client and DTOs
    core_auth/            ← Auth logic and JWT handling
    core_database/        ← PowerSync/SQLite wiring
    core_ui/              ← Shared Brand components
    core_i18n/            ← Translations (EN, ZH, MS)
    core_notifications/   ← Push notifications

​
Next steps