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:

Tool	Version	Notes
Flutter SDK	3.44.4 (pinned)	Use FVM or download directly from flutter.dev
Dart SDK	Bundled with Flutter	Do not install separately
Melos	Latest	Monorepo task runner
Android Studio or Xcode	Latest	Needed 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

Architecture & Layering — Understand the package and layer structure before writing code.
Development Workflow — Step-by-step guide to adding a new feature.
Core Functions — How sync, auth, location, and notifications work.

Overview

Architecture & Design

Development & Testing

Getting Started

Overview

Prerequisites

1. Install Melos

2. Navigate to the mobile workspace

3. Install dependencies

4. Run code generation

5. Run the app

6. Verify everything works

Key daily commands

Project structure at a glance

Next steps

​Overview

​Prerequisites

​1. Install Melos

​2. Navigate to the mobile workspace

​3. Install dependencies

​4. Run code generation

​5. Run the app

​6. Verify everything works

​Key daily commands

​Project structure at a glance

​Next steps

Overview

Prerequisites

1. Install Melos

2. Navigate to the mobile workspace

3. Install dependencies

4. Run code generation

5. Run the app

6. Verify everything works

Key daily commands

Project structure at a glance

Next steps