# ardatan/graphql-mesh architecture

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

- Interactive diagram: https://gitdiagram.com/ardatan/graphql-mesh
- Repository: https://github.com/ardatan/graphql-mesh

## Overview

##### Main Components
- CLI & Config Loader (packages/compose-cli, legacy CLI)
- Core Engine (packages/fusion/composition + cross-helpers + utils)
- Schema Loaders (packages/loaders/*)
- Transforms & Plugins (packages/fusion/composition/src/transforms and packages/plugins/*)
- Transports / Source Handlers (packages/transports/* and legacy/handlers/*)
- Cache Adapters (packages/cache/*)
- Data Sources (external GraphQL services, REST/OpenAPI, gRPC, SOAP, databases like MySQL/SQLite/Neo4j)
- Website / Docs (website/)
- E2E & Example Projects (e2e/, examples/)

##### Relationships & Data Flow
1) Developer invokes `graphql-mesh` CLI → reads `.meshrc.yml` or programmatic config.
2) CLI/compose-cli loads configuration schemas (declarations.d.ts, config-schema).
3) Core Engine calls each Schema Loader:
– Loaders parse API spec (OpenAPI, JSON Schema, OData, etc.) and produce GraphQL type definitions.
– Loaders may use Transports to fetch remote schemas or data (e.g., HTTP, gRPC, SOAP, SQL drivers).
4) Loaded schemas enter the Transform pipeline:
– Namespace/prune/hoist/prefix/federation transforms (packages/fusion).
– Plugin hooks apply execution-time behavior (caching, rate-limit, mock, live queries, metrics).
5) Fusion/composition merges all sub-schemas into a single unified GraphQL schema or a Federation supergraph.
6) Mesh spins up a GraphQL server endpoint:
– Incoming GraphQL queries hit the execution layer.
– Each field resolver uses Transports + Cache + Plugin pipeline to fetch from underlying Data Sources.
7) Results return to client.

##### Architectural Patterns & Principles
- Plugin-Based Pipeline: Loaders, Transforms, Plugins, Transports are independent packages.
- Monorepo/Yarn Workspaces: Each package is versioned/co-developed centrally.
- Composition Pipeline: Clear separation between schema-generation (static) and query execution (dynamic).
- DI/Extensibility: New handlers or plugins drop into `packages/loaders`, `packages/plugins`, or `packages/transports`.

##### Key Technologies
- Node.js + TypeScript
- Yarn v4 Workspaces / PnP
- Jest for unit & e2e tests
- Next.js for the website (static-generated docs)
- GitHub Actions for CI/CD, Docker for containerization

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer
    Dev["Developer"]:::external

    %% CLI Layer
    subgraph "CLI & Config Loader"
        direction TB
        ComposeCLI["Compose CLI"]:::core
        LegacyCLI["Legacy CLI"]:::core
    end

    %% Core Engine
    CoreEngine["Core Engine\npackages/fusion/composition"]:::core

    %% Schema Loaders
    SchemaLoaders["Schema Loaders\npackages/loaders/*"]:::loaders

    %% Transforms & Plugins
    Transforms["Transforms\npackages/fusion/composition/src/transforms"]:::transforms
    Plugins["Plugins\npackages/plugins/*"]:::transforms

    %% Composition
    Composition["Composition Pipeline\nfusion/composition"]:::core

    %% Execution Server
    Server["GraphQL Server\nExecution Layer"]:::core

    %% Cache Adapters
    Cache["Cache Adapters\npackages/cache/*"]:::cache

    %% Transports / Source Handlers
    Transports["Transports / Handlers\npackages/transports/*"]:::loaders

    %% Data Sources
    subgraph "External Data Sources"
        direction TB
        HTTPAPI["HTTP APIs (REST/OpenAPI)"]:::data
        GraphQLAPI["GraphQL Services"]:::data
        gRPCService["gRPC Services"]:::data
        SOAPService["SOAP Services"]:::data
        Databases["Databases\nMySQL/SQLite/Neo4j"]:::data
    end

    %% Website & Examples
    Website["Website & Docs\nwebsite/"]:::website
    Examples["Examples & E2E\nexamples/ & e2e/"]:::website

    %% Relationships
    Dev -->|"invoke graphql-mesh CLI"| ComposeCLI
    Dev -->|"invoke legacy CLI"| LegacyCLI
    ComposeCLI -->|"loads config"| CoreEngine
    LegacyCLI -->|"loads config"| CoreEngine
    CoreEngine -->|"calls"| SchemaLoaders
    SchemaLoaders -->|"produces schema"| Transforms
    Transforms -->|"applies plugins"| Plugins
    Plugins -->|"feeds into"| Composition
    Composition -->|"builds unified schema"| Server
    Server -->|"executes query"| Transports
    Server -->|"uses cache"| Cache
    Transports -->|"fetches data"| HTTPAPI
    Transports -->|"fetches data"| GraphQLAPI
    Transports -->|"fetches data"| gRPCService
    Transports -->|"fetches data"| SOAPService
    Transports -->|"fetches data"| Databases
    Dev -->|"views docs"| Website
    Dev -->|"runs examples/e2e"| Examples

    %% Click Events
    click ComposeCLI "https://github.com/ardatan/graphql-mesh/tree/master/packages/compose-cli/"
    click LegacyCLI "https://github.com/ardatan/graphql-mesh/tree/master/packages/legacy/cli/"
    click CoreEngine "https://github.com/ardatan/graphql-mesh/tree/master/packages/fusion/composition/"
    click SchemaLoaders "https://github.com/ardatan/graphql-mesh/tree/master/packages/loaders/openapi/"
    click Transforms "https://github.com/ardatan/graphql-mesh/tree/master/packages/fusion/composition/src/transforms/"
    click Plugins "https://github.com/ardatan/graphql-mesh/tree/master/packages/plugins/http-cache/"
    click Transports "https://github.com/ardatan/graphql-mesh/tree/master/packages/transports/rest/"
    click Cache "https://github.com/ardatan/graphql-mesh/tree/master/packages/cache/redis/"
    click Website "https://github.com/ardatan/graphql-mesh/tree/master/website/"
    click Examples "https://github.com/ardatan/graphql-mesh/tree/master/examples/"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef loaders fill:#90EE90,stroke:#333,stroke-width:1px
    classDef transforms fill:#FFA500,stroke:#333,stroke-width:1px
    classDef data fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef cache fill:#D8BFD8,stroke:#333,stroke-width:1px
    classDef website fill:#FFFFE0,stroke:#333,stroke-width:1px
    classDef external fill:#FFFFFF,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
