# ekoppenhagen/zip-utils architecture

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

- Interactive diagram: https://gitdiagram.com/ekoppenhagen/zip-utils
- Repository: https://github.com/ekoppenhagen/zip-utils

## Overview

##### Project type and purpose
- This is an open-source JVM library (“zip-utils”) written in Kotlin/Java.
- It provides three core operations on ZIP archives:
- Zipping (compressing files or byte arrays)
- Unzipping (extracting) – marked “TBD” in README
- Comparing two ZIP files or byte arrays for equality
- It has no third-party dependencies and relies on the JDK’s native ZIP APIs.

##### File structure
Top-level folders and files:
- build.gradle.kts, settings.gradle.kts, gradle/… (Gradle build & wrapper)
- config/detekt.yml (static analysis)
- src/main/kotlin/io/github/ekoppenhagen/ziputils/… (production code)
- src/test/kotlin/io/github/ekoppenhagen/ziputils/… (unit tests)
- src/test/resources (sample ZIPs & directories)
Inside the production code area:
- Zip.kt – main entry point for zipping/unzipping
- CompareZip.kt – entry point for comparing archives
- exceptions/ – custom exception types for failure scenarios

##### Key insights from the README
- There is no external service or database—everything is file-system or in-memory (byte arrays).
- The library is designed to be dropped into any Kotlin/Java project via Maven/Gradle.
- It exposes a simple static-method API (Zip.file, Zip.byteArray, CompareZip.files, CompareZip.byteArrays).

##### Details to capture
- The stateless nature of the API and the fact that no persistent storage is used beyond the filesystem.
- The separate code paths for file-based vs byte-array-based operations.
- The error-handling flow when a comparison fails or a target file already exists.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    ClientModule["Client Module\n(Dependent JVM App)"]:::external

    %% API Facades
    ZipFacade["Zip (Facade)\n.compress()/uncompress()"]:::api
    CompareZipFacade["CompareZip (Facade)\n.compare()"]:::api

    %% Domain Logic
    subgraph "Core Domain Logic"
        direction TB
        ArchiveTraversal["Archive Traversal"]:::domain
        EntryComparison["Entry Comparison"]:::domain
    end

    %% JDK ZIP Engine
    subgraph "JDK ZIP Engine"
        direction TB
        ZipInputStream["ZipInputStream"]:::external
        ZipOutputStream["ZipOutputStream"]:::external
    end

    %% External Systems
    FileSystem["File System"]:::external
    MemoryBuffer["In-Memory Buffers"]:::external

    %% Exceptions
    TargetAlreadyExistsException["TargetAlreadyExistsException"]:::exception
    ZipComparisonException["ZipComparisonException"]:::exception

    %% Client to API
    ClientModule -->|calls| ZipFacade
    ClientModule -->|calls| CompareZipFacade

    %% Zip Facade flows
    ZipFacade -->|invokes| ZipOutputStream
    ZipFacade -->|invokes| ZipInputStream
    ZipOutputStream -->|writes to| FileSystem
    ZipOutputStream -->|writes to| MemoryBuffer
    ZipInputStream -->|reads from| FileSystem
    ZipInputStream -->|reads from| MemoryBuffer
    ZipFacade -->|throws| TargetAlreadyExistsException
    TargetAlreadyExistsException -->|propagates| ClientModule

    %% CompareZip Facade flows
    CompareZipFacade -->|uses| ZipInputStream
    CompareZipFacade -->|coordinates| ArchiveTraversal
    ArchiveTraversal -->|uses| ZipInputStream
    ArchiveTraversal -->|provides entries| EntryComparison
    EntryComparison -->|compares entries| ArchiveTraversal
    CompareZipFacade -->|throws| ZipComparisonException
    ZipComparisonException -->|propagates| ClientModule

    %% Tests
    subgraph "Tests"
        direction TB
        ZipTest["ZipTest"]:::test
        CompareTest["CompareTest"]:::test
        AbstractTests["AbstractZipUtilsTest"]:::test
        Resources["Test Resources"]:::external
    end

    ZipTest -->|tests| ZipFacade
    CompareTest -->|tests| CompareZipFacade
    ZipTest --> AbstractTests
    CompareTest --> AbstractTests
    ZipTest --> Resources
    CompareTest --> Resources

    %% Click Events
    click ZipFacade "https://github.com/ekoppenhagen/zip-utils/blob/main/src/main/kotlin/io/github/ekoppenhagen/ziputils/Zip.kt"
    click CompareZipFacade "https://github.com/ekoppenhagen/zip-utils/blob/main/src/main/kotlin/io/github/ekoppenhagen/ziputils/CompareZip.kt"
    click TargetAlreadyExistsException "https://github.com/ekoppenhagen/zip-utils/blob/main/src/main/kotlin/io/github/ekoppenhagen/ziputils/exceptions/TargetAlreadyExistsException.kt"
    click ZipComparisonException "https://github.com/ekoppenhagen/zip-utils/blob/main/src/main/kotlin/io/github/ekoppenhagen/ziputils/exceptions/ZipComparisonException.kt"
    click ZipTest "https://github.com/ekoppenhagen/zip-utils/blob/main/src/test/kotlin/io/github/ekoppenhagen/ziputils/ZipTest.kt"
    click CompareTest "https://github.com/ekoppenhagen/zip-utils/blob/main/src/test/kotlin/io/github/ekoppenhagen/ziputils/CompareTest.kt"
    click AbstractTests "https://github.com/ekoppenhagen/zip-utils/blob/main/src/test/kotlin/io/github/ekoppenhagen/ziputils/AbstractZipUtilsTest.kt"
    click Resources "https://github.com/ekoppenhagen/zip-utils/tree/main/src/test/resources"

    %% Styles
    classDef api fill:#a6d8ff,stroke:#000,stroke-width:1px
    classDef domain fill:#b7e4c7,stroke:#000,stroke-width:1px
    classDef external fill:#e0e0e0,stroke:#000,stroke-width:1px
    classDef exception fill:#ffcccc,stroke:#900,stroke-width:1px
    classDef test fill:#fff2cc,stroke:#000,stroke-width:1px
```
