bloomBUILD•SHIP•BLOOM
Framework ArchitectureBoot & Lifecycle
.md
Deterministic Runtime

Boot & Lifecycle

Bloom eliminates race conditions and scattered initialization boilerplate by orchestrating a deterministic 10-step boot sequence before the first frame renders.

Application Entrypoint

Instead of calling runApp() directly with fragmented await init() calls, pass your bootstrapper to Bloom.boot():

lib/main.dart
dart
// lib/main.dart
import 'package:flutter/material.dart';
import 'package:bloom_framework/bloom.dart';
import 'app/boot.dart';
import 'app/app.dart';

void main() async {
  // Deterministic 10-step boot orchestration
  await Bloom.boot(
    bootstrapper: AppBootstrapper(),
    app: const App(),
  );
}

BloomBootstrapper Interface

Implement BloomBootstrapper to configure services, asynchronous database connections, and auth sessions:

lib/app/boot.dart
dart
// lib/app/boot.dart
import 'package:bloom_framework/bloom.dart';
import '../services/api_service.dart';
import '../services/auth_service.dart';

class AppBootstrapper implements BloomBootstrapper {
  @override
  Future<void> onBoot(BloomContainer container) async {
    // 1. Register base singletons
    container.provideSingleton<BloomConfig>((c) => BloomConfig.fromEnvironment());
    
    // 2. Register typed services with lazy instantiation
    container.provideLazySingleton<ApiService>((c) => ApiService(
      baseUrl: c.inject<BloomConfig>().apiBaseUrl,
    ));

    // 3. Register asynchronous services
    final auth = AuthService();
    await auth.initializeSession();
    container.provideInstance<AuthService>(auth);
  }

  @override
  void onError(Object error, StackTrace stack) {
    BloomLogger.error('Boot sequence failed: $error', error: error, stackTrace: stack);
  }
}

The 10-Step Deterministic Sequence

01

WidgetsFlutterBinding Initialization

Ensures the Flutter engine communication channel is established synchronously.

02

Environment & Config Loading

Parses .env and compiles compile-time String.fromEnvironment variables into BloomConfig.

03

BloomContainer Dependency Setup

Instantiates the hierarchical DI container and registers framework singletons.

04

User Bootstrapper Execution

Executes your custom AppBootstrapper.onBoot(container) hook.

05

Router Compilation & Guards

Loads generated routes.g.dart, sets up route authentication guards and redirect handlers.

06

Data Cache Rehydration

Restores persisted SQLite/Hive SWR cache keys for instant offline startup.

07

Native Autolink Verification

Verifies native platform plugins and config signatures generated by prebuild.

08

Error Boundary Hooks

Connects FlutterError.onError and PlatformDispatcher.onError to BloomLogger.

09

App Shell Assembly

Wraps the root widget with BloomTheme, ToastProvider, and Watch contexts.

10

runApp Launch

Executes runApp() on the Flutter engine with smooth first-frame rendering.

Previous: 5-Minute QuickstartNext: Filesystem Routing