# devnied/emv-nfc-paycard-enrollment architecture

> Architecture diagram of the GitHub repository devnied/emv-nfc-paycard-enrollment, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/devnied/emv-nfc-paycard-enrollment
- Repository: https://github.com/devnied/emv-nfc-paycard-enrollment

## Overview

##### Project Type and Purpose
- This is a Java library whose purpose is to “read and extract public data from NFC EMV credit cards.” It is a tool that provides the core functionality for interacting with EMV paycards via NFC. It also comes with a sample application (under sample-pcsc) that demonstrates how to implement a custom provider (via the IProvider interface) to exchange APDU commands with a card.
- The README provides usage examples that show how to build a configuration, instantiate a parser, plug in a provider, and then read an EMVCard object containing card data. There’s even an Android-related example that uses the IsoDep class.

##### Analyzing the File Structure
- The /library directory contains the core Java code. It is organized into several packages:
– The “enums” package holds various enumerations (such as CommandEnum, EmvCardScheme, SwEnum) that help distinguish command types and card schemes.
– The “exception” package holds custom runtime exceptions (for communication issues or TLV parsing issues).
– The “iso7816emv” package manages low-level interactions with APDU commands and holds classes like TLV parsing, tag representations, and terminal transaction utilities.
– The “model” package contains the data models (e.g., EMVCard, EmvTrack1, EmvTrack2, Application, TransactionRecord) which represent different aspects of the credit card data.
– The “parser” package contains parser implementations including abstract parsers and concrete ones such as EmvParser and GeldKarteParser.
– The “utils” package and its subpackages provide helper functions that support operations such as parsing ATRs, command creation, and TLV processing.
- The /sample-pcsc directory provides a sample application that includes a custom provider (PcscProvider) and its usage – illustrating how to communicate with an NFC device.
- The presence of extensive test directories indicates a broad test suite spanning models, parser functionality, exception handling, and reflective utilities.

##### Additional Notes
- That every package or module directly involved in the key functionality is represented.
- While you don’t need to include every single file, cover all essential architectural elements to fully explain the system to a principal software engineer.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Application
    subgraph "Client Application"
        Client["Client Application"]:::client
    end

    %% Provider Layer
    subgraph "Provider Layer"
        IProvider["IProvider"]:::provider
        PcscProvider["PcscProvider"]:::provider
    end

    %% Parser Layer
    subgraph "Parser Layer"
        EmvTemplate["EmvTemplate/Config"]:::parser
        EmvParser["EmvParser"]:::parser
        GeldKarteParser["GeldKarteParser"]:::parser
    end

    %% Data Model Layer
    subgraph "Data Model Layer"
        DataModels["Data Models"]:::model
    end

    %% Utility Layer
    subgraph "Utility Layer"
        Utilities["Utilities/Helpers"]:::utils
        Exceptions["Exception Handling"]:::exception
    end

    %% Connections
    Client -->|"creates"| IProvider
    Client -->|"configures"| EmvTemplate
    IProvider -->|"implemented_by"| PcscProvider
    EmvTemplate -->|"parses_with"| EmvParser
    EmvTemplate -->|"parses_with"| GeldKarteParser
    EmvParser -->|"builds"| DataModels
    GeldKarteParser -->|"builds"| DataModels
    EmvParser -->|"utilizes"| Utilities
    GeldKarteParser -->|"utilizes"| Utilities
    Utilities -->|"throws"| Exceptions
    Exceptions -->|"handled_in"| EmvTemplate

    %% Click Events
    click Client "https://github.com/devnied/emv-nfc-paycard-enrollment/blob/master/sample-pcsc/src/main/java/com/github/devnied/emvpcsccard/Main.java"
    click IProvider "https://github.com/devnied/emv-nfc-paycard-enrollment/blob/master/library/src/main/java/com/github/devnied/emvnfccard/parser/IProvider.java"
    click PcscProvider "https://github.com/devnied/emv-nfc-paycard-enrollment/blob/master/sample-pcsc/src/main/java/com/github/devnied/emvpcsccard/PcscProvider.java"
    click EmvTemplate "https://github.com/devnied/emv-nfc-paycard-enrollment/blob/master/library/src/main/java/com/github/devnied/emvnfccard/parser/EmvTemplate.java"
    click EmvParser "https://github.com/devnied/emv-nfc-paycard-enrollment/blob/master/library/src/main/java/com/github/devnied/emvnfccard/parser/impl/EmvParser.java"
    click GeldKarteParser "https://github.com/devnied/emv-nfc-paycard-enrollment/blob/master/library/src/main/java/com/github/devnied/emvnfccard/parser/impl/GeldKarteParser.java"
    click DataModels "https://github.com/devnied/emv-nfc-paycard-enrollment/tree/master/library/src/main/java/com/github/devnied/emvnfccard/model"
    click Utilities "https://github.com/devnied/emv-nfc-paycard-enrollment/tree/master/library/src/main/java/com/github/devnied/emvnfccard/utils"
    click Exceptions "https://github.com/devnied/emv-nfc-paycard-enrollment/tree/master/library/src/main/java/com/github/devnied/emvnfccard/exception"

    %% Styles
    classDef client fill:#ffcccc,stroke:#333,stroke-width:2px;
    classDef provider fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef parser fill:#ccccff,stroke:#333,stroke-width:2px;
    classDef model fill:#ffffcc,stroke:#333,stroke-width:2px;
    classDef utils fill:#ffccff,stroke:#333,stroke-width:2px;
    classDef exception fill:#ccffff,stroke:#333,stroke-width:2px;
```
