# legrandin/pycryptodome architecture

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

- Interactive diagram: https://gitdiagram.com/legrandin/pycryptodome
- Repository: https://github.com/legrandin/pycryptodome

## Overview

##### Project Type and Purpose
- PyCryptodome is a self-contained, multilanguage crypto library (Python + C).
- It exposes low-level cryptographic primitives (cipher, hash, public key, protocol, RNG).
- Performance-critical algorithms are implemented in C or bundled C libraries (libtomcrypt); the rest is pure Python.

##### File Structure Analysis
- Top-level “lib/Crypto”: pure-Python package modules (Cipher, Hash, IO, Math, Protocol, PublicKey, Random, Signature, Util, SelfTest).
- Top-level “src”: C source files for block ciphers, hash functions, ECC, big-integer arithmetic, plus embedded libtomcrypt subtree.
- “test_vectors” and “lib/Crypto/SelfTest”: automated test suites.
- “Doc”: Sphinx documentation source.
- Build/config files: setup.py, pyproject.toml, setup.cfg, Makefile (in src), .github workflows.

##### Key Architecture Insights from README
- Python modules import either other Python modules or compiled C extensions.
- C code is compiled into one or more Python extension modules via setuptools.
- External dependency: optional GMP library for faster public-key ops.
- CI pipelines run unit tests, C tests, and integration tests.

