# 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*