# lhns/fs2-compress architecture

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

- Interactive diagram: https://gitdiagram.com/lhns/fs2-compress
- Repository: https://github.com/lhns/fs2-compress

## Overview

##### Main Components
- Core Abstractions:
– A “core” module (found in the core/ directory) housing the central definitions and traits such as Compressor, Decompressor, ArchiveEntry, Archiver, and Unarchiver.
- Algorithm Plugins:
– Individual modules (directories such as gzip, brotli, bzip2, lz4, snappy, tar, zip, zip4j, zstd, and brotli4j) that implement the core typeclasses. Each of these folders contains their own source (src/main/scala/…) and test code.
- Integration with Fs2 and the Functional Ecosystem:
– The project is designed to work with the fs2 streaming library and Cats Effect (as seen in usage examples), so show dependencies on fs2, Cats Effect, and even external libraries such as zip4j when applicable.

##### Relationships and Interactions
- The Core module provides the contractual interfaces (e.g., Compressor.compress, Decompressor.decompress).
- Each algorithm module implements these interfaces – indicate “implements” or “adopts” relationships between the core abstractions and the concrete algorithm modules.
- How a typical pipeline would work: an input stream (from fs2's IO or Files API) flows into a Compressor’s pipe, then the processed (compressed) byte stream is passed downstream for storage or further handling.
- Similarly, for archiving: an entry flow is created by pairing ArchiveEntry objects with their corresponding file streams, then passing them through the Archiver pipe toward file writing.

##### Architectural Patterns and Design Principles
- Abstraction and Inversion of Control: The project uses typeclasses to abstract compression/archiving behavior so that the client’s code can be decoupled from concrete implementations.
- Modular and Extensible Design: Each algorithm is contained in its own module/directory, making it easy to add new implementations or swap out algorithms.
- Functional Composition: The library is designed to produce composable FS2 pipes that can be integrated seamlessly into larger streaming pipelines.
- Separation of Concerns: There’s a clear delineation between core common abstractions and specific algorithm functionalities.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client & Streaming Integration
    subgraph "Client & Streaming Integration"
        FI["File Input"]:::integration
        FS["Fs2 Stream / Cats Effect"]:::integration
    end

    %% Core Abstractions
    subgraph "Core Abstractions"
        CA["Compressor/Decompressor Interfaces"]:::core
        AA["ArchiveEntry, Archiver, Unarchiver Interfaces"]:::core
    end

    %% Algorithm Implementations - Compression
    subgraph "Algorithm Implementations - Compression"
        Gzip["Gzip Module"]:::plugin
        Bzip2["Bzip2 Module"]:::plugin
        Brotli["Brotli Module"]:::plugin
        Brotli4J["Brotli4J Module"]:::plugin
        Lz4["Lz4 Module"]:::plugin
        Snappy["Snappy Module"]:::plugin
        Zstd["Zstd Module"]:::plugin
    end

    %% Algorithm Implementations - Archiving
    subgraph "Algorithm Implementations - Archiving"
        Tar["Tar Module"]:::plugin
        Zip["Zip Module"]:::plugin
        Zip4J["Zip4J Module"]:::plugin
    end

    %% Output
    subgraph "Output"
        FO["File Output"]:::integration
    end

    %% External Libraries
    subgraph "External Libraries"
        ExtZip4J["Zip4J External Library"]:::external
        ExtBrotli4J["Brotli4J External Library"]:::external
    end

    %% Data Flow Connections
    FI -->|"streams"| FS
    FS -->|"calls"| CA
    FS -->|"calls"| AA

    %% Compression Pipeline
    CA -->|"implements"| Gzip
    CA -->|"implements"| Bzip2
    CA -->|"implements"| Brotli
    CA -->|"implements"| Brotli4J
    CA -->|"implements"| Lz4
    CA -->|"implements"| Snappy
    CA -->|"implements"| Zstd

    %% Archiving Pipeline
    AA -->|"implements"| Tar
    AA -->|"implements"| Zip
    AA -->|"implements"| Zip4J

    %% Output connections from modules
    Gzip -->|"outputs"| FO
    Bzip2 -->|"outputs"| FO
    Brotli -->|"outputs"| FO
    Brotli4J -->|"outputs"| FO
    Lz4 -->|"outputs"| FO
    Snappy -->|"outputs"| FO
    Zstd -->|"outputs"| FO
    Tar -->|"outputs"| FO
    Zip -->|"outputs"| FO
    Zip4J -->|"outputs"| FO

    %% External Library Dependencies
    Brotli4J -->|"delegatesTo"| ExtBrotli4J
    Zip4J -->|"delegatesTo"| ExtZip4J

    %% Click Events
    click CA "https://github.com/lhns/fs2-compress/tree/main/core/src/main/scala/de/lhns/fs2/compress"
    click Gzip "https://github.com/lhns/fs2-compress/blob/main/gzip/src/main/scala/de/lhns/fs2/compress/Gzip.scala"
    click Bzip2 "https://github.com/lhns/fs2-compress/blob/main/bzip2/src/main/scala/de/lhns/fs2/compress/Bzip2.scala"
    click Brotli "https://github.com/lhns/fs2-compress/blob/main/brotli/src/main/scala/de/lhns/fs2/compress/Brotli.scala"
    click Brotli4J "https://github.com/lhns/fs2-compress/blob/main/brotli4j/src/main/scala/de/lhns/fs2/compress/Brotli4J.scala"
    click Lz4 "https://github.com/lhns/fs2-compress/blob/main/lz4/src/main/scala/de/lhns/fs2/compress/Lz4Compressor.scala"
    click Snappy "https://github.com/lhns/fs2-compress/blob/main/snappy/src/main/scala/de/lhns/fs2/compress/SnappyCompressor.scala"
    click Tar "https://github.com/lhns/fs2-compress/blob/main/tar/src/main/scala/de/lhns/fs2/compress/Tar.scala"
    click Zip "https://github.com/lhns/fs2-compress/blob/main/zip/src/main/scala/de/lhns/fs2/compress/Zip.scala"
    click Zip4J "https://github.com/lhns/fs2-compress/blob/main/zip4j/src/main/scala/de/lhns/fs2/compress/Zip4J.scala"
    click Zstd "https://github.com/lhns/fs2-compress/blob/main/zstd/src/main/scala/de/lhns/fs2/compress/Zstd.scala"

    %% Styles
    classDef core fill:#ffcccc,stroke:#333,stroke-width:2px;
    classDef plugin fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef integration fill:#ffffcc,stroke:#333,stroke-width:2px;
    classDef external fill:#ccccff,stroke:#333,stroke-width:2px;
```
