# kuankuan2007/do-folder architecture

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

- Interactive diagram: https://gitdiagram.com/kuankuan2007/do-folder
- Repository: https://github.com/kuankuan2007/do-folder

## Overview

doFolder is a Python filesystem-management library with a CLI for comparison, synchronization, and hashing. The main user workflow is to select paths, wrap them as file or directory objects, then inspect differences or calculate hashes; comparison can also apply a sync plan. The graph includes filesystem operations, hash caching/calculation, and CLI dispatch. Some feature links come from README documentation because their implementation was not sampled; uncertain wiring is omitted.

Main entry points: [`src/doFolder/cli/compare.py`](https://github.com/kuankuan2007/do-folder/blob/main/src/doFolder/cli/compare.py) (Compare and Sync CLI), [`src/doFolder/cli/hash.py`](https://github.com/kuankuan2007/do-folder/blob/main/src/doFolder/cli/hash.py) (Hash CLI), [`src/doFolder/fileSystem/tools.py`](https://github.com/kuankuan2007/do-folder/blob/main/src/doFolder/fileSystem/tools.py) (Item Factory), [`src/doFolder/scripts.py`](https://github.com/kuankuan2007/do-folder/blob/main/src/doFolder/scripts.py) (CLI Entrypoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Python Filesystem API"]
  node_public_api["Package API<br/>[__init__.py]"]
  node_item_classes["File and Directory<br/>[classes.py]"]
  node_item_factory["Item Factory<br/>[tools.py]"]
end

subgraph group_compare["Comparison and Sync"]
  node_compare_engine["Compare Engine<br/>[compare.py]"]
  node_sync_cli["Compare and Sync CLI<br/>[compare.py]"]
end

subgraph group_hash["Hashing"]
  node_hash_calculator["Hash Calculators<br/>[calculator.py]"]
  node_hash_calculation["Hash Calculation<br/>[calculate.py]"]
  node_hash_cache[("Hash Cache<br/>[cache.py]")]
  node_hash_executor["Hash Executor<br/>[executor.py]"]
end

subgraph group_cli["Command Line"]
  node_hash_cli["Hash CLI<br/>[hash.py]"]
  node_cli_dispatch["Unified CLI<br/>[main.py]"]
  node_cli_scripts["CLI Entrypoints<br/>[scripts.py]"]
  node_module_entry["Module Entrypoint<br/>[__main__.py]"]
end

node_developer(("Developer"))
node_terminal(("CLI User"))
node_filesystem["Local Filesystem"]

node_developer -->|"uses objects"| node_public_api
node_public_api -->|"exposes"| node_item_classes
node_item_classes -->|"creates items"| node_item_factory
node_item_factory -->|"inspects paths"| node_filesystem
node_item_classes -->|"reads and modifies"| node_filesystem
node_developer -->|"compares paths"| node_compare_engine
node_compare_engine -->|"wraps paths"| node_item_factory
node_compare_engine -->|"reads item data"| node_filesystem
node_terminal -->|"runs commands"| node_cli_scripts
node_cli_scripts -->|"dispatches unified"| node_cli_dispatch
node_cli_scripts -->|"runs compare"| node_sync_cli
node_cli_scripts -->|"runs hash"| node_hash_cli
node_module_entry -->|"starts CLI"| node_cli_dispatch
node_cli_dispatch -->|"dispatches compare"| node_sync_cli
node_cli_dispatch -->|"dispatches hash"| node_hash_cli
node_sync_cli -->|"finds differences"| node_compare_engine
node_sync_cli -->|"wraps sync paths"| node_item_factory
node_sync_cli -->|"copies sync items"| node_filesystem
node_hash_cli -->|"wraps input paths"| node_item_factory
node_hash_cli -->|"requests hashes"| node_hash_calculator
node_hash_calculator -->|"checks and stores"| node_hash_cache
node_hash_calculator -->|"calculates misses"| node_hash_calculation
node_hash_calculation -->|"reads file content"| node_filesystem
node_hash_cli -.->|"uses threaded hashing"| node_hash_executor
node_hash_executor -.->|"submits calculations"| node_hash_calculator

click node_public_api "https://github.com/kuankuan2007/do-folder/blob/main/src/doFolder/__init__.py"
click node_item_classes "https://github.com/kuankuan2007/do-folder/blob/main/src/doFolder/fileSystem/classes.py"
click node_item_factory "https://github.com/kuankuan2007/do-folder/blob/main/src/doFolder/fileSystem/tools.py"
click node_compare_engine "https://github.com/kuankuan2007/do-folder/blob/main/src/doFolder/compare.py"
click node_sync_cli "https://github.com/kuankuan2007/do-folder/blob/main/src/doFolder/cli/compare.py"
click node_hash_calculator "https://github.com/kuankuan2007/do-folder/blob/main/src/doFolder/hashing/calculator.py"
click node_hash_calculation "https://github.com/kuankuan2007/do-folder/blob/main/src/doFolder/hashing/calculate.py"
click node_hash_cache "https://github.com/kuankuan2007/do-folder/blob/main/src/doFolder/hashing/cache.py"
click node_hash_executor "https://github.com/kuankuan2007/do-folder/blob/main/src/doFolder/hashing/executor.py"
click node_hash_cli "https://github.com/kuankuan2007/do-folder/blob/main/src/doFolder/cli/hash.py"
click node_cli_dispatch "https://github.com/kuankuan2007/do-folder/blob/main/src/doFolder/cli/main.py"
click node_cli_scripts "https://github.com/kuankuan2007/do-folder/blob/main/src/doFolder/scripts.py"
click node_module_entry "https://github.com/kuankuan2007/do-folder/blob/main/src/doFolder/__main__.py"

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_public_api,node_item_classes,node_item_factory,node_terminal toneBlue
class node_compare_engine,node_sync_cli toneAmber
class node_hash_calculator,node_hash_calculation,node_hash_cache,node_hash_executor toneMint
class node_hash_cli,node_cli_dispatch,node_cli_scripts,node_module_entry toneRose
class node_developer,node_filesystem toneIndigo
```

## Components

### Python Filesystem API

- [Package API](https://github.com/kuankuan2007/do-folder/blob/main/src/doFolder/__init__.py): `src/doFolder/__init__.py`
- [File and Directory](https://github.com/kuankuan2007/do-folder/blob/main/src/doFolder/fileSystem/classes.py): `src/doFolder/fileSystem/classes.py`
- [Item Factory](https://github.com/kuankuan2007/do-folder/blob/main/src/doFolder/fileSystem/tools.py): `src/doFolder/fileSystem/tools.py`

### Comparison and Sync

- [Compare Engine](https://github.com/kuankuan2007/do-folder/blob/main/src/doFolder/compare.py): `src/doFolder/compare.py`
- [Compare and Sync CLI](https://github.com/kuankuan2007/do-folder/blob/main/src/doFolder/cli/compare.py): `src/doFolder/cli/compare.py`

### Hashing

- [Hash Calculators](https://github.com/kuankuan2007/do-folder/blob/main/src/doFolder/hashing/calculator.py): `src/doFolder/hashing/calculator.py`
- [Hash Calculation](https://github.com/kuankuan2007/do-folder/blob/main/src/doFolder/hashing/calculate.py): `src/doFolder/hashing/calculate.py`
- [Hash Cache](https://github.com/kuankuan2007/do-folder/blob/main/src/doFolder/hashing/cache.py): `src/doFolder/hashing/cache.py`
- [Hash Executor](https://github.com/kuankuan2007/do-folder/blob/main/src/doFolder/hashing/executor.py): `src/doFolder/hashing/executor.py`

### Command Line

- [Hash CLI](https://github.com/kuankuan2007/do-folder/blob/main/src/doFolder/cli/hash.py): `src/doFolder/cli/hash.py`
- [Unified CLI](https://github.com/kuankuan2007/do-folder/blob/main/src/doFolder/cli/main.py): `src/doFolder/cli/main.py`
- [CLI Entrypoints](https://github.com/kuankuan2007/do-folder/blob/main/src/doFolder/scripts.py): `src/doFolder/scripts.py`
- [Module Entrypoint](https://github.com/kuankuan2007/do-folder/blob/main/src/doFolder/__main__.py): `src/doFolder/__main__.py`

### Other components

- **Developer**
- **CLI User**
- **Local Filesystem**

## Connections

- Developer → Package API: uses objects
- Package API → File and Directory: exposes
- File and Directory → Item Factory: creates items
- Item Factory → Local Filesystem: inspects paths
- File and Directory → Local Filesystem: reads and modifies
- Developer → Compare Engine: compares paths
- Compare Engine → Item Factory: wraps paths
- Compare Engine → Local Filesystem: reads item data
- CLI User → CLI Entrypoints: runs commands
- CLI Entrypoints → Unified CLI: dispatches unified
- CLI Entrypoints → Compare and Sync CLI: runs compare
- CLI Entrypoints → Hash CLI: runs hash
- Module Entrypoint → Unified CLI: starts CLI
- Unified CLI → Compare and Sync CLI: dispatches compare
- Unified CLI → Hash CLI: dispatches hash
- Compare and Sync CLI → Compare Engine: finds differences
- Compare and Sync CLI → Item Factory: wraps sync paths
- Compare and Sync CLI → Local Filesystem: copies sync items
- Hash CLI → Item Factory: wraps input paths
- Hash CLI → Hash Calculators: requests hashes
- Hash Calculators → Hash Cache: checks and stores
- Hash Calculators → Hash Calculation: calculates misses
- Hash Calculation → Local Filesystem: reads file content
- Hash CLI → Hash Executor: uses threaded hashing
- Hash Executor → Hash Calculators: submits calculations