# skydoves/balloon architecture

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

- Interactive diagram: https://gitdiagram.com/skydoves/balloon
- Repository: https://github.com/skydoves/balloon

## Overview

##### Project type and purpose
- This is an Android multi‐module library project delivering a tooltip/popup component (“Balloon”) and Jetpack Compose integration (“balloon‐compose”), plus sample/demo apps and benchmarks. The modules are:
- balloon (core Android library)
- balloon‐compose (Jetpack Compose extension)
- app (Android demo showcasing usage)
- benchmark‐app & benchmark (micro‐benchmark apps & generators)
- buildSrc, scripts (build configuration & publishing)

##### File structure
- Top‐level: Gradle settings, CI workflows, lint/spotless, scripts, buildSrc.
- Each Android module (/balloon, /balloon-compose, /app, /benchmark-app, /benchmark) follows standard src/main/{kotlin,res}.
- Dependencies: app & benchmark-app depend on balloon & balloon-compose; buildSrc provides shared version management.
- CI: .github/workflows for Android CI, publishing, docs.

##### Key architectural insights from README
- Core module provides a Builder‐pattern API for tooltips.
- Compose module wraps core as composables.
- Demo & benchmarks illustrate integration points and performance testing.
- Uses lifecycle owners, factory pattern for lazy balloon creation.

