# replit/graphql-codegen-persisted-queries architecture

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

- Interactive diagram: https://gitdiagram.com/replit/graphql-codegen-persisted-queries
- Repository: https://github.com/replit/graphql-codegen-persisted-queries

## Overview

The project is a GraphQL Codegen plugin that generates persisted query manifests. Its purpose is to work as part of the GraphQL Codegen ecosystem—collecting GraphQL operations from your codebase, adding necessary selection set modifications (e.g., inserting __typename), resolving nested fragments, generating hashes for each operation, and finally producing a manifest (in either a client or server format) with the generated persisted queries.

##### Main Components and Their Roles
- GraphQL Codegen CLI Integration:
- This plugin is integrated into the GraphQL Codegen workflow (configured via YAML or TypeScript config files in the README). Represent it as an “Integrator” that accepts configurations and GraphQL documents from a user’s project.

- Document Collector & Preprocessor:

- Fragment Resolver:
- A dedicated component (as evidenced by functions in the utils, e.g., fragments.ts) that recursively gathers and resolves fragments for each operation.

- Operation Sorter:
- Before generating hashes, the plugin orders operations (operations definitions come before fragments) to ensure a consistent hashing process.

- Hash Generator:
- This part (located in src/utils/hashing.ts) implements the logic to generate document hashes (default algorithm is sha256). It supports an option for prefixing these hashes based on configuration (includeAlgorithmPrefix).

- Manifest Generator:
- Two distinct output flows exist based on configuration – one generates a simple mapping for clients and one generates a detailed object for servers (as seen in the README examples).

- Plugin Core:
- This is the core logic of the plugin (implemented in src/core including generator.ts, plugin.ts, and index.ts) that orchestrates the entire process.

- Configuration & Types:
- The src/types and overall configuration files (tsconfig.json, codegen.yml/ts with config) feed into the plugin’s settings.
- As an underpinning “Configuration Module” that feeds parameters such as output type, hash algorithm, etc.

##### Relationships and Data Flow
- Then link to a “Fragment Resolver” that ensures nested fragments are fully gathered.
- One branching into the “Hash Generator”, which handles the actual hash computation.
- Then from the “Hash Generator” branch, feed the result into the “Manifest Generator”.
- The “Manifest Generator” outputs a JSON file following either the “client” or “server” format based on configuration settings.
- External interactions showing that end users or systems (frontend or GraphQL servers) consume these manifests.

##### Architectural Patterns and Design Principles
- Modular Design:
- The separation of concerns is clear (e.g., collection, preprocessing, hashing, manifest generation), which is an excellent example of modular design.
- Plug-in Architecture:
- That the core plugin integrates seamlessly with the GraphQL Codegen CLI, meaning it plays a role in a larger ecosystem.
- Test Coverage:
- The presence of robust tests under src/__tests__ confirms that the system is designed for reliability and maintainability.

##### Technologies, Frameworks, and Build Tools
- TypeScript – primary language indicated by .ts files and tsconfig.json.
- PNPM – package manager is used (see package.json and pnpm-lock.yaml).
- Vitest – testing framework for writing and watching unit tests.
- Build Tools – for example, tsup.config.ts to bundle the code.
- GitHub Actions – present under .github/workflows/ci.yml for continuous integration.

##### Elements
- Clear labels for each module/component (e.g., Plugin Core, Document Collector, etc.).
- Where configuration options (e.g., output type, includeAlgorithmPrefix) impact processing decisions.

## Diagram (Mermaid)

```mermaid
graph TD
    CLI["GraphQL Codegen CLI Integration"]:::external
    Config["Configuration Module"]:::config
    Consumers["Manifest Consumers (Client/Server)"]:::external

    subgraph "Plugin Core (Orchestration)"
         PluginCore["Plugin Core"]:::core
         Collector["Operation Collector & __typename injector"]:::utils
         FragmentResolver["Fragment Resolver"]:::utils
         Sorter["Operation Sorter"]:::core
         HashGenerator["Hash Generator"]:::utils
         ManifestGenerator["Manifest Generator"]:::core
         PluginCore --> Collector
         Collector --> FragmentResolver
         FragmentResolver --> Sorter
         Sorter --> HashGenerator
         HashGenerator --> ManifestGenerator
    end

    CLI --> PluginCore
    Config --> PluginCore
    ManifestGenerator --> Consumers

click CLI "https://github.com/replit/graphql-codegen-persisted-queries/blob/main/README.md"
click CLI "https://github.com/replit/graphql-codegen-persisted-queries/blob/main/src/index.ts"
click Collector "https://github.com/replit/graphql-codegen-persisted-queries/blob/main/src/core/plugin.ts"
click Collector "https://github.com/replit/graphql-codegen-persisted-queries/blob/main/src/utils/transforms.ts"
click FragmentResolver "https://github.com/replit/graphql-codegen-persisted-queries/blob/main/src/utils/fragments.ts"
click Sorter "https://github.com/replit/graphql-codegen-persisted-queries/blob/main/src/core/generator.ts"
click HashGenerator "https://github.com/replit/graphql-codegen-persisted-queries/blob/main/src/utils/hashing.ts"
click ManifestGenerator "https://github.com/replit/graphql-codegen-persisted-queries/blob/main/src/core/generator.ts"
click PluginCore "https://github.com/replit/graphql-codegen-persisted-queries/blob/main/src/core/index.ts"
click PluginCore "https://github.com/replit/graphql-codegen-persisted-queries/blob/main/src/core/plugin.ts"
click PluginCore "https://github.com/replit/graphql-codegen-persisted-queries/blob/main/src/core/generator.ts"
click Config "https://github.com/replit/graphql-codegen-persisted-queries/blob/main/src/types/index.ts"
click Config "https://github.com/replit/graphql-codegen-persisted-queries/blob/main/tsconfig.json"

classDef external fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
classDef core fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
classDef utils fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
classDef config fill:#ABEBC6,stroke:#28B463,stroke-width:2px;
```
