docs: map existing codebase
This commit is contained in:
160
.planning/codebase/ARCHITECTURE.md
Normal file
160
.planning/codebase/ARCHITECTURE.md
Normal file
@@ -0,0 +1,160 @@
|
||||
# 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*
|
||||
Reference in New Issue
Block a user