# Codebase Structure

**Analysis Date:** 2026-04-16

## Directory Layout

```
ch34/                              # Flutter plugin root
├── lib/                           # Dart source code
│   ├── ch34.dart                  # Main library entry point (exports)
│   ├── ch34_platform_interface.dart  # Backward compat: re-exports src/
│   ├── ch34_method_channel.dart   # Backward compat: re-exports src/
│   └── src/                       # Core implementation
│       ├── ch34_manager.dart      # Public static API facade
│       ├── ch34_platform_interface.dart  # Abstract platform interface
│       ├── ch34_method_channel.dart      # MethodChannel implementation
│       └── types/
│           └── ch34_types.dart    # All data types and enums
├── android/                       # Android native code
│   ├── build.gradle               # Android library build config
│   ├── settings.gradle            # Gradle settings
│   ├── libs/                      # Native dependency JARs
│   │   └── CH34XUARTDriver.jar    # WCH UART library
│   └── src/
│       ├── main/java/com/example/ch34/
│       │   ├── Ch34Plugin.java           # Main plugin + MethodCallHandler
│       │   ├── Ch34DataStreamHandler.java # Data EventChannel handler
│       │   ├── Ch34ModemStreamHandler.java # Modem EventChannel handler
│       │   ├── Ch34UsbStateStreamHandler.java # USB hotplug handler
│       │   └── Ch34TypeConverter.java    # Type conversion utilities
│       └── test/java/com/example/ch34/
│           └── Ch34PluginTest.java       # Unit tests
├── example/                       # Example Flutter app
│   ├── lib/
│   │   └── main.dart              # Example app with device scan/connect/send
│   ├── test/
│   │   └── widget_test.dart       # Widget test (stub)
│   └── integration_test/
│       └── plugin_integration_test.dart  # Integration test
├── test/                          # Plugin unit tests
│   ├── ch34_test.dart             # Platform interface + manager tests
│   └── ch34_method_channel_test.dart     # MethodChannel mock tests
├── docs/
│   └── CH34X-api_docs.md          # WCH API documentation reference
├── pubspec.yaml                   # Plugin package manifest
├── analysis_options.yaml          # Dart linting config
├── CHANGELOG.md                   # Version history
├── LICENSE                        # License file
├── README.md                      # Plugin documentation
└── .gitignore                     # Git ignore rules
```

## Directory Purposes

### `lib/` - Dart Source
- **Purpose:** All Dart code for the Flutter plugin
- **Key files:**
  - `lib/ch34.dart` - Primary consumer import: `import 'package:ch34/ch34.dart';`
  - `lib/src/ch34_manager.dart` - Static facade, all public APIs
  - `lib/src/ch34_platform_interface.dart` - Abstract interface with 33 methods
  - `lib/src/ch34_method_channel.dart` - MethodChannel + EventChannel implementation
  - `lib/src/types/ch34_types.dart` - Shared data models and enums

### `android/` - Android Native
- **Purpose:** Java implementation bridging to WCH CH34X UART library
- **Key files:**
  - `android/src/main/java/com/example/ch34/Ch34Plugin.java` - Plugin entry point (788 lines)
  - `android/build.gradle` - Library configuration (compileSdk 34, minSdk 21, Java 8)
  - `android/libs/CH34XUARTDriver.jar` - WCH vendor SDK (binary dependency)

### `example/` - Sample Application
- **Purpose:** Demonstrates plugin usage for development and testing
- **Key files:**
  - `example/lib/main.dart` - Full working example: scan devices, open, set params, send/receive data

### `test/` - Plugin Tests
- **Purpose:** Unit tests for the Dart plugin code
- **Contains:** MethodChannel mock tests, platform interface mock implementation

## Key File Locations

**Entry Points:**
- `lib/ch34.dart`: Main library entry, consumer-facing import
- `android/src/main/java/com/example/ch34/Ch34Plugin.java`: Android plugin entry, registered via `pubspec.yaml`

**Configuration:**
- `pubspec.yaml`: Plugin declaration, Android platform registration (`package: com.example.ch34`, `pluginClass: Ch34Plugin`)
- `android/build.gradle`: Android library build configuration
- `analysis_options.yaml`: Dart linting (extends `flutter_lints`)

**Core Logic:**
- `lib/src/ch34_manager.dart`: Static API facade (all consumer methods)
- `lib/src/ch34_platform_interface.dart`: Abstract interface contract
- `lib/src/ch34_method_channel.dart`: Channel communication implementation
- `android/src/main/java/com/example/ch34/Ch34Plugin.java`: Native bridge logic

**Types:**
- `lib/src/types/ch34_types.dart`: All data classes (`UsbDeviceInfo`, `SerialParameter`, `ModemStatus`, `GpioStatus`) and enums (`DataBits`, `StopBits`, `Parity`, `GpioDirection`, `GpioValue`, `SerialErrorType`)

**Testing:**
- `test/ch34_method_channel_test.dart`: Unit tests with mock platform
- `test/ch34_test.dart`: Integration-style tests with real MethodChannel mock
- `example/integration_test/plugin_integration_test.dart`: On-device integration test

## Naming Conventions

**Files:**
- Dart: `snake_case.dart` for all files (e.g., `ch34_manager.dart`, `ch34_types.dart`)
- Java: `PascalCase.java` for all classes (e.g., `Ch34Plugin.java`, `Ch34TypeConverter.java`)

**Dart Classes:**
- Public API class: `Ch34Manager` (static methods, facade pattern)
- Platform interface: `Ch34Platform` (abstract, extends `PlatformInterface`)
- Channel implementation: `MethodChannelCh34` (extends `Ch34Platform`)
- Data types: `UsbDeviceInfo`, `SerialParameter`, `ModemStatus`, `GpioStatus`
- Enums: `DataBits`, `StopBits`, `Parity`, `GpioDirection`, `GpioValue`, `SerialErrorType`
- Exception: `Ch34Exception`

**Java Classes:**
- Main plugin: `Ch34Plugin` (implements `FlutterPlugin`, `MethodCallHandler`)
- Stream handlers: `Ch34DataStreamHandler`, `Ch34ModemStreamHandler`, `Ch34UsbStateStreamHandler`
- Utility: `Ch34TypeConverter` (static methods only, private constructor)

**MethodChannel names:**
- Method channel: `'ch34'`
- Data event channel: `'ch34/data'`
- Modem event channel: `'ch34/modem'`
- USB state event channel: `'ch34/usb_state'`

**Method names:** Match Dart method names exactly (e.g., `enumDevice`, `openDevice`, `setSerialParameter`, `writeData`, `readData`)

## Where to Add New Code

**New Dart API Method:**
1. Add abstract method signature to `lib/src/ch34_platform_interface.dart`
2. Add concrete implementation to `lib/src/ch34_method_channel.dart` (using `methodChannel.invokeMethod()`)
3. Add static wrapper to `lib/src/ch34_manager.dart` (delegating to `Ch34Platform.instance`)
4. Add mock implementation in `test/ch34_method_channel_test.dart` for testing
5. Add native handler in `android/src/main/java/com/example/ch34/Ch34Plugin.java`

**New EventChannel (streaming):**
1. Create new `*StreamHandler.java` in `android/src/main/java/com/example/ch34/`
2. Register in `Ch34Plugin.onAttachedToEngine()`
3. Add `EventChannel` and `StreamSubscription` in `lib/src/ch34_method_channel.dart`
4. Add platform interface methods to `Ch34Platform`
5. Add static wrappers to `Ch34Manager`

**New Data Type:**
- Add to `lib/src/types/ch34_types.dart`
- Add corresponding conversion in `android/src/main/java/com/example/ch34/Ch34TypeConverter.java`

**New Native Utility:**
- Add to `android/src/main/java/com/example/ch34/` as a new Java class or extend existing

## Module Boundaries

### Dart Layer
```
lib/ch34.dart (exports)
    |
    v
lib/src/ch34_manager.dart (static facade)
    |
    v
lib/src/ch34_platform_interface.dart (abstract contract)
    |
    v
lib/src/ch34_method_channel.dart (concrete implementation)
    |
    +---> lib/src/types/ch34_types.dart (shared types)
```

### Native Layer
```
Ch34Plugin.java (MethodCallHandler + 3 EventChannels)
    |
    +---> Ch34DataStreamHandler.java (data streaming)
    +---> Ch34ModemStreamHandler.java (modem status streaming)
    +---> Ch34UsbStateStreamHandler.java (USB hotplug streaming)
    +---> Ch34TypeConverter.java (type conversion utilities)
    |
    v
CH34XUARTDriver.jar (WCH vendor SDK)
```

### Platform Bridge
```
Dart: MethodChannel('ch34') <---> Java: Ch34Plugin (MethodCallHandler)
Dart: EventChannel('ch34/data') <---> Java: Ch34DataStreamHandler
Dart: EventChannel('ch34/modem') <---> Java: Ch34ModemStreamHandler
Dart: EventChannel('ch34/usb_state') <---> Java: Ch34UsbStateStreamHandler
```

## Special Directories

**`android/libs/`:**
- Purpose: Contains binary JAR dependency (`CH34XUARTDriver.jar`)
- Generated: No, committed to repo
- Referenced by: `android/build.gradle` via `flatDir` repository

**`example/`:**
- Purpose: Self-contained Flutter app demonstrating plugin usage
- Generated: No, committed to repo
- Note: The example app package is `ch34_example`

**`docs/`:**
- Purpose: API documentation reference for WCH WCHUARTManager
- Contains: `CH34X-api_docs.md` - comprehensive API documentation in Markdown

**`lib/` root-level files:**
- Purpose: Backward compatibility re-exports
- `lib/ch34_platform_interface.dart` exports `src/ch34_platform_interface.dart`
- `lib/ch34_method_channel.dart` exports `src/ch34_method_channel.dart`

---

*Structure analysis: 2026-04-16*