Update docs/DeepDives.md, README.md files

README.md

@@ -15,7 +15,6 @@ and reliability.
 
 Sound good so far? Cool! Let's start with basic, interactive usage of the standalone application.
 
-
 The implementation and extension API might be familiar to Scala service developers. To a large
 degree, glngn server is a friendly, constrained, pre-configured typed akka plus ZIO server.  To start
 with the extension API and running a customized server see
@@ -26,11 +25,11 @@ with the extension API and running a customized server see
 prerequisites:
 
 - java runtime version 8 or above
-- agreement to the [Developer License](https://gitlab.com/glngn/glngn-server-examples/blob/master/docs/Developer%20License%20v1.rtf) This license is also included in the jar archive.
+- agreement to the [Developer License](https://gitlab.com/glngn/glngn-server-examples/blob/master/docs/Developer%20License%20v1.rtf?inline=false) This license is also included in the jar archive.
 
 ## Download
 
-Prior to downloading, read and agree to the Application Developer License aggreement (link to license).
+Prior to downloading, read and agree to the [Developer License aggreement](https://gitlab.com/glngn/glngn-server-examples/raw/master/docs/Developer%20License%20v1.rtf?inline=false).
 
 - download [the latest release](https://glngn-server-releases.s3.amazonaws.com/assemblies/glngn/glngn-server-assembly_2.12/0.3.90/jars/glngn-server-assembly_2.12-assembly.jar)
 
@@ -71,19 +70,24 @@ Use of this software is agreement with the included Application Developer Licens
 
 ## Running
 
+Note: For consistency within the docs, the port 10000 is requested using `--port 10000`. If this option is
+not provided a free port will automatically be selected.
+
 Let's run the server configured to store data at `./starter.state`. In a terminal session:
 
 ```bash
 $ java -jar ./glngn-server-assembly.jar --port 10000 run --state-dir ./starter.state
-INFO  use of this software is agreement with the included Application Developer License.
+INFO  use of this software is agreement with the included Developer License.
 ...
 [lots of output]
 ...
 INFO  glngn.server.app.ServerApp$  - application is listening at http://localhost:10000
 ```
 
-For consistency with the docs, the port 10000 is requested using `--port 10000`. If this option is
-not provided a free port will automatically be selected.
+At this point the standalone server is initialized and ready.
+
+See [docs/Deep Dives](https://gitlab.com/glngn/glngn-server-examples/blob/master/docs/DeepDives.md) 
+for more information on what exactly that means.
 
 Hit control-C, or TERM the process (there is only one), to shut down the server. This will take a bit
 for a nice, coordinated shutdown. Which is preferred. That said, the server is configured to attempt
@@ -96,7 +100,7 @@ Even in this default configuration the server provides a few useful routes:
 ### Health Check
 
 ```bash
-$ curl http://localhost:10000/healthz
+$ curl http://localhost:10000/healthz.txt
 OK
 ```
 

docs/DeepDives.md

 # Deep Dives
 
+## An Initialized Server
+
+The properties of an instantiated server:
+
+- A typed akka cluster is available with, by default, 3 members
+- The `healthz` endpoint returns 200 OK
+- The `healthz` endpoint on the operations (ops) port returns 200 OK
+- Akka Management is available on the operations (ops) port
+- All services defined in the prelude are initialized and available
+- No critical errors occurred instantiating all dynamically instantiated services
+- The `openapi.json` route is available and contains endpoint documentation for 
+  all services w/o endpoint definition errors
+
+## Standalone Server Initialization
+
+A standalone server is a single process server hosting multiple cluster nodes.
+While each node is hosted in the same JVM instance there is no assurance 
+of separate class loaders. There is also no assurance of a single akka 
+system instance. With that in mind, on startup:
+
+1. a minimal akka system is initialized for management
+2. the configuration for the cluster nodes is determined. This includes logging, 
+   akka system, and storage.
+3. the requested initial node count of nodes are started
+4. the application waits for configuration from each node of initialization
+5. Either all nodes initialize within the required time or the application
+   exits with an error
+
 ## On the use of an assembly
 
 The default build uses an assembly, non-modular, glngn server library. This