# sminez/penrose architecture

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

- Interactive diagram: https://gitdiagram.com/sminez/penrose
- Repository: https://github.com/sminez/penrose

## Overview

##### Project Type and Purpose
- The project is a “tiling window manager library” meant to be used as a dependency in your own Rust crate.
- Its purpose is to provide a minimal yet extensible core for managing X11 windows, including state management (the “pure” part), rendering (diff-and-render mechanism), and handling events via hooks/extensions.

##### File Structure
- Notice the top-level directories like “crates,” “src,” “docs,” “examples,” “scripts,” and “tests”. The “crates” directory breaks out functionality into separate libraries:
- penrose_keysyms: Likely handles keyboard symbols and key binding resolution.
- penrose_menu: Provides facilities for creating dynamic menus.
- penrose_ui: Handles UI components, status bars, layout rendering, and includes further subdivision for bar widgets.
- The “src” directory holds the core implementation and extensions:
- “src/core” – Contains core window manager logic including bindings, layout, event handling, and hook mechanisms.
- “src/pure” – Implements pure functions for state management (e.g., geometry, workspace, stack management).
- “src/extensions” – Contains user-extensible modules like additional actions, hooks for startup, EWMH compliance, and utility functions.
- “src/x” and “src/x11rb” – Abstractions for interacting with the X window system.

##### Key Components
a. Core Library:
- Break this into “Core State Management” (the “pure” module) and the “Diff-Render Layer” (responsible for rendering updates to X11).
- That the core handles event loops and state transitions.
b. X11 Abstraction Layer:
- Modules under “src/x”/“src/x11rb” that communicate with the X server.
c. Extensions & Builtins:
d. Auxiliary Crates:
- Separate but closely related crates from the “crates” folder:
- penrose_keysyms: Manages key bindings.
- penrose_menu: Provides dynamic menu capabilities.
- penrose_ui: Supports UI components and status bars.
e. Examples, Tests, and Docs:
- Briefly note that examples illustrate use cases and are entry points for users. Documentation and test directories ensure maintainability and clarity of usage.

##### Relationships and Interactions
- That the application using Penrose will:
- Instantiate core state and configure built-in actions.
- Use extension hooks to customize the window manager behavior.
- Communicate with the X server via the X11 abstraction layer.
- Rely on auxiliary crates (keysyms, menu, ui) for handling user input, rendering UI elements, and managing custom layouts.
- From user inputs (e.g., keyboard events) to the keybinding system (penrose_keysyms) and then on to the core event loop.
- From core state transitions through “diff and render” to the actual X11 update process.
- Between the extensions/builtin modules and the core to illustrate plugin-style integrations.

##### Architectural Patterns & Design Principles
- The library adheres to a modular design with clean separation between “pure” logic (state manipulation) and side-effect layers (interfacing with X11).
- It makes use of trait-based APIs designed for extensibility, allowing users to plug in custom modules.
- The layered architecture (core, extensions, X abstraction) can be visually depicted as a stack where each layer has a well-defined role.
- Usage of separate crates for pieces like UI and menus shows a preference for reusability and independent testing.

## Diagram (Mermaid)

```mermaid
graph TD
    user["User's Window Manager"]:::user

    subgraph "Penrose Library"
        subgraph "Core System"
            pure["Core State Management (Pure)"]:::core
            diff["Diff-Render Layer"]:::core
            coreLogic["Core Window Manager Logic & Event Handling"]:::core
            extensions["Extensions"]:::core
            builtin["Builtin Modules"]:::core
        end
        subgraph "X11 Abstraction Layer"
            x11["X11 Abstraction (src/x)"]:::x11
            x11rb["X11 Abstraction (src/x11rb)"]:::x11
        end
        subgraph "Auxiliary Crates"
            keysyms["Key Binding Management"]:::aux
            menu["Dynamic Menu Capabilities"]:::aux
            ui["UI Components and Status Bars"]:::aux
        end
    end

    subgraph "Supporting"
        docs["Documentation & Diagrams"]:::support
        examples["Usage Examples"]:::support
    end

    user -->|"instantiates"| coreLogic
    user -->|"sends_input"| keysyms
    user -->|"references"| docs
    user -->|"references"| examples

    keysyms -->|"interprets_keys"| coreLogic
    coreLogic -->|"updates_state"| pure
    pure -->|"triggers_diff_render"| diff
    diff -->|"updates_X"| x11
    diff -->|"updates_X"| x11rb
    extensions -->|"extends"| coreLogic
    builtin -->|"integrates_with"| coreLogic
    menu -->|"triggers_action"| coreLogic
    ui -->|"requests_layout"| coreLogic

    click pure "https://github.com/sminez/penrose/tree/develop/src/pure"
    click diff "https://github.com/sminez/penrose/blob/develop/src/pure/diff.rs"
    click coreLogic "https://github.com/sminez/penrose/tree/develop/src/core"
    click x11 "https://github.com/sminez/penrose/tree/develop/src/x"
    click x11rb "https://github.com/sminez/penrose/tree/develop/src/x11rb"
    click extensions "https://github.com/sminez/penrose/tree/develop/src/extensions"
    click builtin "https://github.com/sminez/penrose/tree/develop/src/builtin"
    click keysyms "https://github.com/sminez/penrose/tree/develop/crates/penrose_keysyms"
    click menu "https://github.com/sminez/penrose/tree/develop/crates/penrose_menu"
    click ui "https://github.com/sminez/penrose/tree/develop/crates/penrose_ui"
    click docs "https://github.com/sminez/penrose/tree/develop/docs"
    click examples "https://github.com/sminez/penrose/tree/develop/examples"

    classDef core fill:#e0bbff,stroke:#9b59b6,stroke-width:2px;
    classDef x11 fill:#85C1E9,stroke:#2980B9,stroke-width:2px;
    classDef aux fill:#82E0AA,stroke:#27AE60,stroke-width:2px;
    classDef support fill:#F9E79F,stroke:#F1C40F,stroke-width:2px;
    classDef user fill:#D5DBDB,stroke:#616A6B,stroke-width:2px;
```
