# ekino/hibernate-crypto-types architecture

> Architecture diagram of the GitHub repository ekino/hibernate-crypto-types, 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/ekino/hibernate-crypto-types
- Repository: https://github.com/ekino/hibernate-crypto-types

## Overview

This project is a specialized library designed to integrate custom encrypted Hibernate types with Java applications. Based on the file tree and README, it is evident that the library’s purpose is to allow developers to annotate entity fields in Hibernate with custom encryption types. The project primarily provides:
- Custom Hibernate type definitions for encrypting various kinds of data (plain text, salted text, JSON, etc.).
- Beans and configuration examples on how to wire up encryption properties.
- Integration tests and example configurations that demonstrate real-world usage of the library.

##### Main Components
a. Cryptography Module:
- Contains classes for encryption/decryption (e.g., EncryptDecrypt, the various Hibernate type classes like EncryptedJsonType, EncryptedStringType, etc.).
- Utility components (StringSaltManager, StringUUIDSaltManager) that support cryptographic operations.
b. Hibernate Integration:
- Package structure in “com/ekino/oss/crypto/hibernate” – this contains the Hibernate type definitions and descriptors.
- Abstract entity (AbstractEntity) that aggregates type definitions using @TypeDefs.
c. Configuration and Initialization:
- Bean classes in the integration test sample that load and initialize encryption configuration from properties (EncryptProperties, EncryptConfig).
- Resources and configuration files (application.yml, hibernate.properties, database migration scripts).
d. Integration Tests:
- Comprehensive tests in the “src/integrationTest” package that illustrate how to integrate the encryption types in practice.
- These tests also demonstrate how the library interacts with a live database schema (using migration scripts in resources/db/migration).
e. Build and Deployment:
- Build scripts (build.gradle.kts, settings.gradle.kts) and Gradle wrapper files.
- CI/CD configuration (GitHub workflows in .github/workflows) ensuring that tests and builds are automated.
- Docker Compose file which might be used for spinning up dependent services (e.g., a test database).

##### Relationships and Interactions
- The Cryptography Module is at the core, working in tandem with Hibernate. The custom types (and associated type descriptors) are wired through annotations in the entities.
- The configuration component (via EncryptConfig and EncryptProperties) initializes the encryption credentials at runtime – this setup is crucial before any Hibernate session is created.
- Integration tests simulate the full flow: ingestion of configuration properties, encryption/decryption of data with the custom Hibernate types, and validating that entities interact correctly with the underlying database.
- The Build and Deployment segment shows how automated testing and build processes manage code quality and deployment readiness.

##### Architectural Patterns and Design Principles
- Layered Architecture: The design separates concerns – the cryptography logic is encapsulated away from the configuration and testing layers.
- Configuration-Based Initialization: Usage of beans and configuration properties to set up critical runtime dependencies (encryption keys, initialization vectors).
- Extensibility: The use of abstract superclass (AbstractEntity) and Hibernate’s custom type definitions indicates adherence to DRY principles by centralizing common configurations.
- Testing-Driven Integration: Integration tests are provided to demonstrate usage scenarios and guarantee correctness across the full integration spectrum.

##### Instructing the Principal Software Engineer
- Detail each component based on the breakdown above.
- Initialization flow from configuration → encryption code.
- Integration flow from application code (that extends AbstractEntity) to the database (through Hibernate).
- Verification flow within the integration tests.
- That every element – including build scripts and automated workflows – is captured to reflect how the project moves from development to deployment.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration & Initialization
    subgraph "Configuration & Initialization"
        A1["App Config"]:::config
        A2["EncryptConfig"]:::config
        A3["EncryptProperties"]:::config
        A1 -->|"loads"| A2
        A1 -->|"loads"| A3
    end

    %% Cryptography Module
    subgraph "Cryptography Module"
        B1["Encryption/Decryption"]:::crypto
        B2["StringSaltManager"]:::crypto
        B3["StringUUIDSaltManager"]:::crypto
        %% (Utilities are associated with encryption logic)
        B2 --- B1
        B3 --- B1
    end

    %% Hibernate Integration
    subgraph "Hibernate Integration"
        C1["Custom Hibernate Types"]:::hibernate
        C2["Abstract Entity"]:::hibernate
        C1 -->|"appliedIn"| C2
    end

    %% Integration Tests
    subgraph "Integration Tests"
        D1["ApplicationTest"]:::test
        D2["PersonRepositoryTest"]:::test
        D3["Database Migration Script"]:::test
        D1 ---|"validates"| C2
        D2 ---|"validates"| C2
        D1 -->|"usesSchema"| D3
    end

    %% Build & CI/CD Pipeline
    subgraph "Build & CI/CD Pipeline"
        E1["build.gradle.kts"]:::build
        E2["settings.gradle.kts"]:::build
        E3["Docker Compose"]:::build
        E4["CI Workflows"]:::build
        E1 --- E2
        E4 --- E1
    end

    %% Interconnections between major layers
    A2 -->|"init" | B1
    A3 -->|"init" | B1
    B1 -->|"provides" | C1
    C2 -->|"testedBy" | D1
    C2 -->|"testedBy" | D2

    %% Styles
    classDef config fill:#f9e79f,stroke:#d4ac0d,stroke-width:2px;
    classDef crypto fill:#aed6f1,stroke:#3498db,stroke-width:2px;
    classDef hibernate fill:#a9dfbf,stroke:#27ae60,stroke-width:2px;
    classDef test fill:#f5b7b1,stroke:#e74c3c,stroke-width:2px;
    classDef build fill:#f2d7d5,stroke:#c0392b,stroke-width:2px;

    %% Click Events
    click A1 "https://github.com/ekino/hibernate-crypto-types/blob/master/src/integrationTest/resources/application.yml"
    click A2 "https://github.com/ekino/hibernate-crypto-types/blob/master/src/integrationTest/kotlin/com/ekino/oss/hibernate/config/EncryptConfig.kt"
    click A3 "https://github.com/ekino/hibernate-crypto-types/blob/master/src/integrationTest/kotlin/com/ekino/oss/hibernate/config/EncryptProperties.kt"
    click B1 "https://github.com/ekino/hibernate-crypto-types/blob/master/src/main/kotlin/com/ekino/oss/crypto/EncryptDecrypt.kt"
    click B2 "https://github.com/ekino/hibernate-crypto-types/blob/master/src/main/kotlin/com/ekino/oss/crypto/utils/StringSaltManager.kt"
    click B3 "https://github.com/ekino/hibernate-crypto-types/blob/master/src/main/kotlin/com/ekino/oss/crypto/utils/StringUUIDSaltManager.kt"
    click C1 "https://github.com/ekino/hibernate-crypto-types/tree/master/src/main/kotlin/com/ekino/oss/crypto/hibernate/"
    click C2 "https://github.com/ekino/hibernate-crypto-types/blob/master/src/integrationTest/kotlin/com/ekino/oss/hibernate/model/AbstractEntity.kt"
    click D1 "https://github.com/ekino/hibernate-crypto-types/blob/master/src/integrationTest/kotlin/com/ekino/oss/hibernate/ApplicationTest.kt"
    click D2 "https://github.com/ekino/hibernate-crypto-types/blob/master/src/integrationTest/kotlin/com/ekino/oss/hibernate/PersonRepositoryTest.kt"
    click D3 "https://github.com/ekino/hibernate-crypto-types/blob/master/src/integrationTest/resources/db/migration/V1__CREATE_SCHEMA.sql"
    click E1 "https://github.com/ekino/hibernate-crypto-types/blob/master/build.gradle.kts"
    click E2 "https://github.com/ekino/hibernate-crypto-types/blob/master/settings.gradle.kts"
    click E3 "https://github.com/ekino/hibernate-crypto-types/blob/master/docker-compose.yml"
    click E4 "https://github.com/ekino/hibernate-crypto-types/tree/master/.github/workflows/"
```
