# joshjdevl/libsodium-jni architecture

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

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

## Overview

##### Main Components
- Native Libraries & C Code:
- Underlying libsodium components. Include the “jni” folder (with Android.mk, Application.mk, .c files, SWIG interface files such as sodium.i) that are used to build the native (C/C++) component.
- Build scripts (e.g., build-linux.sh, build-mac.sh, various dependency scripts) that compile the native code into shared libraries (.so files) or the AAR packages.
- SWIG Interface & JNI Binding Layer:
- Java API Layer:
- Java packages (under “src/main/java/org/libsodium/jni”) that provide classes such as NaCl, Sodium, and the various cryptographic primitives.
- Utility and helper classes (crypto, keys, encoders, etc.) which expose the cryptographic functionality to Java or Android applications.
- Example Application:
- “example/Sodium” directory that holds an Android project. This shows how the library is integrated into an Android app (with its manifest, Gradle files, and activity code).
- Test Suite:
- Unit and integration tests found in “src/test/java/org/libsodium/jni/…” to illustrate how the code is verified.
- Build & Deployment Infrastructure:
- Build configuration files (build.gradle, pom.xml) and scripts (e.g., download-gradle.sh, docker-compose scripts, Vagrantfile, Travis CI files) to show the multiple environments – local, Docker, and Vagrant – that are used to compile and test the project.
- Optionally, include external CI/CD components (e.g., Travis CI and Docker Hub as indicated by status badges).

##### Relationships & Interactions
- Data/Control Flow:
- That the SWIG tool processes the interface definition (sodium.i) to generate the JNI bindings.
- Build Flow:
- Build-time pipelines: from native code compilation (using scripts and Makefiles) and SWIG generation, through Java compilation (managed by Gradle) that ultimately builds the final AAR or JAR package.
- Testing & Deployment:
- How unit tests in “src/test” interact with the Java API and how Docker/Vagrant environments are used for consistent builds and testing across platforms.

##### Architectural Patterns & Design Principles
- Layered Architecture:
- A clear separation between the native layer, the JNI bindings (auto-generated with SWIG), and the Java API layer. This helps isolate platform-specific code from application-level code.
- Modularity & Extensibility:
- That the project is designed for extensibility – new JNI bindings or platform-specific adjustments can be integrated with minimal changes to the higher-level Java API.
- Build & Integration Pipeline:
- That the multiple build, test, and deployment scripts (Docker, Vagrant, Travis) serve as an abstraction layer to maintain consistency across different operating systems (Linux, macOS, Android).

##### Technologies, Frameworks, & Libraries
- JNI for interfacing Java with native C code.
- SWIG for generating JNI bindings from the provided interface file.
- Gradle (and Maven for publishing) for build automation.
- Docker and Vagrant for environment consistency and deployment automation.
- Travis CI for continuous integration.
- (For Android) Standard Android components (Manifest, Gradle integration) to facilitate usage of the library as an AAR.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Native & JNI Layer"
        A["Native Libraries & C Code"]:::native
        B["SWIG Interface (sodium.i)"]:::swig
        C["SWIG & JNI Binding Layer"]:::jni
        A -->|"supplies_native_calls"| C
        B -->|"processed_by_Swig"| C
    end

    subgraph "Java Layer"
        D["Java API Layer"]:::java
        E["Example Application"]:::android
        F["Test Suite"]:::test
        D -->|"invokes_JNI"| C
        D -->|"integrated_into"| E
        D -->|"verified_by"| F
    end

    G["Build & Deployment Infrastructure"]:::build
    G -->|"builds_native_code"| A
    G -->|"runs_Swig_generation"| B
    G -->|"compiles_JNI_layer"| C
    G -->|"builds_java_code"| D
    G -->|"executes_tests"| F

    click A "https://github.com/joshjdevl/libsodium-jni/tree/master/jni/"
    click B "https://github.com/joshjdevl/libsodium-jni/blob/master/jni/sodium.i"
    click D "https://github.com/joshjdevl/libsodium-jni/tree/master/src/main/java/org/libsodium/jni/"
    click E "https://github.com/joshjdevl/libsodium-jni/tree/master/example/Sodium/"
    click F "https://github.com/joshjdevl/libsodium-jni/tree/master/src/test/java/org/libsodium/jni/"
    click G "https://github.com/joshjdevl/libsodium-jni/blob/master/build.gradle"

    classDef native fill:#f9c,stroke:#333,stroke-width:2px;
    classDef swig fill:#9cf,stroke:#333,stroke-width:2px;
    classDef jni fill:#fc9,stroke:#333,stroke-width:2px;
    classDef java fill:#cff,stroke:#333,stroke-width:2px;
    classDef android fill:#c9f,stroke:#333,stroke-width:2px;
    classDef test fill:#9fc,stroke:#333,stroke-width:2px;
    classDef build fill:#ff9,stroke:#333,stroke-width:2px;
```
