arc/.planning/codebase/ARCHITECTURE.md

Architecture

Analysis Date: 2026-03-30

Pattern Overview

Overall: Flutter Plugin Architecture with Platform Interface Pattern

Key Characteristics:

• Flutter plugin wrapping ArcSoft Face Recognition SDK (Android only)
• Platform interface abstraction for cross-platform extensibility
• Method channel communication between Dart and native Android
• Singleton pattern for native FaceEngine management
• Comprehensive error code enumeration for SDK error handling

Layers

Dart Public API Layer:

• Purpose: Provides user-facing API for face recognition operations
• Location: lib/arc.dart
• Contains: Public methods with detailed documentation
• Depends on: ArcPlatform interface
• Used by: Flutter applications consuming this plugin

Platform Interface Layer:

• Purpose: Abstract interface for platform-specific implementations
• Location: lib/arc_platform_interface.dart
• Contains: Abstract method definitions, platform instance management
• Depends on: plugin_platform_interface package
• Used by: Arc class, mock implementations for testing

Method Channel Layer:

• Purpose: Implements platform interface using Flutter method channels
• Location: lib/arc_method_channel.dart
• Contains: Method channel invocation logic, parameter marshalling
• Depends on: Flutter MethodChannel, ArcPlatform interface
• Used by: Default platform instance registration

Android Native Plugin Layer:

• Purpose: Handles method channel calls, dispatches to engine manager
• Location: android/src/main/java/com/xiarui/arc/ArcPlugin.java
• Contains: Method call handler, parameter validation, result marshalling
• Depends on: FaceEngineManager, Flutter plugin APIs
• Used by: Flutter engine via plugin registration

Android Engine Manager Layer:

• Purpose: Manages ArcSoft FaceEngine singleton, executes SDK operations
• Location: android/src/main/java/com/xiarui/arc/FaceEngineManager.java
• Contains: SDK activation, engine lifecycle, face detection/extraction/comparison logic
• Depends on: ArcSoft SDK (arcsoft_face.jar)
• Used by: ArcPlugin handler methods

Data Model Layer:

• Purpose: Encapsulates face information and error codes
• Location: android/src/main/java/com/xiarui/arc/FaceInfo.java, FaceErrorCode.java
• Contains: Data structures for face results, comprehensive error code enumeration
• Depends on: Android SDK (Rect class)
• Used by: All native layers for data transfer

Data Flow

SDK Activation Flow:

1. Flutter app calls Arc.activeOnline(appId, sdkKey, activeKey)
2. Arc delegates to ArcPlatform.instance.activeOnline()
3. MethodChannelArc invokes method channel with 'activeOnline'
4. ArcPlugin.handleActiveOnline() validates parameters
5. FaceEngineManager.getInstance().activeOnline() calls ArcSoft SDK
6. Error code mapped to FaceErrorCode enum
7. Result Map returned through method channel to Flutter

Face Detection Flow:

1. Flutter app calls Arc.detectFaces(data, width, height, format)
2. Method channel invokes 'detectFaces' with byte array payload
3. ArcPlugin.handleDetectFaces() validates image parameters
4. FaceEngineManager.detectFaces() executes SDK face detection
5. RGB liveness detection processed via faceEngine.process() and getLiveness()
6. FaceInfo list converted to Map structure via convertFaceInfoToList()
7. Result includes faceList, rgbLiveness, isRgbAlive

Face Feature Extraction Flow:

1. Flutter app calls Arc.extractFaceFeature() with face rect from detection
2. Native layer creates FaceInfo object from rect coordinates
3. FaceEngineManager.extractFaceFeature() calls SDK extract method
4. Feature data (byte array) returned in result Map

Feature Comparison Flow:

1. Flutter app calls Arc.compareFaceFeature(featureData1, featureData2, compareModel)
2. Native layer creates FaceFeature objects from byte arrays
3. FaceEngineManager.compareFaceFeature() executes SDK comparison
4. Similarity score (0.0-1.0) returned in result Map

State Management:

• Singleton FaceEngineManager holds FaceEngine instance
• Engine initialization state tracked via isInitialized flag
• Last RGB liveness result cached in lastRgbLiveness field

Key Abstractions

ArcPlatform Interface:

• Purpose: Platform-agnostic interface for face recognition operations
• Examples: lib/arc_platform_interface.dart
• Pattern: Platform Interface pattern with token verification

FaceEngineManager Singleton:

• Purpose: Centralized management of ArcSoft FaceEngine lifecycle
• Examples: android/src/main/java/com/xiarui/arc/FaceEngineManager.java
• Pattern: Singleton with synchronized getInstance()

FaceErrorCode Enumeration:

• Purpose: Maps SDK numeric error codes to human-readable messages
• Examples: android/src/main/java/com/xiarui/arc/FaceErrorCode.java
• Pattern: Enum with code lookup via fromCode()

FaceInfo Data Model:

• Purpose: Represents single face detection result
• Examples: android/src/main/java/com/xiarui/arc/FaceInfo.java
• Pattern: JavaBean with toMap() for Flutter serialization

Entry Points

Flutter Plugin Entry:

• Location: lib/arc.dart
• Triggers: Flutter app imports and instantiates Arc class
• Responsibilities: Public API facade, delegates to platform interface

Android Plugin Registration:

• Location: android/src/main/java/com/xiarui/arc/ArcPlugin.java
• Triggers: Flutter engine attaches plugin via onAttachedToEngine()
• Responsibilities: Method channel setup, call dispatching

Example App Entry:

• Location: example/lib/main.dart
• Triggers: App launch via void main()
• Responsibilities: Demonstrates SDK activation, engine init, camera-based face detection

Error Handling

Strategy: Consistent Map return structure with success/error fields

Patterns:

• All public methods return Map<String, dynamic>? with keys: success, errorCode, message
• Native layer uses FaceErrorCode.fromCode() for error mapping
• Custom error codes for internal failures (e.g., ENGINE_NOT_INITIALIZED = -1)
• Flutter layer receives structured error info, no exception throwing for SDK errors
• Platform exceptions caught in example app with PlatformException handler

Cross-Cutting Concerns

Logging: Android native uses android.util.Log with tag "FaceEngineManager" Validation: Native methods validate engine initialization, image dimensions (width %4, height %2 for NV21) Authentication: SDK requires online activation with appId/sdkKey/activeKey from ArcSoft console Image Format: NV21 (format code 2050) is primary supported format for camera streams

---

Architecture analysis: 2026-03-30