Shuttle

<div align="center">
  <img src="https://github.com/grarcht/Shuttle/raw/main/shuttle_header.png" alt="Shuttle" width="100%"/>

<h3>Prevent <code>TransactionTooLargeException</code> crashes. For good.</h3>
  <p>A modern Android framework for safely transporting large <code>Serializable</code> objects between components, without the crashes.</p>

  <br/>

<a href="https://github.com/grarcht/Shuttle/blob/main/LICENSE.md"><img src="https://img.shields.io/github/license/grarcht/shuttle?color=white&style=plastic" alt="License: MIT"/></a>
<a href="https://search.maven.org/artifact/com.grarcht.shuttle/framework"><img src="https://img.shields.io/maven-central/v/com.grarcht.shuttle/framework?color=teal&style=plastic" alt="Maven Central"/></a>
<a href="https://grarcht.github.io/Shuttle/documentation/"><img src="https://img.shields.io/badge/API%20Docs-Dokka-blueviolet?style=plastic" alt="API Docs"/></a>
<a href="https://developer.android.com/studio/releases/platforms"><img src="https://img.shields.io/badge/Min%20SDK-26-brightgreen?style=plastic" alt="Min SDK"/></a>
<a href="https://kotlinlang.org/"><img src="https://img.shields.io/badge/Kotlin-2.2.10-purple?style=plastic" alt="Kotlin"/></a>

  <br/>

<a href="https://androidweekly.net/issues/issue-594"><img src="https://img.shields.io/badge/Android%20Weekly-Issue%20%23594-orange?style=flat" alt="Android Weekly #594"/></a>
<a href="https://androidweekly.net/issues/issue-455"><img src="https://img.shields.io/badge/Android%20Weekly-Issue%20%23455-orange?style=flat" alt="Android Weekly #455"/></a>

</div>

---

## Get To It Quick

