# mike-ward/gui architecture

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

## Overview

##### Project Type & Purpose
- This is a UI framework for the V language – meaning it’s essentially a library that developers integrate into their V applications for building graphical user interfaces.
- The README clearly states its inspiration from Clay’s rendering algorithm, the immediate mode rendering style, and its microsecond performance expectations.

##### Analyzing the File Structure
- Top-level Files & Folders:
– Files like .gitattributes, .gitignore, LICENSE, and Makefile indicate standard project setup.
– The README.md and the doc directory provide explanatory materials.
- The core source code lives under the “src” directory with two main subdirectories:
- The “v.mod” file confirms the module structure in V.

##### Main Components & Their Roles
a. GUI Core Library:
- This as the core of the framework where the primary logic resides. It includes modules like:
- gui.v – Likely the main entry point for GUI logic.
- container.v, layout.v, and alignment.v – Manage how UI elements arrange themselves.
- button.v, input.v, text.v, etc. – Represent individual UI elements or widgets.
- mouse.v and input_state.v – Manage event handling and view updates.
b. Window & Rendering Pipeline:
- The “window.v” file suggests a dedicated component for window instantiation and management.
- An “Event Loop / Immediate Mode Rendering Engine” block that shows how updates are processed in a thread-safe and immediate (dynamically redrawn) mode.
c. State & Update Cycle:
- The example code shows an “AppState” being updated on interactions. This should be highlighted as a key design feature that enables reactive UI updates.
d. Examples & Usage:

##### Relationships & Interactions
- How the “Window” component interacts with the “Rendering Engine” and “Input/Event Handling”.
- How “UI Components” (like button, label, layout managers) are arranged inside higher-level containers (e.g., rows or columns).
- The flow from user input to state update, which triggers view updates via the immediate mode rendering path.
- That these modules collectively follow a declarative style, meaning the configuration data (as seen in examples) drives the UI’s appearance.

##### Architectural Patterns & Key Principles
- Immediate Mode Rendering: This pattern means that the UI components are redrawn each frame based directly on state.
- Modular Design: Each UI element (button, rectangle, layout, etc.) is in its own module, promoting separation of concerns.
- Thread Safety: Make sure to indicate that view updates occur in a thread-safe manner.

## Diagram (Mermaid)

```mermaid
flowchart TD
    EA["Example Applications"]:::examples

    subgraph "GUI Framework Core"
        A["GUI Core Library"]:::core
        subgraph "Window Management"
            WM["Window Management"]:::window
        end
        subgraph "Layout & Containers"
            LM["Layout Management"]:::layout
            CH["Container Handling"]:::layout
            AL["Alignment"]:::layout
            SI["Sizing"]:::layout
        end
        subgraph "Widgets"
            BW["Button Widget"]:::widget
            TW["Text Widget"]:::widget
            PD["Padding"]:::widget
            VW["View"]:::widget
        end
        subgraph "Rendering Engine"
            RP["Render Pipeline"]:::rendering
            SR["Shape Rendering"]:::rendering
            RR["Rectangle Rendering"]:::rendering
        end
        subgraph "Input and Event Handling"
            UI["User Input"]:::input
            ME["Mouse Events"]:::input
            IS["Input State Management"]:::input
        end
        SU["State Update Cycle"]:::state
    end

    EA -->|"invokes"| WM
    WM -->|"initializes"| A
    A -->|"configures"| LM
    A -->|"configures"| CH
    A -->|"applies"| AL
    A -->|"applies"| SI
    A -->|"creates"| BW
    A -->|"creates"| TW
    A -->|"creates"| PD
    A -->|"creates"| VW
    A -->|"triggers"| RP
    A -->|"initiates"| SR
    A -->|"initiates"| RR
    A -->|"handles"| UI
    A -->|"handles"| ME
    A -->|"handles"| IS
    UI -->|"updates"| SU
    ME -->|"updates"| SU
    IS -->|"updates"| SU
    SU -->|"refreshes"| RP
    RP -->|"rendersTo"| WM

    click A "https://github.com/mike-ward/gui/blob/main/src/gui/gui.v"
    click LM "https://github.com/mike-ward/gui/blob/main/src/gui/layout.v"
    click CH "https://github.com/mike-ward/gui/blob/main/src/gui/container.v"
    click AL "https://github.com/mike-ward/gui/blob/main/src/gui/alignment.v"
    click SI "https://github.com/mike-ward/gui/blob/main/src/gui/sizing.v"
    click BW "https://github.com/mike-ward/gui/blob/main/src/gui/button.v"
    click TW "https://github.com/mike-ward/gui/blob/main/src/gui/text.v"
    click PD "https://github.com/mike-ward/gui/blob/main/src/gui/padding.v"
    click VW "https://github.com/mike-ward/gui/blob/main/src/gui/view.v"
    click RP "https://github.com/mike-ward/gui/blob/main/src/gui/render.v"
    click SR "https://github.com/mike-ward/gui/blob/main/src/gui/shape.v"
    click RR "https://github.com/mike-ward/gui/blob/main/src/gui/rectangle.v"
    click UI "https://github.com/mike-ward/gui/blob/main/src/gui/input.v"
    click ME "https://github.com/mike-ward/gui/blob/main/src/gui/mouse.v"
    click IS "https://github.com/mike-ward/gui/blob/main/src/gui/input_state.v"
    click WM "https://github.com/mike-ward/gui/blob/main/src/gui/window.v"
    click EA "https://github.com/mike-ward/gui/tree/main/src/examples"

    classDef core fill:#aqua,stroke:#333,stroke-width:2px;
    classDef window fill:#ffcccc,stroke:#333,stroke-width:2px;
    classDef layout fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef widget fill:#ffffcc,stroke:#333,stroke-width:2px;
    classDef rendering fill:#ffcce6,stroke:#333,stroke-width:2px;
    classDef input fill:#ffedcc,stroke:#333,stroke-width:2px;
    classDef state fill:#e0e0e0,stroke:#333,stroke-width:2px;
    classDef examples fill:#d9d9d9,stroke:#333,stroke-width:2px;
```
