coder · ericpaulsen · Jul 1, 2024 · Jun 28, 2024 · Jun 28, 2024 · Jun 28, 2024
diff --git a/docs/admin/scaling/scale-testing.md b/docs/admin/scaling/scale-testing.md
@@ -90,11 +90,11 @@ Database:
 
 ## Available reference architectures
 
-[Up to 1,000 users](../architectures/1k-users.md)
+[Up to 1,000 users](../../architecture/1k-users.md)
 
-[Up to 2,000 users](../architectures/2k-users.md)
+[Up to 2,000 users](../../architecture/2k-users.md)
 
-[Up to 3,000 users](../architectures/3k-users.md)
+[Up to 3,000 users](../../architecture/3k-users.md)
 
 ## Hardware recommendation
 

diff --git a/docs/admin/scaling/scale-utility.md b/docs/admin/scaling/scale-utility.md
@@ -6,15 +6,15 @@ infrastructure. For scale-testing Kubernetes clusters we recommend to install
 and use the dedicated Coder template,
 [scaletest-runner](https://github.com/coder/coder/tree/main/scaletest/templates/scaletest-runner).
 
-Learn more about [Coder’s architecture](../architectures/architecture.md) and
+Learn more about [Coder’s architecture](../../architecture/architecture.md) and
 our [scale-testing methodology](scale-testing.md).
 
 ## Recent scale tests
 
 > Note: the below information is for reference purposes only, and are not
 > intended to be used as guidelines for infrastructure sizing. Review the
-> [Reference Architectures](../architectures/validated-arch.md#node-sizing) for
-> hardware sizing recommendations.
+> [Reference Architectures](../../architecture/validated-arch.md#node-sizing)
+> for hardware sizing recommendations.
 
 | Environment      | Coder CPU | Coder RAM | Coder Replicas | Database          | Users | Concurrent builds | Concurrent connections (Terminal/SSH) | Coder Version | Last tested  |
 | ---------------- | --------- | --------- | -------------- | ----------------- | ----- | ----------------- | ------------------------------------- | ------------- | ------------ |

diff --git a/docs/admin/architectures/1k-users.md → docs/architecture/1k-users.md b/docs/admin/architectures/1k-users.md → docs/architecture/1k-users.md
diff --git a/docs/admin/architectures/2k-users.md → docs/architecture/2k-users.md b/docs/admin/architectures/2k-users.md → docs/architecture/2k-users.md
diff --git a/docs/admin/architectures/3k-users.md → docs/architecture/3k-users.md b/docs/admin/architectures/3k-users.md → docs/architecture/3k-users.md
diff --git a/docs/admin/architectures/architecture.md → docs/architecture/architecture.md b/docs/admin/architectures/architecture.md → docs/architecture/architecture.md
@@ -26,7 +26,7 @@ _provisionerd_ is the execution context for infrastructure modifying providers.
 At the moment, the only provider is Terraform (running `terraform`).
 
 By default, the Coder server runs multiple provisioner daemons.
-[External provisioners](../provisioners.md) can be added for security or
+[External provisioners](../admin/provisioners.md) can be added for security or
 scalability purposes.
 
 ### Agents
@@ -43,7 +43,7 @@ It offers the following services along with much more:
 - `startup_script` automation
 
 Templates are responsible for
-[creating and running agents](../../templates/index.md#coder-agent) within
+[creating and running agents](../templates/index.md#coder-agent) within
 workspaces.
 
 ### Service Bundling
@@ -73,7 +73,7 @@ they're destroyed on workspace stop.
 
 ### Single region architecture
 
-![Architecture Diagram](../../images/architecture-single-region.png)
+![Architecture Diagram](../images/architecture-single-region.png)
 
 #### Components
 
@@ -118,11 +118,11 @@ and _Coder workspaces_ deployed in the same region.
 
 - Integrate with existing Single Sign-On (SSO) solutions used within the
   organization via the supported OAuth 2.0 or OpenID Connect standards.
-- Learn more about [Authentication in Coder](../auth.md).
+- Learn more about [Authentication in Coder](../admin/auth.md).
 
 ### Multi-region architecture
 
-![Architecture Diagram](../../images/architecture-multi-region.png)
+![Architecture Diagram](../images/architecture-multi-region.png)
 
 #### Components
 
@@ -168,7 +168,7 @@ disruptions. Additionally, multi-cloud deployment enables organizations to
 leverage the unique features and capabilities offered by each cloud provider,
 such as region availability and pricing models.
 
-![Architecture Diagram](../../images/architecture-multi-cloud.png)
+![Architecture Diagram](../images/architecture-multi-cloud.png)
 
 #### Components
 
@@ -202,7 +202,7 @@ nearest region and technical specifications provided by the cloud providers.
 **Workspace proxy**
 
 - _Security recommendation_: Use `coder` CLI to create
-  [authentication tokens for every workspace proxy](../workspace-proxies.md#requirements),
+  [authentication tokens for every workspace proxy](../admin/workspace-proxies.md#requirements),
   and keep them in regional secret stores. Remember to distribute them using
   safe, encrypted communication channel.
 
@@ -220,11 +220,11 @@ nearest region and technical specifications provided by the cloud providers.
 - For Azure: _Azure Kubernetes Service_
 - For GCP: _Google Kubernetes Engine_
 
-See how to deploy
+See here for an example deployment of
 [Coder on Azure Kubernetes Service](https://github.com/ericpaulsen/coder-aks).
 
-Learn more about [security requirements](../../install/kubernetes.md) for
-deploying Coder on Kubernetes.
+Learn more about [security requirements](../install/kubernetes.md) for deploying
+Coder on Kubernetes.
 
 **Load balancer**
 
@@ -283,9 +283,9 @@ The key features of the air-gapped architecture include:
 - _Secure data transfer_: Enable encrypted communication channels and robust
   access controls to safeguard sensitive information.
 
-Learn more about [offline deployments](../../install/offline.md) of Coder.
+Learn more about [offline deployments](../install/offline.md) of Coder.
 
-![Architecture Diagram](../../images/architecture-air-gapped.png)
+![Architecture Diagram](../images/architecture-air-gapped.png)
 
 #### Components
 
@@ -327,8 +327,8 @@ across multiple regions and diverse cloud platforms.
 - Since the _Registry_ is isolated from the internet, platform engineers are
   responsible for maintaining Workspace container images and conducting periodic
   updates of base Docker images.
-- It is recommended to keep [Dev Containers](../../templates/dev-containers.md)
-  up to date with the latest released
+- It is recommended to keep [Dev Containers](../templates/dev-containers.md) up
+  to date with the latest released
   [Envbuilder](https://github.com/coder/envbuilder) runtime.
 
 **Mirror of Terraform Registry**
@@ -360,7 +360,7 @@ Learn more about
 [Dev containers support](https://coder.com/docs/v2/latest/templates/dev-containers)
 in Coder.
 
-![Architecture Diagram](../../images/architecture-devcontainers.png)
+![Architecture Diagram](../images/architecture-devcontainers.png)
 
 #### Components
 

diff --git a/docs/admin/architectures/validated-arch.md → docs/architecture/validated-arch.md b/docs/admin/architectures/validated-arch.md → docs/architecture/validated-arch.md
@@ -61,14 +61,14 @@ by default.
 
 ### User
 
-A [user](../users.md) is an individual who utilizes the Coder platform to
+A [user](../admin/users.md) is an individual who utilizes the Coder platform to
 develop, test, and deploy applications using workspaces. Users can select
 available templates to provision workspaces. They interact with Coder using the
 web interface, the CLI tool, or directly calling API methods.
 
 ### Workspace
 
-A [workspace](../../workspaces.md) refers to an isolated development environment
+A [workspace](../workspaces.md) refers to an isolated development environment
 where users can write, build, and run code. Workspaces are fully configurable
 and can be tailored to specific project requirements, providing developers with
 a consistent and efficient development environment. Workspaces can be
@@ -82,20 +82,20 @@ Coder templates and deployed on resources created by provisioners.
 
 ### Template
 
-A [template](../../templates/index.md) in Coder is a predefined configuration
-for creating workspaces. Templates streamline the process of workspace creation
-by providing pre-configured settings, tooling, and dependencies. They are built
-by template administrators on top of Terraform, allowing for efficient
-management of infrastructure resources. Additionally, templates can utilize
-Coder modules to leverage existing features shared with other templates,
-enhancing flexibility and consistency across deployments. Templates describe
-provisioning rules for infrastructure resources offered by Terraform providers.
+A [template](../templates/index.md) in Coder is a predefined configuration for
+creating workspaces. Templates streamline the process of workspace creation by
+providing pre-configured settings, tooling, and dependencies. They are built by
+template administrators on top of Terraform, allowing for efficient management
+of infrastructure resources. Additionally, templates can utilize Coder modules
+to leverage existing features shared with other templates, enhancing flexibility
+and consistency across deployments. Templates describe provisioning rules for
+infrastructure resources offered by Terraform providers.
 
 ### Workspace Proxy
 
-A [workspace proxy](../workspace-proxies.md) serves as a relay connection option
-for developers connecting to their workspace over SSH, a workspace app, or
-through port forwarding. It helps reduce network latency for geo-distributed
+A [workspace proxy](../admin/workspace-proxies.md) serves as a relay connection
+option for developers connecting to their workspace over SSH, a workspace app,
+or through port forwarding. It helps reduce network latency for geo-distributed
 teams by minimizing the distance network traffic needs to travel. Notably,
 workspace proxies do not handle dashboard connections or API calls.
 
@@ -212,11 +212,11 @@ resource "kubernetes_deployment" "coder" {
 
 For sizing recommendations, see the below reference architectures:
 
-- [Up to 1,000 users](1k-users.md)
+- [Up to 1,000 users](./1k-users.md)
 
-- [Up to 2,000 users](2k-users.md)
+- [Up to 2,000 users](./2k-users.md)
 
-- [Up to 3,000 users](3k-users.md)
+- [Up to 3,000 users](./3k-users.md)
 
 ### Networking
 
@@ -297,7 +297,7 @@ considerations:
   active users.
 - Enable High Availability mode for database engine for large scale deployments.
 
-If you enable [database encryption](../encryption.md) in Coder, consider
+If you enable [database encryption](../admin/encryption.md) in Coder, consider
 allocating an additional CPU core to every `coderd` replica.
 
 #### Resource utilization guidelines
@@ -320,26 +320,26 @@ could affect workspace users experience once the platform is live.
 
 ### Helm Chart Configuration
 
-1. Reference our [Helm chart values file](../../../helm/coder/values.yaml) and
+1. Reference our [Helm chart values file](../../helm/coder/values.yaml) and
    identify the required values for deployment.
 1. Create a `values.yaml` and add it to your version control system.
 1. Determine the necessary environment variables. Here is the
-   [full list of supported server environment variables](../../cli/server.md).
+   [full list of supported server environment variables](../cli/server.md).
 1. Follow our documented
-   [steps for installing Coder via Helm](../../install/kubernetes.md).
+   [steps for installing Coder via Helm](../install/kubernetes.md).
 
 ### Template configuration
 
 1. Establish dedicated accounts for users with the _Template Administrator_
    role.
 1. Maintain Coder templates using
-   [version control](../../templates/change-management.md).
+   [version control](../templates/change-management.md).
 1. Consider implementing a GitOps workflow to automatically push new template
    versions into Coder from git. For example, on Github, you can use the
    [Update Coder Template](https://github.com/marketplace/actions/update-coder-template)
    action.
 1. Evaluate enabling
-   [automatic template updates](../../templates/general-settings.md#require-automatic-updates-enterprise)
+   [automatic template updates](../templates/general-settings.md#require-automatic-updates-enterprise)
    upon workspace startup.
 
 ### Observability
@@ -351,13 +351,13 @@ could affect workspace users experience once the platform is live.
    leverage pre-configured dashboards, alerts, and runbooks for monitoring
    Coder. This includes integrations between Prometheus, Grafana, Loki, and
    Alertmanager.
-1. Review the [Prometheus response](../prometheus.md) and set up alarms on
+1. Review the [Prometheus response](../admin/prometheus.md) and set up alarms on
    selected metrics.
 
 ### User support
 
-1. Incorporate [support links](../appearance.md#support-links) into internal
-   documentation accessible from the user context menu. Ensure that hyperlinks
-   are valid and lead to up-to-date materials.
+1. Incorporate [support links](../admin/appearance.md#support-links) into
+   internal documentation accessible from the user context menu. Ensure that
+   hyperlinks are valid and lead to up-to-date materials.
 1. Encourage the use of `coder support bundle` to allow workspace users to
    generate and provide network-related diagnostic data.
diff --git a/docs/images/icons/container.svg b/docs/images/icons/container.svg
diff --git a/docs/manifest.json b/docs/manifest.json
@@ -14,6 +14,30 @@
         }
       ]
     },
+    {
+      "title": "Architecture",
+      "description": "Learn about validated and reference architectures for Coder",
+      "path": "./architecture/architecture.md",
+      "icon_path": "./images/icons/container.svg",
+      "children": [
+        {
+          "title": "Validated Architecture",
+          "path": "./architecture/validated-arch.md"
+        },
+        {
+          "title": "Up to 1,000 users",
+          "path": "./architecture/1k-users.md"
+        },
+        {
+          "title": "Up to 2,000 users",
+          "path": "./architecture/2k-users.md"
+        },
+        {
+          "title": "Up to 3,000 users",
+          "path": "./architecture/3k-users.md"
+        }
+      ]
+    },
     {
       "title": "Installation",
       "description": "How to install and deploy Coder",
@@ -343,30 +367,6 @@
       "path": "./admin/README.md",
       "icon_path": "./images/icons/wrench.svg",
       "children": [
-        {
-          "title": "Architecture",
-          "description": "Learn about validated and reference architectures for Coder",
-          "path": "./admin/architectures/architecture.md",
-          "icon_path": "./images/icons/container.svg",
-          "children": [
-            {
-              "title": "Validated Architecture",
-              "path": "./admin/architectures/validated-arch.md"
-            },
-            {
-              "title": "Up to 1,000 users",
-              "path": "./admin/architectures/1k-users.md"
-            },
-            {
-              "title": "Up to 2,000 users",
-              "path": "./admin/architectures/2k-users.md"
-            },
-            {
-              "title": "Up to 3,000 users",
-              "path": "./admin/architectures/3k-users.md"
-            }
-          ]
-        },
         {
           "title": "Authentication",
           "description": "Learn how to set up authentication using GitHub or OpenID Connect",

diff --git a/docs/platforms/other.md b/docs/platforms/other.md
@@ -3,8 +3,7 @@
 Coder is highly extensible and is not limited to the platforms outlined in these
 docs. The control plane can be provisioned on any VM or container compute, and
 workspaces can include any Terraform resource. See our
-[architecture documentation](../admin/architectures/architecture.md) for more
-details.
+[architecture documentation](../architecture/architecture.md) for more details.
 
 The following resources may help as you're deploying Coder.