# yotamnahum/repo-tree architecture

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

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

## Overview

##### Project type and purpose
- This is an open-source Python utility library with an accompanying CLI tool.
- Purpose: provide a Pythonic alternative to the Unix `tree` command, allowing users to programmatically and interactively build and display a repository’s directory structure, apply exclusion patterns (including `.gitignore`), and even flatten and concatenate file contents.

##### File structure
- Top-level files:
- setup.py / requirements.txt – packaging and dependencies
- README.md, LICENSE, TODO.md – documentation
- images/ – logos and documentation assets
- Core package folder: repo_tree/
- __init__.py – package initializer, exports public API
- cli.py – entrypoint for the CLI
- repository_tree.py – the core classes and logic (RepositoryTree, FlatView, pattern filtering, tree building)
- No external microservices or databases—everything runs locally on the filesystem.

##### Key insights from the README
- Two consumption modes:
a. Python API: import and call RepositoryTree.get_tree_paths(), display_tree(), get_concatenated_file_contents().
b. CLI: `python -m repo_tree [dir_path] [options]` or console script installed via setup.py.
- Core features:
- Depth-controlled tree generation
- Hidden-file and pattern-based exclusion (including reading `.gitignore`)
- Flat concatenated view of file contents
- No external service dependencies—pure Python, file-system centric.

##### Main components and their interactions
a. Components:
1. User Interfaces
- CLI Module (repo_tree/cli.py)
- Python API (repo_tree/__init__.py exposes RepositoryTree, FlatView)
2. Core Library (repo_tree/repository_tree.py)
- RepositoryTree: tree builder, exclusion engine, print/display logic
- FlatView: concatenator for file contents
- Pattern Engine: handles exclusion_patterns, exclude_if_contains, .gitignore parsing
3. Filesystem
- OS filesystem abstraction (os, pathlib)
- `.gitignore` file parser
4. Output Renderer
- Text-based tree formatter
- Console I/O for printing
5. Packaging / Distribution
- setup.py defines console_scripts entrypoint
- requirements.txt specifies dependencies

b. Relationships and data flow
- User invokes CLI or imports API
- CLI parses arguments → calls RepositoryTree.display_tree()
- API directly calls RepositoryTree or FlatView methods
- RepositoryTree:
- Reads target directory via Filesystem
- Parses `.gitignore` and user-supplied exclusion patterns via Pattern Engine
- Builds an in-memory tree structure (nodes for directories/files)
- Passes tree to Output Renderer → formatted text
- Returns string or prints to stdout
- FlatView:
- Reuses Pattern Engine and Filesystem traversal
- Aggregates file contents into a concatenated buffer
- Returns combined string

c. Architectural patterns and principles
- Layered design (UI → Core Logic → Filesystem I/O → Output)
- Single Responsibility: CLI module only handles argument parsing and delegation; core library handles scanning, filtering, formatting
- Extensibility: exclusion engine can be extended to accept new filter types
- Separation of concerns: packaging (setup.py) is isolated from runtime logic

d. Key technologies and libraries
- Python 3.6+ standard libs: os, pathlib, fnmatch, argparse (or click if used)
- setuptools for packaging (console_scripts entrypoint)
- No external runtime services or databases

##### Summary of what
- Optional annotation of key methods: display_tree(), get_tree_paths(), get_concatenated_file_contents()
- Emphasis on the pattern-based filtering subcomponent and its use of `.gitignore`

## Diagram (Mermaid)

```mermaid
flowchart TB
    User["User"]:::external
    subgraph "User Interface"
        CLI["CLI Module"]:::ui
        API["Python API"]:::ui
    end
    subgraph "Core Logic"
        RepoTree["RepositoryTree"]:::core
        FlatView["FlatView"]:::core
        PatternEngine["Pattern Engine"]:::core
    end
    subgraph "I/O"
        Filesystem["Filesystem (os, pathlib)"]:::io
        Gitignore[".gitignore Parser"]:::io
        Renderer["Output Renderer"]:::io
    end
    subgraph "Packaging/Distribution"
        Packaging["console_scripts entrypoint\n(setup.py)"]:::pkg
        Requirements["requirements.txt"]:::pkg
    end
    subgraph "Documentation"
        README["README.md"]:::doc
        License["LICENSE"]:::doc
        TODO["TODO.md"]:::doc
        Images["images/"]:::doc
    end

    User -->|"invoke CLI"| CLI
    User -->|"import API"| API
    CLI -->|"parsed args"| RepoTree
    API -->|"calls get_tree_paths(), display_tree()"| RepoTree
    API -->|"calls get_concatenated_file_contents()"| FlatView
    RepoTree -->|"reads directory"| Filesystem
    FlatView -->|"reads directory"| Filesystem
    Filesystem -->|".gitignore rules"| Gitignore
    RepoTree -->|"filters with patterns"| PatternEngine
    FlatView -->|"filters with patterns"| PatternEngine
    RepoTree -->|"formats tree"| Renderer
    Renderer -->|"prints to stdout"| User
    FlatView -->|"returns concatenated string"| User
    Packaging -->|"defines entrypoint"| CLI
    Requirements -->|"specifies deps for"| Packaging

    click CLI "https://github.com/yotamnahum/repo-tree/blob/main/repo_tree/cli.py"
    click API "https://github.com/yotamnahum/repo-tree/blob/main/repo_tree/__init__.py"
    click RepoTree "https://github.com/yotamnahum/repo-tree/blob/main/repo_tree/repository_tree.py"
    click FlatView "https://github.com/yotamnahum/repo-tree/blob/main/repo_tree/repository_tree.py"
    click PatternEngine "https://github.com/yotamnahum/repo-tree/blob/main/repo_tree/repository_tree.py"
    click Packaging "https://github.com/yotamnahum/repo-tree/blob/main/setup.py"
    click Requirements "https://github.com/yotamnahum/repo-tree/blob/main/requirements.txt"
    click README "https://github.com/yotamnahum/repo-tree/blob/main/README.md"
    click License "https://github.com/yotamnahum/repo-tree/tree/main/LICENSE"
    click TODO "https://github.com/yotamnahum/repo-tree/blob/main/TODO.md"
    click Images "https://github.com/yotamnahum/repo-tree/tree/main/images/"
    click Gitignore "https://github.com/yotamnahum/repo-tree/blob/main/.gitignore"

    classDef ui fill:#bbdefb,stroke:#333,stroke-width:1px
    classDef core fill:#c8e6c9,stroke:#333,stroke-width:1px
    classDef io fill:#ffe0b2,stroke:#333,stroke-width:1px
    classDef pkg fill:#eeeeee,stroke:#333,stroke-width:1px
    classDef doc fill:#fff9c4,stroke:#333,stroke-width:1px
    classDef external fill:#e0e0e0,stroke:#333,stroke-width:1px
```
