# Architecture
> Review the components of an Orchard instance, what keeps running if the control plane stops, and how Orchard reads from and writes to Kubernetes.
Source: https://docs.orchard.hackclub.com/operate/architecture/
An Orchard instance is a control plane that runs in a Kubernetes cluster and manages tenant workloads in the same cluster. Kubernetes is the source of truth for every resource that Orchard manages, so Orchard keeps a copy of cluster state for fast reads but always defers to the cluster when the two disagree.
## Components
| Component | Purpose |
| ------------------------- | ------------------------------------------------------------------------------------------------ |
| Frontend | The SvelteKit dashboard. |
| Server | The NestJS API and control plane. |
| MCP server | The [Model Context Protocol](/mcp/) endpoint for agents. |
| Builders | [BuildKit jobs](/deploy/builds/) that build images for tenant apps. |
| Control-plane Postgres | Orchard's own database, run by CloudNativePG. |
| Redis | The event bus between server replicas, and a cache. |
| Registry | Stores the images that builders push. The installer deploys zot. |
| Object storage | Holds database backups and uploads. The installer deploys an S3-compatible store in the cluster. |
| Backup proxy (`r2-proxy`) | Gives each database credentials for [its own backups](/data/backups/) only. |
| Metrics and logs | VictoriaMetrics, [VictoriaLogs, and Vector](/operate/logs/#components). |
Tenant apps and databases run in their own namespaces, separate from the control plane.
The one-command installer runs every component on one machine. With the Helm chart on a multi-node cluster, you can replace the registry, object storage, Redis, and storage with ones you operate. For the options, refer to [Replace bundled components](/operate/production/#replace-bundled-components).
```mermaid
flowchart LR
U[Browser / CLI / MCP] --> API[API server]
API -->|reads| PG[(Control-plane
Postgres)]
API -->|writes| Q[Apply queue]
Q -->|retry| K8S[Kubernetes API]
INF[Engine informers] -->|watch| K8S
INF -->|copy state| PG
K8S --> NS[Tenant namespaces
apps · databases · jobs]
API -->|events via Redis| U
```
The server reads from Postgres and writes through a queue. The Orchard Engine copies cluster state into Postgres.
## Reads
The Orchard Engine lists and watches the Kubernetes objects that Orchard manages, and keeps a copy in Postgres. Most reads come from this copy, so a page load does not call the Kubernetes API.
The Engine follows these rules:
- If the copy and the cluster disagree, the cluster is correct.
- A failed read does not mean that a resource is gone. Only a live `404` response removes it.
- A change made with `kubectl` is adopted into Orchard. Security objects are the exception. Orchard restores its own version of [default-deny network policies](/operate/security/#network-isolation) and records the change in the [audit log](/teams/audit-logs/).
## Writes
Most cluster writes go through an apply queue. The request records the desired state and returns. A worker applies the change and retries with backoff on a failure.
## Events
Orchard sends state changes to the dashboard as server-sent events over Redis Streams. After a reconnect, the client replays from the last event it received. Without Redis, each server replica delivers only its own events.
## Replicas and leases
Background work that must not run twice, such as watching the cluster, uses a Kubernetes lease. Only the replica that holds the lease does that work, so the server can run more than one replica.
By default, each server pod serves the API and runs the queues. To run builds, notifications, and the apply queue in separate pods, set `server.workers.enabled` to `true` in the chart.
## If the control plane stops
Apps, databases, and routes are ordinary Kubernetes objects, so they do not depend on the Orchard server, frontend, or engine. If those stop, apps keep running and serving traffic, and CloudNativePG keeps managing database failover and backups. Builds, deploys, and other changes wait until Orchard is back. An upgrade of Orchard does not restart apps either. For more information, refer to [Upgrade Orchard](/operate/upgrades/#effect-on-running-apps).
## Related resources
- [Security and isolation](/operate/security/) - Review what Orchard isolates between tenants and what they share.
- [Scale the control plane](/operate/scale-control-plane/) - Run more replicas, autoscale, and move builds to worker pods.
- [Configure logs and request data](/operate/logs/) - Learn how the log store collects app and access logs.
- [Concepts](/start/concepts/) - Learn the terms that Orchard uses, such as organizations, projects, and apps.