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)
  ```dart
  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*