Update docs

- Add link in credentials page back, now that we are properly publishing
  the generated CLI docs
- Update the Home page with just a little more explanation and direction
- Update the architecture page and diagram with more detail.

docs/diagram-source/architecture.drawio

@@ -1 +1 @@
-<mxfile host="app.diagrams.net" modified="2022-05-27T22:40:53.380Z" agent="5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.64 Safari/537.36" etag="oCWACmH3ujqzKgspYNrN" version="18.1.3" type="device"><diagram id="w-ScfHoOZrjaktbm7lLD" name="Page-1">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</diagram></mxfile>
+<mxfile host="app.diagrams.net" modified="2022-06-03T20:26:11.849Z" agent="5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.61 Safari/537.36" etag="MTiY-Vwe0tSqm6-ggtFQ" version="18.2.0" type="device"><diagram id="w-ScfHoOZrjaktbm7lLD" name="Page-1">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</diagram></mxfile>

docs/docs/10-home.md

@@ -3,7 +3,12 @@ title: Home
 slug: /
 ---
 
-> <div style={{"font-family":"Apple Chancery", "font-size": 32}}>Great oaks from little acorns grow.</div>
+> <div style={{"font-family":"Apple Chancery", "font-size": 32}}>Mighty oaks from little acorns grow.</div>
 > <br/>
 > 
 > <div style={{"font-family":"Apple Chancery", "font-size": 20}}>~ Old English Proverb, probably a squirrel</div>
+
+
+:::caution
+
+This site is very much a work in progress. The current structure will change drastically over time. For now, the most useful sections are the [Quick Start](20-quickstart.md) and the [CLI Reference](100-Reference/01-command-line/acorn.md).

docs/docs/50-Concepts/credentials.md

@@ -24,4 +24,4 @@ Acorn image and referenced Docker images.
 
 ## CLI
 
-Credentials are managed with the `acorn credential` command.
+Credentials are managed with the [acorn credential](../100-Reference/01-command-line/acorn_credential.md) command.

docs/docs/60-Architecture/01-ten-thousand-foot-view.md

@@ -6,4 +6,28 @@ The following is a high-level diagram of Acorn's architecture.
 
 ![Architecture](/diagrams/architecture.drawio.svg)
 
-**TODO:** Document further
+These components are described in more detail below.
+
+### CLI
+The acorn cli resides on the end user's machine and executes commands against an instance of acorn running inside a Kubernetes cluster.
+
+### API Server
+The acorn API server is a Kubernetes-style API that is made accessible through the Kubernetes [API aggregation layer](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/).
+
+By design, the Acorn CLI only interacts with the `api.acorn.io` API group in Kubernetes. This means that an acorn user only needs RBAC permissions to the API group. The diagram shows the cli talking to the Kubernetes api-server because it is the entrypoint. It handles authentication and routing, but otherwise proxies the request to the acorn API server.
+
+Upon receiving requests from the CLI, the API server will take various actions. Here are a few examples of such actions:
+- To launch an app, the API server will create an instance of AppInstance.internal.acorn.io CRD.
+- To build an image, where the cli is expecting to have a long-lived interactive connection to the image building service (buildkit), the API server just acts as a proxy.
+- To display details about images, it will make requests to internal and external registries.
+
+### Controller
+The acorn-controller is responsible for translating acorn "apps" into concrete Kubernetes resources such as deployments, services, and persistentVolumes. It handles the entire lifecycle of such applications and ensures the Kubernetes resources remain in sync with the application.
+
+### Buildkit and Internal Registry
+The image build service, buildkit, and an internal image registry are deployed as sibling containers in a single pod. This simplifies the communication between the two components when buildkit is building new acorn images.
+
+
+
+
+