Guidelines (#3057)

* WIP: Reorganize the docs

* WIP: Start working on the new guidelines

* WIP: Developer Guidelines

* Update Guidelines.md

* Update Guidelines.md

* Update README

* Create Data-Modeling.md

* Update Guidelines.md

* Update Data-Modeling.md

* Update Data-Modeling.md

* Update Data-Modeling.md

* Update Data-Modeling.md

* Update Data-Modeling.md

* Update Data-Modeling.md

* Update Guidelines.md

* Update Guidelines.md

* Update Error-Handling.md

* Update Error-Handling.md

* Update Error-Handling.md

* Update Error-Handling.md

* Update Error-Handling.md

* Update Error-Handling.md

* Update Error-Handling.md

Author: ILIYANGERMANOV

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,8 +1,8 @@
 ## Pull Request (PR) Checklist
 Please check if your pull request fulfills the following requirements:
 - [ ] The PR is submitted to the `main` branch.
-- [ ] I've read the [Contribution Guidelines](https://github.com/Ivy-Apps/ivy-wallet/blob/main/CONTRIBUTING.md) and my PR doesn't break the rules.
-- [ ] I've read the [Architecture Guidelines](https://github.com/Ivy-Apps/ivy-wallet/blob/main/docs/Architecture.md).
+- [ ] I've read the [Contribution Guidelines](../CONTRIBUTING.md) and my PR doesn't break the rules.
+- [ ] I've read the [Architecture Guidelines](../docs/Guidelines.md).
 - [ ] I confirm that I've run the code locally and everything works as expected.
 - [ ] 🎬 I've attached a **screen recoding** of the changes. 
 

CONTRIBUTING.md

@@ -43,7 +43,7 @@ _Replace "YOUR_ISSUE_NUMBER" with the id/number of your issue._
 
 ### Time to work
 
-Make sure to read the **[Architecture Guidelines 🏗️](docs/Architecture.md)** before you begin.
+Make sure to read the **[Developer Guidelines 🏗️](docs/Guidelines.md)** before you begin.
 
 **🔨 Workflow:**
 

README.md

@@ -58,7 +58,7 @@ Join our Telegram community and drop a message in the "Development" topic.
 
 Ivy Wallet is a great place to code and learn. That's why we're also linking great learning materials (books, articles, videos), check them in **[docs/resources 📚](docs/resources/)**.
 
-Make sure to also check our short **[Architecture Guidelines 🏗️](docs/Architecture.md)** to learn more about the Ivy Wallet's tech side.
+Make sure to also check our short **[Developer Guidelines 🏗️](docs/Guidelines.md)** to learn more about the Ivy Wallet's tech side.
 
 [![PRs welcome!](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/Ivy-Apps/ivy-wallet/blob/main/CONTRIBUTING.md)
 
@@ -73,22 +73,27 @@ Make sure to also check our short **[Architecture Guidelines 🏗️](docs/Archi
 - [Kotlin Flow](https://kotlinlang.org/docs/flow.html) (reactive datastream)
 - [Hilt](https://dagger.dev/hilt/) (DI)
 - [ArrowKt](https://arrow-kt.io/) (functional programming)
-- [Kotest](https://kotest.io/) (unit testing)
+
+
+### Testing
+- [JUnit4](https://github.com/junit-team/junit4) (test framework, compatible with Android)
+- [Kotest](https://kotest.io/) (unit test assertions)
+- [Paparazzi](https://github.com/cashapp/paparazzi) (screneshot testing)
 
 ### Local Persistence
 - [DataStore](https://developer.android.com/topic/libraries/architecture/datastore) (key-value storage)
 - [Room DB](https://developer.android.com/training/data-storage/room) (SQLite ORM)
 
 ### Networking
-- [Ktor Client](https://ktor.io/docs/getting-started-ktor-client.html) (REST client)
+- [Ktor client](https://ktor.io/docs/getting-started-ktor-client.html) (HTTP client)
 - [Kotlinx Serialization](https://github.com/Kotlin/kotlinx.serialization) (JSON serialization)
 
 ### Build & CI
 - [Gradle KTS](https://docs.gradle.org/current/userguide/kotlin_dsl.html) (Kotlin DSL)
 - [Gradle convention plugins](https://docs.gradle.org/current/samples/sample_convention_plugins.html) (build logic)
 - [Gradle version catalogs](https://developer.android.com/build/migrate-to-catalogs) (dependencies versions)
-- [Fastlane](https://fastlane.tools/) (uploads the app to the Google PlayStore)
 - [Github Actions](https://github.com/Ivy-Apps/ivy-wallet/actions) (CI/CD)
+- [Fastlane](https://fastlane.tools/) (uploads the app to the Google PlayStore)
 
 ### Other
 - [Firebase Crashlytics](https://firebase.google.com/products/crashlytics) (stability monitoring)

docs/Guidelines.md

@@ -0,0 +1,42 @@
+# 🏗️ Developer Guidelines
+
+The biggest challenge in software engineering is the fight against **complexity**. If you're planning to contribute to Ivy Wallet, we mainly care about two things:
+
+1. Your PR works and doesn't break anything.
+2. Your PR is simple and doesn't add complexity.
+
+Software engineering is also about **thinking**. Don't just follow blindly best practices and strive to do the "right" thing. Instead, ask yourself:
+
+- Is this the simplest solution?
+- Am I over-engineering? What does this give me?
+- Can we make it simpler?
+
+Be **pragmatic**. Engineering is all about being practical and finding optimal trade-offs. Our world isn't ideal so there isn't a "perfect" solution. The best we can do is optimize for things we care about.
+
+> Follow [the 80/20 principle](https://en.wikipedia.org/wiki/Pareto_principle) - from 20% effort comes 80% of the results.
+
+In Ivy Wallet we care about:
+
+- Software complexity
+- Stability
+- Simplicity
+
+
+To recap - **THINK** and keep it simple.
+
+## [Guidelines Wiki](./guidelines)
+
+To get started read:
+
+1. **[Data Modeling](./guidelines/Data-Modeling.md)**
+2. **[Error Handling](./guidelines/Error-Handling.md)**
+3. **[Unit Testing](./guidelines/Unit-Testing.md)**
+4. **[Architecture](./guidelines/Architecture.md)**
+5. **[Screen Architecture](./guidelines/Screen-Architecture.md)**
+6. **[Screenshot Testing](./guidelines/Screenshot-Testing.md)**
+
+## References
+
+- **[Yoda Style Architecture guidelines](./archive/Yoda-Style-Architecture.md)**
+- **[Adnroid Developers - Guide to app architecture](https://developer.android.com/topic/architecture)**
+- **[The Grug Brained Developer](https://grugbrain.dev/)**

docs/Architecture.md renamed to docs/archive/Yoda-Style-Architecture.md

@@ -23,7 +23,7 @@ Separation, the path of wisdom it is: **Compose UI ≠ Logic of Screen**. Why? H
 4. **Compose Previews:** Mock `UiState`, easy it becomes. Any screen state, preview you can.
 5. **Testability:** ViewModel, easy to test it is - send `UiEvent`s, verify `UiState`. Simple. Hmmm... Compose UI, like celebrity is. Mocked `UiState` if you pass, [Paparazzi](https://github.com/cashapp/paparazzi) screenshot tests pass will.
 
-![screen-viewmodel](assets/screen-vm.svg)
+![screen-viewmodel](../assets/screen-vm.svg)
 
 ### Quick understanding, you seek?
 
@@ -48,7 +48,7 @@ Reason, straightforward it is. More strength and simplicity, the Compose runtime
 
 Follow [offical Guide to app architecture by Google](https://developer.android.com/topic/architecture), we do. Not for fleeting trends or mere style, but for wisdom it holds. Simplicity, at its core.
 
-![app-architecture](assets/app-layers.svg)
+![app-architecture](../assets/app-layers.svg)
 
 ### [Data Layer](https://developer.android.com/topic/architecture/data-layer)
 
@@ -72,7 +72,7 @@ Split our app into many modules, we do. Tangled webs ([spaghetti code](https://e
 
 Each screen, like its own planet it is. Expanding it might, with tales of code and tales. But in its own orbit, it stays. The galaxy of code, peaceful and unshaken it remains.
 
-![modularization-strategy](assets/modularization.svg)
+![modularization-strategy](../assets/modularization.svg)
 
 **Simple, our modularization path is:**
 

docs/guidelines/Architecture.md

@@ -0,0 +1,120 @@
+# Data Modeling
+
+The way your data is modeled is crucial to the complexity of your software. 
+We say that a data model `A` is better than a data model `B` <=> `A` eliminates more impossible cases than `B`. Let me show you what that means in practice.
+
+## Algebraic Data Types
+
+**Screen example**
+
+Imagine that you have to implement a screen with three states - loading, success, and error.
+A naive way to model its UI state could be:
+
+```kotlin
+data class ScreenUiState(
+  val content: String?,
+  val loading: Boolean,
+  val error: String?
+)
+```
+
+The problem with this approach is that our code will have to deal with many impossible (illegal) states. For example:
+
+- What to show if `loading = false`, `content == null`, `error == null`?
+- What to do if we have both `loading = true` and `error != null`?
+
+There are so many ways things to go wrong - for example, a common one is forgetting to reset `loading` back to `false`.
+A better way to model this would be to use [Algebraic Data types (ADTs)](https://wiki.haskell.org/Algebraic_data_type) 
+or simply said in Kotlin: `data classes`, `sealed interfaces`, and combinations of both.
+
+```kotlin
+sealed interface ScreenUiState {
+  data object Loading : ScreenUiState
+  data class Content(val text: String) : ScreenUiState
+  data class Error(val msg: String) : ScreenUiState
+}
+```
+
+With the ADTs representation, we eliminate the impossible cases of having a `content` and `error` at the same time 
+or `loading = false` and nulls for both `content` and `error`. We also eliminate that on compile-time, meaning that
+whatever shit will do - the compiler will never allow this code to run.
+
+**Takeaway:** Model your data using `data classes`, and  `sealed interfaces` (and combinations of them) in a way that:
+
+- Mirrors your domain one-to-one, exactly and explicitly.
+- Impossible cases are eliminated by construction and at compile-time.
+
+## Explicit Types
+
+Unfortunately, not all impossible cases can be eliminated at compile time. For example, imagine that we're building
+a food ordering app and want to model its domain. A naive data model could be:
+
+```kotlin
+data class Order(
+  val id: UUID,
+  val userId: UUID,
+  val itemId: UUID,
+  val count: Int,
+  val time: LocalDateTime,
+  val trackingId: String,
+)
+```
+
+I'm making this up but the goal is to demonstrate common mistakes and how to fix them.
+Do you spot them? 
+
+Let's think and analyze:
+
+1. What if someone orders a `count = 0` or even worse a `count = -1`?
+2. Imagine this function `placeOrder(orderId: UUID, userId: UUID, itemId: UUID, ...)`. How likely is someone to pass a wrong `UUID` and mess UUIDs up?
+3. The `trackingId` seems to be required but what if someone passes `trackingId = ""` or `trackingId = "XYZ "`?
+
+I can go on but you see the point. So let's how we can fix it.
+
+```kotlin
+data class Order(
+  val id: OrderId,
+  val user: UserId,
+  val item: ItemId,
+  val count: PositiveInt,
+  val time: Instant, // <-- always in UTC 
+  val trackingId: NotBlankTrimmedString
+)
+
+@JvmInline
+value class OrderId(val value: UUID)
+
+@JvmInline
+value class UserId(val value: UUID)
+
+@JvmInline
+value class ItemId(val value: UUID)
+
+@JvmInline
+value class PositiveInt private constructor(val value: Int) {
+    companion object : Exact<Int, PositiveInt> {
+        override val exactName = "PositiveInt"
+
+        override fun Raise<String>.spec(raw: Int): PositiveInt {
+            ensure(raw > 0) { "$raw is not >= 0" }
+            ensure(raw.isFinite()) { "Is not a finite number" }
+            return PositiveInt(raw)
+        }
+    }
+}
+```
+
+This data model takes more code but you'll thank me for that later because...
+**If any of your domain functions accept `order: Order` - you immediately know that it's a valid order and almost no validation logic is required.**
+
+We fixed:
+
+- Order `count` of zero, negative, or infinity by explicitly requiring a `PositiveInt` (unfortunately, that happens at runtime because the compiler can't know if a given integer is positive or not by just looking at the code).
+- The `UUID`s now can't be messed up because the compiler will give you an error if for example, you try to pass `UserId` but a function accepts `OrderId`.
+- The `time` is now always in UTC by using `Instant`.
+- The `trackignId` can't be blank or contain trailing whitespaces.
+
+To learn more about Explicit types you can check [the Arrow Exact GitHub repo](https://github.com/arrow-kt/arrow-exact).
+
+> Not all types can be exact. For example, we make an exception for DTOs and entities where we need primitives.
+> However, we still use ADTs and everything in the domain layer where the business logic is must be exact and explicit.

docs/guidelines/Data-Modeling.md

@@ -0,0 +1,104 @@
+# Error Handling
+
+It's common for operations to fail and we should expect that.
+In Ivy Wallet we **do not throw exceptions** but rather make functions that
+can fail return [Either<Error, Data>](https://arrow-kt.io/learn/typed-errors/working-with-typed-errors/).
+
+Either is a generic data type that models two possible cases:
+- `Either.Left` for the unhappy path (e.g. request failing, invalid input, no network connection)
+- `Either.Right` for the happy path
+
+Simplified, `Either` is just:
+
+```kotlin
+sealed interface Either<E, A> {
+  data class Left<E>(val data: E): Either<E, Nothing>
+  data class Right<T>(val data: A): Either<Nothing, A>
+}
+
+fun <E,A,B> Either<E, A>.fold(
+  mapLeft: (E) -> B,
+  mapRight: (A) -> B
+): B = when(this) {
+  Either.Left -> mapLeft(data)
+  Either.Right -> mapRight(data)
+}
+
+// a bunch more extension functions and utils
+```
+
+So in Ivy, operations that can fail (logically or for some other reason) we'll model using **Either**.
+
+## Data Layer example
+
+Imagine that we're building a program that buys BTC if its price is below $50,000.
+
+```kotlin
+interface BtcDataSource {
+  suspend fun fetchCurrentPriceUSD(): Either<String, PositiveDouble>
+  suspend buy(amount: PositiveDouble): Either<BuyError, Unit>
+
+  sealed interface BuyError {
+    data class IO(val e: Throwable) : BuyError
+    data object TooSmallAmount : BuyError
+  }
+}
+
+interface MyBank {
+  suspend fun currentblBalanceUSD(): Either<Unit, PositiveDouble>
+}
+
+class CryptoInvestor @Inject constructor(
+  private val btcDataSource: BtcDataSource,
+  private val myBank: MyBank
+) {
+  suspend buyIfCheap(): Either<String, PositiveDouble> = either {
+    val btcPrice = btcDataSource.fetchCurrentPriceUSD().bind()
+    // .bind() - if it fails returns Either.Left and short-circuits the function
+    if(btcPrice.value > 50_000) {
+      // short-circuits and returns Either.Left with the msg below
+      raise("BTC is expensive! Won't buy.")
+    }
+    val myBalance = myBank.currentBalanceUSD().mapLeft {
+      "Failed to fetch my bank account balance."
+    }.bind()
+    btcDataSource.buy(myBalance).mapLeft { err ->
+       when(err) {
+         is BuyError.IO -> "Failed to buy because of an IO error - ${e.msg}"
+         BuyError.TooSmallAmount -> "Failed to buy because I'm poor."
+       }
+    }.bind() // maps the BuyError to String and short-circuits
+    // Bought BTC with my entire balance!
+    myBalance // <-- the last line returns the Either.Right
+  }
+}
+```
+
+Let's analyze, simplified:
+- `either {}` puts us into a "special" scope where the last line returns `Either.Right` and also gives us access to some functions:
+  - `Operation.bind()`: if the operation fails terminates the `either {}` with operation's `Left` value, otherwise `.bind()` returns the operation's `Right` value
+  - `raise(E)`: like **throw** but for `either {}` - terminates the function with `Left(E)`
+- `Either.mapLeft {}`: transforms the `Left` (error type) of the `Either`. In the example, we do it so we can match the left type of the `either {}`
+
+## Useful `Either` functions
+
+We won't cover all but I'll list the ones that we often use in Ivy Wallet and find the most useful.
+
+- either {}
+  - Either.bind()
+  - raise()
+  - ensure()
+- Either.getOrNull()
+- Either.map {} and Either.mapLeft {}
+- Either.fold({},{})
+
+I strongly recommend allocating some time to also go through [Arrow's Working with typed errors guide](https://arrow-kt.io/learn/typed-errors/working-with-typed-errors/) which covers much more.
+
+## Fun facts about `Either`
+
+- Either is a [monad](https://en.wikipedia.org/wiki/Monad_(functional_programming)).
+- `Either<Throwable, T>` is equivalent to Kotlin's std `Result` type.
+- Many projects create a custom `Result<E, T>` while they can just use `Either` with all of its built-in features.
+
+> In some rare cases it's okay to `throw` a runtime exception. Those are the cases in which you're okay and want the app to crash
+> (e.g. not enough disk space to write in Room DB / local storage).