# temporalio/ui-server architecture

> Architecture diagram of the GitHub repository temporalio/ui-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/temporalio/ui-server
- Repository: https://github.com/temporalio/ui-server

## Overview

#### Purpose and Entrypoint
This repository packages Temporal’s UI server: a Go HTTP service that serves a prebuilt UI and proxies UI API calls to a Temporal gRPC endpoint. The executable starts at `cmd/server/main.go`; server assembly and lifecycle are centered in `server/server.go`.

#### Startup and Configuration
Configuration is modeled and validated by `server/config/config.go`, with provider abstractions in `server/config/config_provider.go`. The filesystem plugin loads YAML configuration (`plugins/fs_config_provider/fs_config_provider.go`), using deployment variants such as `config/base.yaml`, `config/docker.yaml`, and `config/with-auth.yaml`. A refresh-capable provider (`server/config/config_provider_with_refresh.go`) creates a boundary between server runtime and dynamic configuration sources.

#### HTTP Edge and Route Composition
The HTTP-facing server organizes routes by concern: API forwarding in `server/route/api.go`, authentication endpoints in `server/route/auth.go`, health checks in `server/route/health.go`, and UI/static routing in `server/route/ui.go`. This is the primary request dispatch boundary: browser and operational traffic arrive over HTTP, then are classified as static UI, health, auth, or Temporal API requests.

#### API Gateway and Temporal RPC Boundary
`server/api/handler.go` implements API request handling; `server/api/marshaler.go` controls HTTP payload translation and `server/api/rawhistory.go` supports raw workflow-history responses. Requests crossing this layer are sent through the RPC client layer in `server/rpc/rpc.go`, with TLS setup in `server/rpc/tls.go`. The material external dependency is a Temporal gRPC service, particularly the WorkflowService API referenced by the README.

#### Identity and Browser Security
Optional authentication is defined by `server/auth/auth.go` and OpenID Connect integration by `server/auth/oidc.go`; auth configuration is isolated in `server/config/auth.go`. Cross-origin policy is enforced by `server/cors/cors.go`, while CSRF protections—including cookie handling and request-origin checks—live in `server/csrf/cookie.go` and `server/csrf/sec_fetch_site.go`. These layers protect browser-to-server requests before they reach API/RPC handling.

#### UI Delivery
The UI is compiled static content embedded into the Go binary via `ui/embed.go`, sourced from `ui/assets/local/index.html` and its generated `_app` bundles. `server/route/ui.go` serves this embedded application, including public-path behavior handled by `server/route/public_path.go`. The repository contains artifacts rather than UI source, so UI behavior is built elsewhere and delivered here as versioned static assets.

#### Deployment Model
The service is containerized by `Dockerfile`; `docker/start-ui-server.sh` is the container startup wrapper. GitHub Actions build/download the UI and build/push images through `.github/actions/download-and-build-ui/action.yaml` and `.github/actions/docker-build-push/action.yml`. The runtime is therefore a Go server plus embedded frontend, configured externally through YAML and connected to Temporal over gRPC/TLS.

Main entry points: [`server/route/api.go`](https://github.com/temporalio/ui-server/blob/main/server/route/api.go) (HTTP route composition), [`server/server.go`](https://github.com/temporalio/ui-server/blob/main/server/server.go) (Server lifecycle), [`server/config/config_provider_with_refresh.go`](https://github.com/temporalio/ui-server/blob/main/server/config/config_provider_with_refresh.go) (Refreshable config provider), [`cmd/server/main.go`](https://github.com/temporalio/ui-server/blob/main/cmd/server/main.go) (Server executable)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Go Server"]
  node_main["Server executable<br/>Go entrypoint<br/>[main.go]"]
  node_server["Server lifecycle<br/>assembly<br/>[server.go]"]
  node_config["Configuration model<br/>validation<br/>[config.go]"]
  node_config_provider["Refreshable config provider<br/>runtime config"]
  node_fs_provider["YAML config loader<br/>filesystem plugin"]
  node_yaml_configs["Deployment YAML<br/>configuration<br/>[base.yaml]"]
  node_routes["HTTP route composition<br/>dispatch boundary<br/>[api.go]"]
  node_api_handler["API gateway<br/>HTTP-to-RPC handler<br/>[handler.go]"]
  node_rpc["Temporal RPC client<br/>gRPC client<br/>[rpc.go]"]
end

subgraph group_security["Browser Security"]
  node_auth["OIDC authentication<br/>identity integration<br/>[oidc.go]"]
  node_auth_config["Auth configuration<br/>[auth.go]"]
  node_cors["CORS policy<br/>HTTP middleware<br/>[cors.go]"]
  node_csrf["CSRF protection<br/>HTTP middleware<br/>[cookie.go]"]
end

subgraph group_delivery["UI &amp; Deployment"]
  node_ui_routes["UI static routes<br/>asset delivery<br/>[ui.go]"]
  node_embedded_ui["Embedded UI assets<br/>compiled static UI<br/>[embed.go]"]
  node_container["Container startup<br/>Docker runtime<br/>[start-ui-server.sh]"]
end

node_browser(("Browser / operators<br/>HTTP clients"))
node_temporal{{"Temporal WorkflowService<br/>external gRPC service"}}

node_browser -->|"HTTP requests"| node_cors
node_cors -->|"browser policy"| node_csrf
node_csrf -->|"protected requests"| node_routes
node_main -->|"starts"| node_server
node_server -->|"reads runtime config"| node_config_provider
node_config_provider -->|"validates"| node_config
node_config_provider -->|"loads from"| node_fs_provider
node_fs_provider -->|"reads"| node_yaml_configs
node_server -->|"mounts"| node_routes
node_routes -->|"API requests"| node_api_handler
node_routes -->|"auth endpoints"| node_auth
node_routes -->|"UI and static requests"| node_ui_routes
node_auth -->|"uses"| node_auth_config
node_api_handler -->|"translated calls"| node_rpc
node_rpc -->|"gRPC/TLS"| node_temporal
node_ui_routes -->|"serves"| node_embedded_ui
node_container -->|"launches"| node_main

click node_main "https://github.com/temporalio/ui-server/blob/main/cmd/server/main.go"
click node_server "https://github.com/temporalio/ui-server/blob/main/server/server.go"
click node_config "https://github.com/temporalio/ui-server/blob/main/server/config/config.go"
click node_config_provider "https://github.com/temporalio/ui-server/blob/main/server/config/config_provider_with_refresh.go"
click node_fs_provider "https://github.com/temporalio/ui-server/blob/main/plugins/fs_config_provider/fs_config_provider.go"
click node_yaml_configs "https://github.com/temporalio/ui-server/blob/main/config/base.yaml"
click node_routes "https://github.com/temporalio/ui-server/blob/main/server/route/api.go"
click node_api_handler "https://github.com/temporalio/ui-server/blob/main/server/api/handler.go"
click node_rpc "https://github.com/temporalio/ui-server/blob/main/server/rpc/rpc.go"
click node_auth "https://github.com/temporalio/ui-server/blob/main/server/auth/oidc.go"
click node_auth_config "https://github.com/temporalio/ui-server/blob/main/server/config/auth.go"
click node_cors "https://github.com/temporalio/ui-server/blob/main/server/cors/cors.go"
click node_csrf "https://github.com/temporalio/ui-server/blob/main/server/csrf/cookie.go"
click node_ui_routes "https://github.com/temporalio/ui-server/blob/main/server/route/ui.go"
click node_embedded_ui "https://github.com/temporalio/ui-server/blob/main/ui/embed.go"
click node_container "https://github.com/temporalio/ui-server/blob/main/docker/start-ui-server.sh"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_server,node_config,node_config_provider,node_fs_provider,node_yaml_configs,node_routes,node_api_handler,node_rpc toneBlue
class node_auth,node_auth_config,node_cors,node_csrf toneAmber
class node_ui_routes,node_embedded_ui,node_container toneMint
class node_browser,node_temporal toneNeutral
```

## Components

### Go Server

HTTP service and Temporal gateway.

- [Server executable](https://github.com/temporalio/ui-server/blob/main/cmd/server/main.go): Go entrypoint · `cmd/server/main.go`
- [Server lifecycle](https://github.com/temporalio/ui-server/blob/main/server/server.go): assembly · Builds and runs the HTTP server. · `server/server.go`
- [Configuration model](https://github.com/temporalio/ui-server/blob/main/server/config/config.go): validation · `server/config/config.go`
- [Refreshable config provider](https://github.com/temporalio/ui-server/blob/main/server/config/config_provider_with_refresh.go): runtime config · Insulates the server from dynamic configuration sources. · `server/config/config_provider_with_refresh.go`
- [YAML config loader](https://github.com/temporalio/ui-server/blob/main/plugins/fs_config_provider/fs_config_provider.go): filesystem plugin · `plugins/fs_config_provider/fs_config_provider.go`
- [Deployment YAML](https://github.com/temporalio/ui-server/blob/main/config/base.yaml): configuration · Base, Docker, and auth deployment variants. · `config/base.yaml`
- [HTTP route composition](https://github.com/temporalio/ui-server/blob/main/server/route/api.go): dispatch boundary · Classifies UI, health, auth, and API traffic. · `server/route/api.go`
- [API gateway](https://github.com/temporalio/ui-server/blob/main/server/api/handler.go): HTTP-to-RPC handler · Translates UI API requests and raw history responses. · `server/api/handler.go`
- [Temporal RPC client](https://github.com/temporalio/ui-server/blob/main/server/rpc/rpc.go): gRPC client · Connects to Temporal with TLS support. · `server/rpc/rpc.go`

### Browser Security

Optional identity and request protections.

- [OIDC authentication](https://github.com/temporalio/ui-server/blob/main/server/auth/oidc.go): identity integration · Optional authentication endpoints and flow. · `server/auth/oidc.go`
- [Auth configuration](https://github.com/temporalio/ui-server/blob/main/server/config/auth.go): configuration · `server/config/auth.go`
- [CORS policy](https://github.com/temporalio/ui-server/blob/main/server/cors/cors.go): HTTP middleware · `server/cors/cors.go`
- [CSRF protection](https://github.com/temporalio/ui-server/blob/main/server/csrf/cookie.go): HTTP middleware · Cookie and request-origin protections. · `server/csrf/cookie.go`

### UI & Deployment

Embedded UI assets and container delivery.

- [UI static routes](https://github.com/temporalio/ui-server/blob/main/server/route/ui.go): asset delivery · Serves the embedded application and public paths. · `server/route/ui.go`
- [Embedded UI assets](https://github.com/temporalio/ui-server/blob/main/ui/embed.go): compiled static UI · Prebuilt frontend bundled into the Go binary. · `ui/embed.go`
- [Container startup](https://github.com/temporalio/ui-server/blob/main/docker/start-ui-server.sh): Docker runtime · Starts the UI server in the image. · `docker/start-ui-server.sh`

### Other components

- **Browser / operators**: HTTP clients
- **Temporal WorkflowService**: external gRPC service

## Connections

- Browser / operators → CORS policy: HTTP requests
- CORS policy → CSRF protection: browser policy
- CSRF protection → HTTP route composition: protected requests
- Server executable → Server lifecycle: starts
- Server lifecycle → Refreshable config provider: reads runtime config
- Refreshable config provider → Configuration model: validates
- Refreshable config provider → YAML config loader: loads from
- YAML config loader → Deployment YAML: reads
- Server lifecycle → HTTP route composition: mounts
- HTTP route composition → API gateway: API requests
- HTTP route composition → OIDC authentication: auth endpoints
- HTTP route composition → UI static routes: UI and static requests
- OIDC authentication → Auth configuration: uses
- API gateway → Temporal RPC client: translated calls
- Temporal RPC client → Temporal WorkflowService: gRPC/TLS
- UI static routes → Embedded UI assets: serves
- Container startup → Server executable: launches
