# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is the Flutter SDK for CardScan's insurance card scanner - a widget that makes it easy to add AI-powered insurance card scanning to any Flutter application. The package provides two main widgets (`CardScanner` and `CardScannerModal`) that embed a WebView-based scanner interface with TensorFlow.js ML models for real-time card detection.

## Architecture

### Core Components
- **CardScanner** (`lib/src/widgets/card_scanner.dart`) - Embeddable widget for in-app scanning
- **CardScannerModal** (`lib/src/widgets/card_scanner_modal.dart`) - Full-screen modal scanner
- **ScannerWebView** (`lib/src/widgets/scanner_web_view.dart`) - WebView wrapper that handles ML processing
- **CardScanConfig** (`lib/src/models/card_scan_config.dart`) - Configuration and callback definitions

### Technical Architecture
1. **Flutter Widget Layer** - Native Flutter widgets handle permissions and UI
2. **WebView Bridge** - `flutter_inappwebview` loads HTML/JS assets with TensorFlow.js models
3. **Asset Management** - ML models and web assets are bundled locally and served to WebView
4. **API Integration** - Uses `cardscan_client` package for server communication
5. **JavaScript Communication** - Bidirectional messaging between Flutter and WebView JavaScript

### Asset Pipeline
- Web assets downloaded from `cardscan-ai/insurance-cardscan-react` releases
- TensorFlow.js models (`model.json`, `group1-shard1of1.bin`) downloaded from S3
- Assets bundled at `lib/assets/` and referenced in `pubspec.yaml`
- WebView intercepts model requests and serves local assets instead

## Development Commands

### Setup and Dependencies
```bash
# Get dependencies
flutter pub get

# Run example app
cd example && flutter run

# Run on specific platform
flutter run -d chrome  # Web
flutter run -d ios     # iOS Simulator
flutter run -d android # Android Emulator
```

### Testing
```bash
# Run all tests  
flutter test

# Run specific test files
flutter test test/utils/color_extensions_test.dart
flutter test test/dart-client/deserialization_test.dart

# Run integration tests
cd example && flutter test integration_test/
```

### Code Quality
```bash
# Format code
dart format .

# Analyze code
flutter analyze

# Check for outdated dependencies
flutter pub outdated
```

### Release Management
```bash
# Prepare release (updates version, assets, dependencies)
./scripts/prepare-release.sh patch

# Version bumps: patch, minor, major
./scripts/prepare-release.sh minor

# Manual asset download (if needed)
./scripts/download-assets.sh cardscan-ai/insurance-cardscan-react webview-v1.0.36 $GITHUB_TOKEN
```

### Publishing
```bash
# Publish to pub.dev (after version tag is created)
flutter pub publish
```

## Key Dependencies

- **flutter_inappwebview: ^6.0.0** - WebView implementation for ML processing
- **permission_handler: ^11.1.0** - Camera permission management
- **cardscan_client: ^1.0.1** - API client for CardScan services
- **built_value: >=8.4.0** - JSON serialization for API responses
- **package_info_plus: ^8.0.2** - Version information

## Configuration Files

- **pubspec.yaml** - Package configuration, dependencies, and asset declarations
- **analysis_options.yaml** - Dart analyzer configuration (uses flutter_lints)
- **scripts/package.json** - Node.js utilities for build scripts
- **scripts/prepare-release.sh** - Automated release preparation

## Common Development Tasks

### Adding New Widget Properties
1. Add property to `CardScanConfig` in `lib/src/models/card_scan_config.dart`
2. Update JavaScript injection in `lib/src/utils/js_injection.dart`
3. Handle property in web assets (if WebView-related)
4. Update documentation and examples

### Updating ML Models
1. Models are automatically updated via `download-assets.sh` script
2. Manually update by changing S3 URLs in download script
3. Update asset paths in `pubspec.yaml` if needed

### Debugging WebView Issues
1. Enable verbose logging: `CardScanConfig(logging: CardScanLogLevel.verbose)`
2. Enable WebView debugging on Android: `internal: InternalOptions(isInspectable: true)`
3. Check WebView console messages in logs
4. Verify asset loading and JavaScript injection

### Testing with Different Card Types
- Use test resources in `test/resources/` for API response examples
- Example app includes sample integration tests
- Test both front-side and backside scanning flows

## Release Process

1. **Prepare Release**: Run `./scripts/prepare-release.sh <version_bump>`
   - Updates package version
   - Downloads latest web assets from React package
   - Updates cardscan_client dependency
   - Updates CHANGELOG.md
2. **Review Changes**: Check updated files and test functionality
3. **Create PR**: Push changes and create pull request
4. **Tag Release**: After merge, create git tag matching version
5. **Publish**: GitHub Actions automatically publishes to pub.dev

## Testing Strategy

- **Unit Tests**: API response deserialization, utility functions
- **Widget Tests**: Flutter widget behavior and state management
- **Integration Tests**: End-to-end scanning flows with example app
- **Platform Tests**: Verify iOS/Android permission handling and WebView behavior

## Platform-Specific Notes

### iOS
- Requires camera permissions in Info.plist
- Uses WKWebView under the hood
- App Transport Security settings needed for local asset loading

### Android
- Requires camera permissions in AndroidManifest.xml
- WebView debugging available in debug builds
- Hybrid composition mode for better performance

### Web
- Limited functionality due to camera access restrictions
- Primarily for development/testing purposes