# Server engineering documentation

This page documents the structure and the internal architecture of the [GraphQL
Engine Server](https://github.com/hasura/graphql-engine/tree/master/server). To
get started, you can read the [overview](overview.md). We also maintain a
[glossary](glossary.md) of all the terms we use throughout the code and the
documentation.

You can also get started with a list of [tips and tricks](tips.md).

## Haddock documentation

You can browse the generated [haddock documentation](haddock/) for the engine's
code; we automatically update it on every push to a branch of interest:

* [stable branch](haddock/stable)
* [alpha branch](haddock/alpha)
* [beta branch](haddock/beta)
* [main branch](haddock/main)


## Architecture deep-dive

* how to understand our [GraphQL schema](schema.md)
* how to perform [database migrations](migration-guidelines.md)
* how the [execution of remote joins](remote_joins_execution.md) works

TODO: we can either list individual topics here, or point to architecture/ and have a README file there.

## Notes

In our Haskell codebase, we use [GHC-style
notes](https://www.stackbuilders.com/news/the-notes-of-ghc) for long-form
comments detailing a specific aspect of the codebase. We gather all of them, as
of the `main` branch, in the [notes subfolder](notes/).

## Updating this documentation

All markdown files in this folder are either copied *verbatim* from
[`server/documentation`](https://github.com/hasura/graphql-engine/tree/master/server/documentation)
or generated as part of our CI; do not open a PR to modify files in
the `gh-pages` branch, and instead modify their source directly. Notes
are extracted using the `scripts/extract-nodes` bash script. The
haddock documentation is generated by running `cabal haddock
--haddock-internal --haddock-options="--ignore-all-exports"`.