arc/.planning/codebase/STRUCTURE.md

Codebase Structure

Analysis Date: 2026-03-30

Directory Layout

D:\code\new_git_code\arc/
├── lib/                    # Flutter Dart source code
├── android/                # Android native implementation
├── test/                   # Unit tests for Dart code
├── example/                # Example Flutter application
├── docs/                   # Documentation files
├── .dart_tool/             # Dart tool cache (generated)
├── .planning/              # Planning documents (generated)
└── pubspec.yaml            # Flutter package manifest

Directory Purposes

lib:

• Purpose: Flutter plugin Dart source code
• Contains: Public API, platform interface, method channel implementation
• Key files: arc.dart, arc_platform_interface.dart, arc_method_channel.dart

android:

• Purpose: Android native implementation for ArcSoft SDK integration
• Contains: Java source, ArcSoft SDK libraries, Gradle build config
• Key files: src/main/java/com/xiarui/arc/ArcPlugin.java, libs/arcsoft_face.jar

test:

• Purpose: Unit tests for Dart plugin code
• Contains: Mock platform implementations, method channel tests
• Key files: arc_test.dart, arc_method_channel_test.dart

example:

• Purpose: Demonstrates plugin usage with camera-based face detection
• Contains: Complete Flutter app with camera preview and detection UI
• Key files: lib/main.dart, integration_test/plugin_integration_test.dart

docs:

• Purpose: External SDK documentation
• Contains: ArcSoft face recognition API documentation
• Key files: 虹软人脸识别接口文档.md

android/libs:

• Purpose: ArcSoft native SDK JAR files
• Contains: arcsoft_face.jar (face recognition), arcsoft_image_util.jar (image utilities)
• Generated: No (third-party SDK)
• Committed: Yes

android/src/main/jniLibs:

• Purpose: Native library files for different CPU architectures
• Contains: .so files for arm64-v8a, armeabi-v7a
• Generated: No (from ArcSoft SDK)
• Committed: Yes

Key File Locations

Entry Points:

• lib/arc.dart: Public API entry point for plugin consumers
• android/src/main/java/com/xiarui/arc/ArcPlugin.java: Android plugin registration and method handling
• example/lib/main.dart: Example app entry point

Configuration:

• pubspec.yaml: Flutter package configuration, SDK version constraints
• android/build.gradle: Android library build configuration, SDK dependencies
• android/src/main/AndroidManifest.xml: Android permissions (CAMERA, INTERNET, STORAGE)

Core Logic:

• lib/arc_platform_interface.dart: Platform interface abstract class
• lib/arc_method_channel.dart: Method channel implementation
• android/src/main/java/com/xiarui/arc/FaceEngineManager.java: Singleton managing FaceEngine lifecycle

Data Models:

• android/src/main/java/com/xiarui/arc/FaceInfo.java: Face detection result model
• android/src/main/java/com/xiarui/arc/FaceErrorCode.java: Error code enumeration (586 lines)

Testing:

• test/arc_test.dart: Mock platform tests
• test/arc_method_channel_test.dart: Method channel unit tests
• android/src/test/java/com/xiarui/arc/ArcPluginTest.java: Android unit tests

Naming Conventions

Files:

• Dart: lowercase with underscores, e.g., arc_platform_interface.dart
• Java: PascalCase for classes, e.g., ArcPlugin.java, FaceEngineManager.java

Classes:

• Dart: PascalCase, e.g., Arc, ArcPlatform, MethodChannelArc
• Java: PascalCase, e.g., FaceEngineManager, FaceErrorCode

Methods:

• Dart: camelCase with descriptive names, e.g., activeOnline, detectFaces, extractFaceFeature
• Java: camelCase with handler prefix for dispatch, e.g., handleActiveOnline, handleDetectFaces

Variables:

• Dart: camelCase for local/instance variables
• Java: camelCase, enum constants use UPPER_SNAKE_CASE, e.g., MERR_ASF_ACTIVATION_FAIL

Where to Add New Code

New Feature (Dart API):

• Primary code: lib/arc.dart - add public method
• Interface: lib/arc_platform_interface.dart - add abstract method
• Implementation: lib/arc_method_channel.dart - add method channel invocation

New Feature (Android Native):

• Handler: android/src/main/java/com/xiarui/arc/ArcPlugin.java - add case in onMethodCall() switch
• Logic: android/src/main/java/com/xiarui/arc/FaceEngineManager.java - add SDK operation method

New Platform Support (iOS/Web):

• Create platform-specific implementation in appropriate directory
• Register in pubspec.yaml under plugin.platforms

New Data Model:

• Location: android/src/main/java/com/xiarui/arc/ alongside existing models
• Pattern: JavaBean style with getters/setters and toMap() method

Tests:

• Dart tests: test/ directory, named *_test.dart
• Android tests: android/src/test/java/com/xiarui/arc/ directory

Utilities:

• Shared helpers: android/src/main/java/com/xiarui/arc/ as utility classes

Special Directories

android/libs:

• Purpose: ArcSoft SDK JAR files (third-party)
• Generated: No
• Committed: Yes (required for build)
• Note: Contains arcsoft_face.jar, arcsoft_image_util.jar

android/src/main/jniLibs:

• Purpose: Native .so libraries for CPU architectures
• Generated: No (from ArcSoft SDK distribution)
• Committed: Yes
• Architectures: arm64-v8a, armeabi-v7a

example/build:

• Purpose: Flutter/Gradle build artifacts
• Generated: Yes
• Committed: No (should be in .gitignore)

.dart_tool:

• Purpose: Dart package config and tool cache
• Generated: Yes
• Committed: No

.planning:

• Purpose: GSD planning documents
• Generated: Yes (by GSD tools)
• Committed: Yes (for team visibility)

Package Structure

Flutter Package:

• Package name: arc
• Version: 0.0.1
• SDK constraint: ^3.9.0
• Flutter constraint: >=3.3.0
• Platforms: Android only (current)

Android Package:

• Package name: com.xiarui.arc
• Plugin class: ArcPlugin
• Min SDK: 24 (Android 7.0)
• Compile SDK: 36
• Java version: 11

---

Structure analysis: 2026-03-30