# jimzical/file-integrity-manager architecture

> Architecture diagram of the GitHub repository jimzical/file-integrity-manager, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jimzical/file-integrity-manager
- Repository: https://github.com/jimzical/file-integrity-manager

## Overview

1. **What this repository is**
   - This is a **local Go CLI application** for file integrity verification.
   - Its core job is to **walk a directory tree, hash files, persist hashes in a local database, then compare future scans against those stored hashes** to detect changes.

2. **Top-level flow**
   - The executable starts in `cmd/main.go`.
   - From there, the app appears to pass control into a **UI/interaction layer** that collects user input, then into the **file manager orchestration layer** that performs scanning, hashing, and comparison.

3. **Presentation boundary**
   - `ui/` and `pkg/basics/` contain the user-facing console layer: prompts, startup screen, styled output, and basic print/input helpers.
   - This is the boundary between the user and the integrity engine; it does not appear to contain business logic.

4. **Core orchestration**
   - `core/fileManager/fileManager.go` is the central coordination point.
   - It likely ties together:
     - folder traversal,
     - per-file hash generation,
     - DB reads/writes,
     - integrity comparison,
     - and result reporting.
   - This is the main subsystem an architecture diagram should place in the center.

5. **Directory traversal and hashing**
   - `core/fileManager/traverseFolder.go` handles recursive discovery of files in nested directories.
   - `core/fileManager/hashString.go` and `checkFileHash.go` suggest two distinct responsibilities:
     - generating a hash for file contents,
     - checking whether the current hash matches the stored value.
   - The README explicitly says the app uses **goroutines**, so file processing is likely concurrent and parallelized within this subsystem.

6. **Persistence layer**
   - The app uses **BadgerDB** as its local key-value store.
   - `pkg/badgerDB/bdgr.go` looks like the database wrapper/adapter.
   - `core/fileManager/db.go` likely contains file-manager-specific DB operations, such as storing and retrieving hashes by file path or similar key.
   - This is a local persistence boundary: no remote service or network dependency is indicated.

7. **Domain model**
   - `core/models/structs.go` defines the data structures shared across layers.
   - These likely represent file metadata, hash results, scan outcomes, and maybe user/session configuration.
   - In a diagram, this is the shared contract between traversal, hashing, storage, and reporting.

8. **Status and logging**
   - `core/status/status.go` and `core/logs/` provide outcome tracking and human-readable results.
   - `core/logs/constants.go` and `logResults.go` suggest standardized output categories/messages, likely used to report unchanged, modified, or failed files.
   - This layer is important because the CLI’s value is in communicating integrity results clearly.

9. **Configuration and initialization**
   - `configs/configuration.go` likely holds runtime settings or constants such as paths, defaults, or app configuration.
   - This package sits near startup and influences how the CLI initializes its scan and database behavior.

10. **Repository structure as layers**
   - The repo cleanly separates:
     - `cmd/` for process entry,
     - `ui/` and `pkg/basics/` for console interaction,
     - `core/` for business logic,
     - `pkg/badgerDB/` for infrastructure persistence,
     - `configs/` for configuration.
   - That layering is the most important architectural shape in the project.

11. **Test corpus**
   - `tests/` contains nested folders and mixed file types, which act as a realistic fixture set for recursive traversal.
   - The structure is useful for validating depth-first scanning, file-type agnosticism, and comparison across directory hierarchies.

12. **Operational characteristics**
   - The app is fully local, CPU/filesystem-bound, and optimized for concurrency.
   - Its main data flow is: **user selects target directory → scanner walks files → hashes are computed concurrently → hashes are stored in BadgerDB → later scans compare current vs stored hashes → UI reports changes**.

Main entry points: [`core/fileManager/fileManager.go`](https://github.com/jimzical/file-integrity-manager/blob/main/core/fileManager/fileManager.go) (File manager), [`ui/print.go`](https://github.com/jimzical/file-integrity-manager/blob/main/ui/print.go) (Print), [`ui/startScreen.go`](https://github.com/jimzical/file-integrity-manager/blob/main/ui/startScreen.go) (Start screen), [`ui/intput.go`](https://github.com/jimzical/file-integrity-manager/blob/main/ui/intput.go) (Input)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry"]
  node_cmd_main["main<br/>cli entry<br/>[main.go]"]
end

subgraph group_presentation["Console UI"]
  node_ui_start["Start screen<br/>ui screen<br/>[startScreen.go]"]
  node_ui_input["Input<br/>ui prompt<br/>[intput.go]"]
  node_ui_print["Print<br/>ui output<br/>[print.go]"]
  node_ui_style["Style<br/>ui format<br/>[style.go]"]
  node_basics_input["Basics input<br/>console helper<br/>[input.go]"]
  node_basics_prints["Basics prints<br/>console helper<br/>[prints.go]"]
end

subgraph group_core["Core Engine"]
  node_file_manager["File manager<br/>orchestrator<br/>[fileManager.go]"]
  node_traverse_folder["Traverse folder<br/>scanner<br/>[traverseFolder.go]"]
  node_hash_string["Hashing<br/>hash engine<br/>[hashString.go]"]
  node_check_file_hash["Compare hash<br/>integrity check<br/>[checkFileHash.go]"]
end

subgraph group_persistence["Persistence"]
  node_fm_db[("File DB ops<br/>storage adapter<br/>[db.go]")]
  node_badger_db[("BadgerDB<br/>kv store adapter<br/>[bdgr.go]")]
end

subgraph group_shared["Shared Types"]
  node_models["Models<br/>domain model<br/>[structs.go]"]
  node_status["Status<br/>result state<br/>[status.go]"]
  node_logs_consts["Log constants<br/>log vocab<br/>[constants.go]"]
  node_logs_results["Log results<br/>reporting<br/>[logResults.go]"]
end

subgraph group_config["Configuration"]
  node_config["Config<br/>settings<br/>[configuration.go]"]
end

subgraph group_fixtures["Test Corpus"]
  node_tests["Test files<br/>fixture corpus"]
end

node_cmd_main -->|"launches"| node_ui_start
node_ui_start -->|"collects"| node_ui_input
node_ui_input -->|"uses"| node_basics_input
node_ui_start -->|"renders"| node_ui_print
node_ui_print -->|"delegates"| node_basics_prints
node_ui_print -->|"formats"| node_ui_style
node_ui_input -->|"passes target"| node_file_manager
node_file_manager -->|"reads"| node_config
node_file_manager -->|"scans"| node_traverse_folder
node_traverse_folder -.->|"validated by"| node_tests
node_file_manager -->|"hashes"| node_hash_string
node_file_manager -->|"compares"| node_check_file_hash
node_file_manager -->|"stores"| node_fm_db
node_fm_db -->|"backed by"| node_badger_db
node_file_manager -->|"uses"| node_models
node_file_manager -->|"sets"| node_status
node_file_manager -->|"reports"| node_logs_results
node_logs_results -->|"uses"| node_logs_consts
node_logs_results -->|"prints"| node_ui_print

click node_cmd_main "https://github.com/jimzical/file-integrity-manager/blob/main/cmd/main.go"
click node_ui_start "https://github.com/jimzical/file-integrity-manager/blob/main/ui/startScreen.go"
click node_ui_input "https://github.com/jimzical/file-integrity-manager/blob/main/ui/intput.go"
click node_ui_print "https://github.com/jimzical/file-integrity-manager/blob/main/ui/print.go"
click node_ui_style "https://github.com/jimzical/file-integrity-manager/blob/main/ui/style.go"
click node_basics_input "https://github.com/jimzical/file-integrity-manager/blob/main/pkg/basics/input.go"
click node_basics_prints "https://github.com/jimzical/file-integrity-manager/blob/main/pkg/basics/prints.go"
click node_file_manager "https://github.com/jimzical/file-integrity-manager/blob/main/core/fileManager/fileManager.go"
click node_traverse_folder "https://github.com/jimzical/file-integrity-manager/blob/main/core/fileManager/traverseFolder.go"
click node_hash_string "https://github.com/jimzical/file-integrity-manager/blob/main/core/fileManager/hashString.go"
click node_check_file_hash "https://github.com/jimzical/file-integrity-manager/blob/main/core/fileManager/checkFileHash.go"
click node_fm_db "https://github.com/jimzical/file-integrity-manager/blob/main/core/fileManager/db.go"
click node_badger_db "https://github.com/jimzical/file-integrity-manager/blob/main/pkg/badgerDB/bdgr.go"
click node_models "https://github.com/jimzical/file-integrity-manager/blob/main/core/models/structs.go"
click node_status "https://github.com/jimzical/file-integrity-manager/blob/main/core/status/status.go"
click node_logs_consts "https://github.com/jimzical/file-integrity-manager/blob/main/core/logs/constants.go"
click node_logs_results "https://github.com/jimzical/file-integrity-manager/blob/main/core/logs/logResults.go"
click node_config "https://github.com/jimzical/file-integrity-manager/blob/main/configs/configuration.go"
click node_tests "https://github.com/jimzical/file-integrity-manager/tree/main/tests"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cmd_main,node_tests toneBlue
class node_ui_start,node_ui_input,node_ui_print,node_ui_style,node_basics_input,node_basics_prints toneAmber
class node_file_manager,node_traverse_folder,node_hash_string,node_check_file_hash toneMint
class node_fm_db,node_badger_db toneRose
class node_models,node_status,node_logs_consts,node_logs_results toneIndigo
class node_config toneTeal
```

## Components

### Entry

Process startup and CLI handoff

- [main](https://github.com/jimzical/file-integrity-manager/blob/main/cmd/main.go): cli entry · Starts the application and hands off to the UI/flow layer · `cmd/main.go`

### Console UI

User prompts, screens, and formatted output

- [Start screen](https://github.com/jimzical/file-integrity-manager/blob/main/ui/startScreen.go): ui screen · Initial console screen and user-facing startup experience · `ui/startScreen.go`
- [Input](https://github.com/jimzical/file-integrity-manager/blob/main/ui/intput.go): ui prompt · Collects target paths and user choices from the console · `ui/intput.go`
- [Print](https://github.com/jimzical/file-integrity-manager/blob/main/ui/print.go): ui output · Console printing helpers for interactive messaging · `ui/print.go`
- [Style](https://github.com/jimzical/file-integrity-manager/blob/main/ui/style.go): ui format · Text styling and presentation formatting helpers · `ui/style.go`
- [Basics input](https://github.com/jimzical/file-integrity-manager/blob/main/pkg/basics/input.go): console helper · Low-level input helpers shared by the UI layer · `pkg/basics/input.go`
- [Basics prints](https://github.com/jimzical/file-integrity-manager/blob/main/pkg/basics/prints.go): console helper · Low-level printing helpers shared by the UI layer · `pkg/basics/prints.go`

### Core Engine

Directory scanning, hashing, comparison, and reporting

- [File manager](https://github.com/jimzical/file-integrity-manager/blob/main/core/fileManager/fileManager.go): orchestrator · Coordinates traversal, hashing, storage, comparison, and reporting · `core/fileManager/fileManager.go`
- [Traverse folder](https://github.com/jimzical/file-integrity-manager/blob/main/core/fileManager/traverseFolder.go): scanner · Recursively discovers files in nested directories · `core/fileManager/traverseFolder.go`
- [Hashing](https://github.com/jimzical/file-integrity-manager/blob/main/core/fileManager/hashString.go): hash engine · Generates content hashes for scanned files · `core/fileManager/hashString.go`
- [Compare hash](https://github.com/jimzical/file-integrity-manager/blob/main/core/fileManager/checkFileHash.go): integrity check · Checks current hashes against stored values · `core/fileManager/checkFileHash.go`

### Persistence

Local database adapter and file-manager storage access

- [File DB ops](https://github.com/jimzical/file-integrity-manager/blob/main/core/fileManager/db.go): storage adapter · File-manager-specific persistence reads and writes for hashes · `core/fileManager/db.go`
- [BadgerDB](https://github.com/jimzical/file-integrity-manager/blob/main/pkg/badgerDB/bdgr.go): kv store adapter · Wraps the local BadgerDB key-value database · `pkg/badgerDB/bdgr.go`

### Shared Types

Common models, status, and log vocabulary

- [Models](https://github.com/jimzical/file-integrity-manager/blob/main/core/models/structs.go): domain model · Shared structs for files, hashes, and scan results · `core/models/structs.go`
- [Status](https://github.com/jimzical/file-integrity-manager/blob/main/core/status/status.go): result state · Outcome states used to classify scan and integrity results · `core/status/status.go`
- [Log constants](https://github.com/jimzical/file-integrity-manager/blob/main/core/logs/constants.go): log vocab · Standardized result labels and message constants · `core/logs/constants.go`
- [Log results](https://github.com/jimzical/file-integrity-manager/blob/main/core/logs/logResults.go): reporting · Formats human-readable integrity results for output · `core/logs/logResults.go`

### Configuration

Runtime settings and defaults

- [Config](https://github.com/jimzical/file-integrity-manager/blob/main/configs/configuration.go): settings · Runtime configuration and startup defaults · `configs/configuration.go`

### Test Corpus

Nested sample files used to exercise traversal

- [Test files](https://github.com/jimzical/file-integrity-manager/tree/main/tests): fixture corpus · Nested sample tree used to validate recursive scanning · `tests`

## Connections

- main → Start screen: launches · Main hands control to the interactive startup flow
- Start screen → Input: collects · Startup screen leads into prompt collection
- Input → Basics input: uses · UI input delegates to shared console input helpers
- Start screen → Print: renders · Startup flow prints messages to the console
- Print → Basics prints: delegates · Presentation output uses shared printing helpers
- Print → Style: formats · Output is styled before being displayed
- Input → File manager: passes target · Selected directory and choices are handed to the core engine
- File manager → Config: reads · Core flow uses configuration and defaults
- File manager → Traverse folder: scans · Orchestrator requests recursive file discovery
- Traverse folder → Test files: validated by · Fixture tree exercises traversal across nested folders
- File manager → Hashing: hashes · Orchestrator computes per-file content hashes
- File manager → Compare hash: compares · Orchestrator checks current hashes against stored values
- File manager → File DB ops: stores · Hash records are persisted and retrieved through file-manager DB operations
- File DB ops → BadgerDB: backed by · Local persistence is implemented on top of BadgerDB
- File manager → Models: uses · Scan and hash data are exchanged via shared structs
- File manager → Status: sets · Integrity outcomes are classified with shared status values
- File manager → Log results: reports · Final scan results are formatted for human output
- Log results → Log constants: uses · Reporting relies on standardized log labels
- Log results → Print: prints · Reported results flow back to the console layer