##### Main Components
a. Python Layer
- Pure-Python packages under lib/Crypto (modules grouped by functionality).
- SelfTest framework invoking module tests.
b. Native Layer
- C extension modules (built from src/*.c).
- Embedded libtomcrypt (src/libtom).
c. Build & Packaging
- setup.py / pyproject.toml → compiler toolchain → .so/.pyd extension artifacts.
- pip installer.
d. Documentation
- Doc/ sources → Sphinx → HTML/PDF.
e. Testing
- Python SelfTest (lib/Crypto/SelfTest).
- C test harness (src/test).
- Test vectors (test_vectors).
f. CI/CD
- GitHub Actions workflows (.github/workflows/*).

##### Relationships and Data Flow
- Python modules “Crypto” import C extension methods for performance.
- C extensions link against embedded libtomcrypt and optionally GMP.
- Build step compiles C sources into dynamic libraries, then packaging bundles both Python and compiled artifacts.
- Tests drive both Python and C code through normalized API.
- Docs render API from Python code (autodoc) and include high-level design.

##### Architectural Patterns & Design Principles
- Layered modular architecture: Util & Math → cipher/hash primitives → protocol/public-key stacks → user-facing API.
- Extension pattern: fall back to pure Python if C extension absent (where feasible).
- Self-containment: embedded libtomcrypt provides cryptographic kernels rather than relying on OpenSSL.
- Test-driven: bundled test vectors validate cross-language correctness.

##### Technologies & Frameworks
- Python 2.7+ / 3.7+, setuptools, C compiler toolchain (GCC/Clang on Unix; MSVC on Windows), GMP (optional).
- Sphinx for documentation.
- GitHub Actions for CI.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Python Layer
    subgraph "Python Layer"
        direction TB
        PureAPI["Python API"]:::python
        subgraph "Pure-Python Packages"
            direction TB
            Cipher["Cipher"]:::python
            Hash["Hash"]:::python
            IO["IO"]:::python
            Math["Math"]:::python
            Protocol["Protocol"]:::python
            PublicKey["PublicKey"]:::python
            Random["Random"]:::python
            Signature["Signature"]:::python
            Util["Util"]:::python
        end
        SelfTest["SelfTest Framework"]:::python
    end

    %% Native Layer
    subgraph "Native Layer"
        direction TB
        CExt["C Extension Modules"]:::native
        libtom["libtomcrypt"]:::native
        GMP["GMP (optional)"]:::external
    end

    %% Build & Packaging
    subgraph "Build & Packaging"
        direction TB
        SetupPy["setup.py"]:::tooling
        Pyproj["pyproject.toml"]:::tooling
        SetupCfg["setup.cfg"]:::tooling
        Makefile["src/Makefile"]:::tooling
        BuildProc["Build Process"]:::tooling
        Packaging["Package Distribution"]:::tooling
    end

    %% Documentation
    subgraph "Documentation"
        direction TB
        DocSrc["Sphinx Sources"]:::doc
        DocOut["HTML / PDF Output"]:::doc
    end

    %% Testing
    subgraph "Testing"
        direction TB
        PyTest["Python SelfTest"]:::doc
        CTest["C Test Harness"]:::doc
        TVec["Test Vectors"]:::data
    end

    %% CI/CD
    CI["GitHub Actions"]:::tooling

    %% Relationships
    PureAPI -->|"imports"| Cipher
    PureAPI -->|"imports"| Hash
    PureAPI -->|"imports"| IO
    PureAPI -->|"imports"| Math
    PureAPI -->|"imports"| Protocol
    PureAPI -->|"imports"| PublicKey
    PureAPI -->|"imports"| Random
    PureAPI -->|"imports"| Signature
    PureAPI -->|"imports"| Util
    PureAPI -->|"invokes tests"| SelfTest

    Cipher -->|"calls"| CExt
    Hash -->|"calls"| CExt
    Math -->|"calls"| CExt
    Protocol -->|"calls"| CExt
    PublicKey -->|"calls"| CExt
    Random -->|"calls"| CExt
    Signature -->|"calls"| CExt

    CExt -->|"links against"| libtom
    CExt -->|"optional link"| GMP

    SetupPy --> BuildProc
    Pyproj --> BuildProc
    SetupCfg --> BuildProc
    Makefile --> BuildProc
    BuildProc --> CExt
    BuildProc --> Packaging

    Packaging -->|"bundles"| PureAPI
    Packaging -->|"bundles"| CExt

    PureAPI -->|"autodoc"| DocSrc
    DocSrc --> DocOut

    PyTest --> PureAPI
    PyTest --> CExt
    CTest --> CExt
    TVec --> PureAPI
    TVec --> CExt

    CI --> BuildProc
    CI --> PyTest
    CI --> CTest
    CI --> DocOut

    %% Click Events
    click Cipher "https://github.com/legrandin/pycryptodome/tree/master/lib/Crypto/Cipher"
    click Hash "https://github.com/legrandin/pycryptodome/tree/master/lib/Crypto/Hash"
    click IO "https://github.com/legrandin/pycryptodome/tree/master/lib/Crypto/IO"
    click Math "https://github.com/legrandin/pycryptodome/tree/master/lib/Crypto/Math"
    click Protocol "https://github.com/legrandin/pycryptodome/tree/master/lib/Crypto/Protocol"
    click PublicKey "https://github.com/legrandin/pycryptodome/tree/master/lib/Crypto/PublicKey"
    click Random "https://github.com/legrandin/pycryptodome/tree/master/lib/Crypto/Random"
    click Signature "https://github.com/legrandin/pycryptodome/tree/master/lib/Crypto/Signature"
    click Util "https://github.com/legrandin/pycryptodome/tree/master/lib/Crypto/Util"
    click SelfTest "https://github.com/legrandin/pycryptodome/tree/master/lib/Crypto/SelfTest"
    click CExt "https://github.com/legrandin/pycryptodome/tree/master/src"
    click libtom "https://github.com/legrandin/pycryptodome/tree/master/src/libtom"
    click SetupPy "https://github.com/legrandin/pycryptodome/blob/master/setup.py"
    click Pyproj "https://github.com/legrandin/pycryptodome/blob/master/pyproject.toml"
    click SetupCfg "https://github.com/legrandin/pycryptodome/blob/master/setup.cfg"
    click Makefile "https://github.com/legrandin/pycryptodome/tree/master/src/Makefile"
    click DocSrc "https://github.com/legrandin/pycryptodome/tree/master/Doc/"
    click TVec "https://github.com/legrandin/pycryptodome/tree/master/test_vectors/pycryptodome_test_vectors"
    click CTest "https://github.com/legrandin/pycryptodome/tree/master/src/test"
    click CI "https://github.com/legrandin/pycryptodome/tree/master/.github/workflows"

    %% Styles
    classDef python fill:#E0F7FA,stroke:#006064,color:#006064
    classDef native fill:#FFE0B2,stroke:#E65100,color:#E65100
    classDef tooling fill:#E8F5E9,stroke:#2E7D32,color:#2E7D32
    classDef doc fill:#ECEFF1,stroke:#607D8B,color:#607D8B
    classDef data fill:#CFD8DC,stroke:#455A64,color:#455A64
    classDef external fill:#F3E5F5,stroke:#6A1B9A,color:#6A1B9A
```
