# jedisct1/libsodium architecture

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

- Interactive diagram: https://gitdiagram.com/jedisct1/libsodium
- Repository: https://github.com/jedisct1/libsodium

## Overview

##### Project Type and Purpose
- Project type: Cross-platform cryptographic library (C language).
- Purpose: Provide easy-to-use cryptographic primitives (encryption/decryption, signatures, hashing, password hashing, random number generation) and build/publish them across many platforms.

##### File Structure
- Top-level “src” directory with subdirectories for each crypto primitive (crypto_aead, crypto_auth, crypto_box, crypto_core, etc.).
- “include” directory exposing public API headers (sodium.h and per-module headers).
- Build/config layers:
– Autotools files (configure.ac, Makefile.am).
– Platform-specific build scripts under “builds/” (MSVC-projects), “dist-build/” (Android, Emscripten, WASM, iOS/macOS), and “build.zig”.
– CI configurations in “.github/workflows”, “azure-pipelines.yml”, “appveyor.yml”.
- “test” directory: test harnesses for each primitive (reference implementations and expected outputs).
- Packaging: “packaging/dotnet-core” for .NET wrappers.

##### README for Additional Insights
- Confirms it’s an API-focused library, not an application.
- Emphasizes cross-platform portability and API stability.

##### Main Components
a. Public API Layer (“include/” – sodium.h, crypto_* headers)
b. Core Crypto Engine (“src/libsodium/” + per‐algorithm subfolders)
c. Build System Layer
- Autotools Build (configure, Makefile.am)
- Platform/Language Bindings
– MSVC (*.vcxproj under builds/msvc and regen-msvc)
– Emscripten/WASM and Zig (build.zig, dist-build scripts)
– .NET-Core pkgproj (packaging/dotnet-core)
d. Test Harness (“test/” – default and quirks tests)
e. Continuous Integration (GitHub Actions, Azure Pipelines, Appveyor)
f. External Consumers (applications linking against the library, language bindings like Python, Go, Node.js – represented abstractly)

##### Relationships and Data Flows
- Build System Layer compiles the Core Crypto Engine and Public API into a library binary (.dll, .so, .a, .lib).
- The Test Harness drives the Public API and validates outputs from Core Crypto Engine.
- CI pipelines invoke the Build System for each target platform, then run the Test Harness.
- External Consumers link against the compiled library and include headers from the Public API Layer.

##### Architectural Patterns and Design Principles
- Layered modular design: separation of public API vs. implementation vs. build vs. tests.
- Plugin-like modules: each crypto algorithm lives in its own folder and is registered via common build files.
- Portability abstraction: platform-specific code is isolated in build scripts and conditional implementations.
- Reference implementations vs. optimized versions (e.g., AESNI, ARM Crypto, SSE).

##### Technologies, Frameworks, Libraries
- C99 source code (portable crypto implementations, reference & optimized variants).
- Autotools (configure.ac, Makefile.am) for UNIX builds.
- MSBuild / Visual Studio projects for Windows.
- Zig build (build.zig) and Emscripten for WASM.
- Continuous Integration: GitHub Actions, Azure Pipelines, Appveyor.

##### Elements
– API calls → Core modules
– Build scripts → compiled library
– Tests → API → Core modules
– CI → Build & Tests
– Consumers → library
– Rectangles for code components
– Clouds for CI services

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Source Code Layer
    subgraph "Source Code" 
        direction TB
        PublicAPI["Public API Layer"]:::code
        CoreEngine["Core Crypto Engine"]:::code
    end

    %% Build System Layer
    subgraph "Build System" 
        direction TB
        Autotools["Autotools Build"]:::build
        MSVC["MSVC Build Projects"]:::build
        Zig["Zig Build Script"]:::build
        WASM["Emscripten/WASM Scripts"]:::build
        NetCore[".NET-Core Packaging"]:::build
    end

    %% Test Harness
    TestHarness["Test Harness"]:::build

    %% Compiled Artifact
    Library(("Compiled Library")):::artifact

    %% CI Pipelines
    subgraph "CI Pipelines" 
        direction TB
        GitHub["GitHub Actions"]:::ci
        Azure["Azure Pipelines"]:::ci
        Appveyor["Appveyor"]:::ci
    end

    %% External Consumers
    Consumers(("External Consumers")):::external

    %% Relationships
    PublicAPI -->|"calls"| CoreEngine
    Autotools -->|compiles| Library
    MSVC -->|compiles| Library
    Zig -->|compiles| Library
    WASM -->|compiles| Library
    NetCore -->|packages| Library
    TestHarness -->|tests via API| PublicAPI
    PublicAPI -->|invokes| CoreEngine
    GitHub -->|runs build & tests| Autotools
    GitHub -->|runs build & tests| TestHarness
    Azure -->|runs build & tests| Autotools
    Azure -->|runs build & tests| TestHarness
    Appveyor -->|runs build & tests| Autotools
    Appveyor -->|runs build & tests| TestHarness
    Consumers -->|link against| Library
    Consumers -->|include headers| PublicAPI

    %% Click Events
    click PublicAPI "https://github.com/jedisct1/libsodium/blob/master/src/libsodium/include/sodium.h"
    click CoreEngine "https://github.com/jedisct1/libsodium/tree/master/src/libsodium/crypto_aead"
    click Autotools "https://github.com/jedisct1/libsodium/blob/master/configure.ac"
    click MSVC "https://github.com/jedisct1/libsodium/tree/master/builds/msvc/"
    click Zig "https://github.com/jedisct1/libsodium/blob/master/build.zig"
    click WASM "https://github.com/jedisct1/libsodium/tree/master/dist-build/"
    click NetCore "https://github.com/jedisct1/libsodium/blob/master/packaging/dotnet-core/libsodium.pkgproj"
    click TestHarness "https://github.com/jedisct1/libsodium/tree/master/test/default/"
    click GitHub "https://github.com/jedisct1/libsodium/blob/master/.github/workflows/ci.yml"
    click Azure "https://github.com/jedisct1/libsodium/blob/master/azure-pipelines.yml"
    click Appveyor "https://github.com/jedisct1/libsodium/blob/master/appveyor.yml"

    %% Styles
    classDef code fill:#D0E8FF,stroke:#005B9F,color:#000;
    classDef build fill:#E2F0D9,stroke:#388E3C,color:#000;
    classDef artifact fill:#FFF2CC,stroke:#BF9000,color:#000;
    classDef ci fill:#FFE0B2,stroke:#EF6C00,color:#000;
    classDef external fill:#E1BEE7,stroke:#8E24AA,color:#000;
```
