# clearbank/fi-api-signtool-java architecture

> Architecture diagram of the GitHub repository clearbank/fi-api-signtool-java, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/clearbank/fi-api-signtool-java
- Repository: https://github.com/clearbank/fi-api-signtool-java

## Overview

##### Project type and purpose
- This is a small Java “sample tool” / command-line utility whose sole purpose is to demonstrate how to digitally sign a payload (using a private key from disk for demo, but meant to be replaced by an HSM in production) and integrate with ClearBank®’s API.

##### File structure
- Top level: Main.java (entry point), README.md, .gitignore
- Data/: contains sample private/public key PEM files
- No formal src/ or lib/ directories—everything is in one module.
- No build scripts shown (Maven/Gradle would be typical in a larger Java project).

##### README for additional insights
- Describes that in production the private key should reside in a FIPS-compliant HSM.
- Mentions integration with ClearBank®’s live API, implying the sample may also show an HTTP client or at least produce a signature ready to be sent.

##### Main components
a. User / Client: someone invokes the program (CLI or embedded library).
b. Main Application (Main.java): orchestrates reading the payload, invoking the signing logic, optionally calling the API.
c. Signing Module / Service: encapsulates all JCA (Java Cryptography Architecture) logic—loading keys, applying the digital signature algorithm (e.g., SHA256withRSA).
d. Key Provider Abstraction:
- FileSystemKeyProvider (demo) reads PEM files under Data/.
- HSMKeyProvider (prod) would call the HSM via PKCS#11/JCE.
e. Payload Store/Input: wherever the input data comes from (could be CLI args, a file, or an API request).
f. ClearBank® API Endpoint: external HTTP(S) service that validates the signed payload.

##### Relationships and data flows
- The User invokes Main → Main reads the payload → Main invokes Signing Service
- Signing Service calls Key Provider → either reads PEM file or calls HSM → signing operation → returns signature
- Main attaches signature to payload → Main sends HTTP request to ClearBank API (or prints the signature) → receives response

##### Architectural patterns and design principles
- Separation of concerns:
- Main.java handles orchestration
- Signing Service handles cryptography
- Key Provider abstraction hides file vs HSM details
- Dependency inversion: Main depends on an interface IKeyProvider rather than concrete file logic.
- Single responsibility: each component does one thing.

##### Technologies, frameworks, libraries
- Java SE (JDK) – java.security, java.nio.file
- BouncyCastle or built-in JCA providers for PEM parsing and signature
- HTTP client (e.g., HttpURLConnection or Apache HttpClient) for the ClearBank API call
- (In production) PKCS#11 provider for HSM integration

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User / CLI"]:::user
    Main["Main Application<br/>Main.java"]:::core
    Payload["Payload Input Handler"]:::core
    Signing["Signing Service<br/>Crypto Logic"]:::core
    IKey["IKeyProvider Interface"]:::interface
    FSKP["FileSystemKeyProvider<br/>(Demo)"]:::demo
    HSMKP["HSMKeyProvider<br/>(Prod Stub)"]:::prod
    PrivateKey["Private Key PEM<br/>Reference1.PrivateKey.pem"]:::resource
    PublicKey["Public Key PEM<br/>Reference1.PublicKey.pem"]:::resource
    API["ClearBank® API Endpoint"]:::external
    Documentation["Documentation / Usage<br/>README.md"]:::doc

    User --> Main
    Main --> Payload
    Main --> Signing
    Main --> Documentation
    Signing --> IKey
    IKey --> FSKP
    IKey --> HSMKP
    FSKP --> PrivateKey
    FSKP --> PublicKey
    Main --> API

    Signing -.->|"signing error"| Main
    Main -.->|"network error"| API

    click Main "https://github.com/clearbank/fi-api-signtool-java/blob/main/Main.java"
    click Payload "https://github.com/clearbank/fi-api-signtool-java/blob/main/Main.java"
    click Signing "https://github.com/clearbank/fi-api-signtool-java/blob/main/Main.java"
    click IKey "https://github.com/clearbank/fi-api-signtool-java/blob/main/Main.java"
    click FSKP "https://github.com/clearbank/fi-api-signtool-java/blob/main/Data/Reference1.PrivateKey.pem"
    click PrivateKey "https://github.com/clearbank/fi-api-signtool-java/blob/main/Data/Reference1.PrivateKey.pem"
    click PublicKey "https://github.com/clearbank/fi-api-signtool-java/blob/main/Data/Reference1.PublicKey.pem"
    click Documentation "https://github.com/clearbank/fi-api-signtool-java/blob/main/README.md"

    classDef user fill:#D6E9F8,stroke:#31708F;
    classDef core fill:#D9EDF7,stroke:#31708F;
    classDef interface fill:#FCF8E3,stroke:#8A6D3B;
    classDef demo fill:#DFF0D8,stroke:#3C763D;
    classDef prod fill:#FAEBCC,stroke:#8A6D3B;
    classDef external fill:#F2DEDE,stroke:#A94442,stroke-dasharray: 1 2;
    classDef resource fill:#E2F0D9,stroke:#3C763D,stroke-dasharray: 2 2;
    classDef doc fill:#EBF5FB,stroke:#2E6DA4;
```
