-rearrange README.md instructions so there's clear delimitation between AWS and LocalStack instructions.

Author: tinyg210

README.md

@@ -32,7 +32,7 @@ Of course this comes with other advantages, but the first focus point is making
 
 #### What it does
 
-*shipment-list-demo* is a Spring Boot application dealing with CRUD operations an employee can
+*shipment-list-demo* is a Spring Boot application dealing with CRUD operations a person can
 execute
 on a bunch of shipments that they're allowed to view - think of it like the Post app.
 The demo consists of a backend and a frontend implementation, using React to display the
@@ -49,20 +49,64 @@ The AWS services involved are:
 #### How to use it
 
 We’ll be walking through a few scenarios using the application, and we expect it to maintain the
-behavior in both production and development environments. This behaviour can be "scientifically"
-backed up
-by adding integration tests.
+behavior in both production (AWS) and development (LocalStack) environments.
 
 We’ll take advantage of one of the core features of the Spring framework that allows us to bind our
 beans to different profiles, such as dev, test, and prod. Of course, these beans need to know how to
 behave in each environment, so they’ll get that information from their designated configuration
 files, `application-prod.yml`, and  `application-dev.yml`.
 
+#### Terraform
+
+The Terraform configuration file will create the needed S3 bucket, the DynamoDB `shipment` table and populate it with some
+sample data, the Lambda function that will help with the picture processing (make sure you create the jar),
+the SQS and SNS which will bring back the notification when the processing is finished.
+
+
 ## Instructions
 
+### Only run once
+
+The following instructions only need to run once, weather you choose to run both cases, on AWS and
+LocalStack, or just jump straight to LocalStack.
+
+### Building the validator module
+
+Step into the `shipment-picture-lambda-validator` module and run `mvn clean package shade:shade`.
+This will create an uber-jar by packaging all its dependencies. We'll need this one in the next
+steps. We can keep the same jar for both running on AWS and LocalStack.
+
+
+### Running the GUI
+
+`cd` into `src/main/shipment-list-frontend` and run `npm install` and `npm start`.
+This will spin up the React app that can be accessed on `localhost:3000`.
+You'll only see the title, as the backend is not running yet to provide the list of shipments.
+
+For running it on Windows, there are some
+[extra requirements](https://learn.microsoft.com/en-us/windows/dev-environment/javascript/react-on-windows)
+,
+but no worries, it should be straightforward.
+
+#### How to use the GUI
+
+After starting the backend, refreshing the React app will fetch a list of shipments.
+The weight of a shipment is already given, but not the size, that's why we need pictures to
+understand it better, using the "banana for scale" measuring unit. How else would we know??
+
+Current available actions using the GUI:
+
+- upload a new image
+- delete shipment from the list
+- create and update shipment are available only via Postman (or any other API platform)
+
+Files that are not pictures will be deleted
+and the shipment picture will be replaced with a generic icon, because we don't want any trouble.
+
+
 ## Running on AWS
 
-Now, we don’t have a real production environment because that’s not the point here, but most likely,
+Now, we don’t have a real production environment because that’s not the point here, but most likely
 an application like this runs on a container orchestration platform, and all the necessary configs
 are still provided. Since we’re only simulating a production instance, all the configurations are
 kept in the `application-prod.yml` file.
@@ -80,6 +124,7 @@ needs to be created with the following policies:
 - AWSLambdaExecute
 - AmazonS3ObjectLambdaExecutionRolePolicy
 
+For simplicity, we chose to use full access to all the services, so we don't have to add new permissions later on.
 We will be using the user's credentials and export them as temporary environment variables with the
 `export` (`set` on Windows) command:
 
@@ -88,12 +133,6 @@ $ export AWS_ACCESS_KEY_ID=[your_aws_access_key_id]
 $ export AWS_SECRET_ACCESS_KEY=[your_aws_secret_access_key_id]
 ```
 
-### Building the validator module
-
-Step into the `shipment-picture-lambda-validator` module and run `mvn clean package shade:shade`.
-This will create an uber-jar by packaging all its dependencies. We'll need this one in the next
-step.
-
 ### Creating resources - running Terraform
 
 Make sure you have Terraform [installed](https://developer.hashicorp.com/terraform/downloads)
@@ -110,19 +149,9 @@ Once these 2 commands run successfully and no errors occur, it's time to run:
 ```
 $ terraform apply
 ```
+If everything finishes successfully, the AWS services should be up and running.
 
-This should create the needed S3 bucket, the DynamoDB `shipment` table and populate it with some
-sample data, the Lambda function that will help with picture validation, the SQS and SNS.
-
-### Running the GUI
-
-Now `cd` into `src/main/shipment-list-frontend` and run `npm install` and `npm start`.
-This will spin up the React app that can be accessed on `localhost:3000`.
-
-For running it on Windows, there are some
-[extra requirements](https://learn.microsoft.com/en-us/windows/dev-environment/javascript/react-on-windows)
-,
-but no worries, it should be straightforward.
+### Starting the backend
 
 Go back to the root folder and run the backend simply by using
 
@@ -137,32 +166,23 @@ Notice the `prod` profile is being set via command line arguments.
 At `localhost:3000` you should now be able to see a list of shipments with standard icons,
 that means that only the database is populated, the pictures still need to be added from the
 `sample-pictures` folder.
+You can now interact with the application using the React app. All services used in the backend are
+running on the real AWS cloud.
 
-The weight of a shipment is already given, but not the size, that's why we need pictures to
-understand it better,
-using the "banana for scale" measuring unit. How else would we know??
 
-Current available actions using the GUI:
-
-- upload a new image
-- delete shipment from the list
-- create and update shipment are available only via Postman (or any other API platform)
+Before moving on, make sure you clean up your AWS resources by running (also in setup/terraform):
 
-Files that are not pictures will be deleted
-and the shipment picture will be replaced with a generic icon, because we don't want any trouble.
+```
+$ terraform destroy
+```
 
 ## Running on LocalStack
 
 
 To switch to using LocalStack instead of AWS services just run `docker compose up` in the root
-folder
-to spin up a Localstack container.
+folder to spin up a Localstack container.
 
-Before we proceed, make sure you clean up your AWS resources by running
-
-```
-$ terraform destroy
-```
+### Creating resources on LocalStack
 
 To generate the exact same resources on LocalStack, we need `tflocal`, a thin wrapper script around
 the terraform command line client. `tflocal` takes care of automatically configuring the local
@@ -185,18 +205,20 @@ Usage: terraform [global options] <subcommand> [args]
 ...
 ```
 
-From here on, it's smooth sailing, the same as before. In the `setup/terraform` folder, run the `cleanup` script
+From here on, it's the same as using AWS. In the `setup/terraform` folder, run the `cleanup` script
 to get rid of any files that keep track of the resources' state. Then:
 
 ```
 $ tflocal init
-$ tflocal plan -var 'env=dev
+$ tflocal plan -var 'env=dev'
 $ tflocal apply
 ```
 
 What we're doing here is just passing an environmental variable to let the Lambda
 know this is the `dev` environment.
 
+### Running the backend
+
 After that, the Spring Boot application needs to start using the dev profile (make sure you're in
 the
 root folder):