arc/.planning/codebase/CONCERNS.md

Codebase Concerns

Analysis Date: 2026-03-30

Tech Debt

iOS Platform Support Missing:

• Issue: The plugin only supports Android platform; iOS implementation is completely absent
• Files: pubspec.yaml (no iOS platform definition), lib/arc_platform_interface.dart, lib/arc_method_channel.dart
• Impact: Plugin cannot be used in iOS applications; limits market reach
• Fix approach: Create iOS native implementation using Swift/Objective-C with ArcSoft SDK iOS bindings

Unimplemented Mock Methods in Tests:

• Issue: MockArcPlatform in test file does not implement registerFaceFeature and registerFaceFeatureBatch methods
• Files: test/arc_test.dart (lines 8-60)
• Impact: Tests will fail when calling registration methods; incomplete test coverage
• Fix approach: Add mock implementations for all missing methods in MockArcPlatform

Placeholder Documentation:

• Issue: CHANGELOG.md and LICENSE files contain placeholder TODO text
• Files: CHANGELOG.md (line 3), LICENSE (line 1)
• Impact: Project appears incomplete; may confuse users about licensing
• Fix approach: Replace placeholder text with actual content

Known Bugs

No explicit engine disposal:

• Symptoms: FaceEngine instance in FaceEngineManager is never nullified after unInit()
• Files: android/src/main/java/com/xiarui/arc/FaceEngineManager.java (lines 268-278)
• Trigger: Calling unInit() then attempting to reuse engine
• Workaround: Re-initialize engine after disposal

State inconsistency after initialization failure:

• Symptoms: If init() fails, isInitialized remains false but faceEngine object still exists
• Files: android/src/main/java/com/xiarui/arc/FaceEngineManager.java (lines 141-159)
• Trigger: Engine initialization with invalid parameters
• Workaround: Check both isInitialized flag and error code before proceeding

Security Considerations

Hardcoded SDK Credentials in Example:

• Risk: Real SDK credentials (appId, sdkKey, activeKey) hardcoded in example application
• Files: example/lib/main.dart (lines 41-43)

  final String _appId = '4nPFuS2TYAQh9werHL2qbKjtTH9nnoixk7G6yqSUyjVH';
  final String _sdkKey = 'aWMTT3coxNQFETg9f3BGHCiBznAApXmcHFF3J5yQbsZ';
  final String _activeKey = 'NEAT7AU4KLCEK682';
  

• Current mitigation: Comment instructs users to replace with own keys (line 286)
• Recommendations: Use environment variables or config file; never commit real credentials; add .env.example template

Credential Transmission via Method Channel:

• Risk: Sensitive credentials (appId, sdkKey, activeKey) passed through method channel without encryption
• Files: lib/arc_method_channel.dart (lines 24-28), android/src/main/java/com/xiarui/arc/ArcPlugin.java (lines 95-97)
• Current mitigation: None
• Recommendations: Credentials are passed to native SDK which handles secure activation; acceptable for current architecture

Feature Data Privacy:

• Risk: Face feature data transmitted between Flutter and native layers could be intercepted
• Files: lib/arc_method_channel.dart, android/src/main/java/com/xiarui/arc/FaceEngineManager.java
• Current mitigation: Data stays within app boundary
• Recommendations: Ensure no logging of feature data; consider encryption for stored features

Performance Bottlenecks

Large Binary Data Transfer:

• Problem: Image data (NV21 format, potentially several MB per frame) transferred through method channel for each detection
• Files: lib/arc_method_channel.dart (lines 55-61), android/src/main/java/com/xiarui/arc/ArcPlugin.java (lines 154-157)
• Cause: Method channel serialization overhead for large byte arrays
• Improvement path: Consider using FFI for direct memory access; reduce image resolution; implement frame skipping

Real-time Detection Frame Rate:

• Problem: _isDetecting flag prevents concurrent processing but may cause frame drops
• Files: example/lib/main.dart (lines 406-407, 471-473)
• Cause: Sequential processing - new frames wait until current detection completes
• Improvement path: Implement queue-based processing with configurable frame skip; use dedicated detection thread

Feature Extraction Overhead:

• Problem: Feature extraction called synchronously, blocking UI thread potential
• Files: android/src/main/java/com/xiarui/arc/FaceEngineManager.java (lines 365-366)
• Cause: SDK operation runs on method channel thread
• Improvement path: Move heavy processing to background thread pool; provide async callbacks

Fragile Areas

NV21 Format Constraints:

• Files: android/src/main/java/com/xiarui/arc/FaceEngineManager.java (lines 179-189)
• Why fragile: Image width must be multiple of 4, height must be multiple of 2 for NV21 format - violation causes runtime errors
• Safe modification: Always validate dimensions before calling SDK; add Flutter-side validation
• Test coverage: No tests for invalid dimension handling

