# dofire/floating-bubble-view architecture

> Architecture diagram of the GitHub repository dofire/floating-bubble-view, 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/dofire/floating-bubble-view
- Repository: https://github.com/dofire/floating-bubble-view

## Overview

##### Main Components
- Library Module (FloatingBubbleView):
- Contains the core code for the floating bubble functionality.
- Organized into packages such as:
○ Main functionality (e.g., AndroidVersions.kt, AnimHelper.kt, XMath.kt)
○ Bubble components under “bubble” (Bubble, FloatingBubble, FloatingCloseBubble, etc.)
○ Service layer under “service” (including ExpandableBubbleService, FullScreenBubbleService) along with sub-packages like “expandable” (BubbleBuilder, ExpandedBubbleBuilder) and “fullscreen”
○ Helper classes (NotificationHelper, ViewHelper)
○ Supporting utilities (ComposeLifecycleOwner, etc.)
- Resources (animations, drawables, layouts, values) used for the bubble’s appearance and animations.

- Sample App Module (“app”):
- Demonstrates the integration and usage of the library.
- Contains example activities, manifest definitions, and Java/Kotlin sample code.
- Helps in visualizing how the floating bubble service is started, how bubbles are expanded/minimized, and how notifications are integrated.

- External Factors:
- Android OS: Manages system-level aspects like foreground services and special permissions (e.g., SYSTEM_ALERT_WINDOW, FOREGROUND_SERVICE, POST_NOTIFICATIONS for Android 13+).
- Gradle Build System: Used for compiling the project and managing dependencies.

##### Relationships and Interactions
- User Interaction:
- The user interacts with the floating bubble on the screen.
- When the user taps the bubble, an event listener (FloatingBubbleListener) triggers actions such as “expand” to show an expanded bubble view.

- Service Interaction:
- The core logic is encapsulated in the service (ExpandableBubbleService/FloatingBubbleService) that manages showing, collapsing, and animating the bubble.
- The service is responsible for starting in the foreground and managing notifications (handled by NotificationHelper).

- Builder Pattern:
- The library makes use of builder classes (BubbleBuilder and ExpandedBubbleBuilder) to allow flexible configuration of both the bubble view and its expanded variant.

- UI Integration:
- The library supports both traditional XML and Jetpack Compose approaches for defining bubble UIs.

##### Important Architectural Patterns and Technologies
- Modular Architecture:
- Separation between the library (FloatingBubbleView) and the sample application (app) to demonstrate usage.

- Builder Pattern:
- Utilized for configuring the bubble view and the expanded bubble. This provides a clear and extendable API for developers.

- Service-Oriented Design:
- The bubble functionality is delivered through an Android foreground service to handle life-cycle events, notifications, and user interactions reliably.

- UI Flexibility:
- Dual support for XML layouts and Jetpack Compose enables modern UI development alongside legacy methods.

