coder · ammario · Jun 17, 2022 · Jun 17, 2022 · Jun 17, 2022 · Jun 17, 2022
diff --git a/docs/architecture.md b/docs/architecture.md
@@ -0,0 +1,71 @@
+# Architecture
+
+<p align="center">
+  <img src="./images/architecture.png" width="700px">
+</p>
+
+## Agents
+
+An agent is the Coder service that runs within a user's remote workspace.
+It provides a consistent interface for coderd and clients to communicate
+with workspaces regardless of operating system, architecture, or cloud.
+
+It offers the following services along with much more:
+
+- SSH
+- Port forwarding
+- Liveness checks
+- `startup_script` automation
+
+## Service Bundling
+
+While coderd, provisionerd and Postgres can be orchestrated independently,
+our default installation paths bundle them all together into one system service.
+It's perfectly fine to run a production deployment this way, but there are
+certain situations that necessitate decomposition:
+
+- Reducing global client latency (distribute coderd and centralize database)
+- Running untrusted provisioners (separate provisionerd from nodes with DB access)
+- Achieving greater availability and efficiency (horizontally scale individual services)
+
+## coderd
+
+coderd is the service created by running `coder server`. It is a thin
+API that connects workspaces, provisioners and users. coderd stores its state in
+Postgres and is the only service that communicates with Postgres.
+
+It offers:
+
+- Dashboard
+- HTTP API
+- Dev URLs (HTTP reverse proxy to workspaces)
+- Workspace Web Applications (e.g easily access code-server)
+- Agent registration
+
+## provisionerd
+
+provisionerd is the execution context for infrastructure modifying providers.
+At the moment, the only provider is Terraform (running `terraform`).
+
+Since the provisionerd can be separated from coderd, it can run the provider
+in a myriad of ways on the same Coder deployment. For example, provisioners
+can have different `terraform` versions to satisfy the requirements of different
+templates.
+
+Separability is also advantageous for security. Since provisionerd has no
+database access, infrastructure admins that are not necessarily Coder admins
+can be safely given access to the provisionerd node. As Coder scales and
+multiple infrastructure teams appear, each can be given access to their own
+set of provisionerd nodes, with each set of nodes having their own cloud credentials.
+
+## Workspaces
+
+At the highest level, a workspace is a set of cloud resources. These resources
+can be VMs, Kubernetes clusters, storage buckets, or whatever else Terraform
+lets you dream up.
+
+The resources that run the agent are described as _computational resources_,
+while those that don't are called _peripheral resources_.
+
+Each resource may also be _persistent_ or _ephemeral_ depending on whether
+they're destroyed on workspace stop.
diff --git a/docs/images/architecture.png b/docs/images/architecture.png
diff --git a/docs/manifest.json b/docs/manifest.json
@@ -5,7 +5,15 @@
       "title": "About",
       "description": "About Coder",
       "path": "./README.md",
-      "icon": "<svg xmlns=\"http://www.w3.org/2000/svg\" xmlns:xlink=\"http://www.w3.org/1999/xlink\" version=\"1.1\" viewBox=\"0 0 16 16\" width=\"16px\" xml:space=\"preserve\"><path d=\"M15.45,7L14,5.551V2c0-0.55-0.45-1-1-1h-1c-0.55,0-1,0.45-1,1v0.553L9,0.555C8.727,0.297,8.477,0,8,0S7.273,0.297,7,0.555  L0.55,7C0.238,7.325,0,7.562,0,8c0,0.563,0.432,1,1,1h1v6c0,0.55,0.45,1,1,1h3v-5c0-0.55,0.45-1,1-1h2c0.55,0,1,0.45,1,1v5h3  c0.55,0,1-0.45,1-1V9h1c0.568,0,1-0.437,1-1C16,7.562,15.762,7.325,15.45,7z\"></path></svg>"
+      "icon": "<svg xmlns=\"http://www.w3.org/2000/svg\" xmlns:xlink=\"http://www.w3.org/1999/xlink\" version=\"1.1\" viewBox=\"0 0 16 16\" width=\"16px\" xml:space=\"preserve\"><path d=\"M15.45,7L14,5.551V2c0-0.55-0.45-1-1-1h-1c-0.55,0-1,0.45-1,1v0.553L9,0.555C8.727,0.297,8.477,0,8,0S7.273,0.297,7,0.555  L0.55,7C0.238,7.325,0,7.562,0,8c0,0.563,0.432,1,1,1h1v6c0,0.55,0.45,1,1,1h3v-5c0-0.55,0.45-1,1-1h2c0.55,0,1,0.45,1,1v5h3  c0.55,0,1-0.45,1-1V9h1c0.568,0,1-0.437,1-1C16,7.562,15.762,7.325,15.45,7z\"></path></svg>",
+      "children": [
+        {
+          "title": "Architecture",
+          "description": "Learn how Coder works",
+          "icon": "<svg xmlns=\"http:\/\/www.w3.org\/2000\/svg\" enable-background=\"new 0 0 24 24\" height=\"24\" viewBox=\"0 0 24 24\" width=\"24\"><g><rect fill=\"none\" height=\"24\" width=\"24\"\/><\/g><g><g><path d=\"M6.36,18.78L6.61,21l1.62-1.54l2.77-7.6c-0.68-0.17-1.28-0.51-1.77-0.98L6.36,18.78z\"\/><path d=\"M14.77,10.88c-0.49,0.47-1.1,0.81-1.77,0.98l2.77,7.6L17.39,21l0.26-2.22L14.77,10.88z\"\/><path d=\"M15,8c0-1.3-0.84-2.4-2-2.82V3h-2v2.18C9.84,5.6,9,6.7,9,8c0,1.66,1.34,3,3,3S15,9.66,15,8z M12,9c-0.55,0-1-0.45-1-1 c0-0.55,0.45-1,1-1s1,0.45,1,1C13,8.55,12.55,9,12,9z\"\/><\/g><\/g><\/svg>",
+          "path": "./architecture.md"
+        }
+      ]
     },
     {
       "title": "Installation",