# dgame/dgame-system architecture

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

- Interactive diagram: https://gitdiagram.com/dgame/dgame-system
- Repository: https://github.com/dgame/dgame-system

## Overview

##### Project type and purpose
- This is an infrastructure‐as‐code / configuration management project built on Ansible.
- Purpose: automate installation and configuration of a developer’s workstation (shells, editors, programming languages, tools, browsers, container engines, credentials, etc.) across multiple Linux distributions (Arch, Manjaro, Debian) and WSL.

##### File structure
- Top‐level “*.mk” files (arch.mk, debian.mk, manjaro.mk) and Makefile targets drive the installation.
- Distro‐specific playbooks (arch.yml, manjaro.yml, debian.yml, wsl-*.yml) define which roles to run per environment.
- “roles/” directory contains dozens of Ansible roles (system, shell, editor, programming, terminal, browser, docker, credentials, etc.). Each role encapsulates idempotent tasks, default vars, handlers, and metadata.
- “molecule/” directory holds Molecule scenarios for each platform: they spin up a container/VM, run converge.yml, and optionally run tests.
- CI/CD config (.github/workflows/workflow.yml) orchestrates linting, Molecule tests, perhaps test-playbook runs.

##### README for additional insights
- The README shows supported platforms, the install process via Make targets, and a checklist of components the playbook manages.
- It mentions Docker Desktop/WLS integration for local testing and development.

##### Main components & relationships
- Developer’s Workstation (CLI / Git)
- Makefile targets & .mk files (orchestration layer)
- Ansible Engine / Playbook Runner
- Inventory & Playbooks (arch.yml, debian.yml, wsl-*.yml)
- Roles collection (roles/*, grouped by category)
- Molecule Test Harness (docker/wsl driver, converge.yml, tests)
- Target Hosts (bare‐metal Linux distros or WSL distributions)
- External dependencies (Docker daemon, WSL subsystem)
b. Data flows & interactions:
- Developer invokes `make -f <distro>.mk install` → calls Ansible CLI.
- Ansible CLI reads inventory (playbook file) → loads roles → executes tasks on target.
- For CI/testing: CI config triggers Molecule, which uses Docker/WSL to spin up an ephemeral target, runs test converge, then assertions.
- Roles pull packages from package managers (pacman, apt), configure files in /etc, user dotfiles, etc.
c. Architectural patterns/design principles:
- Modular design—each role focuses on one concern (single responsibility).
- Idempotency—Ansible ensures safe repeated runs.
- Test‐driven infrastructure—Molecule scenarios validate roles.
- Environment abstraction—inventory overlays control which roles run per distro.
d. Key technologies/frameworks/libraries:
- Ansible (playbooks, roles)
- Molecule (testing)
- Docker (container driver)
- WSL (Windows target)
- Make (task orchestration)
- Linux package managers (pacman, apt)
- GitHub Actions (CI)

## Diagram (Mermaid)

```mermaid
flowchart TB
    Dev["Developer Workstation (CLI/Git)"]:::external

    subgraph "Orchestration Layer"
        MakeArch["arch.mk"]:::orchestration
        MakeDeb["debian.mk"]:::orchestration
        MakeMan["manjaro.mk"]:::orchestration
        CI["CI/CD Workflow"]:::orchestration
    end

    subgraph "Configuration Engine"
        Ansible["Ansible Engine/Runner"]:::engine
        Inventory["Inventory & Playbooks"]:::storage
        InventoryDetails["arch.yml, debian.yml,\nmanjaro.yml, wsl-*.yml, hosts"]:::storage
    end

    subgraph "Roles Library"
        subgraph "System Roles"
            SysApt["roles/system/apt"]:::role
            SysPac["roles/system/pacman"]:::role
            SysBase["roles/system/base-dev"]:::role
        end
        subgraph "Shell Roles"
            ShellFish["roles/shell/fish"]:::role
            ShellZsh["roles/shell/zsh"]:::role
        end
        subgraph "Editor Roles"
            EditorVim["roles/editor/vim"]:::role
            EditorVS["roles/editor/vs_code"]:::role
        end
        subgraph "Programming Roles"
            ProgPy["roles/programming/python"]:::role
            ProgRust["roles/programming/rust"]:::role
        end
        subgraph "Terminal Roles"
            TermTmux["roles/terminal/tmux"]:::role
            TermAlac["roles/terminal/alacritty"]:::role
        end
        subgraph "Browser Roles"
            BrowFire["roles/browser/firefox"]:::role
            BrowBrave["roles/browser/brave"]:::role
        end
        DockerRole["roles/docker"]:::role
        CredRole["roles/credentials"]:::role
    end

    subgraph "Test Harness (Molecule)"
        MoleculeCore["Molecule Scenarios"]:::engine
    end

    subgraph "Targets"
        Hosts["Target Hosts\n(Arch, Debian, Manjaro, WSL)"]:::target
        Containers["Test Containers\n(Docker/WSL)"]:::target
    end

    Dev -->|"invoke make"| MakeArch
    Dev --> MakeDeb
    Dev --> MakeMan
    MakeArch -->|"calls Ansible CLI"| Ansible
    MakeDeb --> Ansible
    MakeMan --> Ansible
    CI -->|"runs Molecule"| MoleculeCore

    Ansible -->|"reads inventory"| Inventory
    Inventory --> InventoryDetails
    Ansible -->|"loads roles"| SysApt
    Ansible --> SysPac
    Ansible --> SysBase
    Ansible --> ShellFish
    Ansible --> ShellZsh
    Ansible --> EditorVim
    Ansible --> EditorVS
    Ansible --> ProgPy
    Ansible --> ProgRust
    Ansible --> TermTmux
    Ansible --> TermAlac
    Ansible --> BrowFire
    Ansible --> BrowBrave
    Ansible --> DockerRole
    Ansible --> CredRole
    Ansible -->|"applies playbook"| Hosts

    MoleculeCore -->|"spin up"| Containers
    MoleculeCore -->|"run converge"| Ansible
    MoleculeCore -->|"validate roles"| SysApt
    MoleculeCore --> CredRole

    classDef orchestration fill:#D0E6FF,stroke:#0366d6,color:#0366d6;
    classDef engine fill:#E6FFEB,stroke:#28A745,color:#28A745;
    classDef storage fill:#E6FFEB,stroke:#20c997,color:#20c997;
    classDef role fill:#FFF4E6,stroke:#FD7E14,color:#FD7E14;
    classDef target fill:#F0F0F0,stroke:#6c757d,color:#6c757d;
    classDef external fill:#F5E6FF,stroke:#6f42c1,color:#6f42c1;

    click MakeArch "https://github.com/dgame/dgame-system/blob/master/arch.mk"
    click MakeDeb "https://github.com/dgame/dgame-system/blob/master/debian.mk"
    click MakeMan "https://github.com/dgame/dgame-system/blob/master/manjaro.mk"
    click CI "https://github.com/dgame/dgame-system/blob/master/.github/workflows/workflow.yml"
    click Ansible "https://github.com/dgame/dgame-system/blob/master/roles/ansible/tasks/main.yml"
    click InventoryDetails "https://github.com/dgame/dgame-system/blob/master/arch.yml"
    click InventoryDetails "https://github.com/dgame/dgame-system/blob/master/debian.yml"
    click InventoryDetails "https://github.com/dgame/dgame-system/blob/master/manjaro.yml"
    click InventoryDetails "https://github.com/dgame/dgame-system/blob/master/wsl-arch.yml"
    click InventoryDetails "https://github.com/dgame/dgame-system/blob/master/wsl-debian.yml"
    click InventoryDetails "https://github.com/dgame/dgame-system/blob/master/wsl-manjaro.yml"
    click SysApt "https://github.com/dgame/dgame-system/blob/master/roles/system/apt/tasks/main.yml"
    click SysPac "https://github.com/dgame/dgame-system/blob/master/roles/system/pacman/tasks/main.yml"
    click SysBase "https://github.com/dgame/dgame-system/blob/master/roles/system/base-dev/tasks/main.yml"
    click ShellFish "https://github.com/dgame/dgame-system/blob/master/roles/shell/fish/tasks/main.yml"
    click ShellZsh "https://github.com/dgame/dgame-system/blob/master/roles/shell/zsh/tasks/main.yml"
    click EditorVim "https://github.com/dgame/dgame-system/blob/master/roles/editor/vim/tasks/main.yml"
    click EditorVS "https://github.com/dgame/dgame-system/blob/master/roles/editor/vs_code/tasks/main.yml"
    click ProgPy "https://github.com/dgame/dgame-system/blob/master/roles/programming/python/tasks/main.yml"
    click ProgRust "https://github.com/dgame/dgame-system/blob/master/roles/programming/rust/tasks/main.yml"
    click TermTmux "https://github.com/dgame/dgame-system/blob/master/roles/terminal/tmux/tasks/main.yml"
    click TermAlac "https://github.com/dgame/dgame-system/blob/master/roles/terminal/alacritty/tasks/main.yml"
    click BrowFire "https://github.com/dgame/dgame-system/blob/master/roles/browser/firefox/tasks/main.yml"
    click BrowBrave "https://github.com/dgame/dgame-system/blob/master/roles/browser/brave/tasks/main.yml"
    click DockerRole "https://github.com/dgame/dgame-system/blob/master/roles/docker/tasks/main.yml"
    click CredRole "https://github.com/dgame/dgame-system/blob/master/roles/credentials/tasks/main.yml"
    click MoleculeCore "https://github.com/dgame/dgame-system/blob/master/molecule/arch/molecule.yml"
```
