Library architecture and design

Welcome to Magellan! We're working hard on an update; this is the work-in-progress documentation for that update. For the old documentation, see our old wiki page, Magellan 1.x Home. If you have questions/comments/suggestions for the new documentation, please submit an issue and we'll explain ourselves better.

This page describes the class hierarchy of Magellan, including extension points for customization. For help getting started, see Thinking in Magellan and our README. The diagrams have been made with mermaid.js (in their live editor), and are all linked to their editable source. Here's the full diagram in mermaid's live editor, to make editing this wiki page easier.

Class hierarchy

Core library

The core library deals with the basics of lifecycle propagation. All provided implementations are built on these interfaces and classes, and any custom implementation should, too. It includes:

LifecycleAware interface. An object that implements this is able to accept lifecycle events from a parent.
LifecycleOwner interface. An object that implements this is able to have child LifecycleAware objects, and is responsible for managing these children's lifecycle events.
LifecycleAwareComponent abstract class. A default implementation of a LifecycleAware object that is also a LifecycleOwner.
Displayable interface. An object that implements this can be shown on the screen.
Navigable interface. An object that implements this can be navigated to, or stored on a backstack. A union of LifecycleAware and Displayable.
LinearNavigator class: a LifecycleAwareComponent that manages a backstack of Navigables and handles transitions between them.
A handful of LifecycleAwareComponents, like Shown/CreatedCoroutineScope, DialogComponent, ViewComponent, and more.

ViewBinding implementation

On top of this, we provide an opinionated ViewBinding-based implementation, including:

Step abstract class: a LifecycleAwareComponent that is also Navigable. Its associated view is constructed and accessed through view binding and has an associated CoroutineScope for management of asynchronous tasks.
Journey abstract class: a Step that has a LinearNavigator to navigate between child steps and keep a backstack.

Jetpack Compose implentation

And, soon, we'll have a Jetpack-Compose-based implementation, including:

ComposeStep abstract class: a Navigable that is just like the Step above, but with compose support instead of ViewBinding support.
ComposeJourney abstract class: a ComposeStep with a LinearNavigator that works with compose.
A handful of extension functions and wrapper classes that facilitate interoperation between view-based and compose-based Displayables.