Skip to content

GraphQL System Overview

Getting Started

Change the railbird-gql submodule remote

Because the default remote of railbird-gql in all of our repos uses https, you will not be able to push to railbird-gql using your ssh key. Typically, you will want to change the remote to be the ssh remote before making any changes.

First, change your current directory to the root directory of the submodule, (src/gql in railbird-mobile or gql in railbird).

Then run the following commands to make origin use the ssh remote: 

git remote rm origin
git remote add origin ssh://gitea@dev.railbird.ai:1123/railbird/railbird-gql.git

Main Components

  1. Root project
  2. Submodule: railbird-gql

Workflow

The system uses two separate justfiles, each with its own gql command, creating a two-stage process:

  1. In the root project: Generates the GraphQL schema from Strawberry definitions
  2. In the submodule: Generates client-side TypeScript code

Root Project

The primary entrypoint in the root project is the just gql command, which:

  1. Runs export-gql (generates the schema file from Strawberry definitions)
  2. Runs gql-codegen (triggers the submodule's code generation)
  3. Runs prettier-gql (formats the generated schema)

Submodule: railbird-gql

The submodule has its own justfile with a gql command that:

  1. Runs gql-codegen (generates client TypeScript code)
  2. Runs prettier-gql (formats the generated code)

Key process in the submodule: - Takes GraphQL operations defined in the submodule - Combines them with the schema file from the root project - Produces the final client-side TypeScript code

Schema Definition

The GraphQL schema is defined using Strawberry in the root project:

  1. Query class: Combines various query types (e.g., AggregateQuery, BucketSetQuery, etc.)
  2. Mutation class: Combines various mutation types
  3. schema: The Strawberry Schema object, which includes the Query and Mutation types, along with a logging extension

Operations

GraphQL operations (queries and mutations) are defined in various imported modules in the root project (e.g., aggregate.py, bucket_set.py, etc.). These are combined into the main Query and Mutation classes.

Code Generation

The gql-codegen command in the submodule:

  1. Changes to the gql subdirectory
  2. Uses Nix to create a development environment
  3. Runs yarn install and yarn graphql-codegen

This generates TypeScript types and other necessary code based on the GraphQL schema and operations.

Client-Only Workflow

When working exclusively on the client-side and adjusting operations, you can use only the justfile in the submodule:

  1. Navigate to the railbird-gql submodule directory. In railbird-mobile this is src/gql
  2. Make any changes to the operations that are needed.
  3. Use the submodule's just gql command

This workflow is useful when:

  • The server-side schema hasn't changed
  • You're only modifying or adding client-side GraphQL operations
  • You need to regenerate TypeScript code based on updated operations

The submodule's just gql command will:

  • Take the existing schema file
  • Combine it with the updated operations in the submodule
  • Generate and format the new client-side TypeScript code

This approach allows for quicker iterations on the client-side without needing to regenerate the entire schema from the root project.

Railbird Workflow

To work with this system:

  1. Define or update GraphQL types and resolvers using Strawberry in the root project
  2. Run just gql in the root project to generate the schema and trigger the submodule process
  3. The submodule combines the schema with defined operations to generate client-side TypeScript code
  4. Use the generated code in the JavaScript part of the application

This setup allows for separation of concerns between the server-side GraphQL definitions and the client-side code generation, while providing easy-to-use commands for the entire process.

For client-only changes:

  1. Navigate to the railbird-gql submodule
  2. Modify or add GraphQL operations as needed
  3. Run just gql in the submodule to regenerate the client-side TypeScript code
  4. Use the updated generated code in the JavaScript part of the application

This flexibility allows developers to choose the most efficient workflow based on whether they're making server-side schema changes or only client-side operation adjustments.

Update railbird-gql before updating your application repo

Whether you are using the client-only or backend workflow, you will need to make a pull request with your gql specific changes to railbird-gql repo. Its completely fine to make changes in the submodule while you are working without pushing/merging or even comitting while your work is in progress, but when it does come time to package your change up for review, you are going to want to make sure of the following things:

  • You have made a pull request to railbird-gql with a final version of your changes
  • Your change in your application repo (either railbirdor railbird-mobile) bumps the submodule pointer of railbird-gql in that repo to match the commit of your pull request