# chrisbanes/haze architecture

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

- Interactive diagram: https://gitdiagram.com/chrisbanes/haze
- Repository: https://github.com/chrisbanes/haze

## Overview

This project is a Kotlin Multiplatform library called “Haze” with associated materials (themes) and sample apps demonstrating its usage across Android, Desktop, iOS, Web, and other platforms. The project is organized as a multi-module Gradle build with custom build logic, documentation, testing, and benchmarking components.

##### Main Components
- Core Library Modules:
- “haze”: The main library module containing the core functionality. It has a standard Kotlin Multiplatform structure with subdirectories for common code (commonMain), and platform-specific code (androidMain, appleMain, jsMain, jvmMain, skikoMain, wasmJsMain).
- “haze-materials”: An extension module providing “material” design styles and API documentation (located under haze-materials/api) along with its own multiplatform source sets.
- Build & Configuration Modules:
- Gradle build scripts and custom plugin logic are in the “gradle/build-logic” directory. These scripts define conventions and settings for Android, Java, Kotlin, Compose Multiplatform, and other build aspects.
- Gradle files at the project’s root (build.gradle.kts, settings.gradle.kts, gradle.properties, etc.) that orchestrate the overall build.
- Internal and Testing Modules:
- “internal/benchmark”, “internal/context-test”, and “internal/screenshot-test” – these modules provide performance benchmarks, context testing across platforms, and screenshot tests for UI verification.
- Sample Applications:
- Multiple sample modules exist under the “sample” directory for different platforms: Android, Desktop, iOS, Shared, and Web. These represent practical usage examples and integration tests that illustrate how the Haze library is consumed on each platform.
- Documentation & Resources:
- The “docs” directory contains documents such as FAQs, performance guides, migration notes, usage guides, and embedded media. Also, a separate “haze-materials/api” directory holds API documentation files for different versions.
- CI/CD and Project Metadata:
- GitHub workflow definitions in “.github/workflows” and configuration files such as .editorconfig, .gitignore, LICENSE, and README.md support project management and continuous integration.

##### Relationships and Interactions
- The core “haze” module serves as the foundation and is used directly or extended by the “haze-materials” module.
- Both library modules rely on shared Kotlin Multiplatform architecture, separating common logic (in commonMain) from platform-specific code.
- The build system (Gradle) orchestrates these modules using custom build logic (in gradle/build-logic). These build conventions ensure consistency across Android, Java, Kotlin, and Compose Multiplatform projects.
- Samples depend on the core and materials modules to demonstrate functionality; they provide separate entry points for each target platform.
- Internal testing and benchmarking modules interact with the core library to execute performance tests, context tests, and screenshot validations.
- Documentation components (docs and haze-materials/api) serve as external resources for users and developers to understand library usage and evolution.

##### Architectural Patterns and Design Principles
- Multiplatform Architecture: There is a clear separation between shared (commonMain) logic and platform-specific implementations. This is central to Kotlin Multiplatform design.
- Modular Design: The code is organized into multiple, clearly separated modules (core library, materials, internal testing, samples) that reduce coupling and improve maintainability.
- Custom Build Conventions: The presence of a “gradle/build-logic” module indicates a strong emphasis on standardized and reusable build configurations.
- Extensive Testing: Dedicated modules for unit tests, barcode UI, performance benchmarks, and screenshot tests highlight an architecture that supports continuous integration and quality assurance.

##### Relevant Technologies, Frameworks, and Libraries
- Kotlin and Kotlin Multiplatform: The core of the project’s language and compilation strategy.
- Gradle (with Kotlin DSL): Used for project building, dependency management, and custom build logic.
- Android, iOS, Desktop (JVM/Skiko), Web (JS/Wasm): The project targets several platforms, each with its own source sets and configurations.
- Custom Gradle plugins and conventions: Found in the “gradle/build-logic” directory for configuring Android, Java/Kotlin, Compose Multiplatform, etc.

- Branch out into the core library, then further detail the multiplatform source sets (common vs. Android/iOS/JS/JVM, etc.).
- Extension modules (haze-materials) that build on top of the core.
- Supporting modules like internal tests and benchmarks, and then sample apps demonstrating real-world usage.

## Diagram (Mermaid)

```mermaid
flowchart TD
    A["Build & Custom Plugin Infrastructure"]:::build
    A -->|"orchestrates"| B["Core Library (haze)"]:::core

    subgraph "Modules dependent on Core Library"
        C["Materials Extension (haze-materials)"]:::extension

        subgraph "Internal Testing Modules"
            D1["Benchmark Module"]:::test
            D2["Context Testing Module"]:::test
            D3["Screenshot Testing Module"]:::test
        end

        subgraph "Sample Applications"
            E1["Android Sample Application"]:::sample
            E2["Desktop Sample Application"]:::sample
            E3["iOS Sample Application"]:::sample
            E4["Web Sample Application"]:::sample
            E5["Shared Sample Application"]:::sample
        end

        F["Documentation"]:::docs
        H["Materials API Documentation"]:::docs
    end

    G["CI/CD & Metadata"]:::cicd

    %% Establishing Relationships
    B -->|"provides"| C
    B -->|"tested_by"| D1
    B -->|"tested_by"| D2
    B -->|"tested_by"| D3
    B -->|"used_by"| E1
    B -->|"used_by"| E2
    B -->|"used_by"| E3
    B -->|"used_by"| E4
    B -->|"used_by"| E5
    C -->|"enhances"| E1
    C -->|"enhances"| E2
    C -->|"enhances"| E3
    C -->|"enhances"| E4
    C -->|"enhances"| E5
    F -->|"describes"| B
    F -->|"describes"| C
    H -->|"documents"| C
    A -->|"manages"| G

    %% Styles
    classDef build fill:#FFCCFF,stroke:#333,stroke-width:2px;
    classDef core fill:#CCFFCC,stroke:#333,stroke-width:2px;
    classDef extension fill:#CCE5FF,stroke:#333,stroke-width:2px;
    classDef test fill:#FFD9B3,stroke:#333,stroke-width:2px;
    classDef sample fill:#E5CCFF,stroke:#333,stroke-width:2px;
    classDef docs fill:#CCFFDD,stroke:#333,stroke-width:2px;
    classDef cicd fill:#FFCCCC,stroke:#333,stroke-width:2px;

    %% Click Events
    click A "https://github.com/chrisbanes/haze/tree/main/gradle/build-logic/"
    click B "https://github.com/chrisbanes/haze/tree/main/haze/"
    click C "https://github.com/chrisbanes/haze/tree/main/haze-materials/"
    click D1 "https://github.com/chrisbanes/haze/tree/main/internal/benchmark/"
    click D2 "https://github.com/chrisbanes/haze/tree/main/internal/context-test/"
    click D3 "https://github.com/chrisbanes/haze/tree/main/internal/screenshot-test/"
    click E1 "https://github.com/chrisbanes/haze/tree/main/sample/android"
    click E2 "https://github.com/chrisbanes/haze/tree/main/sample/desktop"
    click E3 "https://github.com/chrisbanes/haze/tree/main/sample/ios"
    click E4 "https://github.com/chrisbanes/haze/tree/main/sample/web"
    click E5 "https://github.com/chrisbanes/haze/tree/main/sample/shared"
    click F "https://github.com/chrisbanes/haze/tree/main/docs/"
    click H "https://github.com/chrisbanes/haze/tree/main/haze-materials/api/"
    click G "https://github.com/chrisbanes/haze/tree/main/.github/workflows/"
```
