# peteretelej/tree architecture

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

- Interactive diagram: https://gitdiagram.com/peteretelej/tree
- Repository: https://github.com/peteretelej/tree

## Overview

1. **What this repo is**
   - A single Rust workspace-style crate that builds both a CLI binary and a reusable library.
   - The user-facing product is the `tree` command: it prints a directory hierarchy in a tree-like format, with many flags for filtering, sorting, formatting, and output control.

2. **Top-level runtime shape**
   - `src/main.rs` is the executable entrypoint.
   - It delegates into the library module under `src/rust_tree/`, which contains essentially all product logic.
   - This separation means the same core logic can be used by the CLI and by external Rust callers.

3. **Core public API boundary**
   - `src/lib.rs` and `src/rust_tree/mod.rs` expose the library surface.
   - The README shows the intended API: `list_directory`, `list_directory_as_string`, `TreeOptions`, and utility functions like `bytes_to_human_readable`.
   - This is an important architectural boundary: argument parsing and process I/O are mostly CLI concerns, while traversal and formatting are library concerns.

4. **CLI and configuration flow**
   - `src/rust_tree/cli.rs` parses command-line flags and positional path input.
   - `src/rust_tree/options.rs` centralizes all tree behavior toggles in a single options struct.
   - The flow is: CLI args → `TreeOptions` → traversal/formatting logic.
   - This is where flags like depth, hidden files, full path, ASCII mode, color, directories-only, sorting, pruning, and output destination become runtime configuration.

5. **Filesystem traversal subsystem**
   - `src/rust_tree/traversal.rs` is the main engine that walks the filesystem and decides what nodes to include.
   - It applies filtering and ordering rules: recursion depth, hidden-file rules, include/exclude patterns, directory pruning, file limits, directory-first sorting, time-based sorting, reverse order, and directory-only mode.
   - This subsystem is responsible for turning the filesystem into an internal representation that later stages can render.

6. **Input source variants**
   - `src/rust_tree/fromfile.rs` handles the `--fromfile` feature, where the directory listing comes from a file or stdin rather than a live filesystem walk.
   - This creates a clear input boundary: the same tree-rendering pipeline can consume either real directory traversal or pre-recorded listing data.

7. **Ignore and match semantics**
   - `src/rust_tree/gitignore.rs` adds `.gitignore`-style filtering behavior.
   - Pattern-based include/exclude handling is part of the traversal decision layer rather than the display layer, so filtered nodes never reach rendering unless they are meant to.
   - This keeps matching logic separate from formatting logic, which is useful for reasoning about pruning and “match directories” behavior.

8. **Rendering and presentation**
   - `src/rust_tree/display.rs` is the output formatter.
   - It converts the traversal result into the final tree text, handling indentation, ASCII-vs-Unicode branches, colorization, full-path rendering, file sizes, human-readable sizes, modification dates, permissions, file-type suffixes, and summary/report output.
   - The README’s `list_directory_as_string` indicates this layer can render either to stdout or to an in-memory string.

9. **Ancillary presentation helpers**
   - `src/rust_tree/icons.rs` supplies file-type indicators such as `/` or `*`.
   - `src/rust_tree/utils.rs` holds shared helpers like byte-size formatting and path normalization.
   - These are supporting modules for display and cross-platform correctness, not standalone subsystems.

10. **Cross-platform and packaging concerns**
   - The repo is explicitly portable across Linux, macOS, and Windows, with special support for Windows 7 via `Cargo-win7.lock`.
   - Packaging/release infrastructure includes GitHub Actions workflows, Microsoft Store assets, and WiX installer files.
   - That means the architecture is not just runtime code; it also includes release/build pipelines for multiple distribution channels.

11. **Testing structure**
   - The `tests/` directory contains focused unit/integration coverage by subsystem: CLI parsing, traversal, display, gitignore behavior, icons, fromfile formats, path normalization, and utility functions.
   - Fixtures under `tests/fixtures/` model real directory shapes, hidden files, and nested content, while `tests/dynamic/` suggests tests that create or mutate data at runtime.
   - The test layout mirrors the production module boundaries, which is a strong clue for diagramming the system.

12. **External services and automation**
   - GitHub Actions drives CI, release publishing, and docs/deployment workflows.
   - The release process targets GitHub Releases and crates.io, so distribution is automated from tagged source.
   - GitHub Pages is used for the project website/docs, but it does not affect the runtime architecture of the CLI itself.

13. **Useful diagram takeaway**
   - A good architecture diagram should show a pipeline: CLI args / stdin / fromfile → options and filtering → filesystem traversal or listing ingestion → formatting/rendering → stdout or file output.
   - Around that core, show helper modules for gitignore matching, icons, and utilities, plus separate release/test automation paths.

Main entry points: [`tests/integration_tests.rs`](https://github.com/peteretelej/tree/blob/main/tests/integration_tests.rs) (Test suite), [`src/rust_tree/display.rs`](https://github.com/peteretelej/tree/blob/main/src/rust_tree/display.rs) (Render output), [`src/rust_tree/traversal.rs`](https://github.com/peteretelej/tree/blob/main/src/rust_tree/traversal.rs) (Traversal), [`src/rust_tree/mod.rs`](https://github.com/peteretelej/tree/blob/main/src/rust_tree/mod.rs) (Core module)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main(("tree CLI<br/>binary entrypoint<br/>[main.rs]"))
  node_lib["Library API<br/>crate root<br/>[lib.rs]"]
  node_mod["Core module<br/>module hub<br/>[mod.rs]"]
  node_cli["Arg parsing<br/>cli parser<br/>[cli.rs]"]
  node_options["Tree options<br/>config model<br/>[options.rs]"]
  node_traversal["Traversal<br/>filesystem walk<br/>[traversal.rs]"]
  node_fromfile["From file<br/>input adapter<br/>[fromfile.rs]"]
  node_gitignore["Ignore rules<br/>match filter<br/>[gitignore.rs]"]
  node_display["Render output<br/>formatter<br/>[display.rs]"]
  node_readme_api["Public API<br/>library contract<br/>[README.md]"]
end

subgraph group_helpers["Helpers"]
  node_icons["Icons<br/>presentation helper<br/>[icons.rs]"]
  node_utils["Utilities<br/>shared helpers<br/>[utils.rs]"]
end

subgraph group_automation["Automation"]
  node_ci["CI workflows<br/>automation<br/>[ci.yml]"]
  node_release["Release flow<br/>automation<br/>[release.yml]"]
  node_ghpages["Docs deploy<br/>automation"]
  node_store["Store assets<br/>packaging<br/>[README.md]"]
  node_wix["WiX installer<br/>packaging<br/>[main.wxs]"]
  node_tests["Test suite<br/>verification"]
end

node_main -->|"runs"| node_mod
node_lib -->|"exposes"| node_mod
node_mod -->|"uses"| node_cli
node_mod -->|"configures"| node_options
node_cli -->|"builds"| node_options
node_options -->|"drives"| node_traversal
node_options -->|"drives"| node_display
node_traversal -->|"filters with"| node_gitignore
node_traversal -->|"accepts"| node_fromfile
node_traversal -->|"emits"| node_display
node_display -->|"decorates with"| node_icons
node_display -->|"formats with"| node_utils
node_display -.->|"implements"| node_readme_api
node_lib -.->|"documents"| node_readme_api
node_ci -->|"verifies"| node_tests
node_release -->|"packages"| node_store
node_release -->|"packages"| node_wix
node_ghpages -.->|"publishes"| node_readme_api
node_tests -.->|"covers"| node_cli
node_tests -.->|"covers"| node_traversal
node_tests -.->|"covers"| node_display
node_tests -.->|"covers"| node_fromfile
node_tests -.->|"covers"| node_gitignore
node_tests -.->|"covers"| node_utils

click node_main "https://github.com/peteretelej/tree/blob/main/src/main.rs"
click node_lib "https://github.com/peteretelej/tree/blob/main/src/lib.rs"
click node_mod "https://github.com/peteretelej/tree/blob/main/src/rust_tree/mod.rs"
click node_cli "https://github.com/peteretelej/tree/blob/main/src/rust_tree/cli.rs"
click node_options "https://github.com/peteretelej/tree/blob/main/src/rust_tree/options.rs"
click node_traversal "https://github.com/peteretelej/tree/blob/main/src/rust_tree/traversal.rs"
click node_fromfile "https://github.com/peteretelej/tree/blob/main/src/rust_tree/fromfile.rs"
click node_gitignore "https://github.com/peteretelej/tree/blob/main/src/rust_tree/gitignore.rs"
click node_display "https://github.com/peteretelej/tree/blob/main/src/rust_tree/display.rs"
click node_icons "https://github.com/peteretelej/tree/blob/main/src/rust_tree/icons.rs"
click node_utils "https://github.com/peteretelej/tree/blob/main/src/rust_tree/utils.rs"
click node_readme_api "https://github.com/peteretelej/tree/blob/main/README.md"
click node_ci "https://github.com/peteretelej/tree/blob/main/.github/workflows/ci.yml"
click node_release "https://github.com/peteretelej/tree/blob/main/.github/workflows/release.yml"
click node_ghpages "https://github.com/peteretelej/tree/blob/main/.github/workflows/jekyll-gh-pages.yml"
click node_store "https://github.com/peteretelej/tree/blob/main/store-assets/Microsoft-Store/README.md"
click node_wix "https://github.com/peteretelej/tree/blob/main/wix/main.wxs"
click node_tests "https://github.com/peteretelej/tree/blob/main/tests/integration_tests.rs"

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_main,node_lib,node_mod,node_cli,node_options,node_traversal,node_fromfile,node_gitignore,node_display,node_readme_api toneBlue
class node_icons,node_utils toneAmber
class node_ci,node_release,node_ghpages,node_store,node_wix,node_tests toneMint
```

## Components

### Runtime

CLI entrypoint and core library pipeline

- [tree CLI](https://github.com/peteretelej/tree/blob/main/src/main.rs): binary entrypoint · Executable entrypoint for the `tree` command · `src/main.rs`
- [Library API](https://github.com/peteretelej/tree/blob/main/src/lib.rs): crate root · Public library surface for external callers and the CLI · `src/lib.rs`
- [Core module](https://github.com/peteretelej/tree/blob/main/src/rust_tree/mod.rs): module hub · Re-exports and internal wiring for the Rust tree implementation · `src/rust_tree/mod.rs`
- [Arg parsing](https://github.com/peteretelej/tree/blob/main/src/rust_tree/cli.rs): cli parser · Parses command-line flags and the target path · `src/rust_tree/cli.rs`
- [Tree options](https://github.com/peteretelej/tree/blob/main/src/rust_tree/options.rs): config model · Central configuration for filtering, sorting, formatting, and output behavior · `src/rust_tree/options.rs`
- [Traversal](https://github.com/peteretelej/tree/blob/main/src/rust_tree/traversal.rs): filesystem walk · Walks the filesystem and applies inclusion, depth, and ordering rules · `src/rust_tree/traversal.rs`
- [From file](https://github.com/peteretelej/tree/blob/main/src/rust_tree/fromfile.rs): input adapter · Loads tree input from a file or stdin instead of a live walk · `src/rust_tree/fromfile.rs`
- [Ignore rules](https://github.com/peteretelej/tree/blob/main/src/rust_tree/gitignore.rs): match filter · Implements `.gitignore`-style include and exclude matching · `src/rust_tree/gitignore.rs`
- [Render output](https://github.com/peteretelej/tree/blob/main/src/rust_tree/display.rs): formatter · Turns traversal results into tree text or an in-memory string · `src/rust_tree/display.rs`
- [Public API](https://github.com/peteretelej/tree/blob/main/README.md): library contract · Documented library entry points such as `list_directory` and `list_directory_as_string` · `README.md`

### Helpers

Supporting modules used by traversal and display

- [Icons](https://github.com/peteretelej/tree/blob/main/src/rust_tree/icons.rs): presentation helper · Supplies file-type markers and suffixes · `src/rust_tree/icons.rs`
- [Utilities](https://github.com/peteretelej/tree/blob/main/src/rust_tree/utils.rs): shared helpers · Common helpers for size formatting and path handling · `src/rust_tree/utils.rs`

### Automation

Build, release, packaging, and test infrastructure

- [CI workflows](https://github.com/peteretelej/tree/blob/main/.github/workflows/ci.yml): automation · Continuous integration, labeling, and release checks · `.github/workflows/ci.yml`
- [Release flow](https://github.com/peteretelej/tree/blob/main/.github/workflows/release.yml): automation · Automated packaging and publishing for releases · `.github/workflows/release.yml`
- [Docs deploy](https://github.com/peteretelej/tree/blob/main/.github/workflows/jekyll-gh-pages.yml): automation · Publishes project documentation to GitHub Pages · `.github/workflows/jekyll-gh-pages.yml`
- [Store assets](https://github.com/peteretelej/tree/blob/main/store-assets/Microsoft-Store/README.md): packaging · Microsoft Store packaging assets and installer resources · `store-assets/Microsoft-Store/README.md`
- [WiX installer](https://github.com/peteretelej/tree/blob/main/wix/main.wxs): packaging · Windows installer definitions and resources · `wix/main.wxs`
- [Test suite](https://github.com/peteretelej/tree/blob/main/tests/integration_tests.rs): verification · Integration and subsystem tests mirroring the production modules · `tests/integration_tests.rs`

## Connections

- tree CLI → Core module: runs · Binary delegates into the shared library core
- Library API → Core module: exposes · Crate root exposes the internal Rust tree module
- Core module → Arg parsing: uses · Core module wires CLI parsing into the runtime
- Core module → Tree options: configures · Behavior is centralized in a single options model
- Arg parsing → Tree options: builds · Parsed flags become runtime options
- Tree options → Traversal: drives · Traversal behavior is controlled by options
- Tree options → Render output: drives · Formatting and output are controlled by options
- Traversal → Ignore rules: filters with · Pattern matching influences which nodes are kept
- Traversal → From file: accepts · Traversal can be fed by pre-recorded listing input
- Traversal → Render output: emits · Traversal produces structured data for rendering
- Render output → Icons: decorates with · Presentation may add file-type indicators
- Render output → Utilities: formats with · Shared helpers support size and path formatting
- Render output → Public API: implements · Library API examples map to the rendering pipeline
- Library API → Public API: documents · README describes the intended reusable API surface
- CI workflows → Test suite: verifies · CI runs the test suite and quality checks
- Release flow → Store assets: packages · Release automation produces distribution artifacts
- Release flow → WiX installer: packages · Windows installer assets are part of release packaging
- Docs deploy → Public API: publishes · Docs workflows surface project documentation
- Test suite → Arg parsing: covers · CLI parsing is covered by dedicated tests
- Test suite → Traversal: covers · Traversal behavior is exercised directly
- Test suite → Render output: covers · Rendering output has focused test coverage
- Test suite → From file: covers · From-file input formats are tested
- Test suite → Ignore rules: covers · Ignore semantics have dedicated tests
- Test suite → Utilities: covers · Utility helpers are verified separately