Singleton State Management:

• Files: android/src/main/java/com/xiarui/arc/FaceEngineManager.java (lines 54-59)
• Why fragile: Singleton pattern with mutable lastRgbLiveness field; concurrent access risk
• Safe modification: Add synchronization for mutable fields; or use ThreadLocal for liveness results
• Test coverage: No concurrent access tests

Camera Preview Orientation:

• Files: example/lib/main.dart (line 556)
• Why fragile: Fixed quarterTurns: -1 rotation may not work for all devices/orientations
• Safe modification: Calculate rotation based on device orientation and camera sensor orientation
• Test coverage: No tests for different device orientations

Scaling Limits

Face Database Size:

• Current capacity: Depends on ArcSoft SDK limits (typically 50,000 faces)
• Limit: Memory consumption increases with registered faces; search time increases
• Scaling path: Implement pagination; use external database for large-scale deployments; consider face clustering

Image Resolution:

• Current capacity: Default camera resolution (medium preset)
• Limit: Higher resolution = slower detection, more memory usage
• Scaling path: Allow configurable resolution; implement dynamic resolution adjustment based on device capability

Concurrent Detection Requests:

• Current capacity: Single detection at a time (_isDetecting flag)
• Limit: Multiple simultaneous requests queue up
• Scaling path: Implement request queue with priority; batch processing; dedicated worker threads

Dependencies at Risk

ArcSoft Face SDK:

• Risk: Third-party proprietary SDK; licensing and availability concerns
• Impact: Plugin entirely dependent on ArcSoft SDK availability and compatibility
• Migration plan: Abstract SDK interface; allow alternative face recognition backends (e.g., ML Kit, OpenCV)

camera package:

• Risk: External dependency in example app; version compatibility
• Impact: Example app functionality dependent on camera plugin stability
• Migration plan: Keep camera package updated; abstract camera interface for alternative implementations

Flutter SDK Version:

• Risk: Requires SDK ^3.9.0 which is relatively new
• Files: pubspec.yaml (line 7)
• Impact: Older Flutter versions cannot use plugin
• Migration plan: Consider lowering SDK constraint if backward compatibility needed

Missing Critical Features

Face Search (1:N Matching):

• Problem: registerFaceFeature and registerFaceFeatureBatch exist but no searchFaceFeature method to query registered faces
• Files: lib/arc.dart, android/src/main/java/com/xiarui/arc/FaceEngineManager.java
• Blocks: Cannot implement 1:N face recognition workflow (find matching face from database)

Engine Uninit from Flutter:

• Problem: No Flutter API to release engine resources
• Files: lib/arc.dart (no unInit method)
• Blocks: Memory leak if engine not properly released; cannot reset engine state

Error Code Documentation for Flutter:

• Problem: Error codes defined in Java but no Flutter-accessible documentation
• Files: android/src/main/java/com/xiarui/arc/FaceErrorCode.java (comprehensive), lib/arc.dart (no error code constants)
• Blocks: Flutter developers cannot interpret error codes without referencing native code

IR Liveness Detection:

• Problem: Only RGB liveness detection implemented; IR liveness not exposed
• Files: android/src/main/java/com/xiarui/arc/FaceEngineManager.java (only ASF_LIVENESS mask)
• Blocks: Cannot use more secure IR-based liveness detection if hardware available

Test Coverage Gaps

Native Unit Tests:

• What's not tested: All methods except getPlatformVersion in ArcPluginTest.java
• Files: android/src/test/java/com/xiarui/arc/ArcPluginTest.java (only 1 test method)
• Risk: Native method handling bugs undetected
• Priority: High

Flutter Integration Tests:

• What's not tested: Actual face detection with real image data; end-to-end workflows
• Files: No integration test files in test/ directory
• Risk: Real-world usage patterns not validated
• Priority: High

Method Channel Tests:

• What's not tested: All methods except getPlatformVersion in method channel test
• Files: test/arc_method_channel_test.dart (lines 24-26)
• Risk: Method channel communication bugs for complex methods undetected
• Priority: Medium

Edge Case Tests:

• What's not tested: Invalid parameters, null data, oversized images, engine not initialized
• Files: All test files lack edge case coverage
• Risk: Runtime crashes on invalid inputs
• Priority: Medium

Mock Implementation Completeness:

• What's not tested: registerFaceFeature, registerFaceFeatureBatch methods in mock
• Files: test/arc_test.dart (MockArcPlatform missing methods)
• Risk: Tests fail or skip when new methods are used
• Priority: Low

---

Concerns audit: 2026-03-30