# jp8g/lmfw architecture

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

- Interactive diagram: https://gitdiagram.com/jp8g/lmfw
- Repository: https://github.com/jp8g/lmfw

## Overview

1. **What this repo is**
   - LMFW is a small C windowing library with a deliberately narrow scope: create and destroy platform-specific windows and support software rendering.
   - The current implementation target is Linux, with Wayland supported in-repo and Xcb/Xlib mentioned in the project goals.

2. **Public API boundary**
   - `include/lmfw/lmfw.h` is the main consumer-facing header.
   - Downstream applications are meant to include this header and link against the built library, rather than depend on internal source files.

3. **Core implementation**
   - `src/lmfw.c` is the library’s main implementation unit.
   - This is where the platform logic and window-management behavior are concentrated, making the repository structurally a small single-library codebase rather than a multi-service system.

4. **Backend-oriented architecture**
   - The library is organized around platform-specific windowing backends rather than a broad cross-platform abstraction.
   - The README explicitly says there is not yet a general cross-platform window-management interface; instead, LMFW exposes helpers for platform-dependent windows.

5. **Wayland protocol layer**
   - `external/wayland/` contains vendored/generated Wayland protocol bindings:
     - `xdg-shell`
     - `xdg-decoration-unstable-v1`
     - `wlr-layer-shell-unstable-v1`
   - These files act as the protocol glue between LMFW and a Wayland compositor, defining the surface/window behaviors the library can request and respond to.

6. **Data flow at runtime**
   - Application code calls into the public LMFW API.
   - LMFW routes that request into its internal implementation.
   - On Wayland, that implementation uses the protocol bindings to talk to the compositor and create/manage windows.
   - For rendering, the library supports software-rendering workflows rather than imposing a GPU abstraction.

7. **Vendored external code vs project code**
   - The `external/wayland` directory is a clear boundary: protocol definitions are kept separate from LMFW’s own logic.
   - This keeps the core library minimal while still embedding the necessary Wayland interface code locally.

8. **Build and packaging shape**
   - `Makefile` indicates a simple native build flow.
   - `liblmfw.a` shows the output is a static library, so integration is link-time rather than via a daemon, service, or plugin runtime.
   - `compile_commands.json` suggests the project is intended to be editor/IDE-friendly and C tooling-aware.

9. **How to diagram it**
   - Draw one main application node consuming `include/lmfw/lmfw.h`.
   - Connect that to `src/lmfw.c` as the core library implementation.
   - From there, branch to platform backends, with Wayland explicitly shown via the vendored protocol layer in `external/wayland/`.
   - Show the external Wayland compositor/desktop environment on the far side of those bindings.

Main entry points: [`src/lmfw.c`](https://github.com/jp8g/lmfw/blob/main/src/lmfw.c) (lmfw.c), [`Makefile`](https://github.com/jp8g/lmfw/tree/main/Makefile) (Makefile), [`external/wayland/xdg-shell.c`](https://github.com/jp8g/lmfw/blob/main/external/wayland/xdg-shell.c) (xdg-shell), [`external/wayland/xdg-decoration-unstable-v1.c`](https://github.com/jp8g/lmfw/blob/main/external/wayland/xdg-decoration-unstable-v1.c) (xdg-decoration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_public["Public API"]
  node_public_header["LMFW API<br/>public header<br/>[lmfw.h]"]
end

subgraph group_group_core["Core Library"]
  node_core_impl["lmfw.c<br/>library core<br/>[lmfw.c]"]
  node_static_lib[("liblmfw.a<br/>artifact<br/>[liblmfw.a]")]
  node_build["Makefile<br/>build config"]
end

subgraph group_group_wayland["Wayland Protocols"]
  node_xdg_shell["xdg-shell<br/>wayland protocol<br/>[xdg-shell.c]"]
  node_xdg_decoration["xdg-decoration<br/>wayland protocol"]
  node_wlr_layer_shell["layer-shell<br/>wayland protocol"]
end

subgraph group_group_external["External World"]
  node_app(("App<br/>consumer"))
  node_wayland_compositor(("Compositor<br/>runtime peer"))
end

node_app -->|"includes"| node_public_header
node_app -->|"links"| node_static_lib
node_public_header -->|"declares API for"| node_core_impl
node_core_impl -->|"builds into"| node_static_lib
node_build -->|"compiles"| node_core_impl
node_build -->|"builds"| node_xdg_shell
node_build -->|"builds"| node_xdg_decoration
node_build -->|"builds"| node_wlr_layer_shell
node_core_impl -->|"uses"| node_xdg_shell
node_core_impl -->|"uses"| node_xdg_decoration
node_core_impl -->|"uses"| node_wlr_layer_shell
node_xdg_shell -->|"speaks to"| node_wayland_compositor
node_xdg_decoration -->|"speaks to"| node_wayland_compositor
node_wlr_layer_shell -->|"speaks to"| node_wayland_compositor

click node_public_header "https://github.com/jp8g/lmfw/blob/main/include/lmfw/lmfw.h"
click node_core_impl "https://github.com/jp8g/lmfw/blob/main/src/lmfw.c"
click node_static_lib "https://github.com/jp8g/lmfw/blob/main/liblmfw.a"
click node_build "https://github.com/jp8g/lmfw/tree/main/Makefile"
click node_xdg_shell "https://github.com/jp8g/lmfw/blob/main/external/wayland/xdg-shell.c"
click node_xdg_decoration "https://github.com/jp8g/lmfw/blob/main/external/wayland/xdg-decoration-unstable-v1.c"
click node_wlr_layer_shell "https://github.com/jp8g/lmfw/blob/main/external/wayland/wlr-layer-shell-unstable-v1.c"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_public_header toneBlue
class node_core_impl,node_static_lib,node_build toneAmber
class node_xdg_shell,node_xdg_decoration,node_wlr_layer_shell toneMint
class node_app,node_wayland_compositor toneRose
```

## Components

### Public API

Consumer-facing boundary for downstream applications.

- [LMFW API](https://github.com/jp8g/lmfw/blob/main/include/lmfw/lmfw.h): public header · Consumer-facing entry point for the library. · `include/lmfw/lmfw.h`

### Core Library

Main implementation and build output.

- [lmfw.c](https://github.com/jp8g/lmfw/blob/main/src/lmfw.c): library core · Main implementation unit for window management and platform logic. · `src/lmfw.c`
- [liblmfw.a](https://github.com/jp8g/lmfw/blob/main/liblmfw.a): artifact · Static library output linked by applications. · `liblmfw.a`
- [Makefile](https://github.com/jp8g/lmfw/tree/main/Makefile): build config · Native build entrypoint for compiling and packaging the library. · `Makefile`

### Wayland Protocols

Vendored/generated bindings used by the Linux Wayland backend.

- [xdg-shell](https://github.com/jp8g/lmfw/blob/main/external/wayland/xdg-shell.c): wayland protocol · Wayland shell surface and toplevel protocol bindings. · `external/wayland/xdg-shell.c`
- [xdg-decoration](https://github.com/jp8g/lmfw/blob/main/external/wayland/xdg-decoration-unstable-v1.c): wayland protocol · Wayland decoration protocol bindings. · `external/wayland/xdg-decoration-unstable-v1.c`
- [layer-shell](https://github.com/jp8g/lmfw/blob/main/external/wayland/wlr-layer-shell-unstable-v1.c): wayland protocol · Wayland layer-shell protocol bindings for special surfaces. · `external/wayland/wlr-layer-shell-unstable-v1.c`

### External World

Non-repository runtime peers.

- **App**: consumer · Downstream application using LMFW.
- **Compositor**: runtime peer · External Wayland compositor/desktop environment.

## Connections

- App → LMFW API: includes · Applications consume the public API header.
- App → liblmfw.a: links · Applications link against the static library artifact.
- LMFW API → lmfw.c: declares API for · The header defines the boundary implemented by the library.
- lmfw.c → liblmfw.a: builds into · Core implementation is compiled into the static library.
- Makefile → lmfw.c: compiles · The Makefile drives compilation of the main implementation.
- Makefile → xdg-shell: builds · Build flow includes vendored Wayland bindings.
- Makefile → xdg-decoration: builds · Build flow includes vendored Wayland bindings.
- Makefile → layer-shell: builds · Build flow includes vendored Wayland bindings.
- lmfw.c → xdg-shell: uses · Core implementation talks to Wayland through protocol bindings.
- lmfw.c → xdg-decoration: uses · Core implementation talks to Wayland through protocol bindings.
- lmfw.c → layer-shell: uses · Core implementation talks to Wayland through protocol bindings.
- xdg-shell → Compositor: speaks to · Protocol messages are exchanged with the compositor.
- xdg-decoration → Compositor: speaks to · Protocol messages are exchanged with the compositor.
- layer-shell → Compositor: speaks to · Protocol messages are exchanged with the compositor.
