# laktak/chkbit architecture

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

- Interactive diagram: https://gitdiagram.com/laktak/chkbit
- Repository: https://github.com/laktak/chkbit

## Overview

##### Project Type and Purpose
- chkbit is a Go-based CLI tool for detecting file corruption (via hashing & index checks), plus optional file deduplication and FUSE-backed index merging. It’s not a web app or microservice: it’s a local full-featured command-line utility with a core library and thin front-end.

##### Architectural Analysis of the File Structure
- cmd/chkbit: the single binary’s entrypoint implementing subcommands (e.g. check, dedup, fuse).
- Top-level .go files (common.go, context.go, fuse.go, hashfile.go, ignore.go, index*.go, worker.go, status.go): the core library providing scanning, hashing, indexing, dedup logic, FUSE integration, and task orchestration.
- cmd/chkbit/util & intutil: helper packages for progress bars, rate calculations, sparkline output, platform‐neutral size formatting, and OS abstractions (os_darwin.go, os_linux.go).
- scripts/: build, lint, test automation.
- Config/deployment: go.mod, CI workflows under .github.

##### Key Components
a. CLI Front-End
- Arg parser / command dispatcher
- Subcommands: check, dedup, fuse, update
b. Core Controller
- Orchestrates file traversal, hashing tasks, index store operations
- Manages context (via context.go) and status reporting
c. File System Scanner
- Walks directories, applies ignore rules (ignore.go)
- Dispatches file paths to worker pool
d. Worker Pool (worker.go)
- Concurrent hash calculators (hashfile.go)
- Reports results back via channels
e. Index Store
- Index creation and loading (index.go, indexstore.go)
- Supports “split” vs “atom” modes
f. Dedup Engine
- Identifies duplicate hashes, issues system calls to remove/copy files
g. FUSE Interface
- fuse.go implements merging index files into a single mountable view
h. Utilities
- Progress bars, rate calc, spinner, sparkline, sizing, language support

##### Relationships & Data Flow
- User invokes CLI → Parser → Controller
- Controller launches Scanner → Worker Pool
- Worker Pool → Hash Engine → Channels → Index Store
- Controller ↔ Index Store for read/write checks
- Dedup & Fuse subcommands hook into Controller & Index Store
- Utilities attached to Controller for status output
- OS-specific layers handle file I/O and FUSE bindings

##### Architectural Patterns & Principles
- Pipeline pattern: scanning → hashing → indexing
- Producer-consumer via Go channels for concurrency
- Layered structure: CLI layer, core logic layer, utility layer, OS-abstraction layer
- Separation of concerns: each package handles distinct responsibilities

##### Essential Elements Checklist
- Optionally, note CI/build scripts as a sidebar for tooling context

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "CLI Layer"
        CLI["CLI Front-End\n(arg parser & subcommands)"]:::cli
    end

    subgraph "Core Orchestration"
        Controller["Core Controller\n(context.go, common.go, status.go)"]:::core
    end

    subgraph "Processing Layer"
        Scanner["File System Scanner\n(ignore.go)"]:::processing
        WorkerPool["Worker Pool\n(worker.go)"]:::processing
        HashEngine["Hash Engine\n(hashfile.go)"]:::processing
    end

    subgraph "Storage Layer"
        IndexStore["Index Store\n(index.go, indexstore.go)"]:::storage
    end

    subgraph "Extensions"
        Dedup["Dedup Engine\ndedup.go"]:::core
        FUSE["FUSE Interface\nfuse.go"]:::core
    end

    subgraph "Utilities"
        Utilities["Utilities\n(progress, ratecalc, sparkline, fm, lang, spinner, strings)"]:::utilities
    end

    subgraph "OS Abstraction"
        OS["OS Abstraction\n(os.go, os_darwin.go, os_linux.go)"]:::os
    end

    subgraph "Build & CI"
        Tools["Build & CI Scripts\n(scripts/, .github/, go.mod, go.sum)"]:::tools
    end

    CLI -->|"invoke"| Controller
    Controller -->|"file path list"| Scanner
    Scanner -->|"file paths"| WorkerPool
    WorkerPool -->|"hash requests"| HashEngine
    HashEngine -->|"hash result"| IndexStore
    IndexStore -->|"ack/update"| Controller
    Controller -->|"dedup command"| Dedup
    Dedup -->|"file ops"| OS
    Controller -->|"fuse mount command"| FUSE
    FUSE -->|"FUSE bindings"| OS
    Controller -->|"status update"| Utilities

    %% Click Events
    click CLI "https://github.com/laktak/chkbit/blob/master/cmd/chkbit/main.go"
    click CLI "https://github.com/laktak/chkbit/blob/master/cmd/chkbit/help.go"
    click CLI "https://github.com/laktak/chkbit/blob/master/cmd/chkbit/dedup.go"
    click Controller "https://github.com/laktak/chkbit/blob/master/context.go"
    click Controller "https://github.com/laktak/chkbit/blob/master/common.go"
    click Controller "https://github.com/laktak/chkbit/blob/master/status.go"
    click Scanner "https://github.com/laktak/chkbit/blob/master/ignore.go"
    click Scanner "https://github.com/laktak/chkbit/blob/master/ignore_test.go"
    click WorkerPool "https://github.com/laktak/chkbit/blob/master/worker.go"
    click HashEngine "https://github.com/laktak/chkbit/blob/master/hashfile.go"
    click IndexStore "https://github.com/laktak/chkbit/blob/master/index.go"
    click IndexStore "https://github.com/laktak/chkbit/blob/master/indexstore.go"
    click Dedup "https://github.com/laktak/chkbit/blob/master/dedup.go"
    click FUSE "https://github.com/laktak/chkbit/blob/master/fuse.go"
    click Utilities "https://github.com/laktak/chkbit/blob/master/cmd/chkbit/util/fm.go"
    click Utilities "https://github.com/laktak/chkbit/blob/master/cmd/chkbit/util/lang.go"
    click Utilities "https://github.com/laktak/chkbit/blob/master/cmd/chkbit/util/progress.go"
    click Utilities "https://github.com/laktak/chkbit/blob/master/cmd/chkbit/util/ratecalc.go"
    click Utilities "https://github.com/laktak/chkbit/blob/master/cmd/chkbit/util/sparkline.go"
    click Utilities "https://github.com/laktak/chkbit/blob/master/cmd/chkbit/util/spinner.go"
    click Utilities "https://github.com/laktak/chkbit/blob/master/cmd/chkbit/util/strings.go"
    click OS "https://github.com/laktak/chkbit/blob/master/os.go"
    click OS "https://github.com/laktak/chkbit/blob/master/os_darwin.go"
    click OS "https://github.com/laktak/chkbit/blob/master/os_linux.go"
    click Tools "https://github.com/laktak/chkbit/tree/master/scripts/"
    click Tools "https://github.com/laktak/chkbit/blob/master/.github/workflows/ci.yml"
    click Tools "https://github.com/laktak/chkbit/blob/master/.github/workflows/release.yml"
    click Tools "https://github.com/laktak/chkbit/blob/master/go.mod"
    click Tools "https://github.com/laktak/chkbit/blob/master/go.sum"

    %% Styles
    classDef cli fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef core fill:#87CEFA,stroke:#333,stroke-width:1px
    classDef processing fill:#98FB98,stroke:#333,stroke-width:1px
    classDef storage fill:#FFA500,stroke:#333,stroke-width:1px
    classDef utilities fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef os fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef tools fill:#F5F5F5,stroke:#333,stroke-width:1px
```
