# teslamotors/liblithium architecture

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

- Interactive diagram: https://gitdiagram.com/teslamotors/liblithium
- Repository: https://github.com/teslamotors/liblithium

## Overview

##### Main Components
- Core Cryptographic Library: This is the heart of liblithium. It’s implemented primarily in C (files in “src”, “include”, “trustinsoft” and “hydro”) and implements the cryptographic algorithms (Gimli permutation, hash, signature creation/verification, random number generation).
- Public API and Interfaces: The API is available via C headers (in “include/lithium”) and is used by both the example applications (listed in “examples” and “hydro/examples”) and the test suite.
- Language-Specific Bindings:
- Python Bindings: Found in the “py” directory (including “py/entry_points” and other Python modules) that wrap or expose core functionalities.
- Rust Bindings: Contained in the “rust” folder with source files (Rust wrappers and binary entry points) that also leverage the core cryptographic abilities.
- Build and Integration Tools: Look at the build scripts (SConstruct, SConscript in multiple directories, Cargo.toml for Rust, Dockerfile and docker scripts), which indicate that the project supports multiple build environments including Docker-based builds.
- Testing and Examples: The “test” directory contains the tests (both C and Python tests), and the “examples” directories provide practical demonstration programs (e.g., lith-sign.c, lith-verify.c).
- Documentation and CI Infrastructure: The “doc” directory, various markdown files (README.md, SECURITY.md), and the GitHub workflows suggest integration and continuous testing.

##### Relationships and Interactions
- The core cryptography routines (compiled from src/trustinsoft/hydro/etc.) are the central elements. These modules are accessed through a clearly defined API (exposed in “include/lithium”).
- The API is consumed by demos and examples (in “examples” and “hydro/examples”) which illustrate the signature, key generation, and verification workflows.
- The Python and Rust bindings communicate with the core library via wrapper functions.
- The SCons/SConstruct build system, as well as Docker scripts and Cargo (for Rust), serve as layers to build, test, and distribute the library.
- Testing components (in “test” and “scripts”) are connected to the build pipeline to ensure consistent behavior across the core, bindings, and examples.

##### Architectural Patterns and Design Principles
- Modularity – The library is broken into small components (for signing, verification, and hashing) that can be individually tested and reused.
- Separation of Concerns – There is a clear split between the core cryptography implementation and the language-specific APIs.
- Portability – The library is designed to run in constrained environments and uses only standard C99, which is reflected in its minimalist design.
- Extensibility – With separate directories for examples, tests, and bindings, the design facilitates future extensions or integrations.

##### Technologies, Frameworks, and Tools
- C99 for core implementation.
- SCons (SConstruct and SConscript) for building the C code.
- Docker for containerized builds (via Dockerfile and docker.bash).
- Python (for scripting and binding exposure) found in the “py” folder.
- Rust via Cargo (with its own structure in the “rust” directory).
- GitHub Actions for CI (in the .github/workflows directory).

##### Specific Elements
- Clear labels for each component:
- “Core Cryptographic Engine” (from src/ and trustinsoft/)
- “Public API” (from include/)
- “Python Bindings” (from py/)
- “Rust Bindings” (from rust/)
- “Examples & Demos” (from examples/ and hydro/examples/)
- “Build System and CI/CD” (SConstruct, CI workflows, Docker)
- “Testing Suite” (from test/ and scripts/)
- How the core library feeds into the API, which in turn is accessed by demos, tests, and language bindings.
- The flow from source code → build tools → deployment/testing.
- Use rectangles for modules, ellipses for build systems, and clouds for CI/CD pipelines.

##### How to Proceed
- Labels or annotations indicating that the design emphasizes portability, minimal footprint, and the availability of both high-level example usage and low-level cryptographic primitives.

## Diagram (Mermaid)

```mermaid
flowchart TD
    BS["Build System & CI/CD"]:::build
    %% Core Library & API subgraph
    subgraph "Core Library & API"
        CORE["Core Cryptographic Engine"]:::core
        API["Public API"]:::api
        CORE -->|"exposes"| API
    end
    
    %% Bindings subgraph
    subgraph "Language Bindings"
        PY["Python Bindings"]:::binding
        RS["Rust Bindings"]:::binding
        API -->|"binds"| PY
        API -->|"binds"| RS
    end

    %% Usage subgraph
    subgraph "Usage"
        EX["Examples & Demos"]:::example
        TS["Testing Suite"]:::test
        API -->|"usedBy"| EX
        API -->|"usedBy"| TS
    end

    %% Build system orchestrates all components
    BS --> CORE
    BS --> API
    BS --> PY
    BS --> RS
    BS --> EX
    BS --> TS

    %% Click Events
    click CORE "https://github.com/teslamotors/liblithium/tree/main/src"
    click API "https://github.com/teslamotors/liblithium/tree/main/include/lithium"
    click PY "https://github.com/teslamotors/liblithium/tree/main/py"
    click RS "https://github.com/teslamotors/liblithium/tree/main/rust"
    click EX "https://github.com/teslamotors/liblithium/tree/main/examples"
    click BS "https://github.com/teslamotors/liblithium/tree/main/SConstruct"
    click TS "https://github.com/teslamotors/liblithium/tree/main/test"

    %% Styles
    classDef core fill:#FFEDB3,stroke:#E0A800,stroke-width:2px;
    classDef api fill:#B3E5FC,stroke:#0288D1,stroke-width:2px;
    classDef binding fill:#C8E6C9,stroke:#388E3C,stroke-width:2px;
    classDef example fill:#F8BBD0,stroke:#C2185B,stroke-width:2px;
    classDef build fill:#D1C4E9,stroke:#512DA8,stroke-width:2px;
    classDef test fill:#FFF9C4,stroke:#FBC02D,stroke-width:2px;
```
