Expand documentation

README.md

@@ -9,9 +9,6 @@ system with Temporal. You can run this application locally
 the Temporal Service can be local, a remote self-hosted deployment, 
 or Temporal Cloud. 
 
-NOTE: This application is under development and we're working to 
-expand the documentation before we officially announce it. 
-
 ## Quickstart
 We recommend that you begin by reading the [documentation](docs/README.md), 
 which will explain the features of the application and aspects 
@@ -30,23 +27,21 @@ Run the following command in your terminal:
 temporal server start-dev --ui-port 8080 --db-filename temporal-persistence.db
 ```
 
-This command uses the `--db-filename` option so that the development 
-server will persist its data to a file instead of memory, thus making 
-it available during later sessions. The file will be created if it
-does not already exist.
+The Temporal Service manages application state by assigning tasks
+related to each execution and tracking the completion of those tasks.
+The detailed history it maintains for each execution enables the 
+application to recover from a crash by reconstructing its pre-crash 
+state and resuming the execution.
 
-### Start the Worker
+### Start the Workers
 Run the following command in another terminal:
 
 ```command
 go run ./cmd/oms worker
 ```
 
-Although one Worker is sufficient for local development, Temporal 
-recommends running multiple Workers in production since this can 
-improve both the scalability and availability of an application. 
-You can repeat this step to launch as many additional Workers as 
-you like.
+The Workers run the Workflow and Activity functions that handle
+various aspects of order processing.
 
 ### Start the API Servers
 Run the following command in another terminal:
@@ -80,8 +75,8 @@ You will then be able to access the OMS web application at
 <http://localhost:5173/> and the Temporal Web UI at 
 <http://localhost:8080/>. In the OMS web application, select 
 the **User** role, and then submit an order (we recommend 
-choosing order #1 to start). Next, return to the main page of  
-the web application, select the **Courier** role, locate
+choosing order #1 to start). Next, return to the main page
+of the web application, select the **Courier** role, locate
 the shipments corresponding to your order, and then click 
 the **Dispatch** and **Deliver** buttons to complete the 
 process. As you proceed with each of these steps, be sure 

docs/README.md

@@ -3,7 +3,33 @@
 ![OMS logo](images/oms-logo.png)
 
 The documentation for the Order Management System reference application 
-is split up into multiple sections:
+is organized into multiple sections:
+
+## Understanding the OMS
+* [Overview](overview.md): 
+      Provides a brief high-level overview of the OMS
+* [Product Requirements](product-requirements.md):
+      Describes what the OMS does
+* [Technical Description](technical-description.md):
+      Describes the design and implementation of the OMS
+
+## Running the OMS
+* [Run: Basic](run-basic.md): 
+      Provides step-by-step instructions for running the 
+      application locally and using a local Temporal Service.
+<!--
+* [Run: Temporal Cloud](run-temporal-cloud.md): 
+      TODO Provides step-by-step instructions for running the 
+      application locally and using the Temporal Service provided
+      by Temporal Cloud.
+* [Run: Codec Server](run-codec-server.md): 
+      TODO Provides step-by-step instructions for running the 
+      application and Temporal Service locally, with a Data
+      Converter to encrypt confidential information and a 
+      Codec Server that enables you to view decrypted data 
+      in the Temporal Web UI.
+--> 
+
+## Deploying the OMS
+* [Deploying to Kubernetes](deploy-on-k8s.md) 
 
-* [Product Requirements](product-requirements.md) - describes what the OMS does
-* (Other content is forthcoming, including detailed instructions for running and deploying the application, plus commentary on the design)

docs/overview.md

@@ -1,25 +1,95 @@
-# System Overview
-
-```mermaid
-sequenceDiagram
-    participant Customer
-    participant Order
-    participant Inventory
-    participant Billing
-    participant Shipment
-    participant Courier
-
-    Customer->>Order: place order
-    Order->>Inventory: fulfill order
-    Order->>Billing: create invoice
-    Order->>Billing: charge customer
-    Order->>Shipment: create shipment
-    Shipment->>Courier: book shipment
-    Courier->>Shipment: shipment booked
-    Shipment->>Customer: shipment booked
-    Courier->>Shipment: shipment dispatched
-    Shipment->>Customer: shipment dispatched
-    Courier->>Shipment: shipment delivered
-    Shipment->>Customer: shipment delivered
-    Order->>Customer: order complete
-```
+# About the Order Management System 
+
+The Order Management System (OMS) reference application illustrates a
+common use case for Temporal: processing product orders from customers.
+
+## OMS Overview
+
+An OMS is inherently a back-end system, but we provide a basic web
+application that offers a convenient way to interact with it. It is 
+also possible to interact with it using APIs provided by the OMS or 
+through the `temporal` command-line tool.
+
+The following diagram illustrates the high-level interaction that
+takes place when a user submits an order through the web application:
+
+![OMS high-level overview diagram](images/high-level-overview-diagram-900w.png "OMS high-level overview diagram")
+
+Notice that each item is only connected to the items adjacent to it.
+The user does not interact with either the OMS or the Temporal
+Service. Likewise, the web application does not use any Temporal
+libraries or tools; it only calls APIs provided by the OMS. This
+design increases both security and flexibility.
+
+## Order Processing Overview
+The input to the OMS is an order, which has a unique identifier, is 
+associated with a customer, and specifies a list of SKUs (products) 
+along with the quantities.
+
+Upon receiving an order, the OMS launches a Workflow to orchestrate 
+all of the steps required to process it. This includes claiming the 
+items from inventory, generating invoices and charging the customer 
+for each shipment, and booking couriers who pick them up from the
+warehouse and deliver them to the customers. This Workflow ends when
+all shipments have been delivered or when canceled by the business or 
+customer.
+
+
+## Benefits of Using the Temporal Platform
+
+### Reliability
+The application gains reliability from the support provided by the 
+Temporal Service, which automatically manages application state and 
+allows the system to withstand failure conditions. Once the OMS 
+receives an order, that order will be processed, no matter what.
+
+If the application makes a call to a microservice that’s experiencing
+an outage, for example, that call will be retried according to a
+configurable policy. When the microservice comes back online, the call
+will succeed on the next retry attempt and further processing will
+follow.
+
+If the application terminates unexpectedly while processing is
+underway, the application can automatically reconstruct the
+pre-termination state and resume where it left off, as if the problem
+never happened at all. You can even resume that execution on another
+machine, which allows the application to overcome hardware failures.
+
+### Scalability
+You can increase throughput—enabling the system to handle more orders 
+concurrently—by running additional instances of the application. 
+Although Temporal applications can run on bare metal or virtual 
+machines, many users deploy them in containers managed through 
+Kubernetes, and use metrics provided by the Temporal Service to 
+scale them up or down in response to changing demand.
+
+### Availability
+Each additional instance contributes to the application's
+availability. If one of those instances crashes, another running
+instance will automatically take over processing from where the
+previous one left off.
+
+Any instance can automatically take over processing for one that fails
+(for example, due to a hardware crash).
+
+### Developer Productivity
+Although often initially overlooked, developers who begin using 
+Temporal soon realize that they're much more productive. They 
+spend less time writing code to handle failure scenarios, which 
+frees them up to focus on the business logic and ship features 
+faster.
+
+The productivity boost is also evident in production. The Temporal  
+Service maintains a complete Event History for every execution. Its 
+corresponding Web UI provides a convenient way to view the timeline 
+and details of these Events, both for orders in progress as well as 
+those that have already completed. The result is immediate insight 
+into the status of every order processed.
+
+![Screenshot of an Order Workflow in Temporal Web UI](images/web-ui-example-1020w.png "Screenshot of an Order Workflow in Temporal Web UI")
+
+In fact, a developer can download the Event History for any execution 
+and replay it in a debugger, making it possible to [reproduce and fix
+elusive bugs](https://www.youtube.com/watch?v=fN5bIL7wc5M) in your
+application code. And once it is fixed, you can use that history file 
+in an automated test and be confident that there are no regressions.

docs/product-requirements.md

@@ -4,7 +4,7 @@
 
 
 ## Vision
-The Order Management System (OMS) is a mission-critical system for 
+An Order Management System (OMS) is a mission-critical system for 
 processing product orders.
 
 Reliability is essential, since failure to process individual orders
@@ -94,9 +94,14 @@ click the "Deliver" button. These interactions update the current status
 of each shipment and are immediately visible to customers and support 
 staff.
 
+
 ### Manager Interaction
 As previously described, the store manager has the ability to combat 
 fraud by setting a global limit on the total charges (expressed in 
 cents) that each customer is allowed. This is set to 0 by default, 
 meaning that there is no limit. The manager can increase, decrease, 
 or reset this limit at any time.
+
+Additionally, the manager can enable a maintenance mode in this
+fraud detection system. When this is enabled, no new charges are 
+allowed, regardless of amount.

docs/run-basic.md

@@ -0,0 +1,93 @@
+# Running the OMS Locally
+
+Follow these instructions to run the OMS locally, using the 
+Temporal Service provided that the `temporal` command. This 
+is an expanded version of the instructions found in the 
+_Quickstart_ section of the top-level README file.
+
+
+### Start the Temporal Service
+
+Run the following command in your terminal to start the Temporal 
+Service:
+
+```command
+temporal server start-dev \
+    --ui-port 8080 \
+    --db-filename temporal-persistence.db
+```
+
+The `temporal` CLI provides a convenient way of running a 
+Temporal Service locally for development purposes. By default,
+it provides a Web UI on port 8233 and persists data to an 
+ephemeral in-memory database. The options in this command 
+change the Web UI port to 8080 and instructs the Temporal 
+Service to persist its data to a file so that it will be 
+available in subsequent sessions. This file will be created 
+if it does not exist.
+
+
+### Start the Worker
+
+Run the following command in another terminal to start the Workers:
+
+```command
+go run ./cmd/oms worker
+```
+
+The Workers run the Workflow and Activity code used to implement the
+OMS. Although one Worker is sufficient for local development, Temporal
+recommends running multiple Workers in production since this can improve
+both the scalability and availability of an application. You can repeat
+this step to launch as many additional Workers as you like.
+
+
+### Start the API Servers
+
+Run the following command in another terminal to start the API Servers:
+
+```command
+go run ./cmd/oms api
+```
+
+The API Servers provide REST APIs that the web application uses to 
+interact with the OMS. 
+
+
+### Run the Web Application
+You will need to clone the code for the web application, which is 
+maintained in the [reference-app-orders-web](https://github.com/temporalio/reference-app-orders-web) 
+repository:
+
+```command
+cd ..
+git clone https://github.com/temporalio/reference-app-orders-web.git
+```
+
+You will then need to run the following commands to start it:
+
+```command
+cd reference-app-orders-web
+pnpm install
+pnpm dev
+```
+
+<!--
+	TODO: expand this section to cover more advanced cases
+	      and then move it to a separate document (with a 
+		  demo video) that can be referenced by the other
+		  instructions for running it.
+-->
+
+You will then be able to access the OMS web application at 
+<http://localhost:5173/> and the Temporal Web UI at 
+<http://localhost:8080/>. In the OMS web application, select 
+the **User** role, and then submit an order (we recommend 
+choosing order #1 to start). Next, return to the main page of  
+the web application, select the **Courier** role, locate
+the shipments corresponding to your order, and then click 
+the **Dispatch** and **Deliver** buttons to complete the 
+process. As you proceed with each of these steps, be sure 
+to refresh the Temporal Web UI so that you can see the 
+Workflows created and updated as a result. 
+