Architecture

How seon_orchestration_flutter bridges Flutter to the native SEON SDKs.

Overview

seon_orchestration_flutter is built as a Flutter plugin using MethodChannel to bridge Dart to the native SEON Orchestration SDKs on iOS and Android.

Architecture Layers

Dart Layer

The Dart layer provides the public API, types, and MethodChannel communication.

Key files:

• lib/src/seon_orchestration.dart — Public API with static methods wrapping MethodChannel calls
• lib/src/types.dart — Dart classes and enums (SeonConfig, SeonVerificationResult, SeonVerificationStatus, SeonErrorCode, SeonException)
• lib/seon_orchestration_flutter.dart — Barrel export file

The MethodChannel is defined with the name seon_orchestration:

class SeonOrchestration {
  @visibleForTesting
  static MethodChannel channel = const MethodChannel('seon_orchestration');

  static Future<void> initialize(SeonConfig config) async {
    try {
      await channel.invokeMethod<void>('initialize', {
        'baseUrl': config.baseUrl,
        'token': config.token,
        if (config.language != null) 'language': config.language,
        if (config.themeJson != null) 'theme': config.themeJson,
      });
    } on PlatformException catch (e) {
      throw SeonException(
        code: SeonErrorCode.fromString(e.code),
        rawCode: e.code,
        message: e.message ?? 'Unknown initialization error',
      );
    }
  }

  static Future<SeonVerificationResult> startVerification() async { ... }

  static Future<void> dispose() async { ... }
}

The channel is exposed with @visibleForTesting so tests can swap in a mock channel without needing a platform interface package.

iOS Implementation

The iOS implementation uses Swift with a plugin registrar pattern.

Key files:

• ios/Classes/SeonOrchestrationPlugin.swift — Plugin registrar, receives MethodChannel calls
• ios/Classes/SeonOrchestrationImpl.swift — Swift singleton with actual SDK integration

How it works:

1. SeonOrchestrationPlugin registers as a MethodChannel handler
2. Incoming method calls are dispatched to SeonOrchestrationImpl
3. SeonOrchestrationImpl manages SDK initialization and verification flow
4. Results are returned via the FlutterResult callback

The Swift class SeonOrchestrationImpl handles:

• SDK initialization with configuration
• Managing the UINavigationController for the verification flow
• Implementing SEONOrchSDKServiceDelegate to receive callbacks
• Bridging delegate callbacks to the stored FlutterResult

Android Implementation

The Android implementation is written in Kotlin and uses a proxy Activity pattern.

Key files:

• android/.../SeonOrchestrationPlugin.kt — FlutterPlugin + ActivityAware implementation
• android/.../SeonVerificationActivity.kt — Transparent proxy Activity

How it works:

1. startVerification is called from Dart via MethodChannel
2. Plugin stores the MethodChannel result and launches the proxy Activity
3. Proxy Activity registers an ActivityResultLauncher and starts SEON verification
4. When complete, the Activity resolves the stored result and finishes itself

Why a proxy Activity?

• The SEON SDK requires an Activity to launch its flow
• ActivityResultLauncher must be registered before the Activity reaches STARTED lifecycle state
• The proxy Activity provides a clean lifecycle boundary
• It uses a transparent theme (Theme.Translucent.NoTitleBar) so users don’t see it

class SeonVerificationActivity : ComponentActivity() {
    private val verificationLauncher = registerForActivityResult(StartActivityForResult()) { result ->
        resolveResult(result.resultCode, result.data)
        finish()
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // If restored after process death, pendingResult is gone — finish immediately.
        if (savedInstanceState != null && pendingResult == null) {
            finish()
            return
        }

        OrchestrationService.instance.startVerificationFlow(verificationLauncher, applicationContext)
    }
}

Data Flow

Initialization Flow

Dart                     MethodChannel            Native
  |                          |                       |
  | initialize(config)       |                       |
  |------------------------->|                       |
  |                          | invokeMethod           |
  |                          |----------------------->|
  |                          |                       | Initialize SDK
  |                          |                       | Store config
  |                          |    FlutterResult       |
  |                          |<-----------------------|
  |     Future completes     |                       |
  |<-------------------------|                       |

Verification Flow

Dart                     MethodChannel            Native                  SEON SDK
  |                          |                       |                         |
  | startVerification()      |                       |                         |
  |------------------------->|                       |                         |
  |                          | invokeMethod           |                         |
  |                          |----------------------->|                         |
  |                          |                       | Store result callback    |
  |                          |                       | Launch Activity/Present  |
  |                          |                       |------------------------>|
  |                          |                       |                         | User interaction
  |                          |                       |    Delegate callbacks    |
  |                          |                       |<------------------------|
  |                          |    FlutterResult       |                         |
  |                          |<-----------------------|                         |
  |     Result received      |                       |                         |
  |<-------------------------|                       |                         |

Error Handling

Errors are propagated through PlatformException:

1. Native code catches exceptions
2. Returns error via FlutterResult with error code and message
3. Dart receives PlatformException
4. Plugin wraps it as SeonException with a typed SeonErrorCode enum and the raw platform string

Error codes are defined consistently across platforms to provide a unified error API. The SeonErrorCode.fromString() method maps raw platform strings to enum values, with unknown as a fallback.

Thread Safety

• iOS: All SDK calls are explicitly dispatched to the main thread
• Android: Activity lifecycle ensures operations run on the UI thread
• MethodChannel: Flutter handles thread marshalling automatically

Performance Considerations

• Lazy initialization: SDK is not initialized until initialize() is called
• Single instance: Only one verification can run at a time
• Transparent UI: Android proxy Activity uses transparent theme to avoid UI flicker
• Efficient bridging: MethodChannel uses binary message passing with minimal overhead