# alibaba/transmittable-thread-local architecture

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

- Interactive diagram: https://gitdiagram.com/alibaba/transmittable-thread-local
- Repository: https://github.com/alibaba/transmittable-thread-local

## Overview

##### Project Type and Purpose
- This is an open-source library that provides “transmittable” ThreadLocal context for asynchronous execution. Its key purpose is to capture and propagate ThreadLocal values from when a task is submitted (for example, to a thread pool) to when it is executed.
- It handles both manual wrapping (via TtlRunnable, TtlCallable, and executor wrappers) and transparent enhancement using a Java Agent (instrumenting JDK ThreadPoolExecutor, ForkJoinTask, TimerTask, etc.).

##### File Structure
- The repository is organized into several Maven modules. Key top-level directories include:
- “ttl-core”: Holds the primary API implementation (e.g. TransmittableThreadLocal, wrapper classes, executor wrappers, SPI interfaces, and utility classes).
- “ttl-agent”: Contains the Java Agent implementation that transforms JDK classes at load time (for example, classes in the agent package and transformlet subpackages).
- “ttl-bom”: Provides a Maven bill of materials for dependency management.
- “ttl-integrations”: Includes sample integration projects (for agent extension transformlets and integrations for Vert.x 3/4).
- “ttl-kotlin”: The Kotlin adaptation of the library.
- “ttl2-compatible”: A module ensuring compatibility with TTL v2 interfaces.
- There are also various supporting files like Maven wrappers (mvnw, mvnw.cmd), GitHub workflow configurations, and documentation files (docs/ folder).

##### Architectural Patterns and Design Principles
- The design separates concerns. The cross-cutting concern of context propagation is encapsulated in the TTL API and its wrappers.
- The Java Agent module applies aspect-oriented principles by instrumenting JDK classes transparently.
- The modular Maven structure uses a multi-module design that decouples the core functionality from integrations and compatibility adaptations.

##### Putting It All Together
- Parallel to that, show a “Java Agent” block with sub-components (TtlAgent, TtlTransformer, individual transformlets) that intercept JDK thread pool classes.
- Sample/integration modules in a separate section that shows “Integration: Vert.x, Agent Extension Samples, etc.” interacting with both the core and the agent.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Nodes
    Client["Application / Client"]:::client

    %% Core Modules
    subgraph "Core Modules"
        A["TTL API/Core"]:::core
        B["Executor Wrappers"]:::core
    end

    %% Agent Module with Subcomponents
    subgraph "Agent Module"
        C["TTL Agent<br/>(Bytecode transformation)"]:::agent
        D["TtlAgent"]:::agent
        E["TtlTransformer"]:::agent
        F["Transformlets"]:::agent
    end

    %% JDK Concurrency Components
    subgraph "JDK Concurrency"
        G["ThreadPoolExecutor"]:::agent
        H["ForkJoinPool"]:::agent
        I["TimerTask"]:::agent
    end

    %% Integration Modules
    subgraph "Integrations"
        J["Agent Extension Sample"]:::integration
        K["Vert.x3 Integration"]:::integration
        L["Vert.x4 Integration"]:::integration
    end

    %% Compatibility & Bindings
    subgraph "Compatibility & Bindings"
        M["TTL Kotlin"]:::compat
        N["TTL2 Compatible"]:::compat
    end

    %% Support Modules
    subgraph "Support"
        O["Build & BOM"]:::build
        P["Documentation & Testing"]:::build
    end

    %% Connections
    Client -->|"submitsTask"| A
    A -->|"wrapsRunnable/Callable"| B

    A -->|"triggersContextPropagation"| C
    C -->|"executes:"| D
    C -->|"executes:"| E
    C -->|"executes:"| F

    C -->|"instruments"| G
    C -->|"instruments"| H
    C -->|"instruments"| I

    A ---|"demoIntegration"| J
    C ---|"demoIntegration"| J
    A ---|"demoIntegration"| K
    C ---|"demoIntegration"| K
    A ---|"demoIntegration"| L
    C ---|"demoIntegration"| L

    A -->|"alternativeView"| M
    A -->|"alternativeView"| N

    O ---|"buildManagement"| A
    O ---|"buildManagement"| C
    P ---|"usageGuides"| A

    %% Click Events
    click A "https://github.com/alibaba/transmittable-thread-local/tree/master/ttl-core/src/main/java/com/alibaba/ttl3"
    click B "https://github.com/alibaba/transmittable-thread-local/tree/master/ttl-core/src/main/java/com/alibaba/ttl3"
    click C "https://github.com/alibaba/transmittable-thread-local/tree/master/ttl-agent/src/main/java/com/alibaba/ttl3/agent"
    click J "https://github.com/alibaba/transmittable-thread-local/tree/master/ttl-integrations/sample-ttl-agent-extension-transformlet"
    click K "https://github.com/alibaba/transmittable-thread-local/tree/master/ttl-integrations/vertx3-ttl-integration"
    click L "https://github.com/alibaba/transmittable-thread-local/tree/master/ttl-integrations/vertx4-ttl-integration"
    click M "https://github.com/alibaba/transmittable-thread-local/tree/master/ttl-kotlin/src/main/kotlin/com/alibaba/ttl3/kotlin"
    click N "https://github.com/alibaba/transmittable-thread-local/tree/master/ttl2-compatible/src/main/java/com/alibaba/ttl"
    click O "https://github.com/alibaba/transmittable-thread-local/tree/master/ttl-bom"
    click P "https://github.com/alibaba/transmittable-thread-local/tree/master/docs"

    %% Style Definitions
    classDef client fill:#ccf,stroke:#333,stroke-width:2px;
    classDef core fill:#b3e6ff,stroke:#333,stroke-width:2px;
    classDef agent fill:#ffdb99,stroke:#333,stroke-width:2px;
    classDef integration fill:#ffccc9,stroke:#333,stroke-width:2px;
    classDef compat fill:#d2f8d2,stroke:#333,stroke-width:2px;
    classDef build fill:#e6ccff,stroke:#333,stroke-width:2px;
```
