# tdaron/tdawm architecture

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

- Interactive diagram: https://gitdiagram.com/tdaron/tdawm
- Repository: https://github.com/tdaron/tdawm

## Overview

##### Project type and purpose
- This is a systems-level application: an X11 window manager (“TDAWm”) written in Rust.
- It sits between the X server and user applications, managing windows, layouts, workspaces, screens, and event dispatch.

##### File structure
- src/main.rs: entry point, initializes the event loop and the window-manager context.
- src/x11.rs: low-level X11 bindings / wrappers—connection, event fetching, Xlib calls.
- src/tdawm/: core WM domain objects and logic
- context.rs: global state (open windows, workspaces, screens)
- tdawm.rs: main WM loop, event dispatcher, command router
- screen.rs / workspace.rs / window.rs: representations of physical displays, virtual desktops, individual windows
- src/layouts/: layout algorithms (vertical, horizontal, dwm-style)
- justfile, Cargo.toml: build & run tooling

##### README
- Confirms it is a proof-of-concept X11 WM.
- No external services, just X11 on Linux.
- Roadmap: multi-screen, EWMH support—future expansions.

##### Components
a. Main components
1. X Server (external service)
2. X11 Client Library (src/x11.rs)
3. WM Core
- Event Loop & Dispatcher (tdawm.rs)
- Context (context.rs)
4. Data Models
- Screens (screen.rs)
- Workspaces (workspace.rs)
- Windows (window.rs)
5. Layout Engine (vertical.rs, horizontal.rs, dwm.rs)
6. Configuration Loader (config/mod.rs)
7. CLI / Entry Point (main.rs)
b. Relationships and interactions
- Entry Point (main.rs) calls Config Loader → initializes Context → connects to X11 via x11.rs → enters Event Loop in tdawm.rs.
- Event Loop pulls events from X Server (via x11.rs) → Dispatcher routes to handlers (window mapping, focus changes, reflows).
- Layout Engine computes window placements within each Workspace on each Screen.
- Context updates Data Models (Screens, Workspaces, Windows).
- Config controls keybindings and layout choices.
c. Architectural patterns
- Modular separation: low-level X11 API vs. core WM logic vs. layout algorithms.
- Single event loop (reactor pattern) dispatching to subsystems.
- MVC-like: Model = Context + Data Models; Controller = Dispatcher / tm loop; View = X11 redraw calls.
d. Key technologies
- Rust (Cargo)
- Xlib bindings (via x11.rs)
- justfile (task runner)

##### Detailed capture of essential elements
- Stateful context store that holds open windows/workspaces/screens.
- Modular plug-in nature of layouts and the config loader.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External services
    XServer["X Server"]:::external

    %% Entry point and config
    Main["CLI / Entry Point\nmain.rs"]:::entry
    Config["Configuration Loader\nconfig/mod.rs"]:::config

    %% Low-level API
    X11Client["X11 Client (x11.rs)"]:::lowLevel

    %% Core modules
    subgraph "WM Core"
        WCModule["WM Core Module\nsrc/tdawm/mod.rs"]:::core
        EventLoop["Event Loop & Dispatcher\ntdawm.rs"]:::core
        Context["Context (global state)\ncontext.rs"]:::core
    end

    %% Data models
    subgraph "Data Models"
        Screens["Screens\nscreen.rs"]:::model
        Workspaces["Workspaces\nworkspace.rs"]:::model
        Windows["Windows\nwindow.rs"]:::model
    end

    %% Layout engine plugins
    subgraph "Layout Engine"
        LayoutMod["Core Module\nlayouts/mod.rs"]:::plugin
        DWM["dwm-style layout\nlayouts/dwm.rs"]:::plugin
        Horizontal["horizontal layout\nlayouts/horizontal.rs"]:::plugin
        Vertical["vertical layout\nlayouts/vertical.rs"]:::plugin
    end

    %% Future extensions
    subgraph "Roadmap (future)"
        EWMH["EWMH Support"]:::future
        MultiScreen["Multi-Screen"]:::future
    end

    %% Flow
    Main -->|"load config"| Config
    Config -->|"init context"| Context
    Main -->|"connect X11"| X11Client
    XServer -->|"send events"| X11Client
    X11Client -->|"fetch events"| EventLoop
    EventLoop -->|"dispatch to"| WCModule
    WCModule -->|"update state"| Context
    Context -->|"holds models"| Screens
    Context --> Screens
    Context --> Workspaces
    Context --> Windows
    EventLoop -->|"compute layout"| LayoutMod
    LayoutMod --> DWM
    LayoutMod --> Horizontal
    LayoutMod --> Vertical
    LayoutMod -->|"apply layout"| Context
    Context -->|"redraw"| X11Client
    X11Client -->|"draw calls"| XServer

    %% Roadmap interactions
    WCModule -.-> EWMH
    WCModule -.-> MultiScreen

    %% Click events
    click X11Client "https://github.com/tdaron/tdawm/blob/main/src/x11.rs"
    click Main "https://github.com/tdaron/tdawm/blob/main/src/main.rs"
    click Config "https://github.com/tdaron/tdawm/blob/main/src/config/mod.rs"
    click EventLoop "https://github.com/tdaron/tdawm/blob/main/src/tdawm/tdawm.rs"
    click Context "https://github.com/tdaron/tdawm/blob/main/src/tdawm/context.rs"
    click Screens "https://github.com/tdaron/tdawm/blob/main/src/tdawm/screen.rs"
    click Workspaces "https://github.com/tdaron/tdawm/blob/main/src/tdawm/workspace.rs"
    click Windows "https://github.com/tdaron/tdawm/blob/main/src/tdawm/window.rs"
    click LayoutMod "https://github.com/tdaron/tdawm/blob/main/src/layouts/mod.rs"
    click DWM "https://github.com/tdaron/tdawm/blob/main/src/layouts/dwm.rs"
    click Horizontal "https://github.com/tdaron/tdawm/blob/main/src/layouts/horizontal.rs"
    click Vertical "https://github.com/tdaron/tdawm/blob/main/src/layouts/vertical.rs"
    click WCModule "https://github.com/tdaron/tdawm/blob/main/src/tdawm/mod.rs"

    %% Styles
    classDef external fill:#ffe4b3,stroke:#cc7a00,stroke-width:2px
    classDef entry fill:#d5f5e3,stroke:#1e8449,stroke-width:2px
    classDef config fill:#d6eaf8,stroke:#1f618d,stroke-width:2px
    classDef lowLevel fill:#f9e79f,stroke:#b7950b,stroke-width:2px
    classDef core fill:#f5b7b1,stroke:#922b21,stroke-width:2px
    classDef model fill:#d2b4de,stroke:#6c3483,stroke-width:2px
    classDef plugin fill:#aed6f1,stroke:#21618c,stroke-width:2px
    classDef future fill:#f0f3f4,stroke:#566573,stroke-width:1px,stroke-dasharray: 5 5
```
