# hayes/pothos architecture

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

- Interactive diagram: https://gitdiagram.com/hayes/pothos
- Repository: https://github.com/hayes/pothos

## Overview

##### Project type and purpose
- This is a monorepo for a TypeScript‐based GraphQL schema builder library (“Pothos”) and its plugin ecosystem.
- It contains:
– The core schema builder package (@pothos/core)
– A “converter” CLI tool
– ~30 first-class plugins (add-graphql, complexity, dataloader, prisma, relay, etc.)
– Deno-compatible mirrors of core/plugins in `packages/deno`
– Test utilities and example apps under `examples/`
– A NextJS‐based documentation website under `website/`
– Build/config scripts, CI workflows, and a Changesets‐powered release pipeline

##### File structure
- Top‐level config: `pnpm-workspace.yaml`, `turbo.json`, `.github/workflows/*`, `changeset` folder.
- `packages/`: each subfolder is an NPM package, sharing `tsconfig.json`, `src/`, optional `tests/`, `esm/`, and build outputs.
- `examples/`: dozens of sample GraphQL servers (Prisma, Fastify, Federation, NextJS, etc.) consuming the library.
- `website/`: NextJS app pulling in the packages (probably via a local workspace link) to generate docs.
- CI files orchestrate lint, build, test, docs deploy, and package publishing via Changesets and Turborepo pipeline.

##### Key README insights
- Pothos is purely a “schema‐builder” with zero runtime overhead beyond `graphql-js`.
- Plugin system: each plugin augments core’s builder API.
- No codegen is required; types flow directly via TypeScript inference.
- Wide plugin ecosystem for auth, complexity, directives, Prisma, Relay, mocks, subscriptions, tracing, etc.

