# pkasila/gorm-crypto architecture

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

- Interactive diagram: https://gitdiagram.com/pkasila/gorm-crypto
- Repository: https://github.com/pkasila/gorm-crypto

## Overview

##### Main architectural components
- Library Initialization: Core functions (e.g., gormcrypto.Init, gormcrypto.InitWithFallbacks, gormcrypto.InitSigning) that setup the encryption/signing mechanism.
- Encryption Algorithms: Located in the “algorithms” directory, these components include implementations for different encryption strategies (RSA, AES256CBC, AES256GCM).
- Signing Algorithms: Found under the “signing” directory with subcomponents that implement signature generation and verification using ECDSA and Ed25519.
- Helpers: Utility functions for key generation and conversion in the “helpers” directory. They are used by both encryption and signing modules.
- Serialization: In the “serialization” directory, components here (such as JSON serialization) are responsible for converting values to and from a storable format.
- Integration with GORM: The library’s usage examples in the README show how types like EncryptedValue and SignedValue are attached to model definitions (as part of a full-stack application's data layer).

##### Interactions and relationships
- The Initialization Component communicates with the chosen Encryption algorithm (or a fallback chain) and/or Signing algorithm, while also tying in the Serialization mechanism.
- Encryption algorithms depend on key pairs and configuration provided by the Helpers.
- The Encryption and Signing modules interact with the model layer via custom types (EncryptedValue, SignedValue) which act as data wrappers ensuring encryption/decryption and signing/verification of sensitive data.
- Data flows from the application (e.g., when creating a DB record) into the encryption/signing modules, serializes the data, and then the GORM layer persists it into the database.

##### Architectural patterns and design principles
- Modularity: The project is clearly divided into modules (algorithms, signing, helpers, serialization) that can be independently developed or swapped (as demonstrated by the fallback mechanism).
- Pluggable Algorithms: The design allows choosing between different encryption algorithms and signing algorithms, emphasizing extensibility.
- Single Responsibility: Each directory/component has a focused responsibility (e.g., helpers for key management, serialization for JSON conversion).

##### Relevant technologies/frameworks
- Go (language and module system with go.mod and go.sum).
- GORM ORM (the library integrates specifically with GORM as seen in usage examples).
- Cryptographic algorithms: RSA, AES256GCM, AES256CBC for encryption and ECDSA, Ed25519 for signing.
- JSON serialization for data interchange.

- Since it is a library that integrates with GORM in a full-stack application, visually emphasize the separation between the core cryptographic functionality (encryption, signing, serialization) and the data persistence layer (GORM as the database layer).
- Initialization stage as the entry point where the user’s application configures the library by selecting encryption or signing strategies.
- Fallback mechanics as alternative paths, indicating that multiple algorithms can be chained to provide redundancy or graceful key rotation.

##### Additional detail
- For each encryption/signing method, show how keys are generated/loaded (via the helpers) and then passed to the respective algorithm modules.
- That the Serializer (in this case JSON) is wrapped around both encryption and signing logic to ensure that the types are correctly marshaled/unmarshaled for persistence.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Global Nodes
  App["Application"]:::app

  %% Initialization Layer
  subgraph "Initialization Layer"
    Init["Library Initialization"]:::init
  end

  %% Encryption Algorithms Layer
  subgraph "Encryption Algorithms"
    E_RSA["RSA Algorithm"]:::encrypt
    E_AES256CBC["AES256CBC Algorithm"]:::encrypt
    E_AES256GCM["AES256GCM Algorithm"]:::encrypt
    E_Base["Algorithm Base"]:::encrypt
  end

  %% Signing Algorithms Layer
  subgraph "Signing Algorithms"
    S_ECDSA["ECDSA Algorithm"]:::sign
    S_ED25519["Ed25519 Algorithm"]:::sign
    S_Base["Signature Algorithm Base"]:::sign
  end

  %% Helpers Layer
  subgraph "Helpers"
    H_RSA["RSA Helper"]:::helper
    H_ECDSA["ECDSA Helper"]:::helper
    H_ED25519["Ed25519 Helper"]:::helper
  end

  %% Serialization Layer
  subgraph "Serialization"
    SER_JSON["JSON Serialization"]:::serialize
    SER_Core["Serializer Core"]:::serialize
  end

  %% GORM Integration Layer
  subgraph "GORM Integration"
    G_ENC["EncryptedValue Type"]:::gorm
    G_SIGN["SignedValue Type"]:::gorm
  end

  %% Connections
  App --> Init
  Init -->|"fallback"| E_RSA
  Init -->|"initSigning"| S_ECDSA

  %% Encryption Algorithms use Helpers
  E_RSA --> H_RSA
  E_AES256CBC --> H_RSA
  E_AES256GCM --> H_RSA
  E_Base --> H_RSA

  %% Signing Algorithms use Helpers
  S_ECDSA --> H_ECDSA
  S_ED25519 --> H_ED25519
  S_Base --> H_ECDSA

  %% Helpers to Serialization
  H_RSA --> SER_JSON
  H_ECDSA --> SER_JSON
  H_ED25519 --> SER_JSON

  %% Serialization Flow
  SER_JSON --> SER_Core
  SER_Core --> G_ENC
  SER_Core --> G_SIGN

  %% Click Events
  click Init "https://github.com/pkasila/gorm-crypto/blob/main/initializer.go"
  click E_RSA "https://github.com/pkasila/gorm-crypto/blob/main/algorithms/rsa.go"
  click E_AES256CBC "https://github.com/pkasila/gorm-crypto/blob/main/algorithms/aes256cbc.go"
  click E_AES256GCM "https://github.com/pkasila/gorm-crypto/blob/main/algorithms/aes256gcm.go"
  click E_Base "https://github.com/pkasila/gorm-crypto/blob/main/algorithms/algorithm.go"
  click S_ECDSA "https://github.com/pkasila/gorm-crypto/blob/main/signing/ecdsa.go"
  click S_ED25519 "https://github.com/pkasila/gorm-crypto/blob/main/signing/ed25519.go"
  click S_Base "https://github.com/pkasila/gorm-crypto/blob/main/signing/signature_algorithm.go"
  click H_RSA "https://github.com/pkasila/gorm-crypto/blob/main/helpers/rsa.go"
  click H_ECDSA "https://github.com/pkasila/gorm-crypto/blob/main/helpers/ecdsa.go"
  click H_ED25519 "https://github.com/pkasila/gorm-crypto/blob/main/helpers/ed25519.go"
  click SER_JSON "https://github.com/pkasila/gorm-crypto/blob/main/serialization/json.go"
  click SER_Core "https://github.com/pkasila/gorm-crypto/blob/main/serialization/serializer.go"
  click G_ENC "https://github.com/pkasila/gorm-crypto/blob/main/encrypted_value.go"
  click G_SIGN "https://github.com/pkasila/gorm-crypto/blob/main/signed_value.go"

  %% Styles
  classDef app fill:#8EC0E4,stroke:#333,stroke-width:2px;
  classDef init fill:#f8b400,stroke:#333,stroke-width:2px;
  classDef encrypt fill:#ff9999,stroke:#333,stroke-width:2px;
  classDef sign fill:#99ccff,stroke:#333,stroke-width:2px;
  classDef helper fill:#ccffcc,stroke:#333,stroke-width:2px;
  classDef serialize fill:#ffcc99,stroke:#333,stroke-width:2px;
  classDef gorm fill:#ccccff,stroke:#333,stroke-width:2px;
```
