update docs

README.md

@@ -16,13 +16,11 @@ Test Automation, CI/CD, etc, with built-in modules including:
 - Modules and templates based on [Copier](https://copier.readthedocs.io/en/stable/).
 - CI/CD deployment templates.
 
-## Build a solution by adding modules
+### Build a solution by adding modules
 
-Solutions Builder is designed with modules and templates. When creating a new solution
-folder, it starts from a base template with a terraform foundation and project skeleton.
-Then, you can start adding modules into this solution folder.
+Solutions Builder is designed with modules and templates. It starts from a base project skeleton, then start adding modules into this solution folder.
 
-For example, these are examples of creating a new solution:
+For example, here are the steps when creating a new solution:
 
 - Start a new solution with a base (skeleton) code from a "root template"
 - Add a Cloud Run microservice with APIs
@@ -31,36 +29,41 @@ For example, these are examples of creating a new solution:
 
 ![alt text](docs/assets/adding_modules.png)
 
-Check out the [Quick Start](#quick-start---create-a-new-solution) section to create a sample solution.
+See [Quick Start](#quick-start---create-a-new-solution) section to create a sample solution.
+
+### Concepts and Design Details
+
+- See [Overview](docs/OVERVIEW.md) for overall concepts and design details.
 
 ## Prerequisite
 
-| Tool       | Required Version | Installation                                         |
-| ---------- | ---------------- | ---------------------------------------------------- |
-| Python     | >= 3.11       |                                                      |
-| gcloud CLI | Latest           | https://cloud.google.com/sdk/docs/install            |
-| Terraform  | >= v1.3.7     | https://developer.hashicorp.com/terraform/downloads  |
-| Skaffold   | >= v2.4.0     | https://skaffold.dev/docs/install/#standalone-binary |
+Required dependencies:
 
-[Optional] For deploying to a GKE cluster, please install the following:
+- Python (3.10 or later)
+- [gcloud CLI](https://cloud.google.com/sdk/docs/install) (Latest)
+- [Terraform](https://www.terraform.io/) (v1.4.0 or later)
+- [Skaffold](https://skaffold.dev/docs/install/#standalone-binary) (v2.4.0 or later)
 
-| Tool      | Required Version | Installation                                               |
-| --------- | ---------------- | ---------------------------------------------------------- |
-| Kustomize | >= v5.0.0     | https://kubectl.docs.kubernetes.io/installation/kustomize/ |
+Optional dependencies for GKE cluster deployment:
 
-Install all packages:
+- [Kustomize](https://kubectl.docs.kubernetes.io/installation/kustomize) (v5.0.1 or later)
 
-Mac:
+Install dependencies with package managers:
 
-```
-brew install gcloud terraform skaffold
-```
+- Mac:
 
-Windows:
+  ```
+  brew install gcloud terraform skaffold
+  ```
 
-```
-choco install gcloud terraform skaffold
-```
+- Windows:
+
+  ```
+  choco install gcloud terraform skaffold
+  ```
+
+- Others
+  - Google Cloud Shell - See [docs/guides/cloudshell.md](docs/guides/cloudshell.md)
 
 ## Install Solutions Builder CLI
 
@@ -131,7 +134,11 @@ Copying from template
 Complete. New solution folder created at ./my-solution-folder.
 ```
 
-Add a Sample Cloud Run microservice using `blank_service` module template:
+- At this point, you'll see a solution folder created at `./my-solution-folder`, and a `sb.yaml`
+  file with all configuration about this solution folder.
+- See [overview.md](docs/OVERVIEW.md) for more details about `sb.yaml`.
+
+Next, add a Sample Cloud Run microservice using `blank_service` module template:
 
 ```
 cd my-solution-folder

docs/CLI_USAGE.md

@@ -1,31 +1,5 @@
 # Solutions Builder CLI Usage
 
-## Concept
-
-### Copier-based templates
-
-- All templates and modules are created using [Copier](https://copier.readthedocs.io/en/stable/).
-- Each template folder (e.g. in /modules) has a `copier.yaml` to define questions and variables.
-
-### sb.yaml
-
-- Once creating a solution folder, it will create a `sb.yaml` file in the solution folder.
-- When adding a new component/module, it will add the configuration for the component to the `sb.yaml` file.
-
-### Components / Modules
-
-- A component (or module) can be a Terraform module, a microservice (Python) module, or a frontend module.
-- A template must have a `copier.yaml` to define variables
-  and other configurations. You can still proceed if there's no
-  `copier.yaml` in the template folder, but it will just copy
-  entire folder without any modification.
-
-There are three ways of adding a component:
-
-- Add a component with built-in module template
-- Add a component with a template in local folder
-- Add a component with a template in remote Git repo
-
 ## Installation
 
 With `pip`:
@@ -109,10 +83,11 @@ sb new my-solution-folder -t /path/to/my-template-folder
 To create a new solution folder with a template a remote Git repo, add `-t <path/to/remote.git/folder>` like below:
 
 ```
-sb new my-solution-folder -t [email protected]:GoogleCloudPlatform/solutions-builder.git/modules/blank_service
+sb new my-solution-folder -t [email protected]:GoogleCloudPlatform/solutions-builder.git/modules/root_template
 ```
 
 - This will download the Git repo automatically, and use the "subfolder" as the template path.
+- In this case, the repo path is `[email protected]:GoogleCloudPlatform/solutions-builder.git`, with the subfolder `modules/root_template`.
 
 ## Add a component
 
@@ -202,6 +177,8 @@ To create a component using a template from a remote Git repo:
 sb add component my_service -t [email protected]:GoogleCloudPlatform/solutions-builder.git/modules/blank_service
 ```
 
+- The git repo path is `[email protected]:GoogleCloudPlatform/solutions-builder.git` with the subfolder `modules/blank_service`.
+
 ## Terraform modules
 
 If you create a solution folder using `sb new <my-solution-folder>`, it will create the Terraform base module for you.
@@ -234,17 +211,40 @@ sb terraform apply --all
 - Optionally, add `--yes` to the end of the command to skip the confirmation prompt. E.g.:
 
   ```
+  # This will init and apply all Terraform stages.
   sb terraform apply --all --yes
   ```
 
-- This will init and apply all Terraform stages.
+What's behind the `sb terraform apply` command?
+
+- `sb terraform` runs `terraform` command behind the scene. The `sb terraform apply --all`
+  runs the following steps:
+  ```
+  cd $SOLUTION_FOLDER/terraform/stages/1-bootstrap
+  terraform init
+  terraform apply -auto-approve
+  cd $SOLUTION_FOLDER/terraform/stages/2-foundation
+  terraform init
+  terraform apply -auto-approve
+  cd $SOLUTION_FOLDER/terraform/stages/3-application
+  terraform init
+  terraform apply -auto-approve
+  ```
 
 ### Apply a specific Terraform stage
 
 ```
 sb terraform apploy 3-application
 ```
 
+- Alternatively, this command is equivalent to the following steps:
+
+  ```
+  cd $SOLUTION_FOLDER/terraform/stages/3-application
+  terraform init
+  terraform apply -auto-approve
+  ```
+
 ### Destroy a specific Terraform stage
 
 ```

docs/DEVELOPMENT.md

@@ -9,7 +9,7 @@ git clone https://github.com/GoogleCloudPlatform/solutions-builder
 cd solutions-builder
 ```
 
-To development locally with editable files:
+### To development locally
 
 ```
 poetry lock && poetry install
@@ -35,22 +35,34 @@ poetry build
 
 - If encountering any errors, run `poetry build -vvv` to troubleshoot.
 
-Test package upload to Test-PyPI:
+### Test package upload to Test-PyPI
+
+Publish to Test-PyPI:
 
 ```
-# Publish
 poetry config repositories.test-pypi https://test.pypi.org/legacy/
 poetry config pypi-token.test-pypi $TEST_PYPI_TOKEN
-poetry publish -r test-pypi
+poetry build && poetry publish -r test-pypi
+
+```
 
-# Install and test
+Install and test from Test-PyPI
+
+```
 pip install -U --index-url https://test.pypi.org/simple/ solutions-builder
 ```
 
-Publish to official PyPI:
+### Publish to official PyPI
+
+Publish to PyPI
 
 ```
-# Publish to Test-PyPI
 poetry config pypi-token.pypi $PYPI_TOKEN
-poetry publish
+poetry build && poetry publish
+```
+
+Test with the published package:
+
+```
+pip install -U solutions-builder
 ```