# kaiserrrrrr/aqtive architecture

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

- Interactive diagram: https://gitdiagram.com/kaiserrrrrr/aqtive
- Repository: https://github.com/kaiserrrrrr/aqtive

## Overview

##### Project type & purpose (from file tree + README)
This repo is a **single-purpose Arch Linux post-install automation tool** delivered as a **shell-based installer**. Users run:

- `curl -fsSL https://is.gd/aqtive | sh`

to bootstrap **LXQt desktop setup on Arch** “made effortless”.

##### File structure → architectural roles
Top-level files:

- `main.sh`
Likely the **entrypoint/orchestrator**: checks prerequisites, prompts/prints, calls scripts under `dist/`.

- `dist/`
Contains the “subsystems” / “modules”:
- `dist/install.sh` → the **main installation routine** (package install, enable services, configure LXQt session, etc.)
- `dist/config.sh` → **configuration layer** (variables, toggles, constants, environment detection, paths)
- `dist/clean.sh` → **cleanup / rollback-ish** steps (remove temp files, finalize state)

- `README.md`, `LICENSE` are documentation/legal (don’t need to be main nodes, but README informs “external actor: user on Arch”).

This strongly suggests a **pipeline architecture**: orchestrator → modules → OS components.

Because this is an installer, the “system” includes:
- **External network** (URL shortener + hosting where scripts are fetched)
- **User environment** (non-root user with sudo)
- **Shell runtime** (`sh`/`bash`)
- **Privilege escalation** (`sudo`)
- **Package manager** (`pacman`, possibly AUR helper if used—unknown from files, so keep generic unless confirmed)
- **System services** (`systemd`, display manager, NetworkManager, etc. if installed/enabled)
- **Filesystem configuration** (dotfiles, /etc config, LXQt configs)
- **Desktop environment components** (LXQt packages, X11/Wayland stack depending on what install does)

Shows who runs it and what external endpoints it depends on.
Shows `main.sh` and `dist/*` and what OS subsystems they manipulate.
Shows the runtime order: fetch → execute → config → install → clean → final state.

**Actors**
- *User (sudo-capable)*

**External services**
- *URL shortener* (`https://is.gd/aqtive`)
- *Script hosting origin* (e.g., GitHub raw / release artifact / hosted file; represent as “Remote script host”)

**Local system**
- *Arch Linux machine (post-archinstall)*
- Shell (`sh`/`bash`)
- `sudo`
- Package manager (`pacman`)
- Init/service manager (`systemd`)
- Filesystem (`/etc`, `$HOME`, `/var`)
- LXQt + dependencies (resulting installed components)

- User → Shell: “runs curl | sh”
- Shell → URL shortener → Remote script host: “HTTP(S) GET script”
- Shell → sudo: “elevated actions”
- Script → pacman: “install packages”
- Script → systemd: “enable/start services”
- Script → filesystem: “write config files”
- Script → LXQt environment: “install/configure desktop”

- `main.sh` (Entrypoint / Orchestrator)
- `dist/config.sh` (Configuration + environment detection)
- `dist/install.sh` (Install/Provision module)
- `dist/clean.sh` (Cleanup/Finalize module)

**Key interactions**
- `main.sh` → `dist/config.sh` (source/import variables, detect environment)
- `main.sh` → `dist/install.sh` (execute install workflow)
- `main.sh` → `dist/clean.sh` (cleanup and finalize)

**Each module’s external touchpoints**
- `install.sh` → `pacman` (package installation)
- `install.sh` → `systemd` (enable/start services)
- `install.sh` → filesystem (write configs)
- `config.sh` → filesystem (read system state; may read `/etc/os-release`, check existing configs)
- `clean.sh` → filesystem (remove temp files) and maybe pacman (remove build deps) if applicable

Model the runtime flow as steps:

##### `main.sh`
- validates environment (Arch, network, sudo)
- loads `dist/config.sh`
##### `main.sh` runs `dist/install.sh`
- installs packages (LXQt + deps)
- configures desktop/session and system services
##### `main.sh` runs `dist/clean.sh`
- cleanup temp artifacts
##### End state: “LXQt installed and configured”

- steps running as user
- steps invoking `sudo` (root-level actions)

That separation is essential for an installer’s “real architecture”.

##### Architectural patterns / design principles to highlight
- **Orchestrator + modules**: `main.sh` as coordinator; `dist/*` as single-responsibility modules.
- **Idempotency (desired)**: installers should be safe to re-run; if your scripts attempt that, represent checks (“if installed then skip”).
- **Separation of concerns**:
- config vs install vs cleanup
- **External dependency minimization**: relies on core OS tools (`curl`, `sh`, `sudo`, `pacman`, `systemctl`).

##### What “best” looks like for this repo

1. **System Context**: User ↔ Network ↔ Script host; User machine runs scripts; scripts operate on pacman/systemd/filesystem to produce LXQt environment.
2. **Internal Components**: `main.sh` orchestrates `dist/config.sh`, `dist/install.sh`, `dist/clean.sh`, each pointing to the OS dependencies they touch.
3. **Execution Sequence**: curl/redirect/fetch/execute → config → install → cleanup, with sudo boundaries.

That captures essentially all meaningful architecture in this project, with maximal clarity and without inventing nonexistent services.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================================================
  %% Diagram 1: C4-ish System Context (Installer in Environment)
  %% =========================================================
  subgraph "System Context (Aqtive: Arch LXQt Post-Install Automation)"
    direction TB

    subgraph "Actor"
      direction TB
      USER["User (sudo-capable)"]:::actor
    end

    subgraph "Network"
      direction TB
      SHORT["URL shortener (is.gd/aqtive)"]:::cloud
      HOST["Remote script host (raw/release artifact)"]:::cloud
    end

    subgraph "Local Arch Linux Machine"
      direction TB

      SHELL["Shell runtime (sh/bash)"]:::runtime

      subgraph "Privilege boundary"
        direction TB
        USPACE["User space (no root)"]:::boundary
        ROOT["Root operations (via sudo)"]:::boundary
      end

      SUDO["sudo (privilege escalation)"]:::os
      PACMAN["pacman (package manager)"]:::os
      SYSTEMD["systemd (service manager)"]:::os

      FS[("Filesystem state\n/etc, /var, $HOME/.config")]:::data
      LXQT["Resulting environment\nLXQt + dependencies"]:::result
    end

    USER -->|"runs: curl -fsSL is.gd/aqtive | sh"| SHELL
    SHELL -->|"HTTP(S)_GET"| SHORT
    SHORT -->|"redirects_to"| HOST
    HOST -->|"script_content"| SHELL

    SHELL -->|"invokes"| SUDO
    SUDO -->|"elevated_actions"| PACMAN
    SUDO -->|"systemctl_enable/start"| SYSTEMD
    SHELL -.->|"read/write_config"| FS
    SUDO -.->|"write_system_config"| FS
    PACMAN -->|"installs"| LXQT
    FS -->|"configs_affect"| LXQT
    SYSTEMD -->|"manages_services_for"| LXQT

    USPACE -.->|"executes_in"| SHELL
    ROOT -.->|"grants_privilege_via"| SUDO
  end

  %% =========================================================
  %% Diagram 2: Internal Components (Repo scripts & modules)
  %% =========================================================
  subgraph "Internal Components (Repository: Orchestrator + Modules)"
    direction TB

    subgraph "Aqtive Installer (scripts)"
      direction TB
      MAIN["Entrypoint: main.sh\n(Orchestrator)"]:::script

      subgraph "Installer modules (dist/)"
        direction TB
        CFG["Module: dist/config.sh\n(Configuration + env detection)"]:::module
        INST["Module: dist/install.sh\n(Provision: packages/services/config)"]:::module
        CLEAN["Module: dist/clean.sh\n(Cleanup + finalize)"]:::module
      end

      DOC["README.md\n(Usage / bootstrap command)"]:::doc
      LIC["LICENSE"]:::doc
    end

    MAIN -->|"sources/imports"| CFG
    MAIN -->|"executes"| INST
    MAIN -->|"executes"| CLEAN

    %% Module touchpoints to OS subsystems
    CFG -.->|"reads_system_state"| FS
    INST -->|"pacman_-S"| PACMAN
    INST -->|"systemctl_enable/start"| SYSTEMD
    INST -.->|"writes_configs"| FS
    CLEAN -.->|"removes_temp/finalizes"| FS
  end

  %% =========================================================
  %% Diagram 3: Execution Flow (Activity/Timeline)
  %% =========================================================
  subgraph "Execution Flow (Runtime Timeline with Privilege Boundary)"
    direction TB

    STEP1["1) User runs bootstrap\ncurl -fsSL is.gd/aqtive | sh"]:::step
    STEP2["2) Resolve redirect\nis.gd -> remote host"]:::step
    STEP3["3) Shell executes fetched script\n(main entry)"]:::step
    STEP4["4) main.sh validates prereqs\n(Arch, network, sudo)"]:::step
    STEP5["5) main.sh loads config.sh\n(vars/toggles/env detect)"]:::step
    STEP6U["6) install.sh performs user-level setup\n(dotfiles, session config)"]:::step
    STEP6R["7) install.sh performs root-level setup via sudo\n(pacman, systemd, /etc writes)"]:::step
    STEP7["8) clean.sh cleanup/finalize\n(remove temp artifacts)"]:::step
    STEP8["9) End state\nLXQt installed + configured"]:::step

    STEP1 --> STEP2 --> STEP3 --> STEP4 --> STEP5 --> STEP6U --> STEP6R --> STEP7 --> STEP8

    STEP6R -->|"installs"| PACMAN
    STEP6R -->|"enables/starts"| SYSTEMD
    STEP6U -.->|"writes_user_configs"| FS
    STEP6R -.->|"writes_system_configs"| FS
    STEP8 -->|"ready"| LXQT
  end

  %% -----------------------
  %% Click Events (mappings)
  %% -----------------------
  click MAIN "https://github.com/kaiserrrrrr/aqtive/blob/main/main.sh"
  click CFG "https://github.com/kaiserrrrrr/aqtive/blob/main/dist/config.sh"
  click INST "https://github.com/kaiserrrrrr/aqtive/blob/main/dist/install.sh"
  click CLEAN "https://github.com/kaiserrrrrr/aqtive/blob/main/dist/clean.sh"
  click DOC "https://github.com/kaiserrrrrr/aqtive/blob/main/README.md"
  click LIC "https://github.com/kaiserrrrrr/aqtive/tree/main/LICENSE"

  %% Provide click for directory via an invisible anchor node
  DISTDIR["dist/ (modules directory)"]:::hidden
  click DISTDIR "https://github.com/kaiserrrrrr/aqtive/tree/main/dist/"

  %% -------------
  %% Styling
  %% -------------
  classDef actor fill:#FFE2B8,stroke:#B46B00,color:#3A2400,stroke-width:1px
  classDef cloud fill:#D7ECFF,stroke:#1E6AA8,color:#08304F,stroke-width:1px
  classDef runtime fill:#E7E7FF,stroke:#4B4BB7,color:#1C1C5A,stroke-width:1px
  classDef os fill:#E9FFF2,stroke:#1D7A3A,color:#0E3B1B,stroke-width:1px
  classDef data fill:#FFF3D6,stroke:#B07A00,color:#3B2A00,stroke-width:1px
  classDef result fill:#DFF7E8,stroke:#2E8B57,color:#103A24,stroke-width:1px
  classDef script fill:#FFD6E7,stroke:#A1004F,color:#4A0023,stroke-width:1.2px
  classDef module fill:#FFE3F1,stroke:#A1004F,color:#4A0023,stroke-width:1px
  classDef doc fill:#F2F2F2,stroke:#6B6B6B,color:#222,stroke-width:1px
  classDef boundary fill:#FFFFFF,stroke:#9A9A9A,color:#333,stroke-dasharray:5 4
  classDef step fill:#FFF,stroke:#7A7A7A,color:#222,stroke-width:1px
  classDef hidden fill:#FFFFFF,stroke:#FFFFFF,color:#FFFFFF,stroke-width:0px
```
