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