# rofl0r/ncdu architecture

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

- Interactive diagram: https://gitdiagram.com/rofl0r/ncdu
- Repository: https://github.com/rofl0r/ncdu

## Overview

##### Project Type and Purpose
- ncdu is a command-line, curses-based tool for quickly analyzing disk usage. It replicates and extends the functionality of the “du” command by offering an interactive, ncurses-driven interface.
- The project is a single binary application, structured in C and built using GNU autotools, and mainly designed for POSIX-compliant systems.

##### File Structure and Architectural Insights
- The top-level directories/files – such as README, configure.ac, Makefile.am, and the static build script – point to standard build and configuration processes.
- The src directory contains all the core logic, subdivided into several modules responsible for distinct functionalities such as:
- User interface: Files like browser.c, browser.h, shell.c, and shell.h indicate components that manage the curses-based interactive interface.
- Functional modules: Several files (delete.c/h, help.c/h, quit.c/h) represent operations that users can invoke during runtime.
- Directory and file handling: Files such as dir_common.c, dir_export.c, dir_import.c, dir_mem.c, dir_scan.c, and dirlist.c/h show that scanning, memory handling, and listing directories are organized as modular routines.
- Utility functions: util.c/h, global.h, and others provide common functionalities needed across multiple modules.
- The deps directory reveals bundled dependencies (simple header-based libraries like khashl.h and yopt.h), which lend additional functionality without external requirements.
- The presence of a documentation directory with an ncdu.pod file indicates that detailed usage/docs are maintained separately and might hint at user guide information.

##### Main Components
- Main Entry Point: Represent main.c as the initiating component, responsible for setting up the environment, kicking off initializations, and controlling the program flow.
- User Interface Layer:
- ncurses Frontend: Show components such as browser, shell, help, and quit interfaces that manage user interactions.
- Module: Indicate how the UI handles navigational functionalities and renders interactive menus.
- Directory Scanning Engine:
- Scanning and Listing Module: Include directory scanning (dir_scan.c), listing (dirlist.c), and directory handling (dir_export, dir_import, dir_mem, and dir_common modules).
- File Exclusion: Indicate the exclude module (exclude.c/h) that filters out certain directories/files.
- File Operation / Command Modules:
- Delete Module: Handle actions such as file/folder deletion.
- Auxiliary Commands: Such as shell operations that might provide a deeper shell integration.
- Utility and Shared Libraries:
- Utility Module: Represent universal functions (util.c/h, global defines) that aid in supporting the behavior across modules.
- External Dependencies: Show the dependency on curses libraries for UI rendering and any other packaged dependency in the deps folder.

##### Relationships and Interactions
- Bidirectional flows between the UI components (browser, shell, help, quit) and the directory scanning engine, reflecting the interactive discovery and subsequent operations.
- Utility modules are depicted as shared resources that are accessed by most other components.