a. Main components:
- Gradle Build System (settings.gradle.kts, buildSrc, scripts)
- Core Library Module (“balloon”)
- Compose Extension Module (“balloon-compose”)
- Demo App Module (“app”)
- Benchmark Modules (“benchmark-app”, “benchmark”)
- CI/CD Pipeline (GitHub Actions)
- Publishing (Maven Central)
b. Relationships/interactions:
- app → balloon & balloon-compose (implements tooltips)
- benchmark-app & benchmark → balloon (measures performance)
- buildSrc → all modules (provides versions configuration)
- CI workflows → triggers build/test/publish, runs on commit → module tests → publish artifacts
- Maven Central ← balloon & balloon-compose (artifacts published)
c. Architectural patterns:
- Modularization: separate core, extensions, demos, benchmarks
- Builder & Factory patterns in code (Balloon.Builder, Balloon.Factory)
- Layered build configuration (buildSrc for shared versions)
d. Technologies/frameworks:
- Kotlin & Android SDK
- Jetpack Compose
- Gradle Kotlin DSL & Version Catalog (libs.versions.toml)
- GitHub Actions for CI/CD
- Maven Central for artifact distribution

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build Configuration
    subgraph "Build System"
        direction TB
        settings["settings.gradle.kts"]:::config
        rootBuild["build.gradle.kts (root)"]:::config
        versions["gradle/libs.versions.toml"]:::config
        gradleProps["gradle.properties"]:::config
        buildSrc["buildSrc"]:::config
        publishScript["scripts/publish-module.gradle.kts"]:::config
    end

    %% Library Modules
    subgraph "Library Modules"
        direction TB
        core["balloon"]:::library
        compose["balloon-compose"]:::library
    end

    %% Application Modules
    subgraph "Application Modules"
        direction TB
        appModule["app"]:::app
        benchApp["benchmark-app"]:::app
        benchGen["benchmark"]:::app
    end

    %% Infrastructure
    actions["GitHub Actions (CI/CD)"]:::infra
    maven["Maven Central"]:::infra

    %% Dependencies from Build System
    settings --> core
    settings --> compose
    settings --> appModule
    settings --> benchApp
    settings --> benchGen

    rootBuild --> core
    rootBuild --> compose
    rootBuild --> appModule
    rootBuild --> benchApp
    rootBuild --> benchGen

    versions --> core
    versions --> compose
    versions --> appModule
    versions --> benchApp
    versions --> benchGen

    gradleProps --> core
    gradleProps --> compose
    gradleProps --> appModule
    gradleProps --> benchApp
    gradleProps --> benchGen

    buildSrc --> core
    buildSrc --> compose
    buildSrc --> appModule
    buildSrc --> benchApp
    buildSrc --> benchGen

    publishScript --> core
    publishScript --> compose

    %% Module Dependencies
    appModule -->|"uses"| core
    appModule -->|"uses"| compose
    benchApp -->|"uses"| core
    benchGen -->|"generates"| core

    %% CI/CD Pipeline
    actions --> core
    actions --> compose
    actions --> appModule
    actions --> benchApp
    actions --> benchGen
    core -->|"publish"| maven
    compose -->|"publish"| maven

    %% Styles
    classDef library fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef app fill:#E6FFEA,stroke:#28A745,color:#28A745
    classDef infra fill:#F0F0F0,stroke:#6A737D,color:#6A737D
    classDef config fill:#FFF5B1,stroke:#D29922,color:#D29922

    %% Click Events - Build System
    click settings "https://github.com/skydoves/balloon/blob/main/settings.gradle.kts"
    click rootBuild "https://github.com/skydoves/balloon/blob/main/build.gradle.kts"
    click versions "https://github.com/skydoves/balloon/blob/main/gradle/libs.versions.toml"
    click gradleProps "https://github.com/skydoves/balloon/blob/main/gradle.properties"
    click buildSrc "https://github.com/skydoves/balloon/tree/main/buildSrc/"
    click publishScript "https://github.com/skydoves/balloon/blob/main/scripts/publish-module.gradle.kts"

    %% Click Events - Core Library Module
    click core "https://github.com/skydoves/balloon/blob/main/balloon/build.gradle.kts"
    click core "https://github.com/skydoves/balloon/tree/main/balloon/src/main/kotlin/com/skydoves/balloon/"
    click core "https://github.com/skydoves/balloon/tree/main/balloon/src/main/res/"

    %% Click Events - Compose Extension Module
    click compose "https://github.com/skydoves/balloon/blob/main/balloon-compose/build.gradle.kts"
    click compose "https://github.com/skydoves/balloon/tree/main/balloon-compose/src/main/kotlin/com/skydoves/balloon/compose/"

    %% Click Events - Demo App Module
    click appModule "https://github.com/skydoves/balloon/blob/main/app/build.gradle.kts"
    click appModule "https://github.com/skydoves/balloon/tree/main/app/src/main/kotlin/com/skydoves/balloondemo/"
    click appModule "https://github.com/skydoves/balloon/tree/main/app/src/main/res/"

    %% Click Events - Benchmark App Module
    click benchApp "https://github.com/skydoves/balloon/blob/main/benchmark-app/build.gradle.kts"
    click benchApp "https://github.com/skydoves/balloon/tree/main/benchmark-app/src/main/kotlin/com/skydoves/balloon/benchmark/app/"
    click benchApp "https://github.com/skydoves/balloon/tree/main/benchmark-app/src/main/res/"

    %% Click Events - Benchmark Generator Module
    click benchGen "https://github.com/skydoves/balloon/blob/main/benchmark/build.gradle.kts"
    click benchGen "https://github.com/skydoves/balloon/blob/main/benchmark/src/main/kotlin/com/skydoves/balloon/benchmark/BaselineProfileGenerator.kt"

    %% Click Events - CI/CD Pipeline
    click actions "https://github.com/skydoves/balloon/blob/main/.github/workflows/android.yml"
    click actions "https://github.com/skydoves/balloon/blob/main/.github/workflows/baseline-profile.yml"
    click actions "https://github.com/skydoves/balloon/blob/main/.github/workflows/publish.yml"
    click actions "https://github.com/skydoves/balloon/blob/main/.github/workflows/release-docs.yaml"

    %% Click Events - Publishing
    click maven "https://github.com/skydoves/balloon/blob/main/scripts/publish-module.gradle.kts"
    click maven "https://github.com/skydoves/balloon/blob/main/.github/workflows/publish.yml"

    %% Click Events - Build Configuration Module
    click buildSrc "https://github.com/skydoves/balloon/blob/main/buildSrc/build.gradle.kts"
    click buildSrc "https://github.com/skydoves/balloon/blob/main/buildSrc/src/main/kotlin/com/skydoves/balloon/Configuration.kt"

    %% Click Events - Code Formatting & Linting
    click settings "https://github.com/skydoves/balloon/blob/main/.editorconfig"
    click settings "https://github.com/skydoves/balloon/blob/main/spotless/spotless.license.kt"
    click settings "https://github.com/skydoves/balloon/blob/main/spotless/spotless.license.xml"
```
