Update README.md

Author: AlexITC

README.md

@@ -3,139 +3,54 @@
 ![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 Wiringbits Web Application Template.
+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.
 
-The template provides a reusable skeleton to build web applications in Scala/Scala.js, it was created by extracting common functionality from web applications built by the [Wiringbits](https://wiringbits.net) team.
 
-While this is still a work in progress, it has enough details to save a couple of weeks of work when starting a new project.
+## Why?
 
-Check the [infra](./infra) docs to deploy your application.
+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).
 
-## Demo
-
-To get an idea on what the template provides, play with the live demos, what you see there is what you will get by cloning the template:
-
-- [Web App](https://template-demo.wiringbits.net)
-- [Admin App](https://template-demo-admin.wiringbits.net) (username = `demo`, password = `wiringbits`)
-- [API Docs](https://template-demo.wiringbits.net/api/docs/index.html)
-## Goal
-
-The goal for this project is to include more functionality that is common for web projects, like:
-
-- Better authentication instead of just using a JSON Web Token.
-- Allow updating user details as well as changing password.
-- Enable accounts after verifying the email address (by sending an email).
-- Password recovery after lossing it.
-- A better admin dashboard.
-
-A long-term goal is to allow admins to update most details in the application by auto-generating the views (like [Django](https://www.djangoproject.com/) does).
-
-## Tech stack
-
-The stack used is:
-
-- Scala 2.13 used for the whole app (hoping to upgrade to Scala 3 when the dependencies are ready).
-- Postgresql is the database library.
-- [Scala.js](https://www.scala-js.org/) powers the frontend side.
-- [React](https://reactjs.org/) as the view library.
-- [Slinky](https://slinky.dev/) being the Scala wrapper for React.
-- [Scalablytyped](https://scalablytyped.org/) generates the Scala facades to interact with JavaScript libraries by converting TypeScript definitions to Scala.js facades.
-- [Webpack](https://webpack.js.org) to bundle the web apps.
-- [Scalajs bundler](https://scalacenter.github.io/scalajs-bundler/) being the Scala wrapper for Webpack.
-- [Material UI v3](https://v3.material-ui.com/) as the Material UI framework on top of React (hoping to upgrade to v4 when Scalablytyped supports it).
-- [Play Framework](https://playframework.com/) as the backend framework, used for the REST API.
-- [sttp](https://github.com/softwaremill/sttp/) as the REST API client.
-- [react-router](https://www.npmjs.com/package/react-router) is the frontend routing library.
-- [play-json](https://github.com/playframework/play-json/) is the JSON library.
-- [yarn](https://yarnpkg.com) as the JavaScript package manager.
-- [ansible](https://ansible.com/) as the tool for deploying everything to a VM.
-- [nginx](https://nginx.org/en/) as the reverse proxy for handling the internet traffic, as well as the authentication mechanism for the admin portal.
-- [GitHub](https://github.com/features/actions) actions integration so that you have a way every commit gets tested.
-
-## Features
-
-By cloning this template you will gain a skeleton with:
-
-- A backend server exposing a REST API with a simple JWT based authentication mechanism.
-- A web application intended to be used by multiple users, allowing them to create an account, and to log into it.
-- An admin web application intended to be used by administrators only, using the http basic authentication capability from nginx.
-- A shared library reused by all the modules, yay!
-- The necessary scripts to deploy the applications by running a single command once you set up the necessary config.
-- Mobile-friendly web apps.
-- A simple landing page with a navigation bar, footer, etc.
-- The necessary components to display progress indicators when executing remote actions, as well as a retry button in case of unexpected failures.
-- Hot-reloading to see the code changes without recompiling the apps manually.
-- Database integration tests powered by [testcontainers](https://www.testcontainers.org/), launching a docker container with a clean database to run the tests, so that you are confident that the database layer is in sync with the actual database schema.
-- REST API integration tests, so that you are confident that your changes aren't breaking the API compatibility unintentionally.
-- A user log displaying the interactions with the app.
-
-## Code format
+Our template provides all the necessary boilerplate to get started fast when building a traditional web application.
 
-The code format is checked by [scalafmt](https://scalameta.org/scalafmt) when the CI complains about the format, running `sbt scalafmtAll` should fix it.
+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.
 
-## Ubuntu Setup
+When creating web apps for our customers, we usually pick this template to save time, you can do same.
 
-1. [SDKMan java/sbt setup](./docs/sdkman-java-sbt.md)
-2. [Postgres setup](./docs/postgres.md)
+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.
 
-## server
 
-This is the server side for the project.
-
-Run it with `sbt server/run`, you are expected to have updated the [application.conf](server/src/main/resources/application.conf) to define the settings to reach your postgres instance.
-
-Notes:
-- The server doesn't really start until you send the first request, like `curl localhost:9000/health`
-- Make sure to follow the [Postgres setup](./docs/postgres.md) because the project depends on Postgres Extensions that are created there.
-
-## web
-
-This is the main web app for the users.
-
-Run `sbt dev-web` to launch the website on `localhost:8080` pointing to the server url at `localhost:9000`, which reloads on code changes.
-
-### Deploy
-
-Run this command to package the app for release, the output is stored at `./web/build` (replace the placeholders):
-
-```bash
-API_URL="https://REPLACE_ME" sbt web/build
-```
-
-## admin
-
-This is the admin web app.
-
-Run `sbt dev-admin` to launch the website on `localhost:8081` pointing to the server url at `localhost:9000`, which reloads on code changes.
+## Demo
 
-## lib
+We have a live demo so that you can get a taste on what our template provides.
 
-This is the shared library powering all the Scala apps.
+- [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/).
+- [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.
 
-### common
+### Short videos
 
-The [common](lib/common) module includes all the logic that can be shared on all the apps.
+Users app 1m demo:
 
-### api
+[![Users app 1m demo](https://img.youtube.com/vi/hURUK4NCGBk/0.jpg)](https://youtu.be/hURUK4NCGBk "Users app 1m demo")
 
-The [api](lib/api) module includes the shared APIs like the backend client.
+Admin app 30s demo:
 
-### ui
+[![Admin app 30s demo](https://img.youtube.com/vi/78rxfdPOGqk/0.jpg)](https://youtu.be/78rxfdPOGqk "Admin app 30s demo")
 
-The [ui](lib/ui) module includes the shared UI like some reusable react components.
+Deployment 4m demo:
 
-## Scala.js hints
+[![Deployment 4m demo](https://img.youtube.com/vi/cN599dMa9EA/0.jpg)](https://youtu.be/cN599dMa9EA "Deployment 4m demo")
 
-- Put public resources on the [js](src/main/js) folder.
-- Use IntelliJ, and configure it to format the code on save with [scalafmt](https://scalameta.org/scalafmt/docs/installation.html#intellij) to keep the code consistent.
-- Make sure to follow the [Slinky](https://slinky.dev/) tutorial, and enable the `Slinky` extension on IntelliJ, otherwise, you may find highlighting errors while sbt compiles fine.
-- Follow the [Material UI V3](https://v3.material-ui.com/) docs to understand the components the app is using (V4 is not supported yet by Slinky).
-- Follow the [Material UI Slinky Demo](https://github.com/ScalablyTyped/SlinkyDemos/tree/master/material-ui/) when necessary.
-- Follow the [Scala.js for JavaScript developers](https://www.scala-js.org/doc/sjs-for-js/) tutorial to get an understanding on how the project works.
 
-It's strongly recommended to use these imports while dealing with material-ui components instead of referencing the components directly, otherwise, IntelliJ gets quite slow, and tends to highlight errors while sbt compiles properly:
+## What's included?
 
-```scala
-import com.alexitc.materialui.facade.materialUiCore.{components => mui}
-import com.alexitc.materialui.facade.materialUiIcons.{components => muiIcons}
-```
+1. User registration and authentication; Including email verification, profile updates, password recovery, and, Captchas (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.
+5. Practical frontend utilities, for example, test your frontend forms easily, consistent UI when performing asynchronous actions (fetching/submitting data), etc.
+6. Typed data inputs, don't bother running simple validations to form data at the backend, accepted requests are already validated.
+7. Reasonable Continuous-Integration workflows, don't waste time reviewing code format or asking whether tests are passing, Github Actions do this for you.
+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.