# gulrak/filesystem architecture

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

- Interactive diagram: https://gitdiagram.com/gulrak/filesystem
- Repository: https://github.com/gulrak/filesystem

## Overview

##### Main Components
- Library Core (API and Implementation): The “include/ghc” directory contains the key header files (e.g., filesystem.hpp, fs_impl.hpp, fs_fwd.hpp, and others). This is the library’s interface in the ghc::filesystem namespace.
- Build System & Configuration: The top-level CMakeLists.txt along with additional CMake modules in the “cmake” directory shows how the project is configured, built, and installed. Build scripts (both in .ci and GitHub workflows) illustrate integration with CI systems.
- Testing & Examples: The “test” directory holds unit tests (with Catch2 and special handling for both ghc::filesystem and std::filesystem tests). The “examples” directory contains simple demo programs (like du.cpp) to demonstrate usage.
- Continuous Integration (CI/CD): Files like .appveyor.yml, .cirrus.yml, .drone.yml-disabled, and GitHub Actions workflows define automated build/test processes across multiple platforms.
- Documentation & Release Management: The README file gives a detailed description, while LICENSE and versioning information are in the root and within Git tags.

##### Out Relationships and Interactions
- The CMake build system ties together compiling examples, unit tests, and optionally installing the header-only library.
- The CI/CD configurations directly trigger the build and test processes using CMake, thus showing dependency on the build system.
- Users incorporate the library by either adding the “include/ghc” directory to their project or by using the provided forwarding/implementation headers. This mechanism is diagrammed as the “Public API” leading into their application code.
- The tests and examples depend on the library core to confirm interface conformance and performance across different platforms.

##### Architectural Patterns and Design Principles
- Header-only library design: The core functionality is contained in the header files and is compiled into the client application (while optional separation into forwarding and implementation headers helps hide system includes).
- Cross-platform abstraction: The library adapts to differences among operating systems (Windows, macOS, Linux, FreeBSD, Solaris, and even Haiku or Android in some cases). CI/CD files illustrate how multiple platform builds are handled.
- Conditional compilation and dynamic inclusion: The intricate usage of preprocessor definitions (e.g., GHC_USE_STD_FS, GHC_FILESYSTEM_ENFORCE_CPP17_API, etc.) is key in selecting between native std::filesystem and the fallback implementation.

##### Relevant Technologies and Tools
- C++ (with support from C++11 to C++20).
- CMake as the build system.
- Catch2 for unit testing.
- Various CI/CD systems (GitHub Actions, AppVeyor, Cirrus CI, Drone).
- Git submodules for integration into client projects.
- Optional integration with Bazel (as mentioned in the README).

– Infrastructure components (CI/CD, Build System)
– Code artifacts (API, tests, examples)
– External systems and platforms (Windows, Linux, macOS)

## Diagram (Mermaid)

```mermaid
graph TD
    %% CI/CD Pipelines Subgraph
    subgraph "CI/CD Pipelines"
        A1["AppVeyor"]:::ci
        A2["Cirrus CI"]:::ci
        A3["Drone"]:::ci
        A4["GitHub Actions"]:::ci
        A5["CI Scripts"]:::ci
    end

    %% Build System & Configuration Subgraph
    subgraph "Build System & Configuration"
        B1["Top-level CMakeLists.txt"]:::build
        B2["CMake Modules"]:::build
    end

    %% Library Core Subgraph
    subgraph "Library Core (API & Implementation)"
        C1["Public API (filesystem.hpp)"]:::library
        C2["Implementation Details (fs_impl.hpp, fs_fwd.hpp, fs_std.hpp)"]:::library
    end

    %% Unit Tests Node
    T["Tests (Catch2)"]:::test

    %% Examples/Demos Node
    E["Examples/Demos"]:::test

    %% Documentation & Release Management Subgraph
    subgraph "Documentation & Release Management"
        D1["README"]:::doc
        D2["LICENSE"]:::doc
    end

    %% User Integration Node
    U["User Integration (Client Code)"]:::user

    %% Dependencies / Relationships
    A1 & A2 & A3 & A4 & A5 -->|"triggers"| B1
    B1 -->|"invokes"| B2
    B1 -->|"builds"| T
    B1 -->|"builds"| E
    B2 -->|"compiles"| C1
    B2 -->|"compiles"| C2
    T -->|"verifies"| C1
    T -->|"verifies"| C2
    E -->|"demonstrates"| C1
    E -->|"demonstrates"| C2
    U -->|"includes"| C1
    U -->|"includes"| C2
    D1 -->|"informs"| U
    D2 -->|"informs"| U

    %% Click Events for Component Mapping
    click C1 "https://github.com/gulrak/filesystem/tree/master/include/ghc"
    click B1 "https://github.com/gulrak/filesystem/blob/master/CMakeLists.txt"
    click B2 "https://github.com/gulrak/filesystem/tree/master/cmake"
    click T "https://github.com/gulrak/filesystem/tree/master/test"
    click E "https://github.com/gulrak/filesystem/tree/master/examples"
    click A1 "https://github.com/gulrak/filesystem/blob/master/.appveyor.yml"
    click A2 "https://github.com/gulrak/filesystem/blob/master/.cirrus.yml"
    click A3 "https://github.com/gulrak/filesystem/blob/master/.drone.yml-disabled"
    click A4 "https://github.com/gulrak/filesystem/blob/master/.github/workflows/build_cmake.yml"
    click A5 "https://github.com/gulrak/filesystem/blob/master/.ci"
    click D1 "https://github.com/gulrak/filesystem/blob/master/README.md"
    click D2 "https://github.com/gulrak/filesystem/tree/master/LICENSE"

    %% Styles
    classDef library fill:#a0d2eb,stroke:#333,stroke-width:2px;
    classDef build fill:#ffcc5c,stroke:#333,stroke-width:2px;
    classDef test fill:#c1fba4,stroke:#333,stroke-width:2px;
    classDef ci fill:#ff6f69,stroke:#333,stroke-width:2px;
    classDef doc fill:#ffeead,stroke:#333,stroke-width:2px;
    classDef user fill:#dcedc1,stroke:#333,stroke-width:2px;
```
