# jakewharton/mosaic architecture

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

- Interactive diagram: https://gitdiagram.com/jakewharton/mosaic
- Repository: https://github.com/jakewharton/mosaic

## Overview

##### Major high-level components
- Build System & Support – The top-level build scripts (build.gradle, gradle.properties, settings.gradle) plus the build-support module are responsible for configuring the project’s build and dependency management across all modules.
- Core Runtime – The mosaic-runtime module encapsulates the core mechanics. It contains the common Compose runtime functionality along with platform-specific implementations (jvmMain, nativeMain, etc.) that are responsible for rendering, layout, and state management.
- Animation Layer – The mosaic-animation module handles animated effects. This module contains composable animation APIs and logic (e.g., easing functions, transitions, state changes) that integrate with the runtime.
- Terminal Abstraction – There are two primary terminal-related modules: mosaic-terminal and mosaic-tty-terminal (as well as mosaic-tty). They provide APIs for controlling ANSI output, handling terminal events, and managing platform-specific details (TTY, native, JVM, etc.). These modules connect the rendering system from runtime/animation to the actual console.
- Testing & Samples – Mosaic-testing and the samples folders (e.g., counter, demo, jest, robot, rrtop, snake) demonstrate how the library is used. They provide examples of how to set up and run Mosaic-based UIs, including state management and interactions.

##### Lay out the inter-module relationships
- The entrypoint is the runMosaic function (in the runtime module) called by user applications, which ties together the Compose-based UI definitions.
- The runtime calls on layout and drawing APIs provided by mosaic-runtime which then interface with terminal I/O modules (mosaic-terminal, mosaic-tty, mosaic-tty-terminal) to display the UI on the console.
- The animation module supplements these calls with animated transitions or state-driven UI updates.
- The build-support module helps ensure that all these components compile and integrate correctly in a multiplatform context.
- The samples demonstrate concrete usage and have dependencies on the runtime (and transitively on the animation and terminal modules).

##### Architectural patterns and design principles
- Multiplatform Architecture – Notice the widely separated commonMain code versus platform (jvmMain, nativeMain, etc.), indicating an emphasis on maximum code reuse while tailoring the terminal and rendering behavior to each platform.
- Declarative UI Composition – Inspired by Jetpack Compose’s declarative approach, the project uses composable functions and state management (e.g., composable “remember” blocks and mutable state) to update the UI dynamically.
- Modularity – The project is organized into clearly defined modules (runtime, animation, terminal, testing) to allow each to be developed, tested, and maintained independently. This promotes separation of concerns and extensibility.

##### Final advice
- Every component is clearly labeled.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Build Support & Configuration"
        buildGradle["build.gradle"]:::build
        gradleProps["gradle.properties"]:::build
        settingsGradle["settings.gradle"]:::build
        buildSupport["Build Support Module"]:::build
    end

    subgraph "Core Modules"
        subgraph "Mosaic Runtime"
            runMosaic["runMosaic Entrypoint"]:::runtime
            runtime["Mosaic Runtime"]:::runtime
        end
        animation["Mosaic Animation"]:::animation
    end

    subgraph "Terminal Abstraction"
        terminalAPIs["Terminal APIs"]:::terminal
        ttyTerminal["TTY Terminal"]:::terminal
        ttySupport["TTY Support"]:::terminal
    end

    subgraph "Testing & Samples"
        testing["Mosaic Testing"]:::testing
        samples["Samples & Demos"]:::samples
    end

    %% Relationships
    runMosaic -->|"initiates"| runtime
    samples -->|"uses"| runtime
    runtime -->|"calls"| animation
    runtime -->|"outputs_to"| terminalAPIs

    buildSupport ---|"configures"| runtime
    buildSupport ---|"configures"| animation
    buildSupport ---|"configures"| terminalAPIs
    buildSupport ---|"configures"| testing
    buildSupport ---|"configures"| samples

    %% Click Events
    click buildGradle "https://github.com/jakewharton/mosaic/blob/trunk//build.gradle"
    click gradleProps "https://github.com/jakewharton/mosaic/blob/trunk//gradle.properties"
    click settingsGradle "https://github.com/jakewharton/mosaic/blob/trunk//settings.gradle"
    click buildSupport "https://github.com/jakewharton/mosaic/tree/trunk//build-support"
    click runtime "https://github.com/jakewharton/mosaic/tree/trunk//mosaic-runtime"
    click animation "https://github.com/jakewharton/mosaic/tree/trunk//mosaic-animation"
    click terminalAPIs "https://github.com/jakewharton/mosaic/tree/trunk//mosaic-terminal"
    click ttyTerminal "https://github.com/jakewharton/mosaic/tree/trunk//mosaic-tty-terminal"
    click ttySupport "https://github.com/jakewharton/mosaic/tree/trunk//mosaic-tty"
    click testing "https://github.com/jakewharton/mosaic/tree/trunk//mosaic-testing"
    click samples "https://github.com/jakewharton/mosaic/tree/trunk//samples"

    %% Styles
    classDef build fill:#FFD1DC,stroke:#d6336c,stroke-width:2px;
    classDef runtime fill:#C3DAF9,stroke:#1C7CD6,stroke-width:2px;
    classDef animation fill:#C1F7C5,stroke:#30A46C,stroke-width:2px;
    classDef terminal fill:#F9CCE1,stroke:#D6336C,stroke-width:2px;
    classDef testing fill:#FFF3B0,stroke:#D9A441,stroke-width:2px;
    classDef samples fill:#CFF4FC,stroke:#1FB6FF,stroke-width:2px;
```
