# moov-io/dukpt architecture

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

- Interactive diagram: https://gitdiagram.com/moov-io/dukpt
- Repository: https://github.com/moov-io/dukpt

## Overview

##### Identify the Project Type and Purpose

- **Project Type:**
- **Library and Service:** The project is a Go-based library that implements the ANSI X9.24-3:2017 standard for Triple DES (TDES) and Advanced Encryption Standard (AES) Derived Unique Key Per Transaction (DUKPT) key management.
- **Validation and Debugging Tool:** Primarily used for validation and debugging, especially in environments involving dedicated security hardware.

- **Purpose:**
- **Key Management:** Provides functionalities for deriving keys, encrypting/decrypting data, and generating MACs using DUKPT standards.
- **Command-Line Interface and RESTful Service:** Offers both CLI tools and a web server for interacting with the key management functionalities.

##### Analyze the File Structure

- **Top-Level Directories and Files:**
- **`.github/`:** Contains GitHub workflows for CI/CD (`codeql.yaml`, `go.yml`) and issue templates.
- **`cmd/`:** Hosts command-line applications:
- **`dukptcli/`:** CLI tool for key management operations.
- **`server/`:** Web server application exposing REST APIs.
- **`encryption/`:** Implements encryption algorithms (`aes_ecb.go`, `des_ecb.go`).
- **`pkg/`:** Modular packages:
- **`aes/` and `des/`:** Encryption logic for AES and DES respectively.
- **`server/`:** Contains server-related components like handlers, routing, services, and repositories.
- **`util.go`:** Utility functions utilized across packages.
- **Build and Configuration Files:**
- **`go.mod`, `go.sum`:** Go module dependencies.
- **`Makefile`:** Build automation.
- **`renovate.json`:** Dependency management configuration.
- **`version.go`:** Versioning information.

- **Architectural Indicators:**
- **Modular Structure:** Separation of concerns through distinct packages and command directories.
- **Server and CLI Separation:** Distinct applications for different interfaces (CLI vs. REST API).
- **Testing Presence:** Test files (`*_test.go`) indicate a focus on test-driven development.

##### Examine the README for Additional Insights

- **Architecture Overview:**
- **Go Library:** Core functionalities for DUKPT key management.
- **Command-Line Tools:** `dukptcli` for direct CLI interactions, `server` for running the RESTful service.
- **REST APIs:** Endpoints for managing machines and performing encryption-related operations.
- **Service Instance:** Supports multiple encryption machines with service interfaces.

- **Technical Stack:**
- **Programming Language:** Go (version 1.18+).
- **CI/CD:** GitHub Actions for code analysis and build (`codeql.yaml`, `go.yml`).
- **Testing:** Comprehensive unit tests with coverage reports via Codecov.

- **Usage Details:**
- **Key Derivation and Encryption Functions:** Clearly defined APIs for key management tasks.
- **Service and REST Endpoints:** Detailed methods and routes for interacting with the service.

##### Command-Line Interface (CLI)
- **`dukptcli`:** Provides commands for key derivation, encryption, decryption, and MAC generation.

##### Server
- **RESTful Service:** Exposes HTTP endpoints for all key management operations.

##### Encryption Modules
- **AES (`pkg/aes/`):** Implements AES-specific encryption and key derivation.
- **DES (`pkg/des/`):** Implements DES-specific encryption and key derivation.

##### Service Layer (`pkg/server/service.go`)
- Contains business logic for handling requests from both CLI and REST APIs.

##### Repository Layer (`pkg/server/repository.go`)
- Manages data persistence, likely in-memory based on the repository implementation.

##### Utilities (`pkg/util.go`)
- Provides common utility functions used across various packages.

##### CI/CD Pipelines (`.github/workflows/`)
- **`codeql.yaml`:** Code quality and security analysis.
- **`go.yml`:** Build and test workflows.

##### b. Determine Relationships and Interactions

- **CLI and Server Interaction:**
- Both interact with the **Service Layer** to perform key management operations.

- **Service Layer and Encryption Modules:**
- The **Service Layer** uses **AES** and **DES** modules for encryption, decryption, and key derivation.

- **Service Layer and Repository Layer:**
- Handles data storage and retrieval, such as managing different encryption machines.

- **REST APIs and Service Layer:**
- REST endpoints receive HTTP requests and delegate processing to the **Service Layer**.

- **CI/CD Pipelines and Project Components:**
- Automated workflows handle code analysis, testing, and building processes.

##### c. Highlight Architectural Patterns and Design Principles

- **Modular Architecture:**
- Clear separation between encryption logic, service handling, and interface layers (CLI and REST).

- **Separation of Concerns:**
- Distinct layers for service logic and data management ensure maintainability and scalability.

- **RESTful Design:**
- Adheres to REST principles for web service design, enabling interoperability and standardization.

- **Test-Driven Development:**
- Comprehensive testing ensures reliability and facilitates continuous integration.

##### d. Include Relevant Technologies, Frameworks, or Libraries

- **Programming Language:** Go (Golang)
- **Dependency Management:** Go Modules (`go.mod`, `go.sum`)
- **CI/CD:** GitHub Actions
- **Logging:** Likely uses Go’s standard logging libraries (e.g., `log`)
- **Testing:** Go’s built-in testing framework
- **Version Control:** GitHub

##### Elements

- **Clear Labels for Each Component:**
- E.g., `dukptcli`, `REST Server`, `AES Module`, `DES Module`, `Service Layer`, `Repository Layer`.

- Interactions such as CLI and Server invoking Service Layer functions, which then call Encryption Modules.

- **Supporting Components:**
- **CI/CD:** Represent workflows as part of the infrastructure.
- **Testing Framework:** Indicate the testing process adjacent to relevant components.

##### Ensure Detailed and Comprehensive Representation

- **Capture All Essential Architectural Elements:**
- Do not overlook components like the **Repository Layer** or **Utility Functions**.

- **Maintain Clarity:**

- **Avoid Overcomplication:**
- High-level interactions and critical components without delving into low-level implementation details.

##### Side Components: Infrastructure
- **Testing Framework:** Adjacent to relevant components indicating ongoing testing processes.

##### Utilities and Common Services
- **Utility Functions:** Represented as shared resources or services utilized by multiple components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Interfaces
    dukptcli["dukptcli"]:::interface
    RESTServer["REST Server"]:::interface

    %% Service Components
    ServiceLayer["Service Layer"]:::service
    RepositoryLayer["Repository Layer"]:::service

    %% Core Functionalities
    AESModule["AES Module"]:::encryptionAES
    DESModule["DES Module"]:::encryptionDES

    %% Utilities
    Utilities["Utilities"]:::utilities

    %% Infrastructure
    CICD["CI/CD Pipelines"]:::cicd

    %% Connections
    dukptcli -->|uses| ServiceLayer
    RESTServer -->|uses| ServiceLayer
    ServiceLayer -->|uses| AESModule
    ServiceLayer -->|uses| DESModule
    ServiceLayer -->|uses| RepositoryLayer
    ServiceLayer -->|uses| Utilities
    AESModule -->|uses| Utilities
    DESModule -->|uses| Utilities
    CICD -.->|automates| dukptcli
    CICD -.->|automates| RESTServer
    CICD -.->|automates| ServiceLayer

    %% Click Events
    click dukptcli "https://github.com/moov-io/dukpt/tree/master/cmd/dukptcli/"
    click RESTServer "https://github.com/moov-io/dukpt/tree/master/cmd/server/"
    click AESModule "https://github.com/moov-io/dukpt/tree/master/pkg/aes/"
    click DESModule "https://github.com/moov-io/dukpt/tree/master/pkg/des/"
    click ServiceLayer "https://github.com/moov-io/dukpt/blob/master/pkg/server/service.go"
    click RepositoryLayer "https://github.com/moov-io/dukpt/blob/master/pkg/server/repository.go"
    click Utilities "https://github.com/moov-io/dukpt/blob/master/pkg/util.go"
    click CICD "https://github.com/moov-io/dukpt/tree/master/.github/workflows/"

    %% Styles
    classDef interface fill:#add8e6,stroke:#000,stroke-width:1px
    classDef service fill:#90ee90,stroke:#000,stroke-width:1px
    classDef encryptionAES fill:#ff7f7f,stroke:#000,stroke-width:1px
    classDef encryptionDES fill:#ffa500,stroke:#000,stroke-width:1px
    classDef cicd fill:#dda0dd,stroke:#000,stroke-width:1px
    classDef utilities fill:#d3d3d3,stroke:#000,stroke-width:1px

    class dukptcli,RESTServer interface
    class ServiceLayer,RepositoryLayer service
    class AESModule encryptionAES
    class DESModule encryptionDES
    class CICD cicd
    class Utilities utilities
```
