# lvivona/safelz4 architecture

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

- Interactive diagram: https://gitdiagram.com/lvivona/safelz4
- Repository: https://github.com/lvivona/safelz4

## Overview

##### Project Type and Purpose
- This is an open-source library providing Python bindings to a Rust implementation of the LZ4 compression algorithm (lz4_flex).
- It exposes two main APIs: frame-based compression/decompression and block-based compression/decompression.

##### Top-Level Architecture Overview
- Python Layer (py/safelz4):
- Entry point ( __main__.py ) for CLI use.
- safelz4/__init__.py: exposes compress_file, open_frame, etc.
- safelz4/block.py and safelz4/frame.py: pure-Python wrappers around the Rust extension.
- Rust Core (src/*.rs):
- lib.rs: Rust library exposing block and frame APIs via FFI.
- block.rs, frame.rs, error.rs: implement core compression/decompression logic.
- Build & Packaging
- pyproject.toml & Cargo.toml: configure Python packaging (setuptools-rust) and Rust crate.
- makefile, GitHub workflows (.github/workflows/*.yml): CI for Python tests, Rust tests, releases.
- Tests & Quality
- tests/*.py: Python unit tests against the FFI extension.
- benches/: benchmarks using sample files.
- fuzz/: fuzz tests to validate error handling and round-trips.

##### Main Components
- A. Python Application Layer
- CLI module
- safelz4 Python package
- block API
- frame API
- B. Rust Extension Layer
- FFI boundary (C ABI).
- lz4_flex dependency (external Rust crate).
- C. Build & CI Infrastructure
- setuptools-rust binding generator
- Cargo build pipeline
- GitHub Actions workflows
- D. Test & Validation
- Unit tests (pytest)
- Benchmarks (bench harness)
- Fuzz tests (Python fuzz scripts invoking the FFI)

##### Relationships and Data Flow
- Data Flow A→B: Python calls into the compiled Rust extension via C-ABI (through the wheel/.so).
- lz4_flex: The Rust code imports and uses lz4_flex crate internally.
- Build Flow: pyproject.toml triggers setuptools-rust which invokes cargo to compile src/*.rs into a shared library.
- CI Flow: Code pushed → GitHub Actions → run rust tests, python tests, publish to PyPI.

##### Architectural Patterns and Principles
- FFI Bridge Pattern: decouples Python API from Rust implementation.
- Modular Design: distinct block vs. frame functionality, each in its own module.
- CI/CD Automation: workflows ensure cross-platform builds and releases.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Python Layer
    subgraph "Python Layer"
        CLI["__main__.py (CLI)"]:::python
        Init["__init__.py (Entry Point)"]:::python
        BlockPy["block.py (Block API)"]:::python
        FramePy["frame.py (Frame API)"]:::python
    end

    %% Rust Extension Layer
    subgraph "Rust Extension"
        RustLib["lib.rs (FFI Boundary)"]:::rust
        BlockRs["block.rs"]:::rust
        FrameRs["frame.rs"]:::rust
        ErrorRs["error.rs"]:::rust
    end

    %% External Dependency
    lz4Flex["lz4_flex Crate"]:::external

    %% Build & Packaging
    subgraph "Build & Packaging"
        setuptoolsRust["pyproject.toml (setuptools-rust)"]:::build
        cargo["Cargo.toml & Cargo.lock (Cargo Build)"]:::build
        Makefile["makefile"]:::build
        Wheel["Compiled .so /.pyd → Python Wheel"]:::build
    end

    %% CI/CD
    subgraph "CI/CD (GitHub Actions)"
        actionsPy["python.yml (Python & Rust CI)"]:::build
        actionsRelease["python-release.yml (Release Workflow)"]:::build
    end

    %% Tests & Validation
    subgraph "Tests & Validation"
        Pytest["Python Unit Tests (pytest)"]:::test
        Benches["Benchmarks (benches/)"]:::test
        Fuzz["Fuzz Tests (fuzz/)"]:::test
    end

    %% Data Flow
    BlockPy -->|"compress()/decompress() call"| RustLib
    FramePy -->|"compress()/decompress() call"| RustLib
    RustLib -->|"calls lz4_flex APIs"| lz4Flex

    %% Build Flow
    setuptoolsRust -->|"invokes cargo build"| cargo
    cargo -->|"produces shared library"| Wheel
    Wheel -->|"installable Python package"| CLI
    Wheel -->|"installable Python package"| Init

    %% CI Flow
    actionsPy -->|"runs tests & build"| setuptoolsRust
    actionsRelease -->|"publishes wheel to PyPI"| Wheel

    %% Tests Flow
    Pytest -->|"tests FFI extension"| RustLib
    Pytest -->|"tests Python wrappers"| BlockPy
    Pytest -->|"tests Python wrappers"| FramePy
    Benches -->|"bench harness"| RustLib
    Fuzz -->|"fuzz scripts"| RustLib

    %% Click Events
    click CLI "https://github.com/lvivona/safelz4/blob/main/py/safelz4/__main__.py"
    click Init "https://github.com/lvivona/safelz4/blob/main/py/safelz4/__init__.py"
    click BlockPy "https://github.com/lvivona/safelz4/blob/main/py/safelz4/block.py"
    click FramePy "https://github.com/lvivona/safelz4/blob/main/py/safelz4/frame.py"
    click RustLib "https://github.com/lvivona/safelz4/blob/main/src/lib.rs"
    click BlockRs "https://github.com/lvivona/safelz4/blob/main/src/block.rs"
    click FrameRs "https://github.com/lvivona/safelz4/blob/main/src/frame.rs"
    click ErrorRs "https://github.com/lvivona/safelz4/blob/main/src/error.rs"
    click lz4Flex "https://github.com/lvivona/safelz4/blob/main/Cargo.toml"
    click setuptoolsRust "https://github.com/lvivona/safelz4/blob/main/pyproject.toml"
    click cargo "https://github.com/lvivona/safelz4/blob/main/Cargo.toml"
    click Makefile "https://github.com/lvivona/safelz4/tree/main/makefile"
    click actionsPy "https://github.com/lvivona/safelz4/blob/main/.github/workflows/python.yml"
    click actionsRelease "https://github.com/lvivona/safelz4/blob/main/.github/workflows/python-release.yml"
    click Benches "https://github.com/lvivona/safelz4/tree/main/benches/"
    click Fuzz "https://github.com/lvivona/safelz4/blob/main/fuzz/fuzz_decomp_corrupt_block.py"

    %% Styles
    classDef python fill:#cce5ff,stroke:#66a3ff,color:#003366
    classDef rust fill:#d6f5d6,stroke:#42b342,color:#1a461d
    classDef external fill:#ffe6cc,stroke:#ff9933,color:#663d00
    classDef build fill:#e6e6e6,stroke:#999999,color:#333333
    classDef test fill:#f2ccff,stroke:#bf40bf,color:#330033
```
