# snorsnor9998/sunmi-card-reader architecture

> Architecture diagram of the GitHub repository snorsnor9998/sunmi-card-reader, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/snorsnor9998/sunmi-card-reader
- Repository: https://github.com/snorsnor9998/sunmi-card-reader

## Overview

##### Project Type and Purpose
- This is a single‐module Android demo app (written in Kotlin/Java, Gradle‐based) whose sole purpose is to demonstrate how to integrate and use the Sunmi Pay SDK (AAR) for reading cards (IC/NFC/Magnetic), performing EMV transactions, prompting PIN entry, and extracting TLV data on a Sunmi P2 device. There is no separate backend or network service in this repo—everything runs locally on the device, driven by the SunmiPayKernel.

##### File Structure Analysis
- Top‐level Gradle project with one “app” module.
- app/libs/PayLib-release-1.4.43.aar: the core Sunmi Pay SDK library.
- src/main/java/com/snor/sunmicardreader:
- BaseApp.kt: global initialization and static SDK references.
- InitActivity.kt: calls SunmiPayKernel.initPaySDK(…)
- MainActivity.kt: user triggers card read / EMV flow.
- Callback/: custom subclasses of CheckCardCallback, EMVCallback, PinPadCallback.
- util/: ByteUtil, TLVUtil, EmvUtil, etc., for data conversion and EMV setup.
- Standard Android resources (layouts, drawables, manifest).

##### Key Architectural Patterns
- Layered separation:
- UI layer (Activities + XML layouts)
- SDK integration layer (SunmiPayKernel → mReadCardOptV2, mEMVOptV2, mPinPadOptV2)
- Hardware/Platform abstraction layer (AAR library talking to device hardware)
- Utility & Callback layer for processing TLV, byte conversions, and event handling
- Event‐driven via callbacks: CheckCardCallback, EMVCallback, PinPadCallback wire UI to SDK events.

##### Main Components and Interactions
a. Components:
- UI: InitActivity, MainActivity, Buttons (NFC/IC/Swipe triggers)
- SDK Core: SunmiPayKernel singleton (AAR)
- Module Interfaces: ReadCardOptV2, EMVOptV2, PinPadOptV2, BasicOptV2, SecurityOptV2
- Callback Handlers: CheckCardCallback, EMVCallback, PinPadCallback
- Utility Classes: EmvUtil, ByteUtil, TLVUtil
- Device Hardware: Card Reader, EMV Chip, PIN Pad
b. Data Flow & Relationships:
1) UI → SunmiPayKernel.initPaySDK → ConnectCallback
2) On success: BaseApp stores mReadCardOptV2, mEMVOptV2, mPinPadOptV2
3) UI triggers ReadCardOptV2.checkCard(…) → hardware scans card → CheckCardCallback callbacks
4) On IC/NFC found → call EMVOptV2.initEmvProcess() → EMVOptV2.transactProcess(...) → EMVCallback events (app select, TLV setup, PIN prompt, online processing)
5) PIN entry: PinPadOptV2.initPinPad(...) → PinPadCallback → EMVOptV2.importPinInputStatus(...)
6) EMV online: getTlvList(…) → TLVUtil parses → return TLV map → UI/log
c. Architectural Patterns:
- Singleton SDK gateway (SunmiPayKernel)
- Callback‐driven state machine for EMV transaction
- Utility modules abstract TLV/byte handling
d. Technologies & Frameworks:
- Android (Kotlin/Java, Gradle)
- Sunmi Pay AAR (PayLib-release-1.4.43.aar)
- EMV, ISO 4217/3166/8583, ISO 9564 standards for payment

## Diagram (Mermaid)

```mermaid
graph TD
  subgraph "UI Layer"
    UI1["InitActivity"]:::ui
    UI2["MainActivity"]:::ui
  end

  subgraph "SDK Core"  
    SDK1["BaseApp"]:::sdk
    SDK2["SunmiPayKernel (AAR)"]:::sdk
    SDK3["ReadCardOptV2"]:::sdk
    SDK4["EMVOptV2"]:::sdk
    SDK5["PinPadOptV2"]:::sdk
  end

  subgraph "Callbacks & Utils"
    CB1["CheckCardCallback"]:::cb
    CB2["EMVCallback"]:::cb
    CB3["PinPadCallback"]:::cb
    U["Util Classes (ByteUtil, EmvUtil, TLVUtil, Tuple, TupleUtil)"]:::utils
  end

  subgraph "Hardware Layer"
    HW1["Card Reader"]:::hw
    HW2["EMV Chip"]:::hw
    HW3["PIN Pad"]:::hw
  end

  UI1 -->|"initPaySDK()"| SDK1
  SDK1 -->|"stores opts"| SDK3 & SDK4 & SDK5
  UI2 -->|"checkCard()"| SDK3
  SDK3 -->|"hardware scan"| HW1
  HW1 -->|"onCardFound"| CB1
  CB1 -->|"importAppSelect()"| SDK4
  SDK4 -->|"initEmvProcess()"| HW2
  SDK4 -->|"transactProcess()"| HW2
  HW2 -->|"EMV events"| CB2
  CB2 -->|"onRequestShowPinPad"| SDK5
  SDK5 -->|"initPinPad()"| HW3
  HW3 -->|"onConfirm/Cancel/Error"| CB3
  CB3 -->|"importPinInputStatus()"| SDK4
  CB2 -->|"importPinInputStatus()"| SDK4
  U -.->|"setup AID/CAPK parse TLV"| SDK4

  classDef ui fill:#DAE8FC,stroke:#6C8EBF;
  classDef sdk fill:#D5E8D4,stroke:#82B366;
  classDef cb fill:#FFF2CC,stroke:#D6B656;
  classDef utils fill:#FFF2CC,stroke:#D6B656,stroke-dasharray: 5 5;
  classDef hw fill:#ECECEC,stroke:#A8A8A8;

  click UI1 "https://github.com/snorsnor9998/sunmi-card-reader/blob/master/app/src/main/java/com/snor/sunmicardreader/InitActivity.kt"
  click UI2 "https://github.com/snorsnor9998/sunmi-card-reader/blob/master/app/src/main/java/com/snor/sunmicardreader/MainActivity.kt"
  click SDK1 "https://github.com/snorsnor9998/sunmi-card-reader/blob/master/app/src/main/java/com/snor/sunmicardreader/BaseApp.kt"
  click SDK2 "https://github.com/snorsnor9998/sunmi-card-reader/blob/master/app/libs/PayLib-release-1.4.43.aar"
  click CB1 "https://github.com/snorsnor9998/sunmi-card-reader/blob/master/app/src/main/java/com/snor/sunmicardreader/Callback/CheckCardCallback.kt"
  click CB2 "https://github.com/snorsnor9998/sunmi-card-reader/blob/master/app/src/main/java/com/snor/sunmicardreader/Callback/EMVCallback.kt"
  click CB3 "https://github.com/snorsnor9998/sunmi-card-reader/blob/master/app/src/main/java/com/snor/sunmicardreader/Callback/PinPadCallback.kt"
  click U "https://github.com/snorsnor9998/sunmi-card-reader/tree/master/app/src/main/java/com/snor/sunmicardreader/util"
```
