# frozsgy/file-juggler architecture

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

- Interactive diagram: https://gitdiagram.com/frozsgy/file-juggler
- Repository: https://github.com/frozsgy/file-juggler

## Overview

##### Project type and purpose
- File Juggler is a small open-source, command-line file-scrambling tool written in C. It provides two executables—`juggler` to “juggle” (scramble and chain‐link) files, and `dejuggler` to reverse the process. There is no server or network component—everything runs locally against the filesystem.

##### File structure
- Top-level:
- makefile – build orchestration
- src/ – all C source and headers
- LICENSE, README.md, .gitignore
- Inside src/:
- juggle.c & dejuggle.c – two `main()` entry points
- file.c / file.h – filesystem I/O abstraction
- utils.c / utils.h – common helpers (e.g., argument parsing, error handling)
- dejuggle.c & juggle.c use shared definitions in def.h and block layout in blocks.h

##### Insights from the README
- Describes two binaries (`juggler`, `dejuggler`), usage patterns, block-based linked structure with bit inversion.
- Emphasizes block size parameter, chaining via an unsigned‐int “next block” pointer.

##### Main components
a. User CLI Layer
- Juggler CLI (juggler)
- Dejuggler CLI (dejuggler)
b. Core Library Layer (shared modules)
- FileManager module (file.c / file.h)
- BlockChain module (blocks.h + logic in juggle.c & dejuggle.c)
- BitInversionService (inversion routines – utils.c)
- Configuration & Definitions (def.h)
c. External/System Resources
- Local File System (reads original file, writes jgg/dej files)
- Build System (makefile → invokes gcc to produce both binaries)

##### Relationships and data flows
- User invokes one of the CLIs → that executable initializes parameters (block size, file paths) using Utils.
- CLI calls FileManager to open source & target files.
- Juggler: reads a block → inverts bits → writes block header (next-pointer placeholder) + data → writes to target → updates chain pointer.
- Dejuggler: reads initial block ID → follows chain via BlockChain logic → inverts bits back → writes to output.
- All modules link together at compile time, producing two standalone binaries.

##### Architectural patterns & principles
- Modular C design: separation of concerns between I/O (file.c) and processing logic (juggle.c, utils.c).
- Single‐process, single‐threaded pipeline.
- Explicit dependency injection via function calls—no global state beyond file descriptors.

##### Detail
- At least these discrete components:
- juggle.c main, dejuggle.c main
- file.c/h (I/O abstraction)
- utils.c/h (arg parsing, error)
- blocks.h + def.h (data structures)
- Interactions (parameter passing, file handles) to illustrate full end-to-end flow.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Resources
    subgraph "Build & Docs"
        BuildSystem["Makefile\n(Build System)"]:::external
        Readme["README.md"]:::external
    end

    %% User CLI Layer
    subgraph "User CLI Layer"
        Juggler["juggler\n(src/juggle.c)"]:::entry
        Dejuggler["dejuggler\n(src/dejuggle.c)"]:::entry
    end

    %% Core Library Layer
    subgraph "Core Library Layer"
        FileManager["FileManager\n(src/file.c/h)"]:::core
        BitInversion["BitInversionService\n(src/utils.c/h)"]:::core
        BlockChain["BlockChain Module\n(src/blocks.h)"]:::core
        Config["Config & Definitions\n(src/def.h)"]:::core
    end

    %% External System
    LocalFS[(Local File System)]:::external_db

    %% Connections
    BuildSystem --> Juggler
    BuildSystem --> Dejuggler
    Readme --- BuildSystem

    Juggler -->|"initialize params"| BitInversion
    Juggler -->|"open files"| FileManager
    Juggler -->|"process blocks"| BlockChain

    Dejuggler -->|"initialize params"| BitInversion
    Dejuggler -->|"open files"| FileManager
    Dejuggler -->|"process chain"| BlockChain

    FileManager -->|"read/write"| LocalFS
    BlockChain -->|"read/write blocks"| LocalFS

    BitInversion -->|"uses constants"| Config
    BlockChain -->|"uses structure\n[uint32 nextPtr|data]"| Config

    %% Click Events
    click Juggler "https://github.com/frozsgy/file-juggler/blob/master/src/juggle.c"
    click Dejuggler "https://github.com/frozsgy/file-juggler/blob/master/src/dejuggle.c"
    click FileManager "https://github.com/frozsgy/file-juggler/blob/master/src/file.c"
    click BitInversion "https://github.com/frozsgy/file-juggler/blob/master/src/utils.c"
    click BlockChain "https://github.com/frozsgy/file-juggler/blob/master/src/blocks.h"
    click Config "https://github.com/frozsgy/file-juggler/blob/master/src/def.h"
    click BuildSystem "https://github.com/frozsgy/file-juggler/tree/master/makefile"
    click Readme "https://github.com/frozsgy/file-juggler/blob/master/README.md"

    %% Styles
    classDef entry fill:#9f6,stroke:#333,stroke-width:1px;
    classDef core fill:#6cf,stroke:#333,stroke-width:1px;
    classDef external fill:#ddd,stroke:#333,stroke-width:1px;
    classDef external_db fill:#bbb,stroke:#333,stroke-width:1px;
```
