Frontend App
The portal is “just” React, but the wiring matters: generated hooks keep you honest with the schema, and Apollo’s cache stops every screen from reinventing fetch + merge logic. Here is where the UI lives (apps/portal/), how documents become use* hooks, and why InMemoryCache is part of the product contract—not an implementation detail.
How it works
Here is the end-to-end path from GraphQL operation docs to generated hooks, and where Apollo cache-backed reads happen.1) Apollo caching keeps server-state reads consistent
Inapps/portal/src/main.tsx, Apollo is created with cache: new InMemoryCache():
2) Operation docs become generated hooks
Operation documents live inapps/portal/src/gql/queries/ and apps/portal/src/gql/mutations/. Codegen generates apps/portal/src/gql/hooks.ts using apps/portal/codegen.yml:
3) Components use generated hooks
Your React components call the generated hooks fromapps/portal/src/gql/hooks.ts:
📖 See Frontend GraphQL Layer for the full “ops -> codegen -> hooks” story.
Extending this system
Use this recipe when you add a new GraphQL operation and consume it via generated hooks.- Add an operation document in
apps/portal/src/gql/queries/orapps/portal/src/gql/mutations/.
apps/portal/src/gql/queries/fetchMyWidget.gql.ts:
- Generate the corresponding React hooks by running:
- Use the generated hook in your component (for example,
useFetchMyWidgetQuery):
- If you’re adding a new page/screen, wire it into routing in
apps/portal/src/main.tsx(see Frontend Routing).
Route under the right layout):
- Verify:
What not to do
If you remember one thing, remember these boundaries while working on the frontend GraphQL + caching stack. ❌ Never manually editapps/portal/src/gql/hooks.ts (it is generated).
❌ Never add raw GraphQL documents inline inside React components when an operation doc file already exists.
❌ Never put UI/business logic that decides entitlements, scopes, or Stripe behavior into the React layer; those rules belong in backend utilities + tools.
❌ Never bypass Apollo caching by “re-hydrating” server-state into Redux.
File conventions
This section tells you exactly where to put new frontend GraphQL code and how to name it.What’s next?
Pick the page that matches the kind of work you’re doing right now:- Frontend GraphQL Layer
- Frontend Routing
- Apollo vs Redux State
- Frontend Theming (MUI)
- Frontend Forms (React Hook Form)
- Frontend Error Handling
- Frontend Tracking
- Frontend Testing (Vitest)
