# amlanjlahkar/dwots architecture

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

- Interactive diagram: https://gitdiagram.com/amlanjlahkar/dwots
- Repository: https://github.com/amlanjlahkar/dwots

## Overview

##### Project type and purpose
- This is a “dotfiles”/configuration‐management project for a personal Linux workstation. It collects shell scripts, X11 settings, terminal and window‐manager configs, and uses GNU Stow to symlink them into place.

##### File structure
- Top‐level:
- etc/… : configuration snippets for system‐wide services (X11, doas)
- home/… : per‐user configs under stow groups (X11, gtk, shell, term, wm, etc.)
- home/stowd : installation wrapper script to invoke GNU Stow
- pkglist/… : lists of installed packages (ancillary data)
- Patterns: each directory under home/ corresponds to a stow “package” that, when stowed, symlinks into ~/.config or home root.

##### Key insights from README
- Project purpose: “restore local files” by cloning repo and running stowd
- Usage: stowd script automates `stow -t $HOME …` and `stow -U` for cleanup
- Dependencies: GNU Stow, Bash

a. Main components
- Git host (GitHub) – source of the repository
- Local Git clone (~/dwots) – filesystem container for all dotfiles
- stowd installer script – entry point that invokes GNU Stow
- GNU Stow utility – symlink manager
- Target filesystem locations:
– $HOME/ directories and dotfiles (e.g. ~/.bashrc, ~/.config/i3/config)
– /etc/X11/xorg.conf.d/… for system‐wide config
b. Relationships and interactions
- User runs `git clone` → repository files appear under ~/dwots
- User invokes `./stowd` → stowd calls GNU Stow on each “package” subdirectory under home/ and etc/
- GNU Stow reads package definitions → creates symbolic links from repo paths to actual target paths (e.g. home/wm/i3/.config/i3/config → ~/.config/i3/config)
- Uninstall (`stow -U`) reverses the symlinking
c. Architectural patterns and design principles
- Declarative configuration: all settings live in Git, changes propagate via symlinks
- Single‐responsibility scripts: stowd only orchestrates GNU Stow
- Modular structure: each stow package is an independent group (X11, shell, wm, etc.)
d. Technologies, frameworks, or libraries
- GNU Stow (symlink farm manager)
- Bash (stowd script and custom shell scripts)
- Host Linux filesystem hierarchy (home directory, /etc)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Nodes
    GitHub["Remote Git Repository (GitHub)"]:::code
    LocalRepo["Local Repository (~/dwots)"]:::code
    Stowd["stowd Installer Script"]:::tool
    GNUStow["GNU Stow Utility"]:::tool
    Target["Target Filesystem"]:::fs

    %% Target subgraphs
    subgraph "Target Filesystem"
        direction TB
        HOME["$HOME Directory"]:::fs
        ETCFS["/etc Directory"]:::fs
    end

    %% Local repo structure
    subgraph "Local Repository (~/dwots)"
        direction TB
        README["README.md"]:::code
        subgraph "Configuration Packages"
            direction TB
            subgraph "etc/ (System-wide configs)"
                direction TB
                ETCpkg["etc/"]:::code
            end
            subgraph "home/ (User configs)"
                direction TB
                X11pkg["X11 Package"]:::code
                GTKpkg["GTK Package"]:::code
                Otherpkg["Other Apps Package"]:::code
                ShScripts["Shell Scripts Package"]:::code
                ShUtils["Shell Utils Package"]:::code
                Shellpkg["Shell Package"]:::code
                Termpkg["Terminal Package"]:::code
                Wmpkg["Window Manager Package"]:::code
                WMUtilspkg["WM Utilities Package"]:::code
                XDGpkg["xdg-user-dirs Package"]:::code
            end
        end
        PKGLIST["pkglist/void-pkglist.txt"]:::code
    end

    %% Connections
    GitHub -->|"git clone"| LocalRepo
    LocalRepo -->|"execute ./stowd"| Stowd
    Stowd -->|"invokes"| GNUStow
    GNUStow -->|"creates symlinks"| HOME
    GNUStow -->|"creates symlinks"| ETCFS
    GNUStow -.->|"stow -U uninstall"| HOME

    %% Click events
    click LocalRepo "https://github.com/amlanjlahkar/dwots/tree/main/./"
    click Stowd "https://github.com/amlanjlahkar/dwots/tree/main/home/stowd"
    click ETCpkg "https://github.com/amlanjlahkar/dwots/tree/main/etc/"
    click X11pkg "https://github.com/amlanjlahkar/dwots/tree/main/home/X11"
    click GTKpkg "https://github.com/amlanjlahkar/dwots/tree/main/home/gtk"
    click Otherpkg "https://github.com/amlanjlahkar/dwots/tree/main/home/other"
    click ShScripts "https://github.com/amlanjlahkar/dwots/tree/main/home/sh_scripts"
    click ShUtils "https://github.com/amlanjlahkar/dwots/tree/main/home/sh_utils"
    click Shellpkg "https://github.com/amlanjlahkar/dwots/tree/main/home/shell"
    click Termpkg "https://github.com/amlanjlahkar/dwots/tree/main/home/term"
    click Wmpkg "https://github.com/amlanjlahkar/dwots/tree/main/home/wm"
    click WMUtilspkg "https://github.com/amlanjlahkar/dwots/tree/main/home/wm_utils"
    click XDGpkg "https://github.com/amlanjlahkar/dwots/tree/main/home/xdg-user-dirs"
    click PKGLIST "https://github.com/amlanjlahkar/dwots/blob/main/pkglist/void-pkglist.txt"
    click README "https://github.com/amlanjlahkar/dwots/blob/main/README.md"

    %% Styles
    classDef code fill:#BBDEFB,stroke:#1E88E5,stroke-width:1px
    classDef tool fill:#C8E6C9,stroke:#388E3C,stroke-width:1px
    classDef fs fill:#FFE0B2,stroke:#FB8C00,stroke-width:1px
```
