# surpris/directory-structure-py architecture

> Architecture diagram of the GitHub repository surpris/directory-structure-py, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/surpris/directory-structure-py
- Repository: https://github.com/surpris/directory-structure-py

## Overview

##### Main Components
- Input Handler: Represents the external file system (directories and files) that act as inputs to the system.
- CLI / Command-Line Interface: A user-accessible layer that accepts command-line arguments and options (see usage examples in the README and portable batch/shell scripts).
- Core Python Package (directory_structure_py):
- Entry Point: __main__.py and main.py which parse arguments and orchestrate execution.
- Metadata Extraction Module: Functions imported from get_metadata.py (e.g., get_metadata_of_single_file and get_metadata_of_files_in_list_format), and generate_id. This module uses the pathlib module to recursively scan and gather file attributes.
- Metadata Conversion Module: The conversion.py file includes functions to transform the metadata into different output formats such as TSV, tree representation (via list2tree), and RO-Crate format. Also include rocrate_models.py which likely transforms data according to Research Object Crate standards.
- Configuration & Logging: The config directory (with logging.json) under directory_structure_py, and constants.py for application constants.
- Templates: Jinja2 HTML templates for preview output (located under templates).
- Output Manager: Represents the stage that writes out differing formats (JSON, TSV, HTML preview) into the output directory or user-specified destinations.
- Supporting Components:
- Testing Module: tests directory that gives confidence regarding conversion and metadata extraction.
- Notebooks and Samples: Serve as usage and demonstration examples.
- CI/CD Pipelines: GitHub workflows (.github/workflows) that cover package building (pyinstaller on Ubuntu/Windows, python package packaging) to facilitate continuous integration and deployment.

##### Relationships and Data Flow
- From the CLI, indicate that the control flows to the “Entry Point (main.py/ __main__.py)” which then invokes the “Metadata Extraction Module.”
- The Metadata Extraction Module reads the file system structure (the “Input Handler” representing the file/directory) and emits a JSON-like dictionary containing the metadata.
- Finally, illustrate the “Output Manager” that writes various files (e.g., directory_structure_metadata.json, directory_structure_metadata_tree.json, directory_structure_metadata.tsv, ro-crate-metadata.json, ro-crate-preview.html) to the appropriate directories.

##### Architectural Patterns and Key Technologies
- Modularity: Emphasize how different modules (extraction, conversion, CLI integration) are decoupled. This creates a clean separation of concerns.
- Reusability and Composability: The architecture supports both CLI usage and programmatic interactions within Python applications.
- Template Rendering: Use of Jinja2 or similar templating (as seen with the preview_template HTML) is an important detail for generating preview outputs.
- CI/CD Integration: Though not part of the runtime architecture, the GitHub workflows indicate automated testing, building, and packaging flow.
- Technologies: Make sure to note the usage of Python (and its pathlib module), a potential dependency on Jinja2 (for rendering HTML), and how the logging configuration (JSON format) is centrally used.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A("User (CLI/Developer)"):::external
    G("File System (Input Handler)"):::input
    B("CLI Interface"):::cli
    C("Entry Point (main.py/ __main__.py)"):::entry
    D("Metadata Extraction Module"):::extract
    E("Metadata Conversion Module"):::convert
    F("Output Manager"):::output
    H("Templates for Preview Output"):::template
    I("Configuration & Logging"):::config
    J("Testing Module"):::test
    K("CI/CD Pipelines"):::cicd

    %% Main Flow
    A -->|"triggers"| B
    B -->|"invokes"| C
    C -->|"calls"| D
    D -->|"provides metadata to"| E
    E -->|"sends outputs to"| F

    %% Input Flow
    G -->|"scanned by"| D

    %% Template Usage
    E -.->|"renders preview via"| H

    %% Cross-Cutting Logging/Configuration
    C -.-> I
    D -.-> I
    E -.-> I
    F -.-> I

    %% Development Support Connections
    J -.->|"tests extraction"| D
    J -.->|"tests conversion"| E
    K -.->|"supports build/deploy"| F

    %% Click Events for CLI Interface
    click B "https://github.com/surpris/directory-structure-py/blob/main/for_portable/directory_structure_py.bat"
    click B "https://github.com/surpris/directory-structure-py/blob/main/for_portable/directory_structure_py.sh"

    %% Click Events for Entry Point
    click C "https://github.com/surpris/directory-structure-py/blob/main/directory_structure_py/__main__.py"
    click C "https://github.com/surpris/directory-structure-py/blob/main/directory_structure_py/main.py"

    %% Click Event for Metadata Extraction Module
    click D "https://github.com/surpris/directory-structure-py/blob/main/directory_structure_py/get_metadata.py"

    %% Click Events for Metadata Conversion Module
    click E "https://github.com/surpris/directory-structure-py/blob/main/directory_structure_py/conversion.py"
    click E "https://github.com/surpris/directory-structure-py/blob/main/directory_structure_py/rocrate_models.py"

    %% Click Events for Configuration & Logging
    click I "https://github.com/surpris/directory-structure-py/blob/main/directory_structure_py/config/logging.json"
    click I "https://github.com/surpris/directory-structure-py/blob/main/directory_structure_py/constants.py"

    %% Click Event for Templates
    click H "https://github.com/surpris/directory-structure-py/blob/main/directory_structure_py/templates/preview_template.html.j2"

    %% Click Event for Output Manager
    click F "https://github.com/surpris/directory-structure-py/tree/main/output/sample/"

    %% Click Events for Testing Module
    click J "https://github.com/surpris/directory-structure-py/blob/main/tests/test_conversion.py"
    click J "https://github.com/surpris/directory-structure-py/blob/main/tests/test_get_metadata.py"
    click J "https://github.com/surpris/directory-structure-py/blob/main/tests/test_rocrate_models.py"

    %% Click Events for CI/CD Pipelines
    click K "https://github.com/surpris/directory-structure-py/blob/main/.github/workflows/pyinstaller-ubuntu.yml"
    click K "https://github.com/surpris/directory-structure-py/blob/main/.github/workflows/pyinstaller-windows.yml"
    click K "https://github.com/surpris/directory-structure-py/blob/main/.github/workflows/python-package.yml"

    %% Styles
    classDef external fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef cli fill:#AEE2FF,stroke:#333,stroke-width:2px;
    classDef entry fill:#C1E1C1,stroke:#333,stroke-width:2px;
    classDef extract fill:#C8E6C9,stroke:#333,stroke-width:2px;
    classDef convert fill:#BBDEFB,stroke:#333,stroke-width:2px;
    classDef output fill:#FFE0B2,stroke:#333,stroke-width:2px;
    classDef template fill:#D1C4E9,stroke:#333,stroke-width:2px;
    classDef config fill:#FFCDD2,stroke:#333,stroke-width:2px;
    classDef input fill:#F0F4C3,stroke:#333,stroke-width:2px;
    classDef test fill:#E1BEE7,stroke:#333,stroke-width:2px;
    classDef cicd fill:#B2EBF2,stroke:#333,stroke-width:2px;
```
