# Architecture

Technical overview of DWN's design and implementation

## Overview

DWN is written in ANSI C for X11/Xorg. It uses a modular architecture with a global state singleton and event-driven design. Version 2.0 introduces a comprehensive abstraction layer enabling backend portability and plugin extensibility.

## Abstraction Layer (v2.0)

The new abstraction layer provides backend-agnostic types and a plugin system:

    ┌─────────────────────────────────────────────────────────┐
    │                    DWN Application                       │
    ├─────────────────────────────────────────────────────────┤
    │  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐  │
    │  │   Layout    │  │   Widget    │  │   AI Provider   │  │
    │  │   Plugin    │  │   Plugin    │  │      API        │  │
    │  │   System    │  │   System    │  │   (future)      │  │
    │  └──────┬──────┘  └──────┬──────┘  └─────────────────┘  │
    │         │                │                               │
    │  ┌──────┴────────────────┴───────────────────────────┐  │
    │  │              Abstract Client Manager               │  │
    │  │         (wm_client.h/c - bidirectional sync)       │  │
    │  └───────────────────────┬───────────────────────────┘  │
    │                          │                               │
    │  ┌───────────────────────┴───────────────────────────┐  │
    │  │              Backend Abstraction Interface         │  │
    │  │         (backend_interface.h - vtable-based)       │  │
    │  └───────────────────────┬───────────────────────────┘  │
    │                          │                               │
    │  ┌───────────────────────┴───────────────────────────┐  │
    │  │  X11 Backend  │  Wayland Backend  │  Headless      │  │
    │  │  (complete)   │  (future)         │  (future)      │  │
    │  └───────────────────────────────────────────────────┘  │
    └─────────────────────────────────────────────────────────┘

### Core Abstractions

- wm_types.h - Abstract handles, geometry, colors, events
- wm_string.h/c - Safe dynamic strings
- wm_list.h/c - Dynamic arrays
- wm_hashmap.h/c - Hash tables
- wm_client.h/c - Abstract client type

### Plugin System

- Layout Plugins - Custom window arrangements (tiling, floating, monocle, grid)
- Widget Plugins - Panel components (taskbar, clock, system stats)
- Dynamic Loading - Load plugins from shared libraries

### Backend Interface

The backend interface defines 80+ operations for window management, events, and rendering. Current implementations:

- X11 - Full implementation with event translation
- Wayland - Planned for future
- Headless - For testing and CI

## Module Structure

Each module has a header in `include/` and implementation in `src/`.

Module | Responsibility
--- | ---
`main.c` | X11 initialization, event loop, signal handling
`client.c` | Window management, focus, frame creation
`workspace.c` | 9 virtual desktops, per-workspace state
`layout.c` | Tiling, floating, monocle algorithms
`decorations.c` | Window title bars and borders
`panel.c` | Top/bottom panels, taskbar, workspace indicators
`systray.c` | XEmbed system tray, WiFi/audio/battery widgets
`notifications.c` | D-Bus notification daemon
`atoms.c` | X11 EWMH/ICCCM atom management
`keys.c` | Keyboard shortcut capture and callbacks
`config.c` | INI-style config loading
`api.c` | WebSocket JSON API server
`screenshot.c` | X11 capture + PNG encoding
`ocr.c` | Tesseract OCR integration
`ai.c` | OpenRouter API, Exa search
`util.c` | Logging, memory, string utilities

## Event Loop

The main event loop uses `select()` for multiplexed I/O across X11, D-Bus, and timers.

    void dwn_run(void) {
        int x11_fd = ConnectionNumber(dwn->display);
        int dbus_fd = /* from dbus_connection */;

        while (dwn->running) {
            // 1. Process all pending X11 events
            while (XPending(dwn->display)) {
                XEvent ev;
                XNextEvent(dwn->display, &ev);
                dwn_handle_event(&ev);
            }

            // 2. Process D-Bus messages
            notifications_process_messages();

            // 3. Process async AI/Exa requests
            ai_process_pending();

            // 4. Check notification timeouts
            notifications_update();

            // 5. Handle delayed focus (focus-follow mode)
            handle_pending_focus();

            // 6. Periodic updates (animation, clock)
            if (now - last_update >= 16) {  // 60fps
                news_update();
                panel_render_all();
            }

            // 7. Wait for events with timeout
            fd_set fds;
            FD_SET(x11_fd, &fds);
            FD_SET(dbus_fd, &fds);
            struct timeval tv = {0, 16000};  // 16ms
            select(max_fd + 1, &fds, NULL, NULL, &tv);
        }
    }

### X11 Event Dispatch

Event | Handler
--- | ---
`MapRequest` | New window → client_manage()
`UnmapNotify` | Window hidden → possibly client_unmanage()
`DestroyNotify` | Window destroyed → client_unmanage()
`ConfigureRequest` | Window resize request
`PropertyNotify` | Property changed → update title
`Expose` | Repaint needed → render
`ButtonPress` | Mouse click → focus, drag, panel click
`MotionNotify` | Mouse move → window drag/resize
`KeyPress` | Key pressed → shortcut callback
`ClientMessage` | EWMH requests, systray dock

## Core Data Structures

### DWNState

Global singleton containing all window manager state.

    typedef struct {
        Display *display;           // X11 connection
        int screen;                 // Default screen
        Window root;                // Root window
        int screen_width, screen_height;

        Monitor monitors[MAX_MONITORS];
        int monitor_count;

        Workspace workspaces[MAX_WORKSPACES];  // 9 workspaces
        int current_workspace;

        Client *client_list;        // Doubly-linked list head
        int client_count;

        Panel *top_panel;
        Panel *bottom_panel;
        Config *config;

        bool running;
        bool ai_enabled;

        // Drag state
        Client *drag_client;
        int drag_start_x, drag_start_y;
        bool resizing;

        // Alt-Tab state
        bool is_alt_tabbing;
        Client *alt_tab_client;
    } DWNState;

### Client

Represents a managed window with decoration frame.

    struct Client {
        Window window;              // Application window
        Window frame;               // Decoration frame (parent)
        int x, y, width, height;    // Current geometry
        int old_x, old_y;           // Saved for restore
        int old_width, old_height;
        uint32_t flags;             // CLIENT_FLOATING, etc.
        unsigned int workspace;     // Workspace index (0-8)
        char title[256];
        char class[64];
        SnapConstraint snap;        // Snap state
        Client *next, *prev;        // Global list
        Client *mru_next, *mru_prev; // MRU stack
    };

### Workspace

Per-workspace layout and window state.

    struct Workspace {
        Client *clients;            // Workspace client list
        Client *focused;            // Currently focused
        Client *mru_head, *mru_tail; // MRU stack
        LayoutType layout;          // tiling/floating/monocle
        float master_ratio;         // 0.1 to 0.9
        int master_count;           // 1 to 10
        char name[32];
    };

### Client Flags

    #define CLIENT_NORMAL      0
    #define CLIENT_FLOATING    (1 << 0)
    #define CLIENT_FULLSCREEN  (1 << 1)
    #define CLIENT_URGENT      (1 << 2)
    #define CLIENT_MINIMIZED   (1 << 3)
    #define CLIENT_STICKY      (1 << 4)
    #define CLIENT_MAXIMIZED   (1 << 5)

    // Usage
    if (c->flags & CLIENT_FLOATING) { ... }
    c->flags |= CLIENT_FLOATING;     // Set
    c->flags &= ~CLIENT_FLOATING;    // Clear

## X11 Protocols

### EWMH (Extended Window Manager Hints)

Standard hints for modern window manager features.

- `_NET_SUPPORTED` - List of supported atoms
- `_NET_CLIENT_LIST` - List of managed windows
- `_NET_CURRENT_DESKTOP` - Current workspace
- `_NET_ACTIVE_WINDOW` - Focused window
- `_NET_WM_STATE` - Window state (fullscreen, etc.)
- `_NET_WM_WINDOW_TYPE` - Window type (dialog, etc.)

### ICCCM (Inter-Client Communication)

Core X11 window manager protocol.

- `WM_PROTOCOLS` - Supported protocols (WM_DELETE_WINDOW)
- `WM_NAME` - Window title
- `WM_CLASS` - Application class
- `WM_HINTS` - Input model, icons
- `WM_NORMAL_HINTS` - Size constraints

### XEmbed (System Tray)

Protocol for embedding application icons in system tray.

- Acquire `_NET_SYSTEM_TRAY_S0` selection
- Handle `SYSTEM_TRAY_REQUEST_DOCK` messages
- Send `XEMBED_EMBEDDED_NOTIFY` to docked icons

## Design Patterns

### Opaque Pointers

Hide implementation details. Header exposes typedef, source defines struct.

    // header.h
    typedef struct module_t* Module;
    Module module_create(void);
    void module_destroy(Module m);

    // source.c
    struct module_t {
        int private_field;
    };

### Return Code Error Handling

Functions return status codes, pass results via output parameters.

    typedef enum {
        STATUS_OK = 0,
        STATUS_ERROR_INVALID_ARG,
        STATUS_ERROR_NO_MEMORY
    } Status;

    Status do_work(int input, int *output);

### Goto Cleanup

Centralized resource cleanup for functions with multiple allocations.

    int process(void) {
        char *buf = NULL;
        int status = -1;

        buf = malloc(1024);
        if (!buf) goto cleanup;

        // ... work ...

        status = 0;

    cleanup:
        free(buf);
        return status;
    }

### Module Prefix Convention

All public functions prefixed with module name.

    // client.h
    void client_focus(Client *c);
    void client_move(Client *c, int x, int y);
    void client_resize(Client *c, int w, int h);

    // workspace.h
    void workspace_switch(int index);
    void workspace_arrange(int index);

## Key Constants

Constant | Value | Description
--- | --- | ---
`MAX_CLIENTS` | 256 | Maximum managed windows
`MAX_WORKSPACES` | 9 | Virtual desktops
`MAX_MONITORS` | 8 | Multi-monitor support
`MAX_NOTIFICATIONS` | 32 | Visible notifications
`MAX_KEYBINDINGS` | 64 | Keyboard shortcuts
`MAX_TRAY_ICONS` | 32 | System tray icons