# tauraamui/lilly architecture

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

- Interactive diagram: https://gitdiagram.com/tauraamui/lilly
- Repository: https://github.com/tauraamui/lilly

## Overview

##### Main Components
- Executive Entry & Core Logic: The main entry point (src/main.v) and core program (src/lilly.v, src/debug_view.v) that bootstraps the editor.
- Text Buffer Management: The “buffer” modules (src/lib/buffer/) implement the gap buffer functionality, which is essential for efficient in-place text editing. There are tests and even experimental versions in the experiment/gap_buffer directory.
- User Interface (UI) and Interaction: The editor’s UI is composed of several modules:
- “ui” components (src/lib/ui/) such as buffer_editor, buffer_view, file_picker_modal, and status_line modules.
- Clipboard Management: The “clipboard” modules (src/lib/clipboard/ and src/lib/clipboardv2/) show abstraction layers to support different operating systems (Darwin, Linux, xclip, Wayland etc.) and even a mock implementation for testing.
- Syntax Parsing and Diff: There are dedicated modules for text syntax and differences:
- Syntax parser (src/lib/syntax/parser.v) providing language support for multiple file types (referencing syntax definitions in src/syntax/) and the diff module for comparing texts.
- Search & History: Components such as search (src/lib/search/) and history (src/lib/history/) record changes, searches, and possibly allow undo/redo gestures.
- Workspace and Configuration: The configuration files (src/config/lilly.conf) and workspace modules (src/lib/workspace/) manage the editor’s environment and settings.
- Experiments & Extension Points: The “experiment” directory contains experimental implementations like pattern search and GUI rendering to test new ideas before integrating them into the main codebase.

##### Relationships and Interactions
- The main application (src/main.v) initializes configuration, loads libraries (core, buffer, ui, clipboard, etc.), and delegates user input to the UI modules.
- The core interacts directly with the text buffer (utilizing gap buffers) and the UI modules to render text and update states.
- The UI components have bidirectional communication with underlying logic:
- For example, editing a buffer in the UI will call the core buffer logic that in turn may inform the history or diff modules.
- The clipboard module acts as a service that the UI can invoke for copy/paste operations, factoring in the specific OS-backed implementations.
- The search and syntax components are called when the user performs file or text queries, integrating with the workspace to highlight syntax features and errors.

##### Architectural Patterns and Design Principles
- Modular Design: With distinct directories for core, UI, clipboard, search, etc., the project promotes separation of concerns.
- Test Driven: Numerous test files (e.g., *_test.v) indicate a component-based approach with unit testing for core functionalities.
- Experimental Branching: The “experiment” directory provides a sandbox approach for new ideas, indicating a willingness to iterate on architectural components.
- Platform Abstraction: The clipboard module, for instance, shows clear abstractions for handling different OS-specific details.

##### Additional Specifics
- Experimental nature of some components with an annotation (e.g., "Experimental GUI Render – experiment/gui_render").
- Differentiate platform-dependent implementations in the clipboard module (e.g., macOS vs. Linux backends).
- Test modules separately to show their role in validating core features.

##### Final Advice
- Maintain an overall layout that reflects the flow from program startup (initialization/configuration) to main operations (buffer editing and UI interaction) and modular support services (clipboard, syntax, search).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Executive & Core
    subgraph "Executive & Core"
        M1["Main Entry (src/main.v)"]:::core
        CP["Core Program (src/lilly.v)"]:::core
        DV["Debug View (src/debug_view.v)"]:::core
        CM["Core Module (src/lib/core/core.v)"]:::core
    end

    %% Text Buffer Management
    subgraph "Text Buffer Management"
        GB["Gap Buffer (src/lib/buffer)"]:::buffer
        EGB["Exp Gap Buffer (experiment/gap_buffer)"]:::buffer
    end

    %% User Interface & Rendering
    subgraph "User Interface & Rendering"
        UI["UI Components (src/lib/ui)"]:::ui
        TUI["Rendering TUI (src/lib/draw/tui_notd_gui.v)"]:::ui
        ExpGUI["Experimental GUI Render (experiment/gui_render)"]:::ui
    end

    %% Clipboard Services
    subgraph "Clipboard Services"
        CPri["Clipboard Primary (src/lib/clipboard)"]:::clipboard
        CV2["Clipboard V2 (src/lib/clipboardv2)"]:::clipboard
    end

    %% Syntax & Diff
    subgraph "Syntax & Diff"
        SP["Syntax Parser (src/lib/syntax/parser.v)"]:::syntax
        SD["Syntax Definitions (src/syntax)"]:::syntax
        Diff["Diff Engine (src/lib/diff/diff.v)"]:::syntax
    end

    %% Search & History
    subgraph "Search & History"
        Search["Search (src/lib/search)"]:::search
        Hist["History (src/lib/history)"]:::search
    end

    %% Workspace & Configuration
    subgraph "Workspace & Configuration"
        Conf["Configuration (src/config/lilly.conf)"]:::config
        Work["Workspace (src/lib/workspace)"]:::config
    end

    %% Experiments
    subgraph "Experiments"
        ExpPat["Experimental Pattern Search (experiment/pattern_search)"]:::experiments
    end

    %% Relationships
    M1 -->|"init"| CP
    CP -->|"boots"| DV
    CP -->|"handles"| CM
    CP -->|"manages"| GB
    CP -->|"calls"| UI
    CP -->|"invokes"| CPri
    CP -->|"parses"| SP
    CP -->|"queries"| Search
    CP -->|"loads"| Conf
    CP -->|"compares"| Diff
    CP -->|"logs"| Hist
    CP -->|"sets"| Work
    CP -->|"experiments"| ExpPat

    UI <-->|"syncs"| GB
    UI -->|"renders"| TUI
    UI -->|"triggers"| ExpGUI
    UI -->|"copies"| CPri
    UI -->|"searches"| Search

    SP -->|"uses"| SD

    CPri -.->|"v2_update"| CV2

    %% Styles
    classDef core fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef buffer fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef ui fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef clipboard fill:#FFB6C1,stroke:#333,stroke-width:2px;
    classDef syntax fill:#FFFACD,stroke:#333,stroke-width:2px;
    classDef search fill:#E0FFFF,stroke:#333,stroke-width:2px;
    classDef config fill:#FFE4E1,stroke:#333,stroke-width:2px;
    classDef experiments fill:#DDA0DD,stroke:#333,stroke-width:2px;

    %% Click Events
    click M1 "https://github.com/tauraamui/lilly/blob/master/src/main.v"
    click CP "https://github.com/tauraamui/lilly/blob/master/src/lilly.v"
    click DV "https://github.com/tauraamui/lilly/blob/master/src/debug_view.v"
    click CM "https://github.com/tauraamui/lilly/blob/master/src/lib/core/core.v"
    click GB "https://github.com/tauraamui/lilly/tree/master/src/lib/buffer/"
    click EGB "https://github.com/tauraamui/lilly/tree/master/experiment/gap_buffer/"
    click UI "https://github.com/tauraamui/lilly/tree/master/src/lib/ui/"
    click TUI "https://github.com/tauraamui/lilly/blob/master/src/lib/draw/tui_notd_gui.v"
    click ExpGUI "https://github.com/tauraamui/lilly/tree/master/experiment/gui_render/"
    click CPri "https://github.com/tauraamui/lilly/tree/master/src/lib/clipboard/"
    click CV2 "https://github.com/tauraamui/lilly/tree/master/src/lib/clipboardv2/"
    click SP "https://github.com/tauraamui/lilly/blob/master/src/lib/syntax/parser.v"
    click SD "https://github.com/tauraamui/lilly/tree/master/src/syntax/"
    click Diff "https://github.com/tauraamui/lilly/blob/master/src/lib/diff/diff.v"
    click Search "https://github.com/tauraamui/lilly/tree/master/src/lib/search/"
    click Hist "https://github.com/tauraamui/lilly/tree/master/src/lib/history/"
    click Conf "https://github.com/tauraamui/lilly/blob/master/src/config/lilly.conf"
    click Work "https://github.com/tauraamui/lilly/tree/master/src/lib/workspace/"
    click ExpPat "https://github.com/tauraamui/lilly/tree/master/experiment/pattern_search/"
```