##### Architectural Patterns and Design Principles
- Modular design: Each major function (UI, scanning, command operations) is implemented in its own set of files—illustrating a clean separation of concerns.
- Layered architecture: Define layers (UI, business logic/data scanning, lower-level utilities) to emphasize how high-level components depend on lower-level support functions.
- Inter-component communication: Use of clearly defined interfaces (as seen by the .h header files for each module) aids communication and maintenance.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Main Program"
        main["Main Program - main.c"]:::core
    end

    subgraph "User Interface (ncurses)"
        browser["Browser Module"]:::ui
        shell["Shell Module"]:::ui
        help["Help Module"]:::ui
        quit["Quit Module"]:::ui
    end

    subgraph "Directory Scanning & Handling"
        scan["Scanning Module (dir_scan)"]:::backend
        list["Directory Listing (dirlist)"]:::backend
        common["Common Operations (dir_common)"]:::backend
        export["Export Operations (dir_export)"]:::backend
        import["Import Operations (dir_import)"]:::backend
        mem["Memory Management (dir_mem)"]:::backend
        exclude["Exclusion Filtering (exclude)"]:::backend
    end

    subgraph "File Operation Module"
        delete["Delete Operations"]:::command
    end

    subgraph "Utility & Shared Libraries"
        util["General Utilities (util)"]:::util
        global["Global Definitions (global)"]:::util
    end

    subgraph "External Dependencies"
        deps["Bundled Dependencies"]:::external
    end

    subgraph "Documentation"
        docs["Documentation (ncdu.pod)"]:::doc
    end

    %% Connections from Main Program
    main -->|"init_UI"| browser
    main -->|"init_UI"| shell
    main -->|"init_UI"| help
    main -->|"init_UI"| quit
    main -->|"start_scan"| scan

    %% UI interactions with Scanning Engine
    browser -->|"interact_with"| scan
    shell -->|"interact_with"| scan
    help -->|"interact_with"| scan
    quit -->|"interact_with"| scan

    %% Command module triggered by UI and operating on scanning engine
    delete -->|"triggered_by_UI"| scan

    %% Internal Directory Scanning interactions
    scan -->|"fetch_listing"| list
    list -->|"calls"| common
    list -->|"calls"| export
    list -->|"calls"| import
    list -->|"calls"| mem
    list -->|"calls"| exclude

    %% Utility usage across components
    browser --- util
    shell --- util
    help --- util
    quit --- util
    scan --- util
    list --- util
    delete --- util

    %% External dependency usage for UI components
    browser --- deps
    shell --- deps
    help --- deps
    quit --- deps

    %% Style definitions
    classDef core fill:#D8BFD8,stroke:#000,stroke-width:2px;
    classDef ui fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef backend fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef command fill:#FFDAB9,stroke:#000,stroke-width:2px;
    classDef util fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef external fill:#FFC0CB,stroke:#000,stroke-width:2px;
    classDef doc fill:#FFFACD,stroke:#000,stroke-width:2px;

    %% Click Events
    click main "https://github.com/rofl0r/ncdu/blob/master/src/main.c"
    click browser "https://github.com/rofl0r/ncdu/blob/master/src/browser.c"
    click browser "https://github.com/rofl0r/ncdu/blob/master/src/browser.h"
    click shell "https://github.com/rofl0r/ncdu/blob/master/src/shell.c"
    click shell "https://github.com/rofl0r/ncdu/blob/master/src/shell.h"
    click help "https://github.com/rofl0r/ncdu/blob/master/src/help.c"
    click help "https://github.com/rofl0r/ncdu/blob/master/src/help.h"
    click quit "https://github.com/rofl0r/ncdu/blob/master/src/quit.c"
    click quit "https://github.com/rofl0r/ncdu/blob/master/src/quit.h"
    click scan "https://github.com/rofl0r/ncdu/blob/master/src/dir_scan.c"
    click list "https://github.com/rofl0r/ncdu/blob/master/src/dirlist.c"
    click list "https://github.com/rofl0r/ncdu/blob/master/src/dirlist.h"
    click common "https://github.com/rofl0r/ncdu/blob/master/src/dir_common.c"
    click export "https://github.com/rofl0r/ncdu/blob/master/src/dir_export.c"
    click import "https://github.com/rofl0r/ncdu/blob/master/src/dir_import.c"
    click mem "https://github.com/rofl0r/ncdu/blob/master/src/dir_mem.c"
    click exclude "https://github.com/rofl0r/ncdu/blob/master/src/exclude.c"
    click exclude "https://github.com/rofl0r/ncdu/blob/master/src/exclude.h"
    click delete "https://github.com/rofl0r/ncdu/blob/master/src/delete.c"
    click delete "https://github.com/rofl0r/ncdu/blob/master/src/delete.h"
    click util "https://github.com/rofl0r/ncdu/blob/master/src/util.c"
    click util "https://github.com/rofl0r/ncdu/blob/master/src/util.h"
    click global "https://github.com/rofl0r/ncdu/blob/master/src/global.h"
    click deps "https://github.com/rofl0r/ncdu/tree/master/deps"
    click docs "https://github.com/rofl0r/ncdu/blob/master/doc/ncdu.pod"
```