a. Main components:
– **Monorepo Root**
- Workspace config, CI (GitHub Actions), Changesets, Turborepo
– **Core Package** (@pothos/core)
– **Converter CLI** (packages/converter)
– **Plugin Packages**
- E.g. plugin‐add‐graphql, plugin‐prisma, plugin‐dataloader, plugin‐complexity, plugin‐relay, …
- Deno mirrors under `packages/deno` group
– **Test‐Utils** (shared test server creation)
– **Examples** (example GraphQL servers showing library usage)
– **Website** (NextJS app for docs)
b. Relationships and data flows:
- Converter depends on core (to transform Pothos schemas into some target).
- Plugins also sometimes depend on each other (e.g., plugin-prisma-utils → plugin-prisma).
- Examples import core + relevant plugins to construct working GraphQL servers.
- Website imports core + plugin packages for live code samples and API docs.
- CI flow: changes in any package trigger Turborepo tasks (build, test), Changesets generate release plans, and GitHub Actions publishes updated packages to npm.
c. Architectural patterns/design principles:
- **Monorepo + Turborepo** for orchestrated builds and test caching
- **Plugin‐based architecture**: core provides an extensible schema builder; plugins register “hooks” into the builder API
- **Workspace linking**: local development runs cross‐package references without republishing
- **Dual builds** (ESM under `esm/`, types under `.d.ts`)
- **Zero runtime overhead** beyond the official GraphQL library
d. Relevant technologies:
- TypeScript, pnpm workspaces, Turborepo, GraphQL, graphql-yoga, NextJS, Deno support, Prisma, Fastify, NestJS, OpenTelemetry

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Monorepo Root"
        MR["Monorepo Root"]:::infra
        CI["GitHub Actions CI"]:::infra
        TR["Turborepo"]:::infra
        CS["Changesets"]:::infra
    end
    MR --> CI
    MR --> TR
    MR --> CS

    subgraph "Library Packages"
        Core["@pothos/core"]:::lib
        Conv[/Converter CLI/]:::lib
        PU1["Test Utilities"]:::lib
        subgraph "Plugins"
            PG["plugin-add-graphql"]:::lib
            PC["plugin-complexity"]:::lib
            PD["plugin-dataloader"]:::lib
            PDir["plugin-directives"]:::lib
            PErr["plugin-errors"]:::lib
            PM["plugin-mocks"]:::lib
            PPr["plugin-prisma"]:::lib
            PPrU["plugin-prisma-utils"]:::lib
            PR["plugin-relay"]:::lib
            PSA["plugin-scope-auth"]:::lib
            PSO["plugin-simple-objects"]:::lib
            PSS["plugin-smart-subscriptions"]:::lib
            PSG["plugin-sub-graph"]:::lib
            PTNR["tracing-newrelic"]:::lib
            PTO["tracing-opentelemetry"]:::lib
            PTS["tracing-sentry"]:::lib
            PTX["tracing-xray"]:::lib
            PWI["plugin-with-input"]:::lib
            PDr["plugin-drizzle"]:::lib
            PF["plugin-federation"]:::lib
            PEX["plugin-example"]:::lib
        end
        subgraph "Deno Mirrors"
            DNCore["deno/core"]:::lib
            DNPG["deno/plugin-add-graphql"]:::lib
            DNPC["deno/plugin-complexity"]:::lib
            DNPD["deno/plugin-dataloader"]:::lib
            DNDir["deno/plugin-directives"]:::lib
            DNErr["deno/plugin-errors"]:::lib
            DNM["deno/plugin-mocks"]:::lib
            DNPR["deno/plugin-relay"]:::lib
            DNSA["deno/plugin-scope-auth"]:::lib
            DNSO["deno/plugin-simple-objects"]:::lib
            DNSS["deno/plugin-smart-subscriptions"]:::lib
            DNSG["deno/plugin-sub-graph"]:::lib
            DNTR["deno/plugin-tracing"]:::lib
            DNWI["deno/plugin-with-input"]:::lib
            DNZ["deno/plugin-zod"]:::lib
        end
    end

    subgraph "Consumers"
        EX["Examples"]:::consumer
        WS["Website (NextJS)"]:::consumer
    end

    Conv -->|"depends on"| Core
    PG --> Core
    PC --> Core
    PD --> Core
    PDir --> Core
    PErr --> Core
    PM --> Core
    PPr --> Core
    PPrU --> PPr
    PR --> Core
    PSA --> Core
    PSO --> Core
    PSS --> Core
    PSG --> Core
    PTNR --> Core
    PTO --> Core
    PTS --> Core
    PTX --> Core
    PWI --> Core
    PDr --> Core
    PF --> Core
    PEX --> Core
    DNCore --> Core
    DNPG --> PG
    DNPC --> PC
    DNPD --> PD
    DNDir --> PDir
    DNErr --> PErr
    DNM --> PM
    DNPR --> PR
    DNSA --> PSA
    DNSO --> PSO
    DNSS --> PSS
    DNSG --> PSG
    DNTR --> PTNR
    DNTR --> PTO
    DNTR --> PTS
    DNTR --> PTX
    DNWI --> PWI
    DNZ --> PEX
    PU1 --> Core

    EX --> Core
    EX --> PG
    EX --> PC
    EX --> PD
    EX --> PPr
    EX --> PR
    EX --> PF
    EX --> PDir
    WS --> Core
    WS --> PG
    WS --> PC
    WS --> PD
    WS --> PPr
    WS --> PR

    CI -->|"triggers build/test"| Core
    CI --> Core
    CI --> PG
    CI --> PC
    CI --> PD
    CI --> PPr
    CI --> PR
    CI --> Conv
    CI --> PU1
    CI --> EX
    CI --> WS

    click MR "https://github.com/hayes/pothos/blob/main/pnpm-workspace.yaml"
    click MR "https://github.com/hayes/pothos/blob/main/turbo.json"
    click CI "https://github.com/hayes/pothos/tree/main/.github/workflows/"
    click CS "https://github.com/hayes/pothos/tree/main/.changeset/"
    click Core "https://github.com/hayes/pothos/tree/main/packages/core/"
    click Conv "https://github.com/hayes/pothos/tree/main/packages/converter/"
    click Conv "https://github.com/hayes/pothos/blob/main/packages/converter/src/cli.ts"
    click Conv "https://github.com/hayes/pothos/blob/main/packages/converter/src/index.ts"
    click PU1 "https://github.com/hayes/pothos/blob/main/packages/test-utils/src/create-server.ts"
    click PG "https://github.com/hayes/pothos/tree/main/packages/plugin-add-graphql/"
    click PC "https://github.com/hayes/pothos/tree/main/packages/plugin-complexity/"
    click PD "https://github.com/hayes/pothos/tree/main/packages/plugin-dataloader/"
    click PDir "https://github.com/hayes/pothos/tree/main/packages/plugin-directives/"
    click PErr "https://github.com/hayes/pothos/tree/main/packages/plugin-errors/"
    click PM "https://github.com/hayes/pothos/tree/main/packages/plugin-mocks/"
    click PPr "https://github.com/hayes/pothos/tree/main/packages/plugin-prisma/"
    click PPrU "https://github.com/hayes/pothos/tree/main/packages/plugin-prisma-utils/"
    click PR "https://github.com/hayes/pothos/tree/main/packages/plugin-relay/"
    click PSA "https://github.com/hayes/pothos/tree/main/packages/plugin-scope-auth/"
    click PSO "https://github.com/hayes/pothos/tree/main/packages/plugin-simple-objects/"
    click PSS "https://github.com/hayes/pothos/tree/main/packages/plugin-smart-subscriptions/"
    click PSG "https://github.com/hayes/pothos/tree/main/packages/plugin-sub-graph/"
    click PTNR "https://github.com/hayes/pothos/tree/main/packages/tracing-newrelic/"
    click PTO "https://github.com/hayes/pothos/tree/main/packages/tracing-opentelemetry/"
    click PTS "https://github.com/hayes/pothos/tree/main/packages/tracing-sentry/"
    click PTX "https://github.com/hayes/pothos/tree/main/packages/tracing-xray/"
    click PWI "https://github.com/hayes/pothos/tree/main/packages/plugin-with-input/"
    click PDr "https://github.com/hayes/pothos/tree/main/packages/plugin-drizzle/"
    click PF "https://github.com/hayes/pothos/tree/main/packages/plugin-federation/"
    click PEX "https://github.com/hayes/pothos/tree/main/packages/plugin-example/"
    click DNCore "https://github.com/hayes/pothos/tree/main/packages/deno/packages/core/"
    click DNPG "https://github.com/hayes/pothos/tree/main/packages/deno/packages/plugin-add-graphql/"
    click DNPC "https://github.com/hayes/pothos/tree/main/packages/deno/packages/plugin-complexity/"
    click DNPD "https://github.com/hayes/pothos/tree/main/packages/deno/packages/plugin-dataloader/"
    click DNDir "https://github.com/hayes/pothos/tree/main/packages/deno/packages/plugin-directives/"
    click DNErr "https://github.com/hayes/pothos/tree/main/packages/deno/packages/plugin-errors/"
    click DNM "https://github.com/hayes/pothos/tree/main/packages/deno/packages/plugin-mocks/"
    click DNPR "https://github.com/hayes/pothos/tree/main/packages/deno/packages/plugin-relay/"
    click DNSA "https://github.com/hayes/pothos/tree/main/packages/deno/packages/plugin-scope-auth/"
    click DNSO "https://github.com/hayes/pothos/tree/main/packages/deno/packages/plugin-simple-objects/"
    click DNSS "https://github.com/hayes/pothos/tree/main/packages/deno/packages/plugin-smart-subscriptions/"
    click DNSG "https://github.com/hayes/pothos/tree/main/packages/deno/packages/plugin-sub-graph/"
    click DNTR "https://github.com/hayes/pothos/tree/main/packages/deno/packages/plugin-tracing/"
    click DNWI "https://github.com/hayes/pothos/tree/main/packages/deno/packages/plugin-with-input/"
    click DNZ "https://github.com/hayes/pothos/tree/main/packages/deno/packages/plugin-zod/"
    click EX "https://github.com/hayes/pothos/tree/main/examples/"
    click WS "https://github.com/hayes/pothos/tree/main/website/"

    classDef lib fill:#D0E6FF,stroke:#0366D6,color:#0366D6
    classDef consumer fill:#DFFFE0,stroke:#0A8700,color:#0A8700
    classDef infra fill:#FFE4B2,stroke:#FF8C00,color:#FF8C00
```
