Update docs

Author: AlexITC

.sdkmanrc

@@ -1 +1 @@
-java=11.0.11.hs-adpt
+java=11.0.16-tem

README.md

@@ -3,18 +3,18 @@
 ![wiringbits](https://github.com/wiringbits/scala-webapp-template/workflows/Build%20the%20server%20app/badge.svg)
 [![Scala.js](https://www.scala-js.org/assets/badges/scalajs-1.6.0.svg)](https://www.scala-js.org)
 
-This is the skeleton used by Wiringbits when creating new web applications fully in Scala/Scala.js, so far, we have created ~10 projects from this template, back-porting useful details to improve our template.
+This is the skeleton used by Wiringbits when creating new web applications in Scala/Scala.js, so far, we have created ~10 projects from this template, back-porting useful details to improve it.
+
+If you require building a Web Application in Scala while you do not have the time to do many technical choices, this template could be a reasonable choice.
 
 
 ## Why?
 
-Scala has a common misconception, many people believe that it is hard to get productive with, at Wiringbits, we have proven the contrary with this template. Engineers with no previous Scala experience tend to start contributing simple bug fixes at their first week (including undergrad interns).
+Scala has a common misconception, many people believe that it is hard to get productive with it, at Wiringbits, we have proven the contrary with this template. Engineers with no previous Scala experience tend to start contributing simple bug fixes at their first week (including undergrad interns).
 
 Our template provides all the necessary boilerplate to get started fast when building a traditional web application.
 
-Don't waste your time evaluating every library required to build your web app, pick this template and go from there as a base and move from there.
-
-When creating web apps for our customers, we usually pick this template to save time, you can do same.
+Don't waste your time evaluating every library required to build your web app, pick this template and go from there.
 
 Using Scala.js not only save us considerable time, it also allows us to avoid many common issues, for example, all frontend/backend validations are in sync just because the code is the same.
 
@@ -24,7 +24,7 @@ Using Scala.js not only save us considerable time, it also allows us to avoid ma
 We have a live demo so that you can get a taste on what our template provides.
 
 - [Web App](https://template-demo.wiringbits.net) showcases the web application intended for the general user, explore it and create an account to get an idea on what your users will experience.
-- [Admin App](https://template-demo-admin.wiringbits.net) (username = `demo`, password = `wiringbits`) showcases the web application intended for administrators, this exposes a way to manage the application's data in a nice UI, mostly autogenerated by [react-admin/](https://marmelab.com/react-admin/).
+- [Admin App](https://template-demo-admin.wiringbits.net) (username = `demo`, password = `wiringbits`) showcases the web application intended for administrators, this exposes a way to manage the application's data in a nice UI, mostly autogenerated by [react-admin](https://marmelab.com/react-admin/).
 - [API Docs](https://template-demo.wiringbits.net/api/docs/index.html) showcases the [Swagger UI](https://swagger.io/tools/swagger-ui/) which can help to explore the API directly.
 
 ### Short videos
@@ -37,14 +37,14 @@ Admin app 30s demo:
 
 [![Admin app 30s demo](https://img.youtube.com/vi/78rxfdPOGqk/0.jpg)](https://youtu.be/78rxfdPOGqk "Admin app 30s demo")
 
-Deployment 4m demo:
+Deployment 2m demo:
 
-[![Deployment 4m demo](https://img.youtube.com/vi/cN599dMa9EA/0.jpg)](https://youtu.be/cN599dMa9EA "Deployment 4m demo")
+[![Deployment 2m demo](https://img.youtube.com/vi/cN599dMa9EA/0.jpg)](https://youtu.be/cN599dMa9EA "Deployment 2m demo")
 
 
 ## What's included?
 
-1. User registration and authentication; Including email verification, profile updates, password recovery, and, Captchas (for spam prevention).
+1. User registration and authentication; Including email verification, profile updates, password recovery, and, captcha for spam prevention.
 2. Integration with the React ecosystem, most libraries/components will work right away, while we use [Material UI](https://v3.mui.com/), you can switch to your preferred component library.
 3. PostgreSQL as the data store layer, which is a reasonable choice for most web applications.
 4. Practical components for testing your server-side code, writing tests for the Data/Api layer is real simple, no excuses accepted.
@@ -54,3 +54,7 @@ Deployment 4m demo:
 8. Admin usually have super-powers, which is why you can export most of your Postgres database to an autogenerated UI (https://marmelab.com/react-admin/), just define which tables/columns must be exported.
 9. A simple to follow architecture, including short-guides for doing common tasks.
 10. Deployment scripts to cloud instances, we believe in simplicity and most projects are fine with simple managed servers instead of containers/K8s/etc.
+
+## Get started
+
+Checkout the [docs](./docs/README.md)

docs/README.md

@@ -0,0 +1,4 @@
+# Wiringbits Scala WebApp template - Docs
+
+- [Setup development environment](./setup-dev-environment.md)
+- [Design desicions](./design-decisions.md)

docs/design-docs.md renamed to docs/design-decisions.md

@@ -1,5 +1,24 @@
-# Design docs
-This document explains why we took certain decisions on how the project is built/structured.
+# Design decisions
+This document explains why we took certain design decisions on how the project is built/structured.
+
+## 2022/Aug - Avoid default parameter in most cases
+We commonly deal with models that are similar but belong to a different domain, [chimney](https://scalalandio.github.io/chimney) help us to transform those models from one domain to another, while this tool is handy, it does not play well with default values in arguments.
+
+Take this snippet as an example:
+
+```scala
+case class CreateUserApiRequest(name: String, age: Option[Int])
+
+case class CreateUserData(name: String, yearsOld: Option[Int] = None)
+
+def transform(request: CreateUserApiRequest): CreateUserData = request.into[CreateUserData].transform
+```
+
+While the `transform` function would succeed, the `age` value will never become the `yearsOld` value, if there wasn't a default value, we'd get a compile error which would give us a chance to fix the problem (`request.into[CreateUserData].withFieldRenamed(_.age, _.yearsOld).transform`).
+
+Still, there can be exceptions:
+- The http API layer usually gets default values when adding a new parameter to an API method, this way, we keep backwards compatibility to support old API clients.
+
 
 ## 2022/Apr - Naming conventions for api/data models