Setting Up a New App in the Workspace

What you'll learn

• Generating a complete Flutter app shell within an existing workspace
• Configuring DI, routing, flavors, and bootstrap
• Setting up Fastlane, launcher icons, and splash screens
• Understanding the app's startup lifecycle

Prerequisites

• An existing Archipelago monorepo (see Monorepo Scaffolding)
• Core infrastructure already generated (see Core Infrastructure)

Step 1: Generate the App Scaffold

archipelago generate app_scaffold

You will be prompted for:

• appName — MyApp (the name of this application)
• organization — MyCompany (your organization name)
• domain — com (top-level domain, e.g., com, org, io)
• prefix — App (unique prefix for component naming)

Or use a config file:

{
  "appName": "MyApp",
  "organization": "MyCompany",
  "domain": "com",
  "prefix": "App"
}

archipelago generate app_scaffold --config scaffold_config.json

Step 2: Understand the Generated Structure

The scaffold creates a full-featured app shell ready for feature integration:

apps/my_app/
├── lib/
│   ├── main_development.dart       # Development entry point
│   ├── main_staging.dart           # Staging entry point
│   ├── main_production.dart        # Production entry point
│   ├── app/
│   │   ├── app.dart                # Root widget
│   │   ├── bootstrap.dart          # DI + feature registration
│   │   └── flavor.dart             # Flavor enum
│   └── router/
│       └── app_router.dart         # GoRouter configuration
├── android/
│   └── fastlane/                   # Android build automation
├── ios/
│   └── fastlane/                   # iOS build automation
├── assets/
│   ├── launcher_icons/             # Per-flavor app icons
│   └── splash/                     # Splash screen assets
└── pubspec.yaml

Step 3: Configure the Bootstrap

The generated bootstrap.dart handles two-phase initialization:

Future<void> bootstrap(Flavor flavor) async {
  // Phase 1: Pre-launch (blocking)
  await GlobalDI.init(flavor);
  FeatureRegistry.registerAll();
  final router = AppRouter.create();

  // Phase 2: Post-launch (non-blocking)
  runApp(MyApp(router: router));
  unawaited(PostLaunchInit.run());
}

Step 4: Run Per Flavor

Each flavor has its own entry point:

flutter run --target lib/main_development.dart
flutter run --target lib/main_staging.dart
flutter run --target lib/main_production.dart

Key Customization Points

Customization	Where to Change
Add a new flavor	Create main_<flavor>.dart, update flavor.dart enum
Change app icon per flavor	assets/launcher_icons/ — replace images per flavor
Modify splash screen	assets/splash/ — update branding assets
Add pre-launch blocking init	bootstrap.dart — Phase 1 section
Configure Fastlane lanes	android/fastlane/Fastfile, ios/fastlane/Fastfile

Next Steps

• Set up the Network SDK for API communication
• Set up authentication to add login flows
• Generate a UI Kit to theme the app