# ctt-gob-es/jmulticard architecture

> Architecture diagram of the GitHub repository ctt-gob-es/jmulticard, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ctt-gob-es/jmulticard
- Repository: https://github.com/ctt-gob-es/jmulticard

## Overview

##### And separate the main components
- Core API (jmulticard): Defines interfaces and implementations for smart card operations—APDU commands, card communication, error handling, card types, abstract card representations, and so forth.
- Provider/Implementation Modules:
– jmulticard‑android: Contains Android‐specific implementations and adaptations.
– jmulticard‑jse: Contains provider implementations specific to standard Java environments (and key store providers, signature implementations, etc.).
– jmulticard‑jsr268: Likely adds integration with JSR 268 (Smartcard I/O interfaces).
– jmulticard‑wip: Additional or experimental implementations under development.
- Crypto Layer (jmulticard‑crypto): Implements cryptographic support and helper functions, interfacing with cryptographic libraries (e.g., BouncyCastle classes).
- ASN.1 / APDU / Protocol Utilities: Package subtrees in many modules (especially in the core and crypto modules) include ASN.1 encoding/decoding, DER/BER handling, and APDU command/response handling.

##### Relationships and interactions
- The Core API provides abstract access to a smart card. It depends on lower-level layers such as the APDU construction/decoding utilities, which in turn may use the crypto functions.
- The Crypto module supplies essential cryptographic functions. These functions are invoked either directly by card providers (for example, to perform digital signatures or to support PACE protocols) or via the core API.
- Platform-specific modules (Android, JSE, JSR268) adapt this core functionality to different runtime environments. They expose provider implementations that plug into the core’s interfaces.
- The connection layer is abstracted via “APDU connection” classes and error handling classes that bridge with underlying device APIs (for example, javax.smartcardio in JSE or other native connections on Android). These are central to encoding/decoding messages between a card reader and the smart card.

##### Architectural patterns and design principles
- Layered Architecture: The design decouples high-level business logic (card access, command handling) from lower-level technical details (cryptography, communication protocols, platform-dependent handling).
- Abstraction and Provider Patterns: A common abstract interface (or API) is defined in the core module, while implementations are provided in different modules (custom providers for JSE, Android, etc.). This allows a flexible “plug‑in” mechanism where a consumer can swap the underlying provider based on the runtime environment.
- Separation of Concerns: There is a clear separation between protocol handling (APDU and ASN.1 encoding/decoding), business logic (smart card transactions), and cryptographic functionalities.

- At the top, the Application or Client Layer that interacts with the jmulticard library.
- The Core API (jmulticard) as the central component, exposing interfaces for operations such as “Card”, “APDU”, “Callback”, and exceptions.
- The APDU & Protocol Handling Layer—modules and packages that manage APDU command objects, status words, ASN.1/DER/BER encoders and decoders.
- The Cryptography Layer (jmulticard‑crypto) that uses BouncyCastle libraries; indicate dependencies on cryptographic primitives and algorithms.
- Provider Implementations grouped by environment/platform:
– jmulticard‑android (Android-specific provider and connection handling),
– jmulticard‑jse (JSE provider, key store integration, and signature support),
– jmulticard‑jsr268 (integration with the smart card I/O API),
– jmulticard‑wip (experimental components).
- Connectivity/Communication Layer for handling the physical smart card reader communication (APDU connections, secure messaging, error-checking components).
- Additional submodules for card-specific operations (for example, Dnie, Ceres, or ICAO/BAC implementations).

##### Detail
- That all major modules and their subcomponents are included.
- Concise descriptions (as labels or notes) to explain what each component does.
- That the design is extensible due to its abstraction (a characteristic not found in monolithic designs).

This level of detail (interfaces, core libraries, crypto integration, provider modules, and connection layers) is crucial to accurately capture the complexities of smart card access and abstraction as implemented in this project.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client("Application/Client Layer"):::application
    Core_API("Core API (jmulticard)"):::core
    APDU("APDU Commands & Status Handling"):::utility
    ASN1("ASN.1 and DER/BER Utilities"):::utility
    Crypto("Crypto Support (jmulticard-crypto)"):::crypto
    Connectivity("Connectivity/Communication Layer"):::connectivity
    Android_Provider("Provider: Android"):::provider
    JSE_Provider("Provider: JSE"):::provider
    JSR268_Provider("Provider: JSR268"):::provider
    WIP_Provider("Provider: Experimental/WIP"):::provider
    DNIe("Card-Specific Provider: DNIe"):::card
    Ceres("Card-Specific Provider: Ceres"):::card
    GiDe("Card-Specific Provider: GiDe"):::card
    ICAO("Card-Specific Provider: ICAO/BAC"):::card

    Client -->|"calls"| Core_API
    Core_API -->|"uses"| APDU
    Core_API -->|"uses"| ASN1
    Core_API -->|"invokes"| Crypto
    Core_API -->|"manages"| Connectivity
    Core_API -->|"plugsInto"| Android_Provider
    Core_API -->|"plugsInto"| JSE_Provider
    Core_API -->|"plugsInto"| JSR268_Provider
    Core_API -->|"plugsInto"| WIP_Provider
    Core_API -->|"supports"| DNIe
    Core_API -->|"supports"| Ceres
    Core_API -->|"supports"| GiDe
    Core_API -->|"supports"| ICAO
    APDU -->|"communicatesWith"| Connectivity
    ASN1 -->|"formats"| APDU

    click Core_API "https://github.com/ctt-gob-es/jmulticard/tree/master/jmulticard/src/main/java/es/gob/jmulticard"
    click APDU "https://github.com/ctt-gob-es/jmulticard/tree/master/jmulticard/src/main/java/es/gob/jmulticard/apdu"
    click ASN1 "https://github.com/ctt-gob-es/jmulticard/tree/master/jmulticard/src/main/java/es/gob/jmulticard/asn1"
    click Crypto "https://github.com/ctt-gob-es/jmulticard/tree/master/jmulticard-crypto/src/main/java/es/gob/jmulticard/crypto"
    click Android_Provider "https://github.com/ctt-gob-es/jmulticard/tree/master/jmulticard-android/src/es/gob/jmulticard/android"
    click JSE_Provider "https://github.com/ctt-gob-es/jmulticard/tree/master/jmulticard-jse/src/main/java/es/gob/jmulticard/jse"
    click JSR268_Provider "https://github.com/ctt-gob-es/jmulticard/tree/master/jmulticard-jsr268/src/main/java/es/gob/jmulticard/jse/smartcardio"
    click WIP_Provider "https://github.com/ctt-gob-es/jmulticard/tree/master/jmulticard-wip/src/main/java/es/gob/jmulticard"
    click Connectivity "https://github.com/ctt-gob-es/jmulticard/tree/master/jmulticard/src/main/java/es/gob/jmulticard/connection"
    click DNIe "https://github.com/ctt-gob-es/jmulticard/tree/master/jmulticard/src/main/java/es/gob/jmulticard/card/dnie"
    click Ceres "https://github.com/ctt-gob-es/jmulticard/tree/master/jmulticard-jse/src/main/java/es/gob/jmulticard/jse/provider/ceres"
    click GiDe "https://github.com/ctt-gob-es/jmulticard/tree/master/jmulticard/src/main/java/es/gob/jmulticard/card/gide"
    click ICAO "https://github.com/ctt-gob-es/jmulticard/tree/master/jmulticard/src/main/java/es/gob/jmulticard/card/icao"

    classDef application fill:#B3E5FC,stroke:#0277BD,stroke-width:2px;
    classDef core fill:#C8E6C9,stroke:#388E3C,stroke-width:2px;
    classDef utility fill:#FFF9C4,stroke:#FBC02D,stroke-width:2px;
    classDef crypto fill:#FFCDD2,stroke:#C62828,stroke-width:2px;
    classDef provider fill:#D1C4E9,stroke:#512DA8,stroke-width:2px;
    classDef connectivity fill:#F0F4C3,stroke:#7CB342,stroke-width:2px;
    classDef card fill:#FFECB3,stroke:#FFA000,stroke-width:2px;

    class Client application;
    class Core_API core;
    class APDU,ASN1 utility;
    class Crypto crypto;
    class Android_Provider,JSE_Provider,JSR268_Provider,WIP_Provider provider;
    class Connectivity connectivity;
    class DNIe,Ceres,GiDe,ICAO card;
```
