App Boilerplate

A modular, offline-first Flutter boilerplate for apps that store, sync, and share media and metadata across centralized (Immich, Firebase) and decentralized (Nostr) systems.

Phase 0 - Project Setup

• Flutter project skeleton with config loader
• Testing framework setup
• CI workflow

Quick Start

# Install dependencies
flutter pub get

# Run tests (important: separate from running the app!)
flutter test

# Or run on Android (wait for emulator to fully boot first)
flutter run

# Run with specific environment
flutter run --dart-define=ENV=prod

Note: flutter run launches the app but does not run tests. Always run flutter test separately to verify tests pass.

Configuration

Config Files Location

Configuration is defined in code at:

• lib/config/app_config.dart - Configuration model
• lib/config/config_loader.dart - Environment loader (where to tweak values)

How to Modify Config

Edit lib/config/config_loader.dart to change environment values:

// Current dev config (lines 36-40)
case 'dev':
  return const AppConfig(
    apiBaseUrl: 'https://api-dev.example.com',  // ← Change this
    enableLogging: true,                         // ← Change this
  );

// Current prod config (lines 41-45)
case 'prod':
  return const AppConfig(
    apiBaseUrl: 'https://api.example.com',      // ← Change this
    enableLogging: false,                        // ← Change this
  );

Environment Variables

Currently, the app uses compile-time environment variables via --dart-define:

# Set environment at runtime
flutter run --dart-define=ENV=prod

Future: .env file support can be added in later phases. When implemented, .env files would go in the project root and be loaded at runtime.

Available Environments

• dev - Development (default): Logging enabled, dev API URL
• prod - Production: Logging disabled, production API URL

Running the App

Android Emulator

Important: Wait for emulator to fully boot (30-60 seconds on cold boot).

1. Start emulator from Android Studio AVD Manager
2. Wait for boot animation to complete and home screen appears
3. Run: flutter run

iOS Simulator (macOS)

open -a Simulator
flutter run

Running Tests

# Run all tests
flutter test

# Run with coverage
flutter test --coverage

Important: Tests must be run separately - flutter run does not execute tests.

Project Structure

lib/
 ├── config/
 │    ├── app_config.dart      # Config model
 │    └── config_loader.dart   # Environment loader (edit here!)
 └── main.dart

test/
 └── config/
      └── config_loader_test.dart

.github/workflows/
 └── flutter-ci.yml

CI/CD

GitHub Actions workflow (.github/workflows/flutter-ci.yml) runs on push/PR to main or master branches:

Workflow steps:

1. Checkout code - actions/checkout@v4
2. Setup Flutter - Flutter 3.24.0 (stable channel)
3. Install dependencies - flutter pub get
4. Run tests - flutter test
5. Report results - Success/failure messages

Commands executed:

flutter pub get
flutter test

The workflow runs on Ubuntu latest and reports test results in the GitHub Actions UI.