# whyoleg/cryptography-kotlin architecture

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

- Interactive diagram: https://gitdiagram.com/whyoleg/cryptography-kotlin
- Repository: https://github.com/whyoleg/cryptography-kotlin

## Overview

##### Project type and purpose
- This is a multiplatform Kotlin library (monorepo) providing a type-safe cryptography API.
- It does not run as a service or full-stack application; it is a modular library composed of core APIs (random, big integers, cryptographic operations), serialization modules, and pluggable “provider” implementations (JDK, OpenSSL3, Apple, WebCrypto).

##### File structure
- Top-level build and CI:
- build-logic, build-settings: custom Gradle scripts and plugins to standardize builds and publication.
- .github/workflows and .github/actions: CI pipelines for branch/PR validation, publishing artifacts, website deployment, compatibility tests.
- Main library modules under root:
- cryptography-random
- cryptography-bigint
- cryptography-core
- cryptography-serialization (ASN.1 + PEM)
- cryptography-providers/* (apple, base, jdk, openssl3, webcrypto)
- cryptography-providers-tests-api + cryptography-providers-tests: shared test harness and actual provider compatibility tests.
- Utility/testing/tooling:
- testtool/**: a custom Gradle plugin + client/server for running compatibility tests.
- tests-publication: smoke test for publication.

##### README for additional insights
- The README states:
- A common API (core) for hashing, ciphers, signatures, key derivation, key agreement.
- A separate random-number API.
- Multiple algorithms defined in core.
- Multiple providers that wrap platform-specific implementations.

- Each component (module or subsystem) must have a clear label.
- Blue for core modules (random, bigint, core, serialization).
- Green for provider layers.
- Orange for build/CI.
- Gray for docs/testing tooling.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build System
    subgraph "Build System"
        direction TB
        BuildLogic["build-logic/"]:::build
        BuildSettings["build-settings/"]:::build
        RootBuild["build.gradle.kts"]:::build
        RootSettings["settings.gradle.kts"]:::build
    end

    %% Core API Modules
    subgraph "Core API Modules"
        direction TB
        Random["cryptography-random"]:::core
        BigInt["cryptography-bigint"]:::core
        CoreAPI["cryptography-core"]:::core
        Serialization["cryptography-serialization"]:::core
        subgraph "Serialization"
            direction TB
            ASN1["ASN.1 Module"]:::core
            PEM["PEM Module"]:::core
        end
    end

    %% Provider Layer
    subgraph "Provider Layer"
        direction TB
        JDK["JDK Provider"]:::provider
        OpenSSL3["OpenSSL3 Provider"]:::provider
        Apple["Apple Provider"]:::provider
        WebCrypto["WebCrypto Provider"]:::provider
        BaseProv["Base Operations"]:::provider
    end

    %% Provider Testing
    subgraph "Provider Testing"
        direction TB
        TestsAPI["cryptography-providers-tests-api"]:::test
        TestsImpl["cryptography-providers-tests"]:::test
        subgraph "Testtool"
            direction TB
            Plugin["TesttoolServerPlugin"]:::test
            Client["TesttoolClient"]:::test
            Server["TesttoolServer"]:::test
        end
    end

    %% CI/CD
    subgraph "CI/CD"
        direction TB
        Workflows[".github/workflows"]:::build
        Actions[".github/actions"]:::build
    end

    %% Documentation
    subgraph "Documentation"
        direction TB
        Mkdocs["mkdocs.yml"]:::docs
        DocsFolder["docs/"]:::docs
    end

    %% Dependencies
    BuildLogic -->|used by| Random
    BuildLogic -->|used by| BigInt
    BuildLogic -->|used by| CoreAPI
    BuildLogic -->|used by| Serialization
    BuildSettings -->|applies to| Random
    BuildSettings -->|applies to| BigInt
    BuildSettings -->|applies to| CoreAPI
    BuildSettings -->|applies to| Serialization

    Random -->|feeds| CoreAPI
    BigInt -->|feeds| CoreAPI
    Serialization -->|used by| CoreAPI

    CoreAPI -->|defines interfaces for| JDK
    CoreAPI -->|defines interfaces for| OpenSSL3
    CoreAPI -->|defines interfaces for| Apple
    CoreAPI -->|defines interfaces for| WebCrypto
    CoreAPI -->|defines interfaces for| BaseProv

    Serialization -->|used by| JDK
    Serialization -->|used by| OpenSSL3
    Serialization -->|used by| Apple
    Serialization -->|used by| WebCrypto
    Serialization -->|used by| BaseProv

    TestsAPI -.->|test spec| TestsImpl
    TestsImpl -->|uses| JDK
    TestsImpl -->|uses| OpenSSL3
    TestsImpl -->|uses| Apple
    TestsImpl -->|uses| WebCrypto
    TestsImpl -->|uses| BaseProv

    Plugin -->|registers| TestsImpl
    Client -->|runs| TestsImpl
    Server -->|hosts| TestsImpl

    Workflows -->|invoke| BuildLogic
    Workflows -->|invoke| Workflows
    Workflows -->|run| TestsImpl
    Workflows -->|publish| Documentation
    Workflows -->|deploy| DocsFolder

    Actions -->|setup env| Workflows
    Actions -->|run emulator tests| Workflows

    Mkdocs -->|configures| DocsFolder
    DocsFolder -->|contains| Mkdocs

    %% Click Events
    click BuildLogic "https://github.com/whyoleg/cryptography-kotlin/tree/main/build-logic/"
    click BuildSettings "https://github.com/whyoleg/cryptography-kotlin/tree/main/build-settings/"
    click RootBuild "https://github.com/whyoleg/cryptography-kotlin/blob/main/build.gradle.kts"
    click RootSettings "https://github.com/whyoleg/cryptography-kotlin/blob/main/settings.gradle.kts"
    click Random "https://github.com/whyoleg/cryptography-kotlin/tree/main/cryptography-random/"
    click BigInt "https://github.com/whyoleg/cryptography-kotlin/tree/main/cryptography-bigint/"
    click CoreAPI "https://github.com/whyoleg/cryptography-kotlin/tree/main/cryptography-core/"
    click ASN1 "https://github.com/whyoleg/cryptography-kotlin/blob/main/cryptography-serialization/asn1/src/commonMain/kotlin/Der.kt"
    click PEM "https://github.com/whyoleg/cryptography-kotlin/blob/main/cryptography-serialization/pem/src/commonMain/kotlin/Pem.kt"
    click JDK "https://github.com/whyoleg/cryptography-kotlin/blob/main/cryptography-providers/jdk/src/jvmMain/kotlin/JdkCryptographyProvider.kt"
    click OpenSSL3 "https://github.com/whyoleg/cryptography-kotlin/blob/main/cryptography-providers/openssl3/api/src/commonMain/kotlin/Openssl3CryptographyProvider.kt"
    click Apple "https://github.com/whyoleg/cryptography-kotlin/blob/main/cryptography-providers/apple/src/commonMain/kotlin/AppleCryptographyProvider.kt"
    click WebCrypto "https://github.com/whyoleg/cryptography-kotlin/blob/main/cryptography-providers/webcrypto/src/commonMain/kotlin/WebCryptoCryptographyProvider.kt"
    click BaseProv "https://github.com/whyoleg/cryptography-kotlin/blob/main/cryptography-providers/base/src/commonMain/kotlin/operations/BaseCipher.kt"
    click TestsAPI "https://github.com/whyoleg/cryptography-kotlin/blob/main/cryptography-providers-tests-api/src/commonMain/kotlin/ProviderTest.kt"
    click TestsAPI "https://github.com/whyoleg/cryptography-kotlin/blob/main/cryptography-providers-tests-api/src/commonMain/kotlin/compatibility/CompatibilityTest.kt"
    click TestsImpl "https://github.com/whyoleg/cryptography-kotlin/blob/main/cryptography-providers-tests/src/commonMain/kotlin/compatibility/AesGcmCompatibilityTest.kt"
    click TestsImpl "https://github.com/whyoleg/cryptography-kotlin/blob/main/cryptography-providers-tests/src/commonMain/kotlin/default/CipherTest.kt"
    click Plugin "https://github.com/whyoleg/cryptography-kotlin/blob/main/testtool/plugin/src/main/kotlin/TesttoolServerPlugin.kt"
    click Client "https://github.com/whyoleg/cryptography-kotlin/blob/main/testtool/client/src/commonMain/kotlin/TesttoolClient.kt"
    click Server "https://github.com/whyoleg/cryptography-kotlin/blob/main/testtool/server/src/main/kotlin/TesttoolServer.kt"
    click Mkdocs "https://github.com/whyoleg/cryptography-kotlin/blob/main/mkdocs.yml"
    click DocsFolder "https://github.com/whyoleg/cryptography-kotlin/tree/main/docs/"

    %% Styles
    classDef core fill:#ACE7FF,stroke:#000;
    classDef provider fill:#B2F2BB,stroke:#000;
    classDef build fill:#FFD280,stroke:#000;
    classDef test fill:#D3D3D3,stroke:#000;
    classDef docs fill:#E0E0E0,stroke:#000;
```
