# lusingander/stu architecture

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

- Interactive diagram: https://gitdiagram.com/lusingander/stu
- Repository: https://github.com/lusingander/stu

## Overview

##### Main components
- TUI Frontend – This is the core of the user interface built using the ratatui framework. Within the codebase, it’s divided into screens (pages) and widgets.
- Pages Management – Under src/pages, you have distinct screens such as bucket_list, object_list, object_detail, object_preview, etc. These represent different views that the UI can render.
- S3 Client & Business Logic – Files like src/client.rs, src/config.rs, src/error.rs, src/event.rs, and others encapsulate the business logic, handle configuration, and manage interactions with AWS S3 (or S3-compatible) endpoints.
- Configuration and Customization – The project loads runtime settings (e.g., keybindings and config) from external TOML files (as seen in assets/keybindings.toml and the config file in the user’s STU_ROOT_DIR). This component includes handling of default keybindings, themes, and preview options.
- Auxiliary Tools – The tool directory contains separate utilities (written in Go) such as imgdiff and imggen, which support additional image-related functionality like generating fixtures or comparing images, possibly used for testing or enhancing the TUI image preview features.

##### Architectural patterns and design principles
- Layered Architecture – Emphasize that the system is divided into the presentation layer (TUI pages and widgets), the application logic layer (client, events, error handling), and external integration (S3 API).
- Modular Design – Each directory (pages, widgets, client, config) encapsulates related functionality. This modularity is central to creating a maintainable and extensible application.
- Configuration and Customization – The design supports dynamic keybinding and preview configurations as well as extensibility for additional syntax highlighting themes and image previews.
- Separation of Concerns – The UI rendering is independent from the business logic and external service interfacing, allowing each component to be developed and tested separately.

- Clearly separate the TUI components (pages, widgets) from the business logic (client, events, configuration) and external integrations.
– from the "User" to the "TUI Frontend" indicating input,
– from the TUI components to the business logic (client and configuration) indicating function calls/data flow,
– from the business logic to the "AWS S3 API" showing external interactions,

- Clear labels such as “TUI Frontend – Pages & Widgets”, “S3 Client & Business Logic”, “Configuration Manager” (loading both keybindings and user settings), “External S3 API”, and “Auxiliary Image Tools (imgdiff, imggen)”.
- Incorporate notes that describe key interactions (for example, “loads keybindings from assets/keybindings.toml”, “renders preview using syntect for syntax highlighting”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    User(("User")):::entry

    subgraph "TUI Frontend – Pages & Widgets"
        pages["Pages (src/pages)"]:::ui
        widgets["Widgets (src/widget)"]:::ui
    end

    subgraph "S3 Business Layer"
        eventManager["Event Manager (src/event.rs)"]:::business
        client["S3 Client (src/client.rs)"]:::business
        errorHandler["Error Handling (src/error.rs)"]:::business
        objectManager["Object Manager (src/object.rs)"]:::business
    end

    subgraph "Configuration Manager"
        config["Config Loader (src/config.rs)"]:::config
        key["Keybindings (assets/keybindings.toml)"]:::config
    end

    externalS3["External S3 API"]:::external

    subgraph "Auxiliary Tools"
        imgdiff["imgdiff (tool/imgdiff)"]:::auxiliary
        imggen["imggen (tool/imggen)"]:::auxiliary
    end

    %% Connections
    User -->|"sends_commands"| pages
    pages -->|"renders_view"| widgets
    pages -->|"process_events"| eventManager
    eventManager -->|"invoke_S3_ops"| client
    eventManager -->|"handle_errors"| errorHandler
    eventManager -->|"manage_objects"| objectManager
    client -->|"calls_service"| externalS3
    config -->|"loads_config"| pages
    config -->|"loads_config"| client
    widgets -->|"image_rendering"| imggen
    widgets -->|"image_preview"| imgdiff

    %% Click Events
    click pages "https://github.com/lusingander/stu/tree/master/src/pages"
    click widgets "https://github.com/lusingander/stu/tree/master/src/widget"
    click client "https://github.com/lusingander/stu/blob/master/src/client.rs"
    click config "https://github.com/lusingander/stu/blob/master/src/config.rs"
    click key "https://github.com/lusingander/stu/blob/master/assets/keybindings.toml"
    click imgdiff "https://github.com/lusingander/stu/tree/master/tool/imgdiff"
    click imggen "https://github.com/lusingander/stu/tree/master/tool/imggen"
    click eventManager "https://github.com/lusingander/stu/blob/master/src/event.rs"
    click errorHandler "https://github.com/lusingander/stu/blob/master/src/error.rs"
    click objectManager "https://github.com/lusingander/stu/blob/master/src/object.rs"

    %% Styles
    classDef entry fill:#f4d03f,stroke:#333,stroke-width:2px;
    classDef ui fill:#aed6f1,stroke:#333,stroke-width:2px;
    classDef business fill:#f9e79f,stroke:#333,stroke-width:2px;
    classDef config fill:#d5f5e3,stroke:#333,stroke-width:2px;
    classDef external fill:#f5b7b1,stroke:#333,stroke-width:2px;
    classDef auxiliary fill:#d2b4de,stroke:#333,stroke-width:2px;
```
