# itzmeanjan/ml-kem architecture

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

- Interactive diagram: https://gitdiagram.com/itzmeanjan/ml-kem
- Repository: https://github.com/itzmeanjan/ml-kem

## Overview

- Core ML‑KEM Module:
– Inside or linked to it, detail the three variants (512, 768, 1024) showing that they share common internal components.
- Internal Submodules:
– “utility” functions (force_inline, params, utils) which support the overall cryptographic routines.
- External Cryptographic Primitives:
– “SHA3” – used for hashing (as part of the Fujisaki–Okamoto transform, etc.).
– “RandomShake” – for secure randomness generation.
– “Subtle” – for utility functions around constant‑time implementations.
- Testing & Benchmarking Infrastructure:
- Examples & Build Infrastructure:
– “Examples” (e.g., examples/ml_kem_768.cpp) demonstrating usage by a client.
– “GitHub Workflows”, “Makefile”, and build scripts which integrate with CI and various test modes (debug, release, with sanitizers).

- That a client application (using the “Example” or their own code) includes ML‑KEM’s header files.

##### Architectural Patterns / Design Principles
- That the implementation wraps all operations in statically defined “std::array” and “std::span” patterns for type safety and fixed-size data handling.
- Mention that it adheres to separation of concerns: separating cryptographic mechanics (the ML‑KEM construction) from underlying math routines and from testing/benchmarking harnesses.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client and Build Infrastructure
    subgraph "Client & Build"
        A["Client Application / Example"]:::infra
        B["Examples"]:::infra
        C["CI & Build Infrastructure"]:::infra
        subgraph "CI Tools"
            M["Makefile"]:::infra
            N["GitHub Workflows"]:::infra
        end
        A -->|"includes"| B
    end

    %% ML‑KEM Core Module
    subgraph "ML‑KEM Core Module"
        core1["ML‑KEM‑512 API"]:::core
        core2["ML‑KEM‑768 API"]:::core
        core3["ML‑KEM‑1024 API"]:::core
    end

    %% K-PKE Internal Module
    D["K‑PKE Internal Module"]:::module

    %% Internal Modules
    subgraph "Internal Modules"
        E["Field Arithmetic (Math Utilities)"]:::module
        subgraph "Polynomial Operations"
            P1["NTT"]:::module
            P2["Compression"]:::module
            P3["Poly Vec"]:::module
            P4["Sampling"]:::module
            P5["Serialization"]:::module
        end
        subgraph "Utility Functions"
            U1["force_inline"]:::module
            U2["params"]:::module
            U3["utils"]:::module
        end
    end

    %% External Cryptographic Primitives
    H["SHA3"]:::external
    I["RandomShake"]:::external
    J["Subtle"]:::external

    %% Testing and Benchmarking
    subgraph "Testing & Benchmarking"
        K["Tests"]:::infra
        L["Benchmarks"]:::infra
    end

    %% Connections from Client to ML‑KEM Core
    A -->|"calls"| core1
    A -->|"calls"| core2
    A -->|"calls"| core3

    %% ML‑KEM Core invoking K‑PKE Module
    core2 -->|"invokes"| D
    core3 -->|"invokes"| D

    %% K‑PKE Module utilizing internal routines
    D -->|"uses"| E
    D -->|"uses"| P1
    D -->|"uses"| U1

    %% ML‑KEM Core external calls
    core1 -->|"calls"| H
    core1 -->|"calls"| J
    core2 -->|"calls"| H
    core2 -->|"calls"| J
    core3 -->|"calls"| H
    core3 -->|"calls"| J

    %% RandomShake provides seed to ML‑KEM Core
    I -->|"supplies_seed"| core1
    I -->|"supplies_seed"| core2
    I -->|"supplies_seed"| core3

    %% CI & Build Infrastructure triggers testing and benchmarks
    C -->|"triggers"| K
    C -->|"triggers"| L

    %% Click events for components
    click core1 "https://github.com/itzmeanjan/ml-kem/blob/master/include/ml_kem/ml_kem_512.hpp"
    click core2 "https://github.com/itzmeanjan/ml-kem/blob/master/include/ml_kem/ml_kem_768.hpp"
    click core3 "https://github.com/itzmeanjan/ml-kem/blob/master/include/ml_kem/ml_kem_1024.hpp"
    click D "https://github.com/itzmeanjan/ml-kem/blob/master/include/ml_kem/internals/k_pke.hpp"
    click E "https://github.com/itzmeanjan/ml-kem/blob/master/include/ml_kem/internals/math/field.hpp"
    click P1 "https://github.com/itzmeanjan/ml-kem/blob/master/include/ml_kem/internals/poly/ntt.hpp"
    click P2 "https://github.com/itzmeanjan/ml-kem/blob/master/include/ml_kem/internals/poly/compression.hpp"
    click P3 "https://github.com/itzmeanjan/ml-kem/blob/master/include/ml_kem/internals/poly/poly_vec.hpp"
    click P4 "https://github.com/itzmeanjan/ml-kem/blob/master/include/ml_kem/internals/poly/sampling.hpp"
    click P5 "https://github.com/itzmeanjan/ml-kem/blob/master/include/ml_kem/internals/poly/serialize.hpp"
    click U1 "https://github.com/itzmeanjan/ml-kem/blob/master/include/ml_kem/internals/utility/force_inline.hpp"
    click U2 "https://github.com/itzmeanjan/ml-kem/blob/master/include/ml_kem/internals/utility/params.hpp"
    click U3 "https://github.com/itzmeanjan/ml-kem/blob/master/include/ml_kem/internals/utility/utils.hpp"
    click H "https://github.com/itzmeanjan/ml-kem/tree/master/sha3"
    click I "https://github.com/itzmeanjan/ml-kem/tree/master/RandomShake"
    click J "https://github.com/itzmeanjan/ml-kem/tree/master/subtle"
    click K "https://github.com/itzmeanjan/ml-kem/tree/master/tests"
    click L "https://github.com/itzmeanjan/ml-kem/tree/master/benchmarks"
    click B "https://github.com/itzmeanjan/ml-kem/blob/master/examples/ml_kem_768.cpp"
    click M "https://github.com/itzmeanjan/ml-kem/tree/master/Makefile"
    click N "https://github.com/itzmeanjan/ml-kem/blob/master/.github/workflows/test_ci.yml"

    %% Styles
    classDef core fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef external fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef infra fill:#D5F5E3,stroke:#117A65,stroke-width:2px;
    classDef module fill:#FADBD8,stroke:#922B21,stroke-width:2px;
```
