mobile/android/fenix/docs/Architecture-Decisions.md

   1 # Architecture Decisions
   2
   3 For an overview of our current architecture, please see [this document](https://github.com/mozilla-mobile/fenix/blob/master/docs/architecture-overview.md)
   4
   5 ---
   6
   7 These are some of the major architecture decisions we've made so far in Fenix. [Why?](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions)
   8
   9 ---
  10
  11 ## Overview
  12
  13 Several apps have suffered from insufficient attention to appropriate Android application architecture. This leads to spaghetti code, God objects, and leaky abstractions that make testing and maintaining our apps significantly more costly and challenging.
  14
  15 ---
  16
  17 ## Goals
  18
  19 Our architecture should:
  20
  21 * Have classes which aim to fulfill a single responsibility, thereby separating concerns.
  22 * Improve the ability of developers to write effective automated unit and UI tests.
  23 * Make the bulk of application code more readable, easing onboarding of contributors.
  24 * Improve the ability to debug application errors with useful stack traces.
  25 * Be amenable to code reuse when desirable.
  26 * Handle A/B experimentation without vast code branches or confusion.
  27
  28 ---
  29
  30 ## Special Concerns
  31
  32 As a browser, Fenix will need to interface with the Android Components and the GeckoView rendering engine. This means any architecture we choose must not require that all components of the app are implemented similarly. Also, our application state will need to synchronize with the engine’s state as the two will not always be in perfect sync due to hidden internals.
  33
  34 ---
  35
  36 ## Component Architecture
  37
  38 ### Context
  39
  40 A/B testing of layout and UX is a fundamental necessity of Fenix. We have a lot of hypotheses needing validation and actual usage data about what might make a browser better to acquire and retain more users. A lot of questionable decisions have been made in older mobile browsers that do not seem ideal for mobile devices, but we need data to tell us if our assumptions are correct.
  41
  42 ### Decision
  43
  44 We did a review of modern app architectures used by companies throughout the tech industry and came across the Netflix "componentization" architecture. Netflix had a special desire to A/B test a lot of different layouts for their app's user interface and built their architecture for this express purpose.
  45
  46 Netflix's architecture moves all UX-related code away from activities and fragments. Instead, fragments subscribe to components through RxJava and components inflate themselves.
  47
  48 The actual components' inflated views are dropped into ConstraintLayouts and are tied together by applying programmatic ConstraintSets. ConstraintLayouts and ConstraintSets also tie nicely into the new and ultra-powerful MotionLayouts to empower rich animations.
  49
  50 Here are some videos of Juliano Moraes of Netflix describing their architecture:
  51
  52 [DroidCon NYC part 1 video](https://www.youtube.com/watch?v=dS9gho9Rxn4)
  53
  54 [DroidCon SF part 2 video](https://www.youtube.com/watch?v=1cWwfh_5ZQs)
  55
  56 Here's a [sample repository](https://github.com/julianomoraes/componentizationArch) demonstrating in a very simple form how it functions.
  57
  58 The goal of software architecture is to minimize the cost of change. This decision is possibly the biggest factor for reducing the cost of changes to Fenix. It also plays well with the Android Components project, which provides so many of the components that will make up this project.
  59
  60 ### Consequences
  61
  62 We will package the UI into components which are reusable and can be remixed for A/B layout tests.
  63
  64 We will keep all UI/UX code out of activities and fragments to obey the [Single Responsibility Principle](https://blog.cleancoder.com/uncle-bob/2014/05/08/SingleReponsibilityPrinciple.html). These classes will exist to handle OS business logic and to bind components.
  65
  66 One downside of this is the extra cost of getting contributors to avoid making UI/UX changes directly from activities and fragments. Another is programmatic layouts don't play well with previewing layouts. We'll all need to learn how to use ConstraintLayouts and ConstraintSets effectively.
  67
  68 ---
  69
  70 ## Localized, MVI (Model-View-Intent) Unidirectional Architecture
  71
  72 ### Context
  73
  74 Race conditions are the bane of Android apps everywhere. They often happen because multiple systems cannot agree about state.
  75
  76 ### Decision
  77
  78 The best solution is to have all state changes flow in a functional, reactive manner out from a single source of truth with careful thread locking as required. This solution will be familiar to anyone who has worked with Redux or Flux.
  79
  80 Within each component, we'd like state changes to occur in a cycle. The user interface's contents are rendered by presenting an initial ViewState to the screen. When the user interacts with the app, a Change object is passed to a state reducer. The reducer function copies the current, immutable state with the requested changes and passes it to the Model. The View subscribes to these state changes and updates itself reactively.
  81
  82 In this manner, the UX of the app only flows in a single direction from a source of truth. Because all changes happen in a serialized RxKotlin Observable, they will be applied in the order they happen.
  83
  84 However, unlike some MVI architectures, we will not focus on keeping a global ViewState that encompasses all state. There are times when we want OS calls, NDK calls, and third party component calls to be the source of truth. Rather than trying to make a single ViewState that contains all state, we'll be able to observe a merged observable of all actions and state changes. This will be invaluable for debugging the app.
  85
  86 Here's a [state diagram of the MVI architecture](https://staltz.com/img/mvi-unidir-ui-arch.jpg).
  87
  88 ### Consequences
  89
  90 We will experiment with writing new components using MVI unidirectional principles. We will need to take care when passing data between components that we do not override a more authoritative source of truth.
  91
  92 Because all changes can be represented by a single, merged and serialized Observable or Flowable, we should be able to use this for debugging. All ViewStates, Changes, and Actions/Intents will be easily loggable to observe the causes of state issues.