Update architecture documentation

Change-Id: Ief3fdc4d613524fcc75264b5a80c931c37fc2f38
Relates-To: #427

docs/source/architecture.md

@@ -7,36 +7,42 @@ housed in source control and manage the lifecycle of a site.
 
 ## Example Usage
 
-In a nutshell, users of `airshipctl` should be able to do the following:
+In a nutshell, users of `airshipctl` are able to do the following:
 
-1. Create an `airshipctl` Airship Configuration for their site - sort of like a
+1. Create an `airshipctl` configuration file. `airshipctl` can create a default
-   kubeconfig file. Airshipctl can create a pre-configured config file by
+   configuration file (`~/.airship/config`) running the command
-   running `airshipctl config init`.
+   `airshipctl config init`. Users can modify the config file according to
-1. Create a set of declarative documents representing the infrastructure
+   their needs.
-   (baremetal, cloud) and software.
+1. Run `airshipctl document pull` to clone the document repositories defined in the
-1. Run `airshipctl document pull` to clone the document repositories in your
+   `airshipctl` config file. These repositories contain declarative documents which
-   Airship Configuration.
+   are used to bootstrap and manage infrastructure, kubernetes clusters and workloads.
-1. Run `airshipctl image build` to generate a self-contained ISO
-   that can be used to boot the first host in the cluster into an ephemeral
-   Kubernetes node.
 1. When deploying against baremetal infrastructure, run
-   `airshipctl baremetal remotedirect` to remotely provision the first machine
+   `airshipctl image build` to generate a self-contained ISO that can be
-   in the cluster using the generated ISO, providing an ephemeral Kubernetes
+   used to bootstrap an ephemeral Kubernetes node on top of a baremetal host.
+
+   **NOTE:** *Most of the `airshipctl` functionality is implemented as phases. When `airshipctl`
+   performs an action, it likely runs a phase or multiple phases defined in phase documents.
+   `airshipctl phase` command can be used to run a specific phase. For example
+   to build the ISO one can run the command `airshipctl phase run bootstrap`*
+
+1. Once the ISO is generated, run `airshipctl baremetal remotedirect` to remotely
+   provision the ephemeral baremetal node and deploy a Kubernetes
    instance that `airshipctl` can communicate with for subsequent steps. This
    ephemeral host provides a foothold in the target environment so we can follow
    the standard cluster-api bootstrap flow.
 1. Run `airshipctl phase run initinfra-ephemeral` to bootstrap the new ephemeral cluster
-   with enough of the chosen cluster-api provider components to provision the
+   with the necessary infrastructure components to provision the target cluster.
-   target cluster.
+1. Run `airshipctl phase run clusterctl-init-ephemeral` to install cluster-api components
-1. Run `airshipctl clusterctl` to use the ephemeral Kubernetes host to provision
+   to the ephemeral Kubernetes instance.
-   at least one node of the target cluster using the cluster-api bootstrap flow.
+1. Run `airshipctl phase run controlplane-ephemeral` to create cluster-api objects for the first
-1. Run `airshipctl cluster initinfra --clustertype=target` to bootstrap the new
+   target cluster which will be deployed using cluster-api.
-   target cluster with any remaining infrastructure necessary to begin running
+
-   more complex workflows such as Argo.
+Further steps depend on what exactly a user wants to have as a result. Usually, users transform
-1. Run `airshipctl workflow submit sitemanage` to run the out of the box sitemanage
+their first target cluster into a cluster-api management cluster and then use it to deploy workload
-   workflow, which will leverage Argo to handle bootstrapping the remaining
+clusters. To transform a Kubernetes cluster into a cluster-api management cluster, it is
-   infrastructure as well as deploying and/or updating software.
+necessary to deploy infrastructure components and the cluster-api components.
 
 As users evolve their sites declaration, whether adding additional
-infrastructure, or software declarations, they can re-run `airshipctl workflow
+infrastructure, or software declarations, they can create phase definitions to apply those
-submit sitemanage` to introduce those changes to the site.
+changes to the site using builtin phase executors and run those phases using the command
+`airshipctl phase run <phasename>`.