Frontend GraphQL Layer
This page explains how the frontend talks to the GraphQL API: operation docs inapps/portal/src/gql/, generated hooks in apps/portal/src/gql/hooks.ts, and Apollo’s InMemoryCache.
How it works
Here’s the pipeline I use when I add or change frontend GraphQL operations.1) Operation documents live next to the code
Frontend GraphQL operation docs live under:apps/portal/src/gql/queries/fetchMe.gql.ts exports a typed query document via gql.
2) Codegen generates the React hooks
The generated hooks file is always:/shared/template.schema.graphql) plus the operation docs via:
3) Apollo caching keeps server-state reads consistent
Inapps/portal/src/main.tsx, the Apollo client is created with:
InMemoryCache is the reason components can rely on generated hooks without rebuilding “server-state” in Redux.
📖 See also: GraphQL for the backend/resolver + schema side of the same workflow.
Extending this system
When you add a new operation, use this recipe so codegen and generated hooks stay in sync.- Add (or update) an operation doc under
apps/portal/src/gql/queries/orapps/portal/src/gql/mutations/.
apps/portal/src/gql/queries/fetchMyWidget.gql.ts:
- Regenerate hooks:
- Use the generated hook in your component:
- Verify:
What not to do
These boundaries keep the frontend/GraphQL contract predictable. ❌ Never manually editapps/portal/src/gql/hooks.ts.
❌ Never duplicate server-state into Redux when Apollo cache already drives the hook results.
❌ Never add backend-only SDK usage (Stripe, Redis, etc.) in React; the frontend talks via GraphQL.
File conventions
This section keeps operation docs and generated hooks predictable. Prefer:*.gql.tsfor operation documents (example:fetchMe.gql.ts)- If you see it used, follow the existing repo naming style for
*.gq.ts(example:revokeMembers.gq.ts)
What’s next?
If you’re about to add a new screen that consumes these hooks, follow the routing and state docs next.- Routing
- Apollo vs Redux State
- Testing (or
make test module=portal)
