Ballast Application State Management

Ballast Core is the primary module for application developers using the Ballast MVI framework. It aggregates fundamental Ballast modules to provide core capabilities and platform-specific integrations required for building applications.

Note for Library Developers: If you are building a library, plugin, or integration intended to work with Ballast, you should depend on ballast-api instead of ballast-core to avoid unnecessary platform-specific dependencies.

Ballast Navigation is a Kotlin Multiplatform (KMP) URL-based routing library designed for managing application navigation via a backstack of URLs. It is built on top of the Ballast state management library and is framework-agnostic, making it suitable for Compose, Android, or other application types.

Key characteristics:

• Runtime-only: Operates without reflection or code generation.
• Predictable: Uses simple state management similar to a browser's address bar.
• Extensible: Integrates with the Ballast ecosystem for features like time-travel debugging (Ballast Debugger), undo/redo navigation (Ballast Undo), state synchronization (Ballast Sync), and page view tracking (Ballast Analytics).

Ballast is an opinionated Model-View-Intent (MVI) state management framework designed for Kotlin Multiplatform. It provides a structured way to manage state, handle side effects, and manage business logic across different platforms (Android, iOS, Desktop, Web, and Server-side).

Core components include:

• ViewModels: Manage the state and logic for a screen or component.
• Contracts: Define the State, Intent, and Effect types for a ViewModel.
• Handlers: Process incoming Intents.
• Side Jobs: Manage long-running or asynchronous tasks.
• Interceptors: Allow for cross-cutting concerns like logging, analytics, or crash reporting.

Ballast Queue Core is a lightweight, persistent background job queue system designed for reliable task processing. It is independent of the Ballast MVI architecture, allowing you to use it as a standalone module for enqueuing and running jobs.

Key capabilities include:

• Multiple Named Queues: Support for organizing jobs into different logical queues.
• Automatic Retries: Configurable backoff strategies for failed jobs.
• Job Cancellation: Ability to stop jobs before or during execution.
• Job Checkpoints: Persistence of state between retries to allow jobs to resume progress.
• Stored Results: Retrieval of values produced by completed jobs.

Note that advanced features like priority scheduling, unique jobs, or delayed starts depend on the specific queue driver implementation you choose.

The ballast-queue-exposed-driver is an experimental implementation of a Ballast Driver that uses Jetbrains Exposed for database access. It is designed for high-throughput, server-side workloads requiring safe concurrency.

Key features include:

• Delayed jobs
• Cluster-wide unique jobs
• Message groups

Warning: This module is experimental. The public API may change, and it should be used at your own risk.

Ballast Repository provides an opinionated way to manage application-layer data using the Model-View-Intent (MVI) pattern. It is designed to bridge the gap between UI code and domain objects by providing a state management solution for layers that live longer than a single screen (e.g., account management or API caching).

By using MVI for the repository layer, developers can use the same mental model for both UI and non-UI development, reducing context switching.

Core Concepts:

• BallastRepository: A specialized ViewModel that implements the MVI model for the repository.
• Cached<T>: An interface used to hold and update data within a Repository.
• EventBus: A mechanism to facilitate communication between different Repository instances across the layer.

The examples:desktop module provides Compose Desktop (JVM) implementations of the Ballast example scenarios. These implementations mirror the logic and scenarios found in the web module but are optimized for desktop environments.

Available example scenarios include:

• Counter: Basic state management.
• Kitchen Sink: A comprehensive demonstration of various Ballast features.
• ScoreKeeper: Application logic for scoring.
• Sync: Demonstrates synchronization capabilities.
• Undo/Redo: Demonstrates state history management.
• BGG API & Cache: Demonstrates integration with the BoardGameGeek API and caching mechanisms.

The Android module provides implementations of several Ballast example scenarios. These scenarios demonstrate how to use Ballast in an Android environment. The specific scenarios available are:

• Counter: Basic state management.
• Kitchen Sink: A comprehensive demonstration of various Ballast features.
• ScoreKeeper: Application logic involving scoring.
• Sync: Demonstrates synchronization capabilities.
• Undo/Redo: Demonstrates state history management.
• BGG API & Cache: Demonstrates integration with an external API (BoardGameGeek) and caching mechanisms.

The Shared Compose Multiplatform example supports the following platforms:

• Android
• iOS
• JVM (Desktop)
• Web (via Kobweb)

Ballast Utils supports the following platforms:

• JVM
• Android
• iOS
• JS
• WASM JS

Ballast Scheduler provides a mechanism to run periodic work by dispatching an Input to a ViewModel on a configurable schedule. It is conceptually similar to Spring's @Scheduled or the Java Timer.

It offers two primary modes of operation:

1. Non-persistent work: Runs purely on coroutines and can be embedded into an existing ViewModel. This is supported on all platforms.
2. Persistent work (Experimental): Supported on Android via integration with Android WorkManager.

The core distinction between MVVM and MVI lies in how state is applied to the user interface:

• MVVM relies on an automated framework/middle-man to automatically apply state to the UI and wire up UI interactions (like clicks) back to the Controller/ViewModel. This requires the framework to understand the specific implementation details of your Views.
• MVI (and Ballast) forgoes the automated middle-man. Instead, it provides the programmer with the current State and a way to send Inputs. The programmer then explicitly decides how to apply that state to the UI using their preferred toolkit. This makes the architecture more lightweight, unobtrusive, and compatible with modern declarative UI frameworks like Jetpack Compose, SwiftUI, or Flutter.