# vlang/libsodium architecture

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

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

## Overview

##### Main Components
- Core Libsodium Wrapper Module: Represent this as the central node titled “libsodium (V Wrapper)” which contains the key integration code.
- Submodules: Illustrate individual components for each cryptographic domain:
- AEAD encryption (folder “aead” with its specific xchacha20poly1305_ietf implementation)
- Secret-key cryptography (modules “secret_box.v” and “secretbox/secretbox.v”)
- Digital signatures (module “sign.v”)
- Key management (files like “private_key.v” and possibly “common.v” for shared utilities)
- C Translation Layer: Include a component for “C2V Generated Definitions” indicated by files like “translated.c.v” – this represents the bridge automatically generated from libsodium C source definitions into V.

##### Relationships and Interactions
- Interactions between key management, encryption, and signature modules (e.g., illustrating that keys created with “private_key.v” are used by both secret-key and public-key operations).

##### Architectural Patterns and Design Principles
- Abstraction Layer: Emphasize how the V wrapper abstracts away the complexities of the native libsodium API.
- Integration of Auto-generated Code: Capture the automated C-to-V translation process (C2V) as a bridge component between the high-level V code and the libsodium C library.

##### Relevant Technologies
- V Language: Central to the wrapper.
- Libsodium C Library: The backend cryptographic engine.
- C2V: Automatic translation tool (explaining that “translated.c.v” is generated).

##### Specific Elements
- Main V API Wrapper (central component)
- Separate modules: AEAD (with subfolder and specific implementation such as “xchacha20poly1305_ietf”), Secret-key encryption (secret_box and secretbox), and Public-key operations (sign, key generation)
- Example and Test Files (indicating usage and validation)
- CI/CD Pipeline (optionally, to indicate the automated testing process via GitHub workflows)

This tailored approach should provide a clear roadmap to understand the project’s architecture and can be a valuable reference for further development or modifications.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "V Wrapper Layer"
        VWrapper["libsodium (V Wrapper)\n(common.v)"]:::vmodule
        AEAD["AEAD Module\n(xchacha20poly1305_ietf)"]:::vmodule
        Secret1["Secret-key Module\n(secret_box.v)"]:::vmodule
        Secret2["Secret-key Module\n(secretbox/secretbox.v)"]:::vmodule
        Sign["Digital Signatures Module\n(sign.v)"]:::vmodule
        KeyMgmt["Key Management Module\n(private_key.v)"]:::vmodule
        C2V["C Translation Layer\n(translated.c.v)"]:::c2v
    end

    External["libsodium C Library\n(Underlying C API)"]:::external

    subgraph "Testing and Examples"
        TestAEAD["AEAD Test\n(aead_xchacha20poly1305_ietf_test.v)"]:::test
        TestSecret["Secret-key Module Test\n(secretbox_test.v)"]:::test
        TestSign["Sign Test\n(sign_test.v)"]:::test
        TestGeneral["General Tests\n(libsodium_test.v)"]:::test
        Examples["Examples\n(example.v)"]:::example
        CI["CI Pipeline\n(.github/workflows/ci.yml)"]:::ci
    end

    VWrapper -->|"API_Calls"| External
    AEAD -->|"API_Calls"| External
    Secret1 -->|"API_Calls"| External
    Secret2 -->|"API_Calls"| External
    Sign -->|"API_Calls"| External
    C2V -->|"Bridges_To"| External

    KeyMgmt -->|"Provides_Keys"| AEAD
    KeyMgmt -->|"Provides_Keys"| Secret1
    KeyMgmt -->|"Provides_Keys"| Secret2
    KeyMgmt -->|"Provides_Keys"| Sign

    TestAEAD -->|"Validates"| AEAD
    TestSecret -->|"Validates"| Secret2
    TestSign -->|"Validates"| Sign
    TestGeneral -->|"Validates"| VWrapper
    Examples -->|"Uses"| VWrapper

    CI -->|"Runs"| TestAEAD
    CI -->|"Runs"| TestSecret
    CI -->|"Runs"| TestSign
    CI -->|"Runs"| TestGeneral

    classDef vmodule fill:#a1c4fd,stroke:#084298,stroke-width:2px;
    classDef external fill:#fddb92,stroke:#f58e1f,stroke-width:2px;
    classDef test fill:#d4fc79,stroke:#74c365,stroke-width:2px;
    classDef ci fill:#f7cac9,stroke:#c94c4c,stroke-width:2px;
    classDef example fill:#c1f7d5,stroke:#3eea8c,stroke-width:2px;
    classDef c2v fill:#f3eac2,stroke:#b8a455,stroke-width:2px;

    click VWrapper "https://github.com/vlang/libsodium/blob/master/common.v"
    click AEAD "https://github.com/vlang/libsodium/blob/master/aead/xchacha20poly1305_ietf/xchacha20poly1305_ietf.v"
    click Secret1 "https://github.com/vlang/libsodium/blob/master/secret_box.v"
    click Secret2 "https://github.com/vlang/libsodium/blob/master/secretbox/secretbox.v"
    click Sign "https://github.com/vlang/libsodium/blob/master/sign.v"
    click KeyMgmt "https://github.com/vlang/libsodium/blob/master/private_key.v"
    click C2V "https://github.com/vlang/libsodium/blob/master/translated.c.v"
    click TestAEAD "https://github.com/vlang/libsodium/blob/master/aead_xchacha20poly1305_ietf_test.v"
    click TestSecret "https://github.com/vlang/libsodium/blob/master/secretbox_test.v"
    click TestSign "https://github.com/vlang/libsodium/blob/master/sign_test.v"
    click TestGeneral "https://github.com/vlang/libsodium/blob/master/libsodium_test.v"
    click Examples "https://github.com/vlang/libsodium/blob/master/examples/example.v"
    click CI "https://github.com/vlang/libsodium/blob/master/.github/workflows/ci.yml"
```