- [API Documentation](https://grarcht.github.io/Shuttle/documentation/)
- [Why Shuttle?](#-why-shuttle)
- [How It Works](#-how-it-works)
- [Requirements](#requirements)
- [Quick Start](#-quick-start)
- [Usage](#-usage)
  - [Transport with Intents](#transport-with-intents)
  - [Transport with the Navigation Component](#transport-with-the-navigation-component)
  - [Pick Up Cargo at the Destination](#pick-up-cargo-at-the-destination)
  - [Cargo States (LCE Pattern)](#cargo-states-lce-pattern)
  - [Using @ShuttleCargo](#using-shuttlecargo)
  - [Cleaning Up](#cleaning-up)
- [Architecture](#️-architecture)
  - [Context Diagram](#context-diagram)
  - [Module Overview](#module-overview)
  - [Module Dependency Diagram](#module-dependency-diagram)
- [Demo Apps](#-demo-apps)
- [Heads Up: Know the Tradeoffs](#️-heads-up-know-the-tradeoffs)
- [Contributing](#-contributing)
- [License](#-license)

---

## 🚨 Why Shuttle?

> 🗞️ **Featured in [Android Weekly #594](https://androidweekly.net/issues/issue-594) and [Android Weekly #455](https://androidweekly.net/issues/issue-455)**, validated by the Android community twice.

You've seen this before. Maybe last week:

```
android.os.TransactionTooLargeException: data parcel size X bytes
```

It didn't show up in dev. It didn't show up in QA. It showed up at 2am, in production, for real users. Your Play Store rating took the hit before anyone on the team even knew.

So you triaged it. Filed the ticket. Wrote the fix. Reviewed the PR. Ran QA again. Cut the hotfix. And then you added it to the code review checklist, hoping the next engineer would catch it before it happened again.

They won't. Not reliably. **You can't review your way out of a structural problem.**

Shuttle provides a modern, guarded way to pass large `Serializable` objects with `Intent` objects or save them in `Bundle` objects to avoid app crashes. The crash class is structurally prevented, not governed against.

Why keep spending more time and money on governance through code reviews? Why not embrace the problem by providing a solution for it?

**Shuttle reduces the high level of governance needed to catch `TransactionTooLargeException` inducing code by:**
1. storing the `Serializable` and passing an identifier for the `Serializable`
2. using a small-sized `Bundle` for binder transactions
3. avoiding app crashes from `TransactionTooLargeException`s
4. enabling retrieval of the stored `Serializable` at the destination

**Shuttle also excels by:**
1. providing a solution with maven artifacts
2. providing Solution Building Blocks (SBBs) for building on
3. saving time by avoiding DB and table setup, especially when creating many tables for the content of different types of objects

When envisioning, designing, and creating the architecture, quality attributes and best practices were kept in mind. These attributes include usability, readability, recognizability, reusability, maintainability, and more.

| Without Shuttle                                                      | With Shuttle                                                    |
|----------------------------------------------------------------------|-----------------------------------------------------------------|
| Large `Serializable` passed in `Intent`/`Bundle`                     | Object stored in a warehouse; only a small identifier is passed |
| Silent in dev, catastrophic in production                            | Binder transaction stays within safe size limits, everywhere    |
| Time and money spent on crash investigation, fixes, QA, and hotfixes | Crash class is structurally impossible                          |
| Requires constant code review governance                             | Ship with confidence                                            |
| Engineers manually manage object lifecycles                          | Automatic or on-demand cargo cleanup built in                   |
| <img src="media/videos/without_shuttle.gif" width="75%"/>           | <img src="media/videos/with_shuttle.gif" width="75%"/>         |

---

## ⚙️ How It Works

[![Saving Android Apps From Crashes | The Shuttle Framework and Solution](https://markdown-videos-api.jorgenkh.no/url?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3D4Nl9zlcbwU4)](https://www.youtube.com/watch?v=4Nl9zlcbwU4)

The Shuttle framework takes its name from cargo transportation in the freight industry. Moving and storage companies experience scenarios where large moving trucks cannot transport cargo the entire way to the destination (warehouses, houses, et cetera). These scenarios might occur from road restrictions, trucks being overweight from large cargo, and more. As a result, companies use small Shuttle vans to transport smaller cargo groups on multiple trips to deliver the entire shipment.

After the delivery is complete, employees remove the cargo remnants from the shuttle vans and trucks. This clean-up task is one of the last steps for the job.

The Shuttle framework takes its roots in these scenarios:
- creating a smaller cargo bundle object to use in successfully delivering the data to the destination
- shuttling the corresponding large cargo to a warehouse and storing it for pickup
- linking the smaller cargo with the larger cargo by an identifier
- providing a single source of truth (Shuttle interface) to use for transporting cargo
- providing convenience functions to remove cargo (automatically or on-demand)

Shuttle applies this same logic to Android's binder transaction limit:

```
┌─────────────────────────────────────────────────────────────┐
│  Source Component                                           │
│  1. Large Serializable -> stored in Warehouse (Room/DB)     │
│  2. Small cargo ID     -> passed in Intent/Bundle           │
└──────────────────────────────┬──────────────────────────────┘
                               │ (tiny binder transaction)
┌──────────────────────────────▼──────────────────────────────┐
│  Destination Component                                      │
│  3. Cargo ID received -> retrieved from Warehouse           │
│  4. Large Serializable -> delivered via Kotlin Channel      │
│  5. Cleanup -> cargo removed from Warehouse automatically   │
└─────────────────────────────────────────────────────────────┘
```

---

## Requirements

| Requirement | Minimum |
|---|---|
| Android min SDK | 26 |
| Kotlin | 2.2.10 |
| AGP (Android Gradle Plugin) | 8.0+ |
| KSP | Required only when using `@ShuttleCargo` |
| Java | 21 |

---

## 🚀 Quick Start

### 1. Add Dependencies

**`settings.gradle.kts`** — apply the Shuttle Gradle plugin so the `@ShuttleCargo` annotation processor is wired into your build:

`@ShuttleCargo` annotates the cargo class you want to transport between screens. At build time, the annotation processor generates the serialization code Shuttle needs to store and retrieve cargo, without any manual `Serializable` boilerplate.
```kotlin
pluginManagement {
    plugins {
        id("com.grarcht.shuttle.cargo") version "4.0.0"
    }
}
```

The Shuttle Cargo Gradle plugin configures KSP and registers the Shuttle compiler plugin automatically. Without it, `@ShuttleCargo`-annotated classes will not generate the required serialization glue code.

**`build.gradle.kts`:**
```kotlin
plugins {
    id("com.grarcht.shuttle.cargo")
}

dependencies {
    implementation(platform("com.grarcht.shuttle:shuttle-bom:4.0.0"))
    implementation("com.grarcht.shuttle:framework")
    implementation("com.grarcht.shuttle:framework-integrations-persistence")
    implementation("com.grarcht.shuttle:framework-integrations-extensions-room")
    implementation("com.grarcht.shuttle:framework-addons-navigation-component") // Optional

    // Annotation-based API — use @ShuttleCargo to own the serialization contract
    implementation("com.grarcht.shuttle:framework-annotations")
    ksp("com.grarcht.shuttle:framework-annotations-processor")
}
```

**Version Catalog (`libs.versions.toml`):**
```toml
[versions]
shuttle = "4.0.0"

[plugins]
shuttle-cargo = { id = "com.grarcht.shuttle.cargo", version.ref = "shuttle" }

[libraries]
shuttle-bom = { group = "com.grarcht.shuttle", name = "shuttle-bom", version.ref = "shuttle" }
shuttle-framework = { group = "com.grarcht.shuttle", name = "framework" }
shuttle-persistence = { group = "com.grarcht.shuttle", name = "framework-integrations-persistence" }
shuttle-room = { group = "com.grarcht