Overhaul "Building a Full Stack Web App with Kotlin Multiplatform"

Author: SebastianAigner

Full Stack Web App with Kotlin Multiplatform/01_Introduction.md

@@ -1,35 +1,48 @@
 # Introduction
 
-In this hands-on, we will learn how to build a connected application consisting of a Kotlin/JVM server part, and a Kotlin/JS client part. This includes providing simple JSON API, as well as consuming this API from a Kotlin + React application running in the browser.
+In this hands-on, we will build a connected application consisting of two parts:
 
-We structure our application as a Kotlin multiplatform project. Throughout the hands-on, we will see how this allows us to manage both server and client from within the same Gradle project, and keep an overview of our whole system from within our IDE. We will also explore how multiplatform projects enable us to share code and data models between client and server in our application. This will help us to make sure that our whole system is consistent, and lets us avoid duplicating code unnecessarily.
+- A server, using Kotlin/JVM
+- A web client, using Kotlin/JS
 
-By using popular Kotlin multiplatform libraries such as `kotlinx.serialization`, `kotlinx.coroutines`, and the `ktor` framework for API server and client, we will see how we can keep our application concise, performant, and type-safe – *even when communicating across network boundaries*.
+We will build a simple JSON API, and learn how to use the API from a web app using Kotlin & React.
 
-For this hands-on, you are expected to have an understanding of Kotlin. Some knowledge about basic concepts in React and Kotlin Coroutines may be helpful in understanding some of the sample code, but is not strictly required.
+We write both parts of the project together, as one Kotlin Multiplatform project.
+This will allow us to manage both server and client from within the same Gradle project, and keep an overview of our whole system from within our IDE.
+It's also a great way to learn more about code and data model sharing between client and server for our app.
+This will help us to make sure that our whole system is consistent, and lets us avoid duplicating code unnecessarily.
+
+By using popular Kotlin multiplatform libraries such as [`kotlinx.serialization`](https://github.com/Kotlin/kotlinx.serialization), [`kotlinx.coroutines`](https://github.com/Kotlin/kotlinx.coroutines), and the [Ktor](https://ktor.io/) framework for API server and client, we will build an app that is concise, performant, and type-safe – *even when communicating across network boundaries*.
+
+For this hands-on, you are expected to have an understanding of Kotlin. Some knowledge about basic concepts in React and Kotlin Coroutines may be helpful in understanding some sample code, but is not strictly required.
 
 ### What we will build
 
-When going out to the supermarket, it's always good to know what we want to buy, rather than rely on impulse purchases. That's how you end up with candy and chips, and not enough fruits and vegetables! So, for our demo application, we will build a simple shopping list application that allows us to plan out our groceries.
+When going out to the supermarket, it's always good to know what we want to buy, rather than rely on impulse purchases (That's how you end up with candy and chips, and not enough fruits and vegetables!)
+
+So, for our demo application, we will build a simple shopping list application that allows us to plan out our groceries.
 
-In the interest of concise and easy to understand code, we will keep the user interface of our application quite simple: a list of planned purchases and a field to enter any new shopping plans. By clicking on an element in our shopping list, we automatically remove it.
+To focus on the essentials, we will keep the user interface simple: a list of planned purchases and a field to enter new shopping items. By clicking on an element in the shopping list, it gets removed.
 
-Because not all purchases might be equally important, we also allow our users to specify a priority level. Simply by entering a number of exclamation points `!` to their shopping list entry, the user can assign a priority to the item. We'll also make sure that the list is always ordered, so that we can see the most important entries first.
+We'll also allow the user to specify a priority level for list entries.
+By adding an exclamation point `!` to an item, it gets a higher priority.
+We'll use this information to order the shopping list.
 
 ![](/assets/finished.gif)
 
-To achieve all this functionality, we will first build a small backend that serves a JSON API. Afterwards, we will use the data served by this API to populate our simple web interface. Last but not least, we'll expand the server of the application to include a proper database, to make sure that our data persists even across multiple reloads and restarts of the application.
+There's a lot ahead of us! First, we need to build a small backend that serves a JSON API. Then, we need to build our web interface which consumes that API.
+An a bonus, we'll also expand the server of the application to include a proper database, making data persistent across multiple reloads and restarts of the application.
 
-To make the app available even while we're standing in the supermarket, we'll also cover how to deploy the shopping list to a cloud provider in the last chapter.
+We'll also talk about how to deploy the shopping list to a cloud provider in the last chapter (so that while we're standing in the supermarket, the app will still be available). 
 
-Before we dive in and start coding our application, let's talk for a brief moment about why choosing a Kotlin multiplatform architecture for such a type of project can be beneficial.
+Before we dive in and start coding our application, let's talk about why choosing Kotlin Multiplatform for this project can be beneficial.
 
 ### Benefits of a multiplatform architecture
 
-We will write this whole application in Kotlin: the backend will use Kotlin/JVM, the frontend will use Kotlin/JS. This has a number of benefits: besides syntax, it also allows us to share our libraries and  programming paradigms (such as using coroutines for concurrency), on both frontend and backend.
+When we're done, the whole app will be written in Kotlin: the backend will use Kotlin/JVM, the frontend will use Kotlin/JS. This has a number of benefits: besides syntax, it also allows us to share our libraries and  programming paradigms (such as using coroutines for concurrency), on both frontend and backend.
 
-Using Kotlin throughout the whole stack also makes it possible to write classes and functions that can be used from both the JVM and JS targets of our application. For this application, we will primarily use this functionality to share a typesafe representation of our data between client and server.
+Using Kotlin throughout the whole stack also makes it possible to write classes and functions that can be used from both the JVM and JS targets of our application. In this tutorial, we will primarily use this functionality to share a typesafe representation of our data between client and server.
 
-By delegating the task of serizaliation and deserialization from and to typesafe objects to multiplatform Kotlin libraries such as `kotlinx.serialization`, we can make the communication of data safe and practically trivial.
+By delegating the task of serialization and deserialization from and to typesafe objects to the `kotlinx.serialization` multiplatform library, we can make the communication of data safe and practically trivial.
 
 Motivated enough? Let's dive in!

Full Stack Web App with Kotlin Multiplatform/02_Project_Setup.md

@@ -1,23 +1,23 @@
 # Project setup
 
-If we were to start a fresh idea from zero, the wizard for multiplatform projects which is available in IntelliJ IDEA would be our go-to solution. In order to reduce the amount of time spent adjusting Gradle imports while going through this tutorial, a starter template is available for this specific tutorial that includes configuration and all required dependencies for Kotlin/JS, Kotlin/JVM, as well as common code.
+For your own projects, you would usually start out using the Kotlin wizard included with IntelliJ IDEA. To keep things simple, we've made a starter template available for this specific tutorial. It already includes all the configuration and required dependencies for all parts of the project (which includes JVM, JS, and common code).
 
 [**Please clone the project repository from GitHub, and open it in IntelliJ IDEA.**](https://github.com/kotlin-hands-on/jvm-js-fullstack)
 
-Of course, we still don't want to treat our Gradle configuration as a black box. Throughout the hands-on, we can have a look at parts of our Gradle build file and how it relates to what we are trying to achieve.
+It still makes sense to get an understanding of the configuration and project setup. Throughout the hands-on, we will have a look at parts of the Gradle build file, and how it relates to the current tasks at hand.
 
 **You don't need to make any changes to the Gradle configuration throughout this whole hands-on – so if you want to get right to programming, feel free to skip over parts of this page, or move on directly to the next section.**
 
-**The section below and other sections talking about Gradle structures are only supposed to help your understanding, and prepare you for any projects where you might need to write your own configurations.**
+**The section below and other sections talking about Gradle structures are here to help your understanding, and prepare you for any projects where you might need to write your own configurations.**
 
-We start by having a coarse look at the structure of a Kotlin project that targets multiple platforms.
+Let's start with an overview of the structure for our multiplatform Kotlin project.
 
 ### Multiplatform Gradle Structure
 
-Like all Kotlin projects targeting more than one platform, our project uses the Kotlin `multiplatform` Gradle plugin. It allows us to manage the targets we need for our application (Kotlin/JVM and Kotlin/JS) from within the same Gradle project, and exposes a number of tasks. For a more detailed look, check out the reference on [Building Multiplatform Projects with Gradle](https://kotlinlang.org/docs/reference/building-mpp-with-gradle.html). Besides `multiplatform`, we add two more plugins:
+Like all Kotlin projects targeting more than one platform, our project uses the Kotlin `multiplatform` Gradle plugin. It provides a single point to configure the targets we need for our application (in our case Kotlin/JVM and Kotlin/JS), and exposes a number of lifecycle tasks for them. For a more detailed look, check out the reference on [Building Multiplatform Projects with Gradle](https://kotlinlang.org/docs/mpp-intro.html). Additionally, we add two more plugins:
 
-- The [`application`](https://docs.gradle.org/current/userguide/application_plugin.html) plugin, which takes care of running the JVM (server) part of our application.
-- The [`serialization`](https://github.com/Kotlin/kotlinx.serialization#gradle) plugin, which ensures that multiplatform conversion between Kotlin objects and their text representation (JSON) is available.
+- The [`application`](https://docs.gradle.org/current/userguide/application_plugin.html) plugin, which takes care of running the server part of our application, which lives on the JVM.
+- The [`serialization`](https://github.com/Kotlin/kotlinx.serialization#gradle) plugin, which ensures provides multiplatform conversions between Kotlin objects and their JSON text representation JSON is available.
 
 ```kotlin
 plugins {
@@ -46,7 +46,7 @@ For more detailed information on targets, check out the [respective section](htt
 
 #### Source Sets
 
-Kotlin source sets are a collection of Kotlin sources, along with their resources, dependencies, and language settings, that belong to one or more targets. They are used to set up our platform-specific and common dependency blocks.
+Kotlin source sets are a collection of Kotlin sources, along with their resources, dependencies, and language settings, that belong to one or more targets. You use them to set up our platform-specific and common dependency blocks.
 
 ```kotlin
 sourceSets {
@@ -70,7 +70,7 @@ sourceSets {
 }
 ```
 
-Each source set also corresponds to a folder in the `src` directory. In our project, we see the corresponding three folders `commonMain`, `jsMain`, and `jvmMain`, which contain their own `resources` and `kotlin` folders.
+Each source set also corresponds to a folder in the `src` directory. In our project, we see the three folders `commonMain`, `jsMain`, and `jvmMain`, which contain their own `resources` and `kotlin` folders.
 
 For more detailed information on source sets, check out the [respective section](https://kotlinlang.org/docs/reference/mpp-discover-project.html#source-sets) in the guide. There are a few other snippets that are yet to be explained – but we will discuss them at later chapters in this hands-on, when they become relevant to what we are trying to achieve.