How mvallim/emv-qrcode works
Project type and purpose
• This is a Java library (EMV QRCode) distributed via Maven Central and designed to encode, decode, and validate EMV QR Codes in two modes:
• Merchant Presented Mode (MPM)
• Consumer Presented Mode (CPM)
• It is a domain-specific, open-source tool (no UI or network service) consumed by JVM-based applications.
High-level architecture and package structure
• src/main/java/com/emv/qrcode/core
• Core utilities: CRC calculation, TLV (Tag-Length-Value) building, configuration maps (DecodersCpmMap, DecodersMpmMap)
• Exception definitions (InvalidTagException, DuplicateTagException, etc.)
• src/main/java/com/emv/qrcode/decoder
• CPM and MPM decoder pipelines (DecoderCpm, DecoderMpm)
• Field-level decoders (e.g. BERTLNumericDecoder, MerchantAccountInformationTemplateDecoder)
• src/main/java/com/emv/qrcode/model
• In-memory data model (TLV, Template classes, domain constants for field codes)
• src/main/java/com/emv/qrcode/validators
• Validation logic for CPM/MPM models (e.g. MerchantPresentedModeValidate, Crc16Validate)
• src/main/java/com/emv/qrcode/utils
• Low-level BER/TLV parsing utilities (BERUtils, TLVUtils)
• Build & config files
• pom.xml (Maven), lombok.config, CI workflows (.github)
Main components and their roles
• Public API classes
• MerchantPresentedMode, ConsumerPresentedMode – entry points for encode()/toString(), decode(), validate()
• Encoder modules
• Methods on Mode classes assemble TLV entries, call core.CRC and TLVUtils to build final payload string
• Decoder modules
• DecoderMpm.decode()/DecoderCpm.decode() orchestrate parsing via DecodeMpmIterator/DecodeCpmIterator and per-tag decoders
• Model layer
• Holds decoded data in strongly typed objects (e.g. MerchantAccountInformationTemplate, ApplicationTemplate)
• Validation modules
• Apply domain rules, detect duplicate tags, invalid tags, CRC errors – return ValidationResult
• Core utilities & exception handling
• Common routines and configuration maps drive decoder choice; exceptions bubble up on invalid inputs
Relationships and data-flow
• Client Application
↓ invokes
• Public API (encode/decode/validate)
↓ uses
• Encoder or Decoder pipelines
↔ calls
• Core utils (TLVUtils, BERUtils, CRC)
↔ constructs or reads
• Model classes (TLV, Templates)
↔ passed to
• Validator classes → returns → ValidationResult or throws Exception
↗
• Client Application
Essential elements
• Clear, descriptive labels for each package/module