# anssi-fr/mla architecture

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

- Interactive diagram: https://gitdiagram.com/anssi-fr/mla
- Repository: https://github.com/anssi-fr/mla

## Overview

##### Project type and purpose
- This is a multi‐crate Rust repository implementing a custom archive format (“Multi Layer Archive” or MLA).
- Core deliverables:
- mla: the Rust library (reader + writer + repair) implementing the layered archive format
- mlar: a command‐line tool built atop the mla library for create/list/extract/convert operations
- curve25519‐parser: a helper library for parsing Ed25519/X25519 keys in PEM/DER
- mla‑fuzz‑afl: an AFL‐based fuzzing harness for testing mla
- bindings/C and bindings/python: language bindings exposing mla to C/C++ and Python
- samples: test archives and key files
- .github: CI pipelines (build, test, bench, release)

##### File structure
- Top‐level crates (each with Cargo.toml): mla, mlar, curve25519‐parser, mla‑fuzz‑afl
- bindings/ subdirectories for C and Python wrappers
- samples/ for shipped artifacts to test backward compatibility
- .github/ for CI definitions (benchmarks, tests, releases)
- FORMAT.md and README.md describe the layered “pipeline” architecture of the archive format

##### Extract architecture insights from the README
- MLA is built as a chain of optional/mandatory “layers” (Raw → Compression → Encryption → Position → File storage)
- Each layer provides a Writer, Reader, and FailSafeReader for repairability
- ArchiveWriterConfig / ArchiveReaderConfig govern which layers are enabled
- Cryptographic services: AES‑GCM (RustCrypto), ECIES over Curve25519 (x25519‑dalek), random nonces (getrandom + ChaChaRng)
- Compression service: Brotli chunks via rust‑brotli
- File storage: chunked, interleaved, indexed blocks with SHA‑256 file hashes
- CLI (mlar) and language bindings consume the mla library’s public API

##### Main components and their interactions
A. MLA Core Library (crate: mla)
- Modules:
- config – defines ArchiveWriterConfig, ArchiveReaderConfig
- layers – submodules: raw, compress, encrypt, position, file storage (plus traits)
- crypto – aesgcm.rs, ecc.rs, hash.rs
- helpers – StreamWriter, linear_extract
- errors, tests, benches
B. CLI Tool (crate: mlar)
- Uses mla::{ArchiveWriter, ArchiveReader} + curve25519‑parser to perform user‐facing commands
- Exposes subcommands: keygen, create, list, extract, convert, keyderive
C. Curve25519 Parser (crate: curve25519-parser)
- Provides parse_openssl_25519_pubkey / privkey for key ingestion
- Dependency of mla and mlar
D. Fuzzer (crate: mla‑fuzz‑afl)
- Invokes mla’s API in randomized scenarios to test robustness + repair
E. Language Bindings (bindings/C and bindings/python)
- C: cbindgen → C header + C++ header, wraps mla functions via FFI
- Python: pyo3‐based binding crate → Python module exposing writer/reader
F. CI/Benchmarking/Fuzz pipelines (.github workflows)
- Build & test all crates, run Criterion benchmarks, release artifacts, run AFL fuzzing, publish Python/C packages

##### Architectural patterns & design principles
- Layered pipeline: each processing layer implements the same IO traits, enforces a strict order, and is repairable without footer data
- Modularity: separate crates for core format, CLI, parsing, fuzzing, language bindings
- Single‐source‐of‐truth: all logic lives in Rust; bindings and tools are thin layers
- Streaming & seekable design: enables interleaved writes and random access reads

##### Essential elements
- Annotation of optional vs mandatory layers

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% MLA Core Library
    subgraph "MLA Core Library" 
        direction TB
        config["config"]:::green
        subgraph "Layers" 
            direction TB
            raw["RawLayer"]:::green
            compress["CompressionLayer"]:::green
            encrypt["EncryptionLayer"]:::green
            position["PositionLayer"]:::green
            fileStorage["FileStorageLayer"]:::green
            traits["Layer Traits"]:::green
        end
        subgraph "Crypto" 
            direction TB
            aesgcm["AES-GCM"]:::yellow
            ecc["ECIES (x25519)"]:::yellow
            hash["SHA-256 Hash"]:::yellow
        end
        helpers["helpers"]:::green
        errors["errors"]:::green
        benches["bench_archive.rs"]:::green
        tests["tests"]:::green
    end

    %% CLI Tool
    mlar["CLI Tool (mlar)"]:::rustCrate
    main_rs["main.rs"]:::rustCrate

    %% Curve25519 Parser
    parser["Curve25519 Parser"]:::rustCrate
    parser_lib["lib.rs"]:::rustCrate

    %% Fuzzer Harness
    fuzzer["Fuzzer (mla-fuzz-afl)"]:::rustCrate
    fuzzer_main["main.rs"]:::rustCrate

    %% Language Bindings
    subgraph "Bindings/C" 
        direction TB
        cffi["C FFI crate"]:::orange
        header_c["mla.h"]:::orange
        header_cpp["mla.hpp"]:::orange
    end
    subgraph "Bindings/Python" 
        direction TB
        pyffi["PyO3 crate"]:::orange
        pyproject["pyproject.toml"]:::orange
        cargo_toml["Cargo.toml"]:::orange
    end

    %% CI Pipelines
    subgraph ".github Workflows" 
        direction TB
        test_yml["test.yml"]:::purple
        bench_yml["bench.yml"]:::purple
        mla_release["mla_release.yml"]:::purple
        mlar_release["mlar_release.yml"]:::purple
        py_bindings["py-bindings.yml"]:::purple
        sanitize["sanitize.yml"]:::purple
    end

    %% Samples & Docs
    samples["samples"]:::gray
    docs["FORMAT.md & README.md"]:::gray

    %% External Crates
    subgraph "External Dependencies"
        direction TB
        brotli["rust-brotli"]:::yellow
        rand["getrandom & ChaChaRng"]:::yellow
        criterion["Criterion.rs"]:::yellow
        afl["AFL.rs"]:::yellow
    end

    %% Relationships
    mlar -->|"uses ArchiveWriter/Reader"| config
    mlar -->|calls| raw
    mlar -->|calls| compress
    mlar -->|calls| encrypt
    mlar -->|calls| position
    mlar -->|calls| fileStorage

    raw -->|"optional pipeline"| compress
    compress -->|"optional pipeline"| encrypt
    encrypt -->|"mandatory pipeline"| position
    position -->|"mandatory pipeline"| fileStorage

    aesgcm --> encrypt
    ecc --> encrypt
    hash --> fileStorage
    brotli --> compress
    rand --> encrypt

    config --> raw
    config --> compress
    config --> encrypt
    config --> position
    config --> fileStorage

    parser --> parser_lib
    mlar --> parser_lib
    encrypt --> parser_lib

    fuzzer --> raw
    fuzzer --> encrypt
    fuzzer --> fileStorage

    cffi --> raw
    cffi --> encrypt
    pyffi --> raw
    pyffi --> encrypt

    bench_yml --> benches
    test_yml --> tests
    mla_release --> mlar
    mlar_release --> mlar
    py_bindings --> pyffi
    sanitize --> fuzzer

    samples --> fileStorage
    docs --> config

    %% Click events
    click config "https://github.com/anssi-fr/mla/blob/master/mla/src/config.rs"
    click raw "https://github.com/anssi-fr/mla/blob/master/mla/src/layers/raw.rs"
    click compress "https://github.com/anssi-fr/mla/blob/master/mla/src/layers/compress.rs"
    click encrypt "https://github.com/anssi-fr/mla/blob/master/mla/src/layers/encrypt.rs"
    click position "https://github.com/anssi-fr/mla/blob/master/mla/src/layers/position.rs"
    click traits "https://github.com/anssi-fr/mla/blob/master/mla/src/layers/traits.rs"
    click aesgcm "https://github.com/anssi-fr/mla/blob/master/mla/src/crypto/aesgcm.rs"
    click ecc "https://github.com/anssi-fr/mla/blob/master/mla/src/crypto/ecc.rs"
    click hash "https://github.com/anssi-fr/mla/blob/master/mla/src/crypto/hash.rs"
    click helpers "https://github.com/anssi-fr/mla/blob/master/mla/src/helpers.rs"
    click errors "https://github.com/anssi-fr/mla/blob/master/mla/src/errors.rs"
    click benches "https://github.com/anssi-fr/mla/blob/master/mla/benches/bench_archive.rs"
    click tests "https://github.com/anssi-fr/mla/tree/master/mla/tests/"
    click mlar "https://github.com/anssi-fr/mla/blob/master/mlar/src/main.rs"
    click parser_lib "https://github.com/anssi-fr/mla/blob/master/curve25519-parser/src/lib.rs"
    click fuzzer_main "https://github.com/anssi-fr/mla/blob/master/mla-fuzz-afl/src/main.rs"
    click cffi "https://github.com/anssi-fr/mla/blob/master/bindings/C/src/lib.rs"
    click header_c "https://github.com/anssi-fr/mla/blob/master/bindings/C/mla.h"
    click header_cpp "https://github.com/anssi-fr/mla/blob/master/bindings/C/mla.hpp"
    click pyffi "https://github.com/anssi-fr/mla/blob/master/bindings/python/src/lib.rs"
    click pyproject "https://github.com/anssi-fr/mla/blob/master/bindings/python/pyproject.toml"
    click cargo_toml "https://github.com/anssi-fr/mla/blob/master/bindings/python/Cargo.toml"
    click samples "https://github.com/anssi-fr/mla/tree/master/samples/"
    click docs "https://github.com/anssi-fr/mla/blob/master/FORMAT.md"
    click docs "https://github.com/anssi-fr/mla/blob/master/README.md"

    %% Styles
    classDef rustCrate fill:#cbe4ff,stroke:#333,stroke-width:1px
    classDef green fill:#e2f0d9,stroke:#333,stroke-width:1px
    classDef yellow fill:#fff2cc,stroke:#333,stroke-width:1px
    classDef orange fill:#ffd9b3,stroke:#333,stroke-width:1px
    classDef gray fill:#d9d9d9,stroke:#333,stroke-width:1px
    classDef purple fill:none,stroke:#8a2be2,stroke-dasharray: 5 5,stroke-width:2px,stroke:#8a2be2
```
