# tailcallhq/tailcall architecture

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

- Interactive diagram: https://gitdiagram.com/tailcallhq/tailcall
- Repository: https://github.com/tailcallhq/tailcall

## Overview

This project is an open‐source, high–performance GraphQL backend engine (named Tailcall) that lets you build a GraphQL server where both the schema definition and the query resolution logic—including instructions on how to call HTTP/GRPC endpoints—are embedded into a single file. In short, the project is designed to parse enhanced GraphQL schema files carrying directives (like @server, @http, @upstream, etc.), then compile and execute them by orchestrating calls to external data sources.

##### Main Architectural Components
- Core Engine: This is the heart of the system and includes modules covering parsing, blueprint processing, resolution, and schema generation. It sits in the “src” directory with lots of subcomponents such as the CLI, generator, JIT compiler, configuration management, caching, directive processing, and upstream integrations.
- CLI and Runtime Interfaces: The “src/cli” subtree provides command definitions, runtime support, and various executors for starting up servers (HTTP/GRPC) or running tests.
- External Connectors: Components targeted for HTTP (REST), GRPC, and even AWS Lambda, Cloudflare, Wasm edge deployments (as seen in directories like tailcall-aws-lambda, tailcall-cloudflare, tailcall-wasm) represent the project’s flexibility in deployment.
- Data Loader & Caching Modules: These are responsible for batching calls, deduplication of requests, and managing cached results.
- Configuration & Blueprint Setup: The project contains a complex configuration system (e.g., under src/core/config) that ingests GraphQL configuration files, transforms them via “blueprint” and “transformer” modules.
- JIT Compilation: There’s a JIT module (src/core/jit) that builds and executes query plans in a performant manner.
- Testing & Benchmarks: The project integrates extensive tests and benchmarking (located in tests/ and benches/) to ensure high performance.

##### Relationships and Data Flows
- From the CLI, illustrate the path into the Core Engine’s parser and blueprint modules which process the GraphQL schema file (with extra directives) into an internal configuration or IR.
- Next, display branches that lead from the IR into various submodules: the HTTP resolver (which makes HTTP calls to external endpoints), GRPC resolver modules, and data loaders that manage caching and batching.
- JIT compilation module acting on the IR to build an optimized execution pathway.

##### Patterns and Design Principles
- Modular and Layered Architecture: Identify separations between configuration processing, query compilation, network connectors, caching, and external integrations.
- Extensibility/Plug-in Design: Make note of the “directives” that allow injection of various resolution strategies (HTTP, GRPC, etc.), as well as the distinct deployment modules for serverless environments.
- Performance Optimizations: Emphasize components such as the Data Loader, caching modules, and the JIT compiler, which together ensure high throughput (as demonstrated by benchmarks in the README).

##### Specific Technologies and Frameworks
- Programming Language: Rust (evident from Cargo.toml files and Rust modules).
- Deployment environments: AWS Lambda, Cloudflare, WASM (as seen in dedicated directories).
- That the GraphQL-specific transformation, directive handling, and blueprint layers are central to tailoring queries and handling compositions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI & Runtime Layer
    CLI["CLI & Runtime Interfaces"]:::cliStyle

    %% Core Engine Layer
    Engine["GraphQL Engine (Core)"]:::coreStyle
    Config["Configuration Setup"]:::coreStyle
    Blueprint["Blueprint Setup"]:::coreStyle
    Parser["Parser"]:::coreStyle
    IR["Intermediate Representation (IR)"]:::coreStyle
    JIT["JIT Compiler"]:::coreStyle
    Resolver["Resolver Module"]:::coreStyle
    DataLoader["Data Loader"]:::coreStyle
    Cache["Caching Module"]:::coreStyle
    HTTPCache["HTTP Cache"]:::coreStyle
    CacheAgg["Cache Aggregation"]:::coreStyle
    Exec["Execution Engine"]:::coreStyle
    Server["GraphQL Server (HTTP/GRPC)"]:::coreStyle

    %% External Connectors
    AWS["AWS Lambda"]:::externalStyle
    Cloudflare["Cloudflare"]:::externalStyle
    WASM["WASM Edge"]:::externalStyle
    GRPC["GRPC Upstream"]:::externalStyle

    %% Testing & Benchmarks
    Tests["Testing Suite"]:::testStyle
    Benches["Benchmarks"]:::testStyle

    %% Data Flow
    CLI --> Engine
    Engine --> Config
    Config --> Blueprint
    Blueprint --> Parser
    Parser --> IR

    %% Branching from IR
    IR --> JIT
    IR --> Resolver

    %% Resolver branch with DataLoader and Caching modules
    Resolver --> DataLoader
    DataLoader --> Cache
    DataLoader --> HTTPCache
    Cache --> CacheAgg
    HTTPCache --> CacheAgg

    %% Merge branches into Execution Engine
    JIT --> Exec
    CacheAgg --> Exec

    %% Execution to Server
    Exec --> Server

    %% Server calls External Connectors
    Server -->|"HTTP/GRPCcalls"| AWS
    Server -->|"HTTP/GRPCcalls"| Cloudflare
    Server -->|"HTTP/GRPCcalls"| WASM
    Server -->|"HTTP/GRPCcalls"| GRPC

    %% Testing and Benchmarks link from Core Engine
    Engine --> Tests
    Engine --> Benches

    %% Click events
    click CLI "https://github.com/tailcallhq/tailcall/tree/main/src/cli"
    click Engine "https://github.com/tailcallhq/tailcall/tree/main/src/core"
    click Config "https://github.com/tailcallhq/tailcall/tree/main/src/core/config"
    click Blueprint "https://github.com/tailcallhq/tailcall/tree/main/src/core/blueprint"
    click JIT "https://github.com/tailcallhq/tailcall/tree/main/src/core/jit"
    click DataLoader "https://github.com/tailcallhq/tailcall/tree/main/src/core/data_loader"
    click Cache "https://github.com/tailcallhq/tailcall/tree/main/src/core/cache"
    click HTTPCache "https://github.com/tailcallhq/tailcall/tree/main/tailcall-http-cache"
    click AWS "https://github.com/tailcallhq/tailcall/tree/main/tailcall-aws-lambda"
    click Cloudflare "https://github.com/tailcallhq/tailcall/tree/main/tailcall-cloudflare"
    click WASM "https://github.com/tailcallhq/tailcall/tree/main/tailcall-wasm"
    click GRPC "https://github.com/tailcallhq/tailcall/tree/main/tailcall-upstream-grpc"
    click Tests "https://github.com/tailcallhq/tailcall/tree/main/tests/"
    click Benches "https://github.com/tailcallhq/tailcall/tree/main/benches/"

    %% Styles
    classDef cliStyle fill:#AEDFF7,stroke:#333,stroke-width:2px;
    classDef coreStyle fill:#CFF7C7,stroke:#333,stroke-width:2px;
    classDef externalStyle fill:#F7D6AE,stroke:#333,stroke-width:2px;
    classDef testStyle fill:#F7AEDF,stroke:#333,stroke-width:2px;
```
