# bismuth-forge/bismuth architecture

> Architecture diagram of the GitHub repository bismuth-forge/bismuth, 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/bismuth-forge/bismuth
- Repository: https://github.com/bismuth-forge/bismuth

## Overview

##### Main Components
- Build & Utility Infrastructure:
– Files like CMakeLists.txt, Makefile, various shell scripts (in /scripts and /github/scripts) show that the project is built using CMake and Make, and it includes scripts for building, testing, and installation.
- Core Functionality (src/core):
– This component (controller.cpp/hpp, qmldir, ts-proxy, etc.) handles the basic window tiling logic, configuration reading, and logic common to the application.
- Configuration and Integration with KDE Settings (src/config and src/kcm):
– The src/config directory contains configuration definitions and CMake configurations.
– The src/kcm folder contains the KDE Control Module (KCM) for configuring Bismuth from the System Settings. This includes QML user interface files and config definitions.
- Window Decorations (src/kdecoration):
– This module provides the window decoration logic (e.g., border-only decorations) integrating with Plasma’s appearance settings.
- KWin Scripting and Layout Engine (src/kwinscript):
– A large subtree in this folder shows the use of TypeScript for KWin scripting, layout algorithms (tile, cascade, spiral, etc.), and both the engine and controller pieces.
– This is where different window layout algorithms reside and where the tiling behavior is implemented.
- Testing & External Dependencies:
– The tests folder (with CMakeLists.txt and core tests) and the external/doctest library help set up automated testing.

##### Relationships and Interactions
- The KCM (in src/kcm) exposes configuration settings via a QML-based UI. When a user changes settings, these configurations are passed to the Core Functionality (src/core) and the Window Tiling logic.
- The Core Layer acts as a bridge between the configuration, user commands, and real-time window management.
- The KWin Script module (src/kwinscript) implements the actual tiling algorithms and layout management. It listens to window events triggered by the Plasma shell/KWin, processes them (often invoking layout-specific code), and then calls back into the core logic if needed.
- The Window Decoration module (src/kdecoration) uses the core logic’s decisions to alter window style and appearance.
- The build system and scripts ensure these components are compiled, tested, and packaged correctly.

##### Architectural Patterns and Key Technologies
- Modular Design: Each of the main components (core, config, KCM, decoration, and scripting) are organized into separate subdirectories with their own CMakeLists.txt files, indicating a highly modular structure.
- Integration Pattern: There is a clear separation between UI (KCM/QML), business logic (core and configuration), and the tiling engine (kwinscript). Data flows from the user configuration interface to the core logic and is then used to drive the KWin scripting engines.
- Technologies & Libraries:
– C++ (for core logic, kcm, decoration)
– TypeScript/JavaScript (for the kwinscript engine)
– Qt/QML (for UI components and QML plugins)
– CMake (for the build process)
– KDE Frameworks (to integrate with Plasma and KWin)

##### Specific Elements to Be Included
- Module/component with labels (e.g., “Src/Core”, “Src/KCM”, “Src/KWinScript”).

## Diagram (Mermaid)

```mermaid
flowchart TD

  %% Build & Utility Infrastructure Subgraph
  subgraph "Build & Utility Infrastructure"
    buildCMake["CMakeLists.txt"]:::build
    buildMake["Makefile"]:::build
    buildScripts["Scripts (/scripts, /.github/scripts)"]:::build
  end

  %% Configuration Module (KCM & Config) Subgraph
  subgraph "Configuration Module (KCM & Config)"
    config["src/config"]:::cpp
    kcm["src/kcm"]:::cpp
  end

  %% Core Logic Subgraph
  subgraph "Core Logic"
    core["src/core (controller.cpp, qmldir, ts-proxy, etc.)"]:::cpp
  end

  %% KWin Scripting & Layout Engine Subgraph
  subgraph "KWin Scripting & Layout Engine"
    kwin["src/kwinscript (layout algorithms, controller, driver)"]:::ts
  end

  %% Window Decoration Subgraph
  subgraph "Window Decoration"
    decoration["src/kdecoration (decoration.cpp, metadata.json)"]:::cpp
  end

  %% Testing & External Dependencies Subgraph
  subgraph "Testing & External Dependencies"
    tests["tests (CMakeLists.txt, core tests)"]:::test
    doctest["external/doctest"]:::test
  end

  %% External System Node
  plasma["KDE Plasma"]:::external

  %% Interactions and Data Flow
  kcm -->|"UserSettings/ConfigUpdates"| core
  config -->|"UserSettings/ConfigUpdates"| core
  core -->|"WindowManagementEvents"| kwin
  kwin -->|"LayoutDecisions"| decoration
  plasma -->|"IntegratesWith"| kcm
  plasma -->|"IntegratesWith"| config

  %% Build Infrastructure builds the modules
  buildCMake -->|"Builds"| config
  buildCMake -->|"Builds"| core
  buildCMake -->|"Builds"| kwin
  buildCMake -->|"Builds"| decoration

  %% Testing Infrastructure
  tests -->|"Tests"| core
  tests -->|"Tests"| kwin

  %% Click Events for Build & Utility Infrastructure
  click buildCMake "https://github.com/bismuth-forge/bismuth/blob/master/CMakeLists.txt"
  click buildMake "https://github.com/bismuth-forge/bismuth/tree/master/Makefile"
  click buildScripts "https://github.com/bismuth-forge/bismuth/tree/master//scripts"
  click buildScripts "https://github.com/bismuth-forge/bismuth/tree/master//.github/scripts"

  %% Click Events for Core Functionality
  click core "https://github.com/bismuth-forge/bismuth/tree/master/src/core"

  %% Click Events for Configuration and KDE Integration
  click config "https://github.com/bismuth-forge/bismuth/tree/master/src/config"
  click kcm "https://github.com/bismuth-forge/bismuth/tree/master/src/kcm"

  %% Click Event for Window Decorations
  click decoration "https://github.com/bismuth-forge/bismuth/tree/master/src/kdecoration"

  %% Click Event for KWin Scripting & Layout Engine
  click kwin "https://github.com/bismuth-forge/bismuth/tree/master/src/kwinscript"

  %% Click Events for Testing & External Dependencies
  click tests "https://github.com/bismuth-forge/bismuth/tree/master/tests"
  click doctest "https://github.com/bismuth-forge/bismuth/tree/master/external/doctest"

  %% Styles
  classDef build fill:#d3d3d3,stroke:#333,stroke-width:2px;
  classDef cpp fill:#add8e6,stroke:#000,stroke-width:2px;
  classDef ts fill:#90ee90,stroke:#000,stroke-width:2px;
  classDef test fill:#ffcccb,stroke:#000,stroke-width:2px;
  classDef external fill:#f5deb3,stroke:#000,stroke-width:2px;
```
