vsindustries/idscan-sdk

Purpose and entry points

idscan is a multi-module Android SDK for fully on-device identity-document scanning: PDF417/AAMVA barcode decoding, ICAO MRZ parsing, OCR-based extraction, normalization, and deterministic warnings. Public core entry points are IdScanSdk, IdScanProcessor, and request/config types in idscan-core/src/main/kotlin/com/idscan/core/IdScanSdk.kt, idscan-core/src/main/kotlin/com/idscan/core/IdScanProcessor.kt, and idscan-core/src/main/kotlin/com/idscan/core/IdScanRequest.kt. Android host apps normally use an Activity Result contract from exactly one UI flavor.

Module boundaries and runtime integration

idscan-core is pure Kotlin domain/pipeline logic; idscan-core-android adapts Android bitmaps, parceling, model assets, and localizer runtimes. Key boundary paths: idscan-core-android/src/main/kotlin/com/idscan/core/android/IdScanProcessorAndroid.kt, idscan-core-android/src/main/kotlin/com/idscan/core/android/model/AssetModelManifestProvider.kt. Android runtime requirement is API 23+; builds use JDK 21.

Scan UI flavors and capture control

Two parallel camera/UI distributions expose the host-facing IdScanContract, scanner activity, Compose screen, and live capture controller:

• Dynamic ML Kit delivery: idscan-ui-dynamic/src/main/kotlin/com/idscan/ui/dynamic/IdScanContract.kt, idscan-ui-dynamic/src/main/kotlin/com/idscan/ui/dynamic/camera/LiveScanController.kt, idscan-ui-dynamic/src/main/kotlin/com/idscan/ui/dynamic/readiness/MlKitReadinessProvider.kt.

• Bundled recognition: idscan-ui-bundled/src/main/kotlin/com/idscan/ui/bundled/IdScanContract.kt, idscan-ui-bundled/src/main/kotlin/com/idscan/ui/bundled/IdScanScannerActivity.kt, idscan-ui-bundled/src/main/kotlin/com/idscan/ui/bundled/ocr/TesseractTextRecognizerBinding.kt.

The host owns camera permission. Capture frames flow through CameraX-oriented adapters/controller, coordinate mapping, tracking/quality feedback, then processor invocation.

Processing pipeline

PipelineOrchestrator composes stages over PipelineInput: localize the document, assess image quality, then execute barcode, MRZ, and OCR branches; resolve fields and apply rules into a result. Primary paths: idscan-core/src/main/kotlin/com/idscan/core/pipeline/PipelineOrchestrator.kt, idscan-core/src/main/kotlin/com/idscan/core/pipeline/LocalizerStage.kt, idscan-core/src/main/kotlin/com/idscan/core/pipeline/QualityStage.kt.

Image preprocessing is a distinct boundary for grayscale, contrast, deskew, perspective warp, and escalation: idscan-core/src/main/kotlin/com/idscan/core/preprocess/BitmapPreprocessingPipeline.kt, idscan-core/src/main/kotlin/com/idscan/core/preprocess/EscalationPreprocessor.kt.

Extraction, parsing, and resolution

Barcode scanning produces payloads consumed by AAMVA parsing; OCR text is converted to field candidates; MRZ recognition detects/reconstructs candidates and validates TD1/TD2/TD3/MRV formats. Paths: idscan-core/src/main/kotlin/com/idscan/core/pipeline/BarcodeBranchStage.kt, idscan-core/src/main/kotlin/com/idscan/core/parser/aamva/AamvaParser.kt, idscan-core/src/main/kotlin/com/idscan/core/pipeline/MrzBranchStage.kt.

FieldResolverStage merges competing sources according to trust hierarchy and preserves provenance; rules then produce eligibility/quality/mismatch warnings. Paths: idscan-core/src/main/kotlin/com/idscan/core/pipeline/FieldResolverStage.kt, idscan-core/src/main/kotlin/com/idscan/core/pipeline/resolver/FieldMerger.kt, idscan-core/src/main/kotlin/com/idscan/core/pipeline/RulesStage.kt.

Results, privacy, and models

The stable output is IdScanResult, containing status, normalized fields, source provenance, warnings, optional retained frames, and model readiness state: idscan-core/src/main/kotlin/com/idscan/core/result/IdScanResult.kt, idscan-core/src/main/kotlin/com/idscan/core/result/IdScanResultFactory.kt. Logging is redacted via idscan-core/src/main/kotlin/com/idscan/core/log/RedactingLogger.kt.

Localizer model/runtime selection uses packaged manifests and a decision table: idscan-core-android/src/main/kotlin/com/idscan/core/android/localizer/RuntimePathSelector.kt, idscan-core-android/src/main/assets/model-manifest.json. OCR assets are checksum-pinned and fetched at build time; dynamic ML Kit is the material external service dependency, while bundled Tesseract supports environments without Play Services.

Delivery and assurance

Gradle convention/build logic implements publication, API, model-manifest, privacy, license, reproducibility, and dependency-boundary gates: build-logic/src/main/kotlin/com/idscan/buildlogic/VerifyModelManifestTask.kt, build-logic/src/main/kotlin/com/idscan/buildlogic/privacy/NetworkIsolationScanTask.kt. Benchmarks select and record LiteRT runtime behavior: idscan-benchmark/src/main/kotlin/com/idscan/benchmark/BenchmarkRunner.kt, idscan-benchmark/src/main/kotlin/com/idscan/benchmark/report/DecisionTableWriter.kt.