# emad-elsaid/dirtree architecture

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

- Interactive diagram: https://gitdiagram.com/emad-elsaid/dirtree
- Repository: https://github.com/emad-elsaid/dirtree

## Overview

1. **What this repo is**
   - `dirtree` is a single Ruby gem/CLI tool that turns a list of file paths into an HTML visualization of a directory tree.
   - It is not a server or web app; the primary runtime is the Ruby CLI, and the final artifact is static HTML viewed in a browser.

2. **Top-level execution path**
   - The user runs `exe/dirtree` with file paths from arguments or stdin.
   - The CLI selects a template, builds an in-memory tree from the input paths, renders HTML, and either prints it to stdout or writes it to a file via `-o`.

3. **Core domain model**
   - `lib/dirtree/node.rb` is the main data model boundary.
   - It likely represents hierarchical nodes for directories/files and the relationships needed to aggregate a flat path list into a tree structure.

4. **Library entry point**
   - `lib/dirtree.rb` is the gem’s main require point and orchestrator for the library side.
   - This is where the CLI-facing functionality is exposed to the executable and where the app’s internal pieces are wired together.

5. **Template rendering layer**
   - `templates/` contains four ERB HTML templates: `tree`, `circles`, `flame`, and `treemap`.
   - The templates are the presentation boundary: they transform the same tree data into different visual encodings without changing the underlying model.

6. **Data flow from input to visualization**
   - Input is a stream of file paths, typically from `git ls-files`, `find`, `ag -l`, or shell globbing.
   - Those paths are normalized into a tree structure, then serialized into HTML/JS inside one of the ERB templates, producing a standalone page.

7. **Output modes**
   - The default output is HTML to stdout, which supports shell piping and redirection.
   - `-o` writes to a file, making the tool usable both in pipelines and as a report generator.

8. **Asset/loading boundary**
   - The README’s `--local-dependencies` option indicates the generated HTML can either reference remote JavaScript libraries or use bundled/local ones.
   - That means visual rendering is split between server-side Ruby template generation and browser-side JS/CSS assets.

9. **Optional screenshot path**
   - The `--screenshot` option suggests an additional export mode that captures the generated visualization as an image.
   - Architecturally, this is a secondary output pipeline layered on top of the same HTML generation path.

10. **CLI ergonomics**
   - `exe/dirtree-completion.bash` provides shell completion, showing the project treats the CLI as the primary user interface.
   - The executable and completion script are packaging concerns around the same core library.

11. **Packaging and release boundary**
   - `dirtree.gemspec`, `Gemfile`, and `Rakefile` define the gem packaging, dependencies, and release/build workflow.
   - `lib/dirtree/version.rb` isolates version metadata for the gem and CLI version flag.

12. **What to show in an architecture diagram**
   - A good diagram would show: input sources → CLI/executable → path-to-tree model (`Node`) → template renderer (`ERB` templates) → HTML output → browser rendering.
   - Optional branches should show local-vs-remote JS assets and the screenshot/export mode as separate terminal paths.

Main entry points: [`lib/dirtree/node.rb`](https://github.com/emad-elsaid/dirtree/blob/master/lib/dirtree/node.rb) (Node), [`exe/dirtree`](https://github.com/emad-elsaid/dirtree/tree/master/exe/dirtree) (dirtree), [`dirtree.gemspec`](https://github.com/emad-elsaid/dirtree/blob/master/dirtree.gemspec) (Gem build), [`lib/dirtree.rb`](https://github.com/emad-elsaid/dirtree/blob/master/lib/dirtree.rb) (Library API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_cli["CLI"]
  node_input_paths["File paths<br/>input"]
  node_exe_dirtree["dirtree<br/>CLI entry"]
  node_completion["Completion<br/>shell script"]
  node_stdout["Stdout<br/>output"]
  node_file_output["Output file"]
end

subgraph group_grp_core["Core"]
  node_lib_entry["Library API<br/>orchestrator<br/>[dirtree.rb]"]
  node_node_model(("Node<br/>tree model<br/>[node.rb]"))
end

subgraph group_grp_templates["Templates"]
  node_template_tree["Tree view<br/>ERB template<br/>[tree.html.erb]"]
  node_template_circles["Circles view<br/>ERB template<br/>[circles.html.erb]"]
  node_template_flame["Flame view<br/>ERB template<br/>[flame.html.erb]"]
  node_template_treemap["Treemap view<br/>ERB template<br/>[treemap.html.erb]"]
  node_template_assets["Local assets<br/>asset mode"]
  node_html_output["HTML page<br/>artifact"]
  node_browser["Browser<br/>viewer"]
  node_screenshot["Screenshot<br/>export"]
end

subgraph group_grp_packaging["Packaging"]
  node_version["Version<br/>metadata<br/>[version.rb]"]
  node_packaging["Gem build<br/>packaging<br/>[dirtree.gemspec]"]
  node_gemfile["Dependencies<br/>build config"]
  node_rakefile["Rake tasks<br/>build config"]
end

node_input_paths -->|"provide paths"| node_exe_dirtree
node_exe_dirtree -->|"invoke library"| node_lib_entry
node_lib_entry -->|"build tree"| node_node_model
node_node_model -->|"render data"| node_template_tree
node_node_model -->|"render data"| node_template_circles
node_node_model -->|"render data"| node_template_flame
node_node_model -->|"render data"| node_template_treemap
node_template_tree -->|"emit html"| node_html_output
node_template_circles -->|"emit html"| node_html_output
node_template_flame -->|"emit html"| node_html_output
node_template_treemap -->|"emit html"| node_html_output
node_template_assets -->|"load assets"| node_html_output
node_html_output -->|"print"| node_stdout
node_html_output -->|"write -o"| node_file_output
node_html_output -->|"view"| node_browser
node_html_output -->|"capture"| node_screenshot
node_completion -.->|"assist"| node_exe_dirtree
node_packaging -->|"ship"| node_exe_dirtree
node_gemfile -->|"deps"| node_packaging
node_rakefile -->|"automation"| node_packaging
node_version -->|"versioning"| node_packaging

click node_exe_dirtree "https://github.com/emad-elsaid/dirtree/tree/master/exe/dirtree"
click node_completion "https://github.com/emad-elsaid/dirtree/blob/master/exe/dirtree-completion.bash"
click node_lib_entry "https://github.com/emad-elsaid/dirtree/blob/master/lib/dirtree.rb"
click node_node_model "https://github.com/emad-elsaid/dirtree/blob/master/lib/dirtree/node.rb"
click node_version "https://github.com/emad-elsaid/dirtree/blob/master/lib/dirtree/version.rb"
click node_template_tree "https://github.com/emad-elsaid/dirtree/blob/master/templates/tree.html.erb"
click node_template_circles "https://github.com/emad-elsaid/dirtree/blob/master/templates/circles.html.erb"
click node_template_flame "https://github.com/emad-elsaid/dirtree/blob/master/templates/flame.html.erb"
click node_template_treemap "https://github.com/emad-elsaid/dirtree/blob/master/templates/treemap.html.erb"
click node_packaging "https://github.com/emad-elsaid/dirtree/blob/master/dirtree.gemspec"
click node_gemfile "https://github.com/emad-elsaid/dirtree/tree/master/Gemfile"
click node_rakefile "https://github.com/emad-elsaid/dirtree/tree/master/Rakefile"

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_input_paths,node_exe_dirtree,node_completion,node_stdout,node_file_output toneBlue
class node_lib_entry,node_node_model toneAmber
class node_template_tree,node_template_circles,node_template_flame,node_template_treemap,node_template_assets,node_html_output,node_browser,node_screenshot toneMint
class node_version,node_packaging,node_gemfile,node_rakefile toneRose
```

## Components

### CLI

Executable entrypoints and user-facing command flow

- **File paths**: input · Paths read from arguments, stdin, or shell pipelines
- [dirtree](https://github.com/emad-elsaid/dirtree/tree/master/exe/dirtree): CLI entry · Primary executable that parses options and drives rendering · `exe/dirtree`
- [Completion](https://github.com/emad-elsaid/dirtree/blob/master/exe/dirtree-completion.bash): shell script · Bash completion for the CLI · `exe/dirtree-completion.bash`
- **Stdout**: output · Default output stream for piping and redirection
- **Output file**: output · File written with the -o option

### Core

Library entrypoint and tree model

- [Library API](https://github.com/emad-elsaid/dirtree/blob/master/lib/dirtree.rb): orchestrator · Main require point wiring the library-side functionality · `lib/dirtree.rb`
- [Node](https://github.com/emad-elsaid/dirtree/blob/master/lib/dirtree/node.rb): tree model · Hierarchical data model for directories and files · `lib/dirtree/node.rb`

### Templates

Alternative HTML visual encodings

- [Tree view](https://github.com/emad-elsaid/dirtree/blob/master/templates/tree.html.erb): ERB template · Indented tree visualization · `templates/tree.html.erb`
- [Circles view](https://github.com/emad-elsaid/dirtree/blob/master/templates/circles.html.erb): ERB template · Circle-based visualization · `templates/circles.html.erb`
- [Flame view](https://github.com/emad-elsaid/dirtree/blob/master/templates/flame.html.erb): ERB template · Flame-style visualization · `templates/flame.html.erb`
- [Treemap view](https://github.com/emad-elsaid/dirtree/blob/master/templates/treemap.html.erb): ERB template · Treemap visualization · `templates/treemap.html.erb`
- **Local assets**: asset mode · Switches generated HTML between remote and bundled browser dependencies
- **HTML page**: artifact · Standalone visualization emitted by the templates
- **Browser**: viewer · Renders the generated static HTML page
- **Screenshot**: export · Optional image capture layered on top of HTML generation

### Packaging

Gem and release metadata

- [Version](https://github.com/emad-elsaid/dirtree/blob/master/lib/dirtree/version.rb): metadata · Gem and CLI version metadata · `lib/dirtree/version.rb`
- [Gem build](https://github.com/emad-elsaid/dirtree/blob/master/dirtree.gemspec): packaging · Gem specification, dependencies, and release workflow · `dirtree.gemspec`
- [Dependencies](https://github.com/emad-elsaid/dirtree/tree/master/Gemfile): build config · Bundler dependency definition · `Gemfile`
- [Rake tasks](https://github.com/emad-elsaid/dirtree/tree/master/Rakefile): build config · Build and release automation · `Rakefile`

## Connections

- File paths → dirtree: provide paths · CLI consumes paths from args or stdin
- dirtree → Library API: invoke library · Executable delegates orchestration to the library entry point
- Library API → Node: build tree · Library turns normalized paths into hierarchical nodes
- Node → Tree view: render data · Tree model feeds the selected ERB template
- Node → Circles view: render data · Same tree model supports alternate visual encodings
- Node → Flame view: render data · Same tree model supports alternate visual encodings
- Node → Treemap view: render data · Same tree model supports alternate visual encodings
- Tree view → HTML page: emit html · Template produces the standalone page
- Circles view → HTML page: emit html · Template produces the standalone page
- Flame view → HTML page: emit html · Template produces the standalone page
- Treemap view → HTML page: emit html · Template produces the standalone page
- Local assets → HTML page: load assets · Generated HTML can reference remote or bundled browser dependencies
- HTML page → Stdout: print · Default mode writes HTML to standard output
- HTML page → Output file: write -o · Optional file output path
- HTML page → Browser: view · Browser consumes the generated static page
- HTML page → Screenshot: capture · Optional export path for a rendered image
- Completion → dirtree: assist · Shell completion supports the primary CLI
- Gem build → dirtree: ship · Gem packaging installs the executable
- Dependencies → Gem build: deps · Bundler feeds dependency resolution
- Rake tasks → Gem build: automation · Rake handles build and release tasks
- Version → Gem build: versioning · Version metadata is consumed by packaging and CLI flags