async-graphql/ARCHITECTURE.md

# async-graphql Architecture

This document describes the internal architecture of `async-graphql`, and can be useful to
people wanting to contribute.

## Schema

When you create a schema, the first thing it does it asks the query, mutation and subscription types
to register themselves in the schema's list of GraphQL types called the **registry**. Those types
will then recursively register all the types that they depend on in the registry, and so on until
every single type that is used has been registered in the registry.

## Query Execution

First of all, `async-graphql` will use the `async-graphql-parser` crate (located in the `parser/`
directory) to parse the request document source. This also performs some necessary validations
such as making sure that operation (i.e. query/mutation/subscription) names are unique and that the
query does not contain an anonymous operation as well as a named one.

It then will validate the document as per the rest of GraphQL's validation rules. The `validation/`
module handles this, and it works by walking through the entire document once and notifying the
validation rules on the way to perform their validations and report errors if necessary. If
`ValidationMode::Fast` is turned on, far far fewer rules are used.

Also at this stage some non-validators use the same architecture, such as the query depth calculator
which keeps track of how deeply nested the query gets as the document is walked through.

At this point all the unnecessary operations (ones not selected by `operationName`) are dropped, and
we will execute just one.

At the core of all the resolver logic there are two traits: `InputType` and `OutputType`
which represent a GraphQL input value and GraphQL output value respectively. `InputType` just
requires conversions to and from `async_graphql::Value`. `OutputType` is an async trait with a
single method, `resolve`, which takes a field (e.g. `user(name: "sunli829") { display_name }`) and
resolves it to a single value.

Scalars and enums are expected to ignore the input and serialize themselves, while objects,
interfaces and unions are expected to read the selection set in the field and resolve and serialize
each one of their fields.

As implementing `OutputType::resolve` manually quickly becomes very tedious helpful utilities
are provided in the `resolver_utils` module and via macros.