# shawalli/bubbles architecture

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

## Overview

##### Main Components
- Calendar Module – This contains functionality to render and manage both monthly and weekly calendars. Key files include month.go, week.go, keymap.go, style.go, and their associated tests and golden files in the testdata directories.
- Radio Module – This provides various implementations of radio buttons including simple, grouped, and pill-style variants. Core files are radio.go, button.go, keymap.go, style.go along with its tests and sample golden outputs.
- Tabs Module – Handling tab-based navigation with features like basic tabs, wraparound, and resizable tabs; code and tests are found in tabs.go, tab.go, keymap.go, style.go.
- Examples – Each TUI component has associated example applications (found under examples/*) demonstrating how to utilize these modules. Even though these are not part of the core library, they indicate intended usage patterns and integration points.
- Assets – Contains media files (e.g., GIFs) used to showcase the demos and likely aiding in documentation.
- CI/CD and Auxiliary Configuration – The .github directory (with workflows and dependabot configurations), .gitignore, LICENSE, and go.mod/go.sum files are essential for project configuration, dependency management, and continuous integration.

##### Relationships and Interactions
- At the core, the components (calendar, radio, tabs) are standalone modules that share a similar design philosophy: they process user input via key mapping, render views using Bubble Tea constructs, and are tested independently using golden files to ensure rendering accuracy.
- Each component module interacts with the Bubble Tea framework (an assumed external dependency) and thus should be represented as depending on external services/libraries.
- Example applications serve as consumer applications that import and demonstrate the usage of these components. They interact with one or more modules, showing how the UI components are integrated into an app built with Bubble Tea.
- The CI/CD pipeline is behind the scenes but ensure to mention testing and build steps that maintain code quality.

##### Architectural Patterns and Design Principles
- Test-Driven/Golden Files Testing – Highlight that each module includes test data directories to validate UI renderings using golden files.
- Clear Separation of Core Library (functionality and logic) from Example Applications (usage/demonstration).
- Dependency Management – Clearly indicate that the project leverages Go modules (go.mod and go.sum) as well as external CI configurations (.github) for automated testing and builds.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Core Library"
        subgraph "Calendar Module"
            CA1["month.go"]:::component
            CA2["week.go"]:::component
            CA3["keymap.go"]:::component
            CA4["style.go"]:::component
            CA5["Test Data/Golden Files"]:::test
        end
        subgraph "Radio Module"
            RA1["radio.go"]:::component
            RA2["button.go"]:::component
            RA3["keymap.go"]:::component
            RA4["style.go"]:::component
            RA5["Test Data/Golden Files"]:::test
        end
        subgraph "Tabs Module"
            TA1["tabs.go"]:::component
            TA2["tab.go"]:::component
            TA3["keymap.go"]:::component
            TA4["style.go"]:::component
            TA5["Test Data/Golden Files"]:::test
        end
    end

    %% External Dependency
    BT["Bubble Tea Framework"]:::external

    %% CI/CD and Configuration
    CICD["CI/CD Pipeline (.github, go.mod, go.sum, .gitignore, LICENSE)"]:::ci

    %% Assets
    AS["Assets (Media Files)"]:::assets

    %% Example Applications
    subgraph "Example Applications"
        EX1["Calendar Example"]:::example
        EX2["Radio Example"]:::example
        EX3["Tabs Example"]:::example
    end

    %% Testing Infrastructure
    TEST["Testing (Golden Files)"]:::testInfra

    %% Relationships between Core Modules and External Dependency (Bubble Tea Framework)
    CA1 -->|"renders"| BT
    CA2 -->|"renders"| BT
    RA1 -->|"renders"| BT
    TA1 -->|"renders"| BT

    %% Each module integrates with Testing strategy
    CA5 -->|"verifies"| TEST
    RA5 -->|"verifies"| TEST
    TA5 -->|"verifies"| TEST

    %% Example Applications using the Core Modules
    EX1 -->|"uses"| CA1
    EX2 -->|"uses"| RA1
    EX3 -->|"uses"| TA1

    %% CI/CD Pipeline triggers builds and tests of Core Modules
    CICD -->|"builds/tests"| CA1
    CICD -->|"builds/tests"| RA1
    CICD -->|"builds/tests"| TA1

    %% Example Applications utilize Assets for demos
    EX1 -->|"displays"| AS
    EX2 -->|"displays"| AS
    EX3 -->|"displays"| AS

    %% Click Events for Component Mapping
    click CA1 "https://github.com/shawalli/bubbles/tree/main/calendar"
    click RA1 "https://github.com/shawalli/bubbles/tree/main/radio"
    click TA1 "https://github.com/shawalli/bubbles/tree/main/tabs"
    click EX1 "https://github.com/shawalli/bubbles/tree/main/examples/calendar"
    click EX2 "https://github.com/shawalli/bubbles/tree/main/examples/radio"
    click EX3 "https://github.com/shawalli/bubbles/tree/main/examples/tabs"
    click AS "https://github.com/shawalli/bubbles/tree/main/assets"
    click CICD "https://github.com/shawalli/bubbles/blob/main/.github"

    %% Styles
    classDef component fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef test fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef external fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef ci fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef example fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef assets fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef testInfra fill:#fcefee,stroke:#f5c6cb,stroke-width:2px;
    
    class CA1,CA2,CA3,CA4,RA1,RA2,RA3,RA4,TA1,TA2,TA3,TA4 component;
    class CA5,RA5,TA5 test;
    class BT external;
    class CICD ci;
    class EX1,EX2,EX3 example;
    class AS assets;
    class TEST testInfra;
```
