> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/temporalio/temporal/llms.txt
> Use this file to discover all available pages before exploring further.

# Frontend Service

> API gateway and request routing for the Temporal cluster

# Frontend Service

The Frontend Service is the entry point for all external communication with the Temporal cluster. It acts as an API gateway, handling request validation, rate limiting, and routing to appropriate internal services.

## Overview

The Frontend Service exposes three main gRPC APIs:

1. **Workflow Service API**: Primary API for workflow operations (start, signal, query, etc.)
2. **Operator Service API**: Cluster operations and maintenance (add search attributes, etc.)
3. **Admin Service API**: Advanced administrative operations (workflow reset, shard management)

```mermaid theme={null}
flowchart TB
    subgraph External["External Clients"]
        App[User Application]
        Worker[Worker Process]
        Admin[Admin Tools]
    end
    
    subgraph Frontend["Frontend Service"]
        Workflow[Workflow API Handler]
        Operator[Operator API Handler]
        AdminAPI[Admin API Handler]
        
        subgraph Middleware
            RateLimit[Rate Limiter]
            Auth[Authorization]
            Validation[Request Validation]
        end
    end
    
    subgraph Internal["Internal Services"]
        History[History Service]
        Matching[Matching Service]
        Worker2[Worker Service]
    end
    
    App -->|gRPC| Workflow
    Worker -->|gRPC| Workflow
    Admin -->|gRPC| AdminAPI
    Admin -->|gRPC| Operator
    
    Workflow --> Middleware
    Operator --> Middleware
    AdminAPI --> Middleware
    
    Middleware --> History
    Middleware --> Matching
    Middleware --> Worker2
    
    style Frontend fill:#fff4e1
```

## Core Responsibilities

### API Gateway

The Frontend Service acts as the single entry point for all external requests:

* **Protocol Translation**: Converts external gRPC requests to internal service calls
* **Request Routing**: Directs requests to the appropriate History or Matching Service instance
* **Response Aggregation**: Collects responses from internal services and returns to clients

### Request Validation

Before forwarding requests, the Frontend validates:

<AccordionGroup>
  <Accordion title="Namespace Validation">
    * Verifies namespace exists and is active
    * Checks namespace state (registered, deprecated, deleted)
    * For global namespaces, checks if cluster is active
  </Accordion>

  <Accordion title="Payload Size Limits">
    * Workflow input payload size
    * Activity input payload size
    * Memo and search attribute sizes
    * Configurable via dynamic config
  </Accordion>

  <Accordion title="ID Length Limits">
    * Workflow ID length
    * Activity ID length
    * Task queue name length
    * Prevents database key length issues
  </Accordion>

  <Accordion title="API-Specific Validation">
    * Required fields are present
    * Enum values are valid
    * Timeout values are reasonable
    * Retry policies are valid
  </Accordion>
</AccordionGroup>

```go theme={null}
// Code entrypoint: service/frontend/workflow_handler.go
// Main handler for Workflow Service API
// Contains validation logic for all workflow operations
```

### Rate Limiting

The Frontend Service enforces multiple layers of rate limiting:

#### Global Rate Limits

* **Global RPS**: Total requests per second across all namespaces
* **Operator RPS**: Separate limit for operator APIs
* Protects the cluster from overload

#### Namespace Rate Limits

* **Per-Namespace RPS**: Requests per second per namespace
* **Visibility RPS**: Separate limit for list/scan operations
* **Long-Running Request Concurrency**: Limits concurrent long-poll requests

Rate limits are configured via dynamic configuration:

```go theme={null}
// Code entrypoint: service/frontend/configs/quotas.go
// Rate limiting configuration and enforcement
```

#### Per-API Rate Limits

Some APIs have specialized rate limits:

* Namespace replication-inducing APIs (create, update, delete namespace)
* Worker versioning APIs (build ID operations)
* Batch operations

### Request Routing

The Frontend routes requests to the correct service instance:

#### History Service Routing

For workflow operations:

1. Calculate shard ID from workflow ID (consistent hashing)
2. Look up History Service instance owning that shard
3. Forward request via gRPC to that instance

```go theme={null}
// Shard ID calculation:
// shardID = hash(namespaceID, workflowID) % numShards
```

#### Matching Service Routing

For task queue operations:

1. Hash task queue name to determine partition
2. Look up Matching Service instance owning that partition
3. Forward request via gRPC to that instance

#### Namespace-Based Routing

For multi-cluster setups:

* Check if namespace is active in current cluster
* If not, optionally forward to active cluster
* Controlled by `EnableNamespaceNotActiveAutoForwarding` config

### Health Checking

The Frontend provides gRPC health check endpoints:

* Standard gRPC health check protocol
* Returns `SERVING` when all dependencies are healthy
* Returns `NOT_SERVING` during shutdown or degraded state

```go theme={null}
// Code entrypoint: service/frontend/health_check.go
// Health check implementation
```

## API Handlers

### Workflow Service API

The primary API for workflow operations:

**Workflow Lifecycle:**

* `StartWorkflowExecution`
* `SignalWorkflowExecution`
* `SignalWithStartWorkflowExecution`
* `RequestCancelWorkflowExecution`
* `TerminateWorkflowExecution`

**Queries and Updates:**

* `QueryWorkflowExecution`
* `UpdateWorkflowExecution`
* `PollWorkflowExecutionUpdate`

**History and Metadata:**

* `GetWorkflowExecutionHistory`
* `DescribeWorkflowExecution`
* `ListOpenWorkflowExecutions`
* `ListClosedWorkflowExecutions`
* `ScanWorkflowExecutions`
* `CountWorkflowExecutions`

**Task Operations:**

* `PollWorkflowTaskQueue`
* `PollActivityTaskQueue`
* `RespondWorkflowTaskCompleted`
* `RespondActivityTaskCompleted`
* `RecordActivityTaskHeartbeat`

```go theme={null}
// Code entrypoint: service/frontend/workflow_handler.go
// Main implementation of Workflow Service API
// Over 7000 lines of handler code
```

### Operator Service API

Cluster operations and configuration:

**Search Attributes:**

* `AddSearchAttributes`
* `RemoveSearchAttributes`
* `ListSearchAttributes`

**Cluster Management:**

* `AddOrUpdateRemoteCluster`
* `RemoveRemoteCluster`
* `ListClusters`

**Nexus Endpoints:**

* `CreateNexusEndpoint`
* `UpdateNexusEndpoint`
* `DeleteNexusEndpoint`
* `ListNexusEndpoints`

```go theme={null}
// Code entrypoint: service/frontend/operator_handler.go
// Operator API implementation
```

### Admin Service API

Advanced administrative operations:

**Workflow Maintenance:**

* `DescribeMutableState`
* `GetWorkflowExecutionRawHistory`
* `ResendReplicationTasks`
* `RefreshWorkflowTasks`

**Shard Management:**

* `CloseShard`
* `GetShard`

**DLQ Operations:**

* `GetDLQMessages`
* `PurgeDLQMessages`
* `MergeDLQMessages`

**History Imports:**

* `ImportWorkflowExecution`

```go theme={null}
// Code entrypoint: service/frontend/admin_handler.go
// Admin API implementation
```

## Namespace Handling

### Namespace Registry

The Frontend maintains a cache of namespace metadata:

* Loaded from persistence on startup
* Updated via watch mechanism
* Provides fast lookup for request validation
* Handles namespace state transitions

```go theme={null}
// Code entrypoint: service/frontend/namespace_handler.go
// Namespace operations and registry management
```

### Global Namespaces

For multi-cluster deployments:

* Namespaces can be global (replicated across clusters)
* One cluster is "active" for write operations
* Frontend checks if current cluster is active
* Can auto-forward requests to active cluster

### Namespace State Machine

Namespaces have states:

* `Registered`: Normal operational state
* `Deprecated`: Marked for deletion, read-only
* `Deleted`: Namespace is removed

## HTTP APIs

### Nexus HTTP Handler

The Frontend exposes an HTTP endpoint for Nexus operations:

* Implements Nexus protocol over HTTP
* Used for cross-namespace workflow invocations
* Supports synchronous and asynchronous operations

```go theme={null}
// Code entrypoint: service/frontend/nexus_http_handler.go
// HTTP handler for Nexus protocol
```

### OpenAPI HTTP Handler

Provides OpenAPI/Swagger documentation:

* Serves OpenAPI specification
* UI for exploring APIs
* Useful for development and debugging

## Version Checking

The Frontend checks client and server version compatibility:

* Validates SDK versions are supported
* Checks worker build IDs
* Enforces minimum version requirements
* Provides upgrade recommendations

```go theme={null}
// Code entrypoint: service/frontend/version_checker.go
// Version validation logic
```

## Error Handling

The Frontend translates internal errors to gRPC status codes:

* Maps service errors to appropriate gRPC codes
* Adds error details for client consumption
* Sanitizes error messages to avoid leaking internals

```go theme={null}
// Code entrypoint: service/frontend/errors.go
// Error handling and translation
```

### Common Error Patterns

**`InvalidArgument`**: Request validation failed
**`NotFound`**: Workflow or namespace not found
**`AlreadyExists`**: Workflow ID already in use
**`FailedPrecondition`**: Namespace not active, wrong cluster
**`ResourceExhausted`**: Rate limit exceeded
**`Unavailable`**: Temporary failure, retry
**`PermissionDenied`**: Authorization failed

## Configuration

Frontend Service configuration includes:

```go theme={null}
// Code entrypoint: service/frontend/service.go
type Config struct {
    NumHistoryShards int32  // Total number of history shards
    RPS              int     // Global requests per second
    GlobalRPS        int     // Global RPS across all instances
    
    // Per-namespace limits
    MaxNamespaceRPSPerInstance int
    MaxNamespaceVisibilityRPSPerInstance int
    
    // Size limits
    BlobSizeLimitError int  // Max payload size (error)
    BlobSizeLimitWarn  int  // Max payload size (warning)
    MemoSizeLimitError int  // Max memo size
    MaxIDLengthLimit   int  // Max ID length
    
    // Feature flags
    EnableNamespaceNotActiveAutoForwarding bool
    DisableListVisibilityByFilter bool
}
```

Most configuration is **dynamic** and can be changed at runtime via dynamic configuration.

## Metrics and Observability

The Frontend emits metrics for:

* Request counts per API
* Request latency percentiles
* Error rates by error type
* Rate limiting events
* Long-poll queue depth

## Shutdown Behavior

During graceful shutdown:

1. Health check returns `NOT_SERVING`
2. Drain period allows in-flight requests to complete
3. New requests are rejected
4. gRPC server stops accepting connections

Configured via:

* `ShutdownDrainDuration`: Time to drain in-flight requests
* `ShutdownFailHealthCheckDuration`: When to fail health checks

## Further Reading

<CardGroup cols={2}>
  <Card title="History Service" icon="database" href="/architecture/history-service">
    Where Frontend routes workflow operations
  </Card>

  <Card title="Matching Service" icon="arrows-split-up-and-left" href="/architecture/matching-service">
    Where Frontend routes task operations
  </Card>

  <Card title="Architecture Overview" icon="sitemap" href="/architecture/overview">
    High-level system architecture
  </Card>

  <Card title="Workflow Lifecycle" icon="diagram-project" href="/architecture/workflow-lifecycle">
    How requests flow through services
  </Card>
</CardGroup>