# lapce/floem architecture

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

## Overview

##### Main Components
- Floem Core Library – The “src” directory holds the core functionality (e.g., event handling, view creation, state management, style, animations, layout, theming, etc.). This represents the “heart” of your library.
- Reactive Engine – The “reactive” crate implements the fine-grained reactivity system (using reactive primitives such as RwSignals) that drives much of the dynamic UI updates.
- Rendering System – Multiple crates are dedicated to rendering:
- The “renderer” crate integrates with wgpu for GPU rendering and falls back to using CPU rendering with tiny-skia.
- Other crates like “tiny_skia”, “vello”, and “vger” also play roles in rendering/vector graphics. Even if these appear as separate libraries (or lower-level layers), they are part of the rendering abstraction.
- Specialized / Supporting Components – For example:
- “editor-core”: Provides an editor or text editing component built atop Floem.
- “views” in the core “src” directory: These files include definitions of various UI widgets (buttons, labels, text editors, etc.) that rely on the reactive and rendering systems.
- Examples – The “examples” directory contains numerous sample applications that demonstrate how to utilize Floem in different contexts (from a simple counter to more complex layouts and graphics). They represent client usage of the core library.

##### Relationships and Data Flows
- The UI Layer (widgets, views, event handling, etc.) built in the core library is supported by the reactive engine. Reactive components (signals, effects) update state and trigger the re-rendering of views.
- Inputs and events (from modules like “src/event”, “src/keyboard”, “src/pointer”) feed into the reactive layer and subsequently update the view state.
- The consolidated view tree, once updated, is passed to the rendering system, which interprets layout and draws UI elements using GPU (via wgpu) or CPU (tiny-skia) backends.
- Components such as “editor-core” may also have their own sub-modules that integrate with both the reactive layer and the rendering layer, offering specialized UI behavior.
- The examples leverage these components to demonstrate real-world usage, bridging theory with practical application and showing integration points where developers interact with Floem.

##### Architectural Patterns and Design Principles
- Modular / Layered Architecture – The project separates core UI logic, reactivity, and rendering into distinct crates. This separation increases maintainability and promotes reusability.
- Declarative & Reactive Paradigm – Similar in spirit to frameworks like React, the library uses reactive primitives to update only the necessary parts of the UI when data changes.
- Example Applications as Consumers – The design should also capture how example apps, spread across many subdirectories, “pull in” the core library to build specific UIs.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Example Applications"]:::applications
    click A "https://github.com/lapce/floem/tree/main/examples"

    subgraph "Floem Core Library"
        B0["Floem Core Library"]:::core
        click B0 "https://github.com/lapce/floem/tree/main/src"
        B1["UI Core (Events,State,Styling)"]:::core
        B2["UI Widgets/Views"]:::core
        click B2 "https://github.com/lapce/floem/tree/main/src/views"
        B0 --> B1
        B0 --> B2
    end

    C["Reactive Engine"]:::reactive
    click C "https://github.com/lapce/floem/tree/main/reactive"

    subgraph "Rendering System"
        D1["GPU Rendering (wgpu)"]:::rendering
        click D1 "https://github.com/lapce/floem/tree/main/renderer"
        subgraph "CPU Rendering Fallback"
            D2["tiny-skia"]:::rendering
            click D2 "https://github.com/lapce/floem/tree/main/tiny_skia"
            D3["Vector Graphics (vello,vger)"]:::rendering
        end
    end

    E["Specialized Module - Editor"]:::specialized
    click E "https://github.com/lapce/floem/tree/main/editor-core"

    A -->|"uses"| B0
    B1 -->|"triggers_update"| C
    C -->|"updates_view"| B2
    C -->|"renders"| D1
    C -->|"renders"| D2
    C -->|"renders"| D3
    E -->|"integrates_with"| B0
    E -->|"integrates_with"| C
    E -->|"integrates_with"| D1
    E -->|"integrates_with"| D2
    E -->|"integrates_with"| D3

    classDef core fill:#B3CDE0,stroke:#08457E,stroke-width:2px;
    classDef reactive fill:#FBB4AE,stroke:#C44D58,stroke-width:2px;
    classDef rendering fill:#C5E1A5,stroke:#558B2F,stroke-width:2px;
    classDef specialized fill:#FFD700,stroke:#B8860B,stroke-width:2px;
    classDef applications fill:#D1C4E9,stroke:#673AB7,stroke-width:2px;
```
