# temporalio/ui architecture

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

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

## Overview

##### Main Components
- Frontend/UI Layer: Represented by the “src” directory, including all Svelte components, pages, layouts, and styles. This layer is built with Vite and processed with tools like Tailwind CSS.
- UI Server/Backend API: Found in the “server” directory (written in Go), which contains subdirectories for API routing, configuration, authentication, RPC, plugins, and static asset serving (for instance, “server/ui/assets” when built for the UI server).
- Temporal Integration: The “temporal” directory shows workflows, activities, and clients that integrate the UI with Temporal. Also note that the README outlines the need for a running Temporal instance (with CLI integration) so that the UI can interact with the Temporal server.
- External Dependencies: The Temporal CLI (downloaded on installation and/or located in PATH), Temporal Server (which must be running, either via Docker or locally), and possibly Docker infrastructure (Dockerfile, docker-compose references for containerization).
- Build & Testing Infrastructure:
- Build scripts and configuration (package.json, pnpm scripts, Vite config, etc.) to create production-ready assets.
- Test suites (e2e tests with Playwright, integration tests, and various test utilities under the “tests” folder) outlining how the components are validated.
- Configuration files/environment variables (all the .env variants) that point to API endpoints, build targets, and Temporal port numbers.
- Auxiliary Tools: For example, the “plugins” directory which contains plugins integrating with Vite for running the Temporal and UI servers.

##### Relationships and Interactions
- The UI (frontend) communicates with the backend API via HTTP calls. This connection is facilitated by endpoints exposed by the Go-based server.
- The backend API, in turn, interacts with the Temporal server to create workflows, fetch workflow statuses, and handle real-time updates. It may use RPC/gRPC or HTTP bridges based on the implementation in “server/rpc” and “server/api.”
- The Temporal workflows and activities (from the “temporal” directory) define how business logic is executed and how events are recorded and processed.
- Build and deployment are managed by scripts (pnpm commands, Dockerfiles, Makefiles) and CI/CD pipelines defined in the “.github” directory. Testing tools (like Playwright) are spawned by configuration in “playwright.config.ts” and tied into scripts like “pnpm test:e2e.”
- Developers running the application locally must have a running Temporal server (via the Temporal CLI or Docker) and configure their environment (via the provided .env files) so that the UI server knows where to reach Temporal and vice versa.

##### Architectural Patterns and Design Principles
- Modular Separation: The project exhibits a clear separation between the UI (client-side code) and the API/backend server (Go code). There is also a distinct separation for workflow logic (Temporal workflows) and testing/deployment.
- Configurability/Environment-Based Behavior: Multiple .env files indicate that the project is designed to support various modes (development, testing, production) with different configurations for API endpoints, ports, and build targets.
- Plugin Architecture: The “plugins” directory indicates a modular integration point for tool-specific functionalities (e.g., vite-plugin-temporal-server.ts and vite-plugin-ui-server.ts).
- Testing First: With extensive tests (unit, integration, and e2e), the architecture is designed for robustness and continuous validation of both UI and backend components.
- Microservice-Friendly: While the UI and server are housed in one repository, the use of Docker, separate build commands, and distinct folders for server and workflows suggest an architecture that can be scaled or re-deployed as microservices if needed.

##### Relevant Technologies, Frameworks, and Libraries
- Frontend: Svelte, Vite, Tailwind CSS, and potentially Storybook (as evidenced by the “.storybook” directory).
- Backend: Go (with modules and plugins for configuration, authentication, and API handling), gRPC/RPC based on the “server/rpc” folder, and possibly a standard Go HTTP server.
- Temporal: Temporal CLI, Temporal Server, and client SDKs for connecting workflows.
- DevOps/CI: GitHub Actions workflows, Docker configurations, and Vercel deployment configuration.
- Testing: Playwright for e2e tests, Vitest for unit testing, and various test utilities.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend/UI Layer
    subgraph "Frontend/UI Layer"
        UI["Svelte/Vite UI"]:::frontend
    end

    %% Backend API Server
    subgraph "Backend API Server"
        API["Go API Server"]:::backend
    end

    %% Temporal Integration
    subgraph "Temporal Integration"
        TEMP["Temporal Workflows & Activities"]:::temporal
    end

    %% Build & Testing Infrastructure
    subgraph "Build & Testing Infrastructure"
        BUILD_SCRIPTS["Build Scripts<br/>(package.json, vite.config.ts, tailwind.config.ts)"]:::build
        TEST_SUITES["Test Suites<br/>(tests, playwright.config.ts)"]:::build
    end

    %% Plugin Architecture
    subgraph "Plugin Architecture"
        PLUG["Vite Plugins<br/>(plugins)"]:::plugin
    end

    %% CI/CD and Deployment
    subgraph "CI/CD and Deployment"
        CICD["GitHub Actions & Deployments<br/>(.github)"]:::cicd
    end

    %% External Dependencies
    subgraph "External Dependencies"
        EXTERNAL["Temporal Server & CLI"]:::external
        DOCKER["Docker Infrastructure"]:::external
    end

    %% Relationships
    UI -->|"HTTPrequests"| API
    API -->|"TriggersWorkflows"| TEMP
    TEMP --o|"WorkflowUpdates"| API

    CICD -.->|"Automates"| BUILD_SCRIPTS
    CICD -.->|"Automates"| API
    CICD -.->|"Deploys"| UI

    UI -->|"Uses"| PLUG
    BUILD_SCRIPTS -->|"Bundles"| UI
    TEST_SUITES -->|"Validates"| UI
    TEST_SUITES -->|"Validates"| API

    API -->|"ConnectsTo"| EXTERNAL
    API -->|"Uses"| DOCKER
    TEMP -->|"Requires"| EXTERNAL

    %% Click Events
    click UI "https://github.com/temporalio/ui/tree/main/src"
    click API "https://github.com/temporalio/ui/tree/main/server"
    click TEMP "https://github.com/temporalio/ui/tree/main/temporal"
    click BUILD_SCRIPTS "https://github.com/temporalio/ui/blob/main/package.json"
    click TEST_SUITES "https://github.com/temporalio/ui/tree/main/tests"
    click PLUG "https://github.com/temporalio/ui/tree/main/plugins"
    click CICD "https://github.com/temporalio/ui/blob/main/.github"

    %% Styles
    classDef frontend fill:#fef3c7,stroke:#f59e0b,stroke-width:2px;
    classDef backend fill:#e0f2fe,stroke:#0284c7,stroke-width:2px;
    classDef temporal fill:#d1fae5,stroke:#10b981,stroke-width:2px;
    classDef build fill:#ede9fe,stroke:#7c3aed,stroke-width:2px;
    classDef plugin fill:#fce7f3,stroke:#db2777,stroke-width:2px;
    classDef cicd fill:#cffafe,stroke:#06b6d4,stroke-width:2px;
    classDef external fill:#f0fdfa,stroke:#14b8a6,stroke-width:2px;
```