- Integration with Android's Foreground Services and Permission Model:
- Clear reliance on Android OS permissions and service management for rendering UI elements on top of other apps.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Entities
    User("User"):::external
    AndroidOS("Android OS"):::external
    Gradle("Gradle Build System"):::external

    %% FloatingBubbleView Library Module
    subgraph "FloatingBubbleView Library"
        FBL["FloatingBubbleView Library"]:::core

        %% UI Components
        subgraph "UI Components"
            Bubble["Bubble"]:::ui
            FloatingBubble["FloatingBubble"]:::ui
            FloatingCloseBubble["FloatingCloseBubble"]:::ui
        end

        %% Service Layer
        subgraph "Service Layer"
            FBS["FloatingBubbleService"]:::service
            Expandable["ExpandableBubbleService"]:::service
            FullScreen["FullScreenBubbleService"]:::service
        end

        %% Builder Components
        subgraph "Builder Components"
            BubbleBuilder["BubbleBuilder"]:::builder
            ExpandedBubbleBuilder["ExpandedBubbleBuilder"]:::builder
        end

        %% Helper Classes
        subgraph "Helper Classes"
            NotificationHelper["NotificationHelper"]:::helper
            ViewHelper["ViewHelper"]:::helper
            ComposeLifecycleOwner["ComposeLifecycleOwner"]:::helper
        end

        %% Utilities & Event Listener
        subgraph "Utilities & Event Listener"
            AndroidVersions["AndroidVersions"]:::util
            AnimHelper["AnimHelper"]:::util
            XMath["XMath"]:::util
            FloatingBubbleListener["FloatingBubbleListener"]:::util
        end

        %% Resource Layer
        subgraph "Resource Layer"
            Animations["Animations"]:::resource
            Layouts["Layouts"]:::resource
            Drawables["Drawables"]:::resource
            Values["Values"]:::resource
        end
    end

    %% Sample Application Module
    SampleApp["Sample Application"]:::sample

    %% Relationships and Interactions

    %% User interaction cycle:
    User -->|"taps"| Bubble
    Bubble -->|"triggers"| FloatingBubbleListener
    FloatingBubbleListener -->|"handles"| Expandable

    %% Service interactions:
    Expandable -->|"configures"| BubbleBuilder
    Expandable -->|"configures"| ExpandedBubbleBuilder
    Expandable -->|"manages notifications"| NotificationHelper

    %% UI Integration:
    FBS -->|"renders UI via"| ViewHelper
    ViewHelper -->|"updates"| FloatingBubble
    ComposeLifecycleOwner -->|"manages"| FloatingBubble

    %% Sample Application integration:
    SampleApp -->|"starts service"| FBS

    %% External interactions:
    AndroidOS -->|"manages permissions for"| FBS
    AndroidOS -->|"manages permissions for"| Expandable
    Gradle -->|"builds"| SampleApp

    %% Click Events for FloatingBubbleView Library and its components
    click FBL "https://github.com/dofire/floating-bubble-view/tree/master/FloatingBubbleView/src/main/java/com/torrydo/floatingbubbleview"
    click Bubble "https://github.com/dofire/floating-bubble-view/blob/master/FloatingBubbleView/src/main/java/com/torrydo/floatingbubbleview/bubble/Bubble.kt"
    click FloatingBubble "https://github.com/dofire/floating-bubble-view/blob/master/FloatingBubbleView/src/main/java/com/torrydo/floatingbubbleview/bubble/FloatingBubble.kt"
    click FloatingCloseBubble "https://github.com/dofire/floating-bubble-view/blob/master/FloatingBubbleView/src/main/java/com/torrydo/floatingbubbleview/bubble/FloatingCloseBubble.kt"
    click FBS "https://github.com/dofire/floating-bubble-view/blob/master/FloatingBubbleView/src/main/java/com/torrydo/floatingbubbleview/service/FloatingBubbleService.kt"
    click Expandable "https://github.com/dofire/floating-bubble-view/blob/master/FloatingBubbleView/src/main/java/com/torrydo/floatingbubbleview/service/expandable/ExpandableBubbleService.kt"
    click FullScreen "https://github.com/dofire/floating-bubble-view/blob/master/FloatingBubbleView/src/main/java/com/torrydo/floatingbubbleview/service/fullscreen/FullScreenBubbleService.kt"
    click BubbleBuilder "https://github.com/dofire/floating-bubble-view/blob/master/FloatingBubbleView/src/main/java/com/torrydo/floatingbubbleview/service/expandable/BubbleBuilder.kt"
    click ExpandedBubbleBuilder "https://github.com/dofire/floating-bubble-view/blob/master/FloatingBubbleView/src/main/java/com/torrydo/floatingbubbleview/service/expandable/ExpandedBubbleBuilder.kt"
    click NotificationHelper "https://github.com/dofire/floating-bubble-view/blob/master/FloatingBubbleView/src/main/java/com/torrydo/floatingbubbleview/helper/NotificationHelper.kt"
    click ViewHelper "https://github.com/dofire/floating-bubble-view/blob/master/FloatingBubbleView/src/main/java/com/torrydo/floatingbubbleview/helper/ViewHelper.kt"
    click ComposeLifecycleOwner "https://github.com/dofire/floating-bubble-view/blob/master/FloatingBubbleView/src/main/java/com/torrydo/floatingbubbleview/ComposeLifecycleOwner.kt"
    click AndroidVersions "https://github.com/dofire/floating-bubble-view/blob/master/FloatingBubbleView/src/main/java/com/torrydo/floatingbubbleview/AndroidVersions.kt"
    click AnimHelper "https://github.com/dofire/floating-bubble-view/blob/master/FloatingBubbleView/src/main/java/com/torrydo/floatingbubbleview/AnimHelper.kt"
    click XMath "https://github.com/dofire/floating-bubble-view/blob/master/FloatingBubbleView/src/main/java/com/torrydo/floatingbubbleview/XMath.kt"
    click FloatingBubbleListener "https://github.com/dofire/floating-bubble-view/blob/master/FloatingBubbleView/src/main/java/com/torrydo/floatingbubbleview/FloatingBubbleListener.kt"
    click Animations "https://github.com/dofire/floating-bubble-view/tree/master/FloatingBubbleView/src/main/res/anim"
    click Layouts "https://github.com/dofire/floating-bubble-view/tree/master/FloatingBubbleView/src/main/res/layout"
    click Drawables "https://github.com/dofire/floating-bubble-view/tree/master/FloatingBubbleView/src/main/res/drawable"
    click Values "https://github.com/dofire/floating-bubble-view/tree/master/FloatingBubbleView/src/main/res/values"
    click SampleApp "https://github.com/dofire/floating-bubble-view/tree/master/app"

    %% Styles
    classDef core fill:#FAD7A0,stroke:#D35400,stroke-width:2px,color:#000;
    classDef ui fill:#AED6F1,stroke:#2471A3,stroke-width:2px,color:#000;
    classDef service fill:#C8E6C9,stroke:#1B5E20,stroke-width:2px,color:#000;
    classDef builder fill:#F9E79F,stroke:#B7950B,stroke-width:2px,color:#000;
    classDef helper fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px,color:#000;
    classDef util fill:#F5B7B1,stroke:#C0392B,stroke-width:2px,color:#000;
    classDef resource fill:#D6EAF8,stroke:#2E86C1,stroke-width:2px,color:#000;
    classDef sample fill:#D5F5E3,stroke:#27AE60,stroke-width:2px,color:#000;
    classDef external fill:#FDEDEC,stroke:#E74C3C,stroke-width:2px,color:#000;
```
