ch34/.planning/codebase/STRUCTURE.md

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