​

GraphQL

​

How it works

1. You write a resolver in apps/backend/src/gql/.
2. Running make gql-codegen dumps the full schema to /shared/template.schema.graphql.
3. The frontend codegen reads that schema plus any useQuery / useMutation calls in the frontend source, and generates apps/portal/src/gql/hooks.ts — a fully typed file of React hooks.
4. Your React component imports and calls the generated hook. TypeScript ensures the component’s types stay in sync with the API.

​

Resolver structure

// apps/backend/src/gql/queries/fetchCountries.ts
export const fetchCountries: ResolverType<undefined, FetchCountriesReturn> =
  async (_parent, args, context: ContextWithUser) => {
    return resolveWithMiddlewares(_parent, args, context, [
      async (_parent, _args, context) => {
        const { tools } = context;
        // all external services come from tools — no direct SDK imports
        const cached = await tools.cache.client.get('countries');
        if (cached) return { countries: JSON.parse(cached) };

        const countries = Country.getAllCountries().map(c => ({
          name: c.name,
          iso: c.isoCode,
          flag: c.flag,
          currency: c.currency,
        }));

        await tools.cache.client.set('countries', JSON.stringify(countries), { EX: 86400 });
        return { countries };
      },
    ]);
  };

export const buildFetchCountriesSchema: GQLSchemaBuilder = () => {
  const typeDefs = new GraphQLSchema({
    query: new GraphQLObjectType({
      name: 'Query',
      fields: {
        fetchCountries: {
          type: new GraphQLObjectType({ ... }),
          resolve: fetchCountries,
        },
      },
    }),
  });
  return makeExecutableSchema({ typeDefs, resolvers: { Query: { fetchCountries } } });
};

• The resolver function (named after the operation, e.g. fetchCountries)
• A schema builder function (named build<OperationName>Schema)
• The parameter type, exported so tests can import it instead of redefining it

​

Middleware chain

return resolveWithMiddlewares(_parent, form, context, [
  isLoggedIn,
  populateUserWithMemberships,
  isAdmin,
  async (_parent, form, context) => {
    // safe to run — user is authenticated and has the admin role
    return myUtilityFunction(form, context.tools);
  },
]);

​

Mutation return types

type MutationReturn =
  | { success: true }
  | { success: false; message: string }
  | { success: false; reason: string };

⚠️ Watch out: the resolver’s return shape must match the GraphQL SDL response fields exactly. For example, if your resolver returns reason: string, your SDL must type reason as GraphQLString (not a list).

​

Adding a new query or mutation

1. Create the resolver file For a query: apps/backend/src/gql/queries/fetchMyThing.ts For a mutation: apps/backend/src/gql/mutations/createMyThing.ts Export the resolver function, the schema builder, and the params type:
   export type FetchMyThingParams = { id: string };
   
   export const fetchMyThing: ResolverType<FetchMyThingParams, FetchMyThingReturn> =
     async (_parent, form, context) => {
       return resolveWithMiddlewares(_parent, form, context, [
         isLoggedIn,
         async (_parent, form, context) => {
           return myUtilityFunction(form, context.tools);
         },
       ]);
     };
   
2. Add business logic to a utility apps/backend/src/utilities/myThing.ts — pure function, no direct SDK calls:
   export const myUtilityFunction = async (
     params: FetchMyThingParams,
     tools: ToolsType,
   ) => {
     // query the DB, call tools.cache, etc.
   };
   

   💡 Tip: for input normalization and validation, keep pure helpers colocated with the operation (e.g. inside apps/backend/src/gql/mutations/<operationName>.ts) or in stable apps/backend/src/utilities/*. Avoid importing helpers from a mutation folder you plan to delete during extraction.

3. Register the schema builder In apps/backend/src/gql/index.ts, add your builder to the merged schema:
   import { buildFetchMyThingSchema } from './queries/fetchMyThing';
   // add it to the mergeSchemas() call
   

   💡 Tip: schema registration is a hard gate. Don’t delete or rename the previous operation module until you’ve updated apps/backend/src/gql/index.ts and make gql-codegen succeeds.

4. Run codegen
   make gql-codegen
   
   This generates the updated apps/portal/src/gql/hooks.ts with a new useFetchMyThingQuery hook.
5. Use the hook in the frontend
   import { useFetchMyThingQuery } from '@/gql/hooks';
   
   const MyComponent = () => {
     const { data, loading } = useFetchMyThingQuery({ variables: { id: '123' } });
     // ...
   };
   
6. Write a test apps/backend/src/gql/queries/__tests__/fetchMyThing.spec.ts:
   import { fetchMyThing, FetchMyThingParams } from '../fetchMyThing';
   // import the exported param type — never redefine it in the test
   
7. Verify
   make test module=backend
   

   💡 Tip: after running make gql-codegen, sanity-check apps/shared/template.schema.graphql to ensure your operation field names (e.g. updateMailingListContact) appear exactly once. This catches accidental SDL duplication that unit tests alone might not reveal.

​

What’s next?

• Architecture Overview — where GraphQL fits in the full request lifecycle.
• Tooling System — how the tools object gets into context.
• Testing — how to test resolvers and utility functions.