diff --git a/floxhub-onprem/reference-architectures/overview.mdx b/floxhub-onprem/reference-architectures/overview.mdx
index 03f4780..5505d93 100644
--- a/floxhub-onprem/reference-architectures/overview.mdx
+++ b/floxhub-onprem/reference-architectures/overview.mdx
@@ -1,15 +1,133 @@
---
title: "Reference architectures"
-description: "Supported deployment topologies for FloxHub on-prem."
+description: "The supported deployment topology for FloxHub on-prem, what each component does, and where your infrastructure meets it."
---
-
- **This page is under construction.** FloxHub on-prem documentation is
- being written section by section. This page is a placeholder so the
- surrounding navigation and links are complete.
-
+A reference architecture is a layout Flox builds, tests, and supports. It tells
+you which components run where, which pieces you supply, and what the
+arrangement does and does not give you.
-## Planned contents
+**One topology is documented today: a single host.** Every component runs on one
+machine, with your database and your TLS edge beside it.
-The supported topology, what each component is responsible for, and how to
-choose between architectures.
+
+ The component topology, network boundaries, persistent state, and operator
+ responsibilities in detail.
+
+
+## The shape of a deployment
+
+```mermaid
+flowchart TB
+ subgraph clients [Clients]
+ cli[Flox CLI]
+ browser[Browser]
+ end
+
+ subgraph yours [Your infrastructure]
+ edge[TLS edge]
+ idp[("Identity provider")]
+ db[("PostgreSQL")]
+ store[("Object store, optional")]
+ end
+
+ subgraph host [FloxHub host]
+ door{{"Front door"}}
+ subgraph web [Web]
+ ui[Web UI]
+ bff[Web backend]
+ end
+ subgraph core [Core services]
+ catalog[Catalog]
+ envs[Environments]
+ git[("Git storage")]
+ end
+ subgraph identity [Identity]
+ accounts[Accounts]
+ broker[OIDC broker]
+ authz[Authorization]
+ end
+ subgraph background [Background]
+ refresh[Catalog refresh]
+ builds[Builds]
+ upgrades[Scheduled upgrades]
+ end
+ end
+
+ cli --> edge
+ browser --> edge
+ edge --> door
+ door --> web
+ door --> core
+ door --> identity
+ broker --> idp
+ core --> db
+ identity --> db
+ background --> db
+ builds --> store
+ catalog --> store
+```
+
+## What runs on the host
+
+| Component | Responsibility |
+| --- | --- |
+| Front door | Receives every client request, authenticates it, and routes it |
+| Web UI and backend | The browser interface and the session it runs in |
+| Catalog | Resolving and serving packages |
+| Environments | Storing environments and their generations |
+| Git storage | Backing `flox push` and `flox pull` |
+| Accounts | Users, organizations, and tokens |
+| OIDC broker | Translating your identity provider into one interface |
+| Authorization | Deciding what each identity may reach |
+| Catalog refresh | Populating the catalog and keeping it current |
+| Builds | Building and publishing packages inside the deployment |
+| Scheduled upgrades | Advancing managed environments on a cadence |
+
+Every component that can be switched off is switched off by configuration
+rather than by editing the environment. A component whose gate is off idles, so
+turning one on or off is a setting change and a restart.
+
+## What you supply
+
+| Piece | Why it is yours |
+| --- | --- |
+| The host | Provisioning, sizing, and OS patching |
+| PostgreSQL | The deployment ships no database; this is its durable state |
+| The TLS edge | The front door speaks plain HTTP and holds no certificate |
+| An identity provider | The deployment holds no passwords |
+| An object store | Optional, and only for carrying published binaries |
+
+See [Installation requirements](/floxhub-onprem/install/requirements) for the
+prerequisites each of these has to meet.
+
+## Choosing an architecture
+
+With one documented topology, the question is not which to pick but whether
+single-host meets your needs. It does when:
+
+- One host can carry your users and your catalog.
+- Planned downtime for upgrades is acceptable. An upgrade stops services.
+- Your availability requirement is met by your own host and database recovery
+ rather than by redundancy inside FloxHub.
+
+It does not give you high availability. There is no second host to fail over
+to, and no component runs redundantly. Availability comes from the resilience
+of the host and the database you supply, plus your ability to restore from
+backup — so
+[Back up and restore](/floxhub-onprem/administration/maintain/backup-restore)
+matters more here than it would in a redundant deployment.
+
+
+ Separating components across hosts, running any of them redundantly, or
+ pointing the deployment at managed equivalents of its bundled pieces are not
+ documented or supported arrangements today. The single-host topology is what
+ Flox tests and supports.
+
+
+## Sizing
+
+How much host to provision for a given number of users and catalog size is
+being measured, and will be published alongside the single-host topology once
+those figures exist. Until then, treat capacity as something to validate in
+your own environment rather than something this page can answer.
diff --git a/llms.txt b/llms.txt
index c86f63a..e62ee95 100644
--- a/llms.txt
+++ b/llms.txt
@@ -133,7 +133,7 @@ Key terms:
## FloxHub on-prem: Reference architectures
-- [Reference architectures](https://flox.dev/docs/floxhub-onprem/reference-architectures/overview.md): Supported deployment topologies for FloxHub on-prem.
+- [Reference architectures](https://flox.dev/docs/floxhub-onprem/reference-architectures/overview.md): The supported deployment topology for FloxHub on-prem, what each component does, and where your infrastructure meets it.
- [Single-host deployment](https://flox.dev/docs/floxhub-onprem/reference-architectures/single-host.md): Every FloxHub service on one host, with the database alongside it.
## FloxHub on-prem: Administer