# temporalio/sdk-typescript architecture

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

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

## Overview

##### Project Identification and Purpose
- This is a monorepo for the Temporal TypeScript SDK. Its purpose is to provide a comprehensive framework (SDK) for writing durable, fault‑tolerant workflows and activities in TypeScript/JavaScript.
- The README makes clear that it supports complex workflow execution and contains multiple packages (client, worker, workflow, etc.) which together interface with the Temporal backend.

##### Analyzing the File Structure
- The repository is organized into many top‑level directories. Key folders include:
– packages/client: Implements the client APIs to communicate with a Temporal server.
– packages/worker: Contains the workflow worker implementation, including logic to process and manage workflows and activities.
– packages/workflow: Provides APIs and runtime components to define workflows.
– packages/activity: Contains the code for workflow activities.
– packages/common: Shared utilities that are leveraged across other packages.
– packages/proto: Houses protocol buffer (protobuf) definitions and scripts to compile them.
– packages/testing: Contains the SDK’s internal tests to simulate workflows, client interactions, and worker behavior.
– Additional packages (e.g., create-project, docs, interceptors-opentelemetry, meta) provide scaffolding, documentation, or integration points.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core SDK Modules
    subgraph "Core SDK Modules"
        CLIENT("Client API"):::sdk
        WORKER("Worker Runtime"):::sdk
        WORKFLOW("Workflow Engine"):::sdk
        ACTIVITY("Activity Handler"):::sdk
    end

    %% Shared Libraries
    subgraph "Shared Libraries"
        COMMON("Common Libs"):::shared
        PROTO("Proto Definitions"):::shared
    end

    %% Integrations & Extensions
    subgraph "Integrations & Extensions"
        CORE("Core Bridge"):::integrations
        OBS("Observability Interceptors"):::integrations
        SCAFFOLD("Project Scaffold"):::integrations
        DOCS("Documentation"):::integrations
        META("Meta Helpers"):::integrations
    end

    %% External System
    TEMP("Temporal Server"):::external

    %% Testing
    TEST("Testing Suite"):::testing

    %% Connections between Core SDK Modules
    CLIENT -->|"calls"| WORKER
    WORKER -->|"executes"| WORKFLOW
    WORKER -->|"executes"| ACTIVITY
    CLIENT -->|"communicates"| TEMP

    %% Connections to Shared Libraries
    CLIENT -->|"uses"| COMMON
    WORKER -->|"uses"| COMMON
    WORKFLOW -->|"uses"| COMMON
    ACTIVITY -->|"uses"| COMMON

    CLIENT -->|"uses"| PROTO
    WORKER -->|"uses"| PROTO
    WORKFLOW -->|"uses"| PROTO
    ACTIVITY -->|"uses"| PROTO

    %% Integrations with Core SDK Modules
    WORKER -->|"integrates"| CORE
    WORKER -->|"observed-by"| OBS

    SCAFFOLD -->|"bootstraps"| CLIENT
    DOCS ---|"documents"| CLIENT
    DOCS ---|"documents"| WORKER
    DOCS ---|"documents"| WORKFLOW
    DOCS ---|"documents"| ACTIVITY
    META -->|"assists"| WORKER

    %% Testing Relationships
    TEST -->|"tests"| CLIENT
    TEST -->|"tests"| WORKER
    TEST -->|"tests"| WORKFLOW
    TEST -->|"tests"| ACTIVITY

    %% Styles
    classDef sdk fill:#D1E8FF,stroke:#1F78B4,stroke-width:2px;
    classDef shared fill:#FEEBAB,stroke:#D95F02,stroke-width:2px;
    classDef integrations fill:#C7F9CC,stroke:#33A02C,stroke-width:2px;
    classDef external fill:#FFD1DC,stroke:#E31A1C,stroke-width:2px;
    classDef testing fill:#E6FFED,stroke:#33A02C,stroke-width:2px;

    %% Click Events
    click CLIENT "https://github.com/temporalio/sdk-typescript/tree/main/packages/client"
    click WORKER "https://github.com/temporalio/sdk-typescript/tree/main/packages/worker"
    click WORKFLOW "https://github.com/temporalio/sdk-typescript/tree/main/packages/workflow"
    click ACTIVITY "https://github.com/temporalio/sdk-typescript/tree/main/packages/activity"
    click COMMON "https://github.com/temporalio/sdk-typescript/tree/main/packages/common"
    click PROTO "https://github.com/temporalio/sdk-typescript/tree/main/packages/proto"
    click TEST "https://github.com/temporalio/sdk-typescript/tree/main/packages/testing"
    click CORE "https://github.com/temporalio/sdk-typescript/tree/main/packages/core-bridge"
    click OBS "https://github.com/temporalio/sdk-typescript/tree/main/packages/interceptors-opentelemetry"
    click SCAFFOLD "https://github.com/temporalio/sdk-typescript/tree/main/packages/create-project"
    click DOCS "https://github.com/temporalio/sdk-typescript/tree/main/packages/docs"
    click META "https://github.com/temporalio/sdk-typescript/tree/main/packages/meta"
```
