# kormax/android-universal-reader architecture

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

- Interactive diagram: https://gitdiagram.com/kormax/android-universal-reader
- Repository: https://github.com/kormax/android-universal-reader

## Overview

Android Universal Reader is a demonstration NFC app for reading Apple VAS and Google Smart Tap passes. The main workflow is: load a reader configuration, detect a nearby NFC device, exchange ISO 7816 commands, then display pass data and read statuses alongside optional logs and command/response output. The protocol implementations and configuration models are documented, but most of their source was not excerpted; links involving those internals are therefore documented or left unverified rather than inferred from imports. The custom NDEF and BER-TLV codecs and shared byte-packing interfaces form the internal encoding layer.

Main entry points: [`app/src/main/java/com/kormax/universalreader/MainActivity.kt`](https://github.com/kormax/android-universal-reader/blob/main/app/src/main/java/com/kormax/universalreader/MainActivity.kt) (Reader UI), [`app/src/main/java/com/kormax/universalreader/android/IsoDepIso7816Target.kt`](https://github.com/kormax/android-universal-reader/blob/main/app/src/main/java/com/kormax/universalreader/android/IsoDepIso7816Target.kt) (Android IsoDep adapter), [`app/src/main/java/com/kormax/universalreader/ndef/NdefMessage.kt`](https://github.com/kormax/android-universal-reader/blob/main/app/src/main/java/com/kormax/universalreader/ndef/NdefMessage.kt) (NDEF codec), [`app/src/main/java/com/kormax/universalreader/tlv/ber/BerTlvMessage.kt`](https://github.com/kormax/android-universal-reader/blob/main/app/src/main/java/com/kormax/universalreader/tlv/ber/BerTlvMessage.kt) (BER-TLV message)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App and configuration"]
  node_activity["Reader UI<br/>[MainActivity.kt]"]
  node_config_model["Reader config models"]
  node_reader_config["Protocol configuration"]
  node_read_result["Read results"]
end

subgraph group_nfc["NFC transport"]
  node_android_target["Android IsoDep adapter"]
  node_iso_target["ISO 7816 target<br/>[Iso7816Target.kt]"]
  node_apdu["ISO 7816 commands<br/>[Iso7816Command.kt]"]
  node_apdu_response["ISO 7816 responses<br/>[Iso7816Response.kt]"]
end

subgraph group_protocols["Pass protocols"]
  node_vas_reader["Apple VAS reader"]
  node_vas_crypto["VAS decryption"]
  node_vas_payload["VAS payload<br/>[VasPayload.kt]"]
  node_smarttap_reader["Smart Tap reader"]
  node_smarttap_crypto["Smart Tap decryption"]
  node_smarttap_pass["Smart Tap pass data"]
end

subgraph group_encoding["Encoding layer"]
  node_ndef["NDEF codec<br/>[NdefMessage.kt]"]
  node_ndef_record["NDEF records<br/>[NdefRecord.kt]"]
  node_ber_message["BER-TLV message<br/>[BerTlvMessage.kt]"]
  node_ber_tlv["BER-TLV codec<br/>[BerTlv.kt]"]
  node_packing["Byte packing<br/>[Packable.kt]"]
  node_unpacking["Byte unpacking<br/>[Unpackable.kt]"]
end

node_user(("Reader user"))
node_pass_device(("Pass device"))

node_user -->|"uses"| node_activity
node_user -->|"loads config"| node_activity
node_activity -->|"deserializes"| node_config_model
node_activity -->|"invokes read"| node_reader_config
node_pass_device -->|"presents pass"| node_activity
node_activity -->|"creates target"| node_android_target
node_android_target -->|"implements"| node_iso_target
node_android_target -->|"transmits"| node_apdu
node_android_target -->|"parses response"| node_apdu_response
node_reader_config -.->|"dispatches to"| node_vas_reader
node_reader_config -.->|"dispatches to"| node_smarttap_reader
node_vas_reader -.->|"decrypts with"| node_vas_crypto
node_vas_crypto -->|"produces"| node_vas_payload
node_smarttap_reader -.->|"decrypts with"| node_smarttap_crypto
node_smarttap_crypto -.->|"decodes pass"| node_smarttap_pass
node_activity -->|"displays results"| node_read_result
node_ndef -->|"parses records"| node_ndef_record
node_ber_message -->|"parses tags"| node_ber_tlv
node_ndef -->|"serializes with"| node_packing
node_ndef -->|"parses with"| node_unpacking
node_ber_message -->|"serializes with"| node_packing
node_ber_message -->|"parses with"| node_unpacking

click node_activity "https://github.com/kormax/android-universal-reader/blob/main/app/src/main/java/com/kormax/universalreader/MainActivity.kt"
click node_config_model "https://github.com/kormax/android-universal-reader/blob/main/app/src/main/java/com/kormax/universalreader/model/ReaderConfigurationModel.kt"
click node_reader_config "https://github.com/kormax/android-universal-reader/blob/main/app/src/main/java/com/kormax/universalreader/UniversalReaderConfiguration.kt"
click node_read_result "https://github.com/kormax/android-universal-reader/blob/main/app/src/main/java/com/kormax/universalreader/UniversalReaderResult.kt"
click node_android_target "https://github.com/kormax/android-universal-reader/blob/main/app/src/main/java/com/kormax/universalreader/android/IsoDepIso7816Target.kt"
click node_iso_target "https://github.com/kormax/android-universal-reader/blob/main/app/src/main/java/com/kormax/universalreader/iso7816/Iso7816Target.kt"
click node_apdu "https://github.com/kormax/android-universal-reader/blob/main/app/src/main/java/com/kormax/universalreader/iso7816/Iso7816Command.kt"
click node_apdu_response "https://github.com/kormax/android-universal-reader/blob/main/app/src/main/java/com/kormax/universalreader/iso7816/Iso7816Response.kt"
click node_vas_reader "https://github.com/kormax/android-universal-reader/blob/main/app/src/main/java/com/kormax/universalreader/apple/vas/VasReaderConfiguration.kt"
click node_vas_crypto "https://github.com/kormax/android-universal-reader/blob/main/app/src/main/java/com/kormax/universalreader/apple/vas/VasRegularCryptoProvider.kt"
click node_vas_payload "https://github.com/kormax/android-universal-reader/blob/main/app/src/main/java/com/kormax/universalreader/apple/vas/VasPayload.kt"
click node_smarttap_reader "https://github.com/kormax/android-universal-reader/blob/main/app/src/main/java/com/kormax/universalreader/google/smarttap/SmartTapReaderConfiguration.kt"
click node_smarttap_crypto "https://github.com/kormax/android-universal-reader/blob/main/app/src/main/java/com/kormax/universalreader/google/smarttap/SmartTapRegularCryptoProvider.kt"
click node_smarttap_pass "https://github.com/kormax/android-universal-reader/blob/main/app/src/main/java/com/kormax/universalreader/google/smarttap/SmartTapObjectPass.kt"
click node_ndef "https://github.com/kormax/android-universal-reader/blob/main/app/src/main/java/com/kormax/universalreader/ndef/NdefMessage.kt"
click node_ndef_record "https://github.com/kormax/android-universal-reader/blob/main/app/src/main/java/com/kormax/universalreader/ndef/NdefRecord.kt"
click node_ber_message "https://github.com/kormax/android-universal-reader/blob/main/app/src/main/java/com/kormax/universalreader/tlv/ber/BerTlvMessage.kt"
click node_ber_tlv "https://github.com/kormax/android-universal-reader/blob/main/app/src/main/java/com/kormax/universalreader/tlv/ber/BerTlv.kt"
click node_packing "https://github.com/kormax/android-universal-reader/blob/main/app/src/main/java/com/kormax/universalreader/structable/Packable.kt"
click node_unpacking "https://github.com/kormax/android-universal-reader/blob/main/app/src/main/java/com/kormax/universalreader/structable/Unpackable.kt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_activity,node_config_model,node_reader_config,node_read_result,node_user toneBlue
class node_android_target,node_iso_target,node_apdu,node_apdu_response toneAmber
class node_vas_reader,node_vas_crypto,node_vas_payload,node_smarttap_reader,node_smarttap_crypto,node_smarttap_pass toneMint
class node_ndef,node_ndef_record,node_ber_message,node_ber_tlv,node_packing,node_unpacking toneRose
class node_pass_device toneIndigo
```

## Components

### App and configuration

- [Reader UI](https://github.com/kormax/android-universal-reader/blob/main/app/src/main/java/com/kormax/universalreader/MainActivity.kt): `app/src/main/java/com/kormax/universalreader/MainActivity.kt`
- [Reader config models](https://github.com/kormax/android-universal-reader/blob/main/app/src/main/java/com/kormax/universalreader/model/ReaderConfigurationModel.kt): `app/src/main/java/com/kormax/universalreader/model/ReaderConfigurationModel.kt`
- [Protocol configuration](https://github.com/kormax/android-universal-reader/blob/main/app/src/main/java/com/kormax/universalreader/UniversalReaderConfiguration.kt): `app/src/main/java/com/kormax/universalreader/UniversalReaderConfiguration.kt`
- [Read results](https://github.com/kormax/android-universal-reader/blob/main/app/src/main/java/com/kormax/universalreader/UniversalReaderResult.kt): `app/src/main/java/com/kormax/universalreader/UniversalReaderResult.kt`

### NFC transport

- [Android IsoDep adapter](https://github.com/kormax/android-universal-reader/blob/main/app/src/main/java/com/kormax/universalreader/android/IsoDepIso7816Target.kt): `app/src/main/java/com/kormax/universalreader/android/IsoDepIso7816Target.kt`
- [ISO 7816 target](https://github.com/kormax/android-universal-reader/blob/main/app/src/main/java/com/kormax/universalreader/iso7816/Iso7816Target.kt): `app/src/main/java/com/kormax/universalreader/iso7816/Iso7816Target.kt`
- [ISO 7816 commands](https://github.com/kormax/android-universal-reader/blob/main/app/src/main/java/com/kormax/universalreader/iso7816/Iso7816Command.kt): `app/src/main/java/com/kormax/universalreader/iso7816/Iso7816Command.kt`
- [ISO 7816 responses](https://github.com/kormax/android-universal-reader/blob/main/app/src/main/java/com/kormax/universalreader/iso7816/Iso7816Response.kt): `app/src/main/java/com/kormax/universalreader/iso7816/Iso7816Response.kt`

### Pass protocols

- [Apple VAS reader](https://github.com/kormax/android-universal-reader/blob/main/app/src/main/java/com/kormax/universalreader/apple/vas/VasReaderConfiguration.kt): `app/src/main/java/com/kormax/universalreader/apple/vas/VasReaderConfiguration.kt`
- [VAS decryption](https://github.com/kormax/android-universal-reader/blob/main/app/src/main/java/com/kormax/universalreader/apple/vas/VasRegularCryptoProvider.kt): `app/src/main/java/com/kormax/universalreader/apple/vas/VasRegularCryptoProvider.kt`
- [VAS payload](https://github.com/kormax/android-universal-reader/blob/main/app/src/main/java/com/kormax/universalreader/apple/vas/VasPayload.kt): `app/src/main/java/com/kormax/universalreader/apple/vas/VasPayload.kt`
- [Smart Tap reader](https://github.com/kormax/android-universal-reader/blob/main/app/src/main/java/com/kormax/universalreader/google/smarttap/SmartTapReaderConfiguration.kt): `app/src/main/java/com/kormax/universalreader/google/smarttap/SmartTapReaderConfiguration.kt`
- [Smart Tap decryption](https://github.com/kormax/android-universal-reader/blob/main/app/src/main/java/com/kormax/universalreader/google/smarttap/SmartTapRegularCryptoProvider.kt): `app/src/main/java/com/kormax/universalreader/google/smarttap/SmartTapRegularCryptoProvider.kt`
- [Smart Tap pass data](https://github.com/kormax/android-universal-reader/blob/main/app/src/main/java/com/kormax/universalreader/google/smarttap/SmartTapObjectPass.kt): `app/src/main/java/com/kormax/universalreader/google/smarttap/SmartTapObjectPass.kt`

### Encoding layer

- [NDEF codec](https://github.com/kormax/android-universal-reader/blob/main/app/src/main/java/com/kormax/universalreader/ndef/NdefMessage.kt): `app/src/main/java/com/kormax/universalreader/ndef/NdefMessage.kt`
- [NDEF records](https://github.com/kormax/android-universal-reader/blob/main/app/src/main/java/com/kormax/universalreader/ndef/NdefRecord.kt): `app/src/main/java/com/kormax/universalreader/ndef/NdefRecord.kt`
- [BER-TLV message](https://github.com/kormax/android-universal-reader/blob/main/app/src/main/java/com/kormax/universalreader/tlv/ber/BerTlvMessage.kt): `app/src/main/java/com/kormax/universalreader/tlv/ber/BerTlvMessage.kt`
- [BER-TLV codec](https://github.com/kormax/android-universal-reader/blob/main/app/src/main/java/com/kormax/universalreader/tlv/ber/BerTlv.kt): `app/src/main/java/com/kormax/universalreader/tlv/ber/BerTlv.kt`
- [Byte packing](https://github.com/kormax/android-universal-reader/blob/main/app/src/main/java/com/kormax/universalreader/structable/Packable.kt): `app/src/main/java/com/kormax/universalreader/structable/Packable.kt`
- [Byte unpacking](https://github.com/kormax/android-universal-reader/blob/main/app/src/main/java/com/kormax/universalreader/structable/Unpackable.kt): `app/src/main/java/com/kormax/universalreader/structable/Unpackable.kt`

### Other components

- **Reader user**
- **Pass device**

## Connections

- Reader user → Reader UI: uses (evidence: `README.md`)
- Reader user → Reader UI: loads config (evidence: `README.md`)
- Reader UI → Reader config models: deserializes (evidence: `app/src/main/java/com/kormax/universalreader/MainActivity.kt`)
- Reader UI → Protocol configuration: invokes read (evidence: `app/src/main/java/com/kormax/universalreader/MainActivity.kt`)
- Pass device → Reader UI: presents pass (evidence: `README.md`)
- Reader UI → Android IsoDep adapter: creates target (evidence: `app/src/main/java/com/kormax/universalreader/MainActivity.kt`)
- Android IsoDep adapter → ISO 7816 target: implements (evidence: `app/src/main/java/com/kormax/universalreader/android/IsoDepIso7816Target.kt`)
- Android IsoDep adapter → ISO 7816 commands: transmits (evidence: `app/src/main/java/com/kormax/universalreader/android/IsoDepIso7816Target.kt`)
- Android IsoDep adapter → ISO 7816 responses: parses response (evidence: `app/src/main/java/com/kormax/universalreader/android/IsoDepIso7816Target.kt`)
- Protocol configuration → Apple VAS reader: dispatches to (evidence: `app/src/main/java/com/kormax/universalreader/UniversalReaderConfiguration.kt`)
- Protocol configuration → Smart Tap reader: dispatches to (evidence: `app/src/main/java/com/kormax/universalreader/UniversalReaderConfiguration.kt`)
- Apple VAS reader → VAS decryption: decrypts with
- VAS decryption → VAS payload: produces (evidence: `app/src/main/java/com/kormax/universalreader/apple/vas/VasRegularCryptoProvider.kt`)
- Smart Tap reader → Smart Tap decryption: decrypts with
- Smart Tap decryption → Smart Tap pass data: decodes pass
- Reader UI → Read results: displays results (evidence: `app/src/main/java/com/kormax/universalreader/MainActivity.kt`)
- NDEF codec → NDEF records: parses records (evidence: `app/src/main/java/com/kormax/universalreader/ndef/NdefMessage.kt`)
- BER-TLV message → BER-TLV codec: parses tags (evidence: `app/src/main/java/com/kormax/universalreader/tlv/ber/BerTlvMessage.kt`)
- NDEF codec → Byte packing: serializes with (evidence: `app/src/main/java/com/kormax/universalreader/ndef/NdefMessage.kt`)
- NDEF codec → Byte unpacking: parses with (evidence: `app/src/main/java/com/kormax/universalreader/ndef/NdefMessage.kt`)
- BER-TLV message → Byte packing: serializes with (evidence: `app/src/main/java/com/kormax/universalreader/tlv/ber/BerTlvMessage.kt`)
- BER-TLV message → Byte unpacking: parses with (evidence: `app/src/main/java/com/kormax/universalreader/tlv/ber/BerTlvMessage.kt`)
