Skip to main content

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

In apps/portal/src/main.tsx, Apollo is created with cache: new InMemoryCache():
That cache is the backbone behind generated hooks.

2) Operation docs become generated hooks

Operation documents live in apps/portal/src/gql/queries/ and apps/portal/src/gql/mutations/. Codegen generates apps/portal/src/gql/hooks.ts using apps/portal/codegen.yml:
Example operation doc:

3) Components use generated hooks

Your React components call the generated hooks from apps/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.
  1. Add an operation document in apps/portal/src/gql/queries/ or apps/portal/src/gql/mutations/.
Example: create apps/portal/src/gql/queries/fetchMyWidget.gql.ts:
  1. Generate the corresponding React hooks by running:
  1. Use the generated hook in your component (for example, useFetchMyWidgetQuery):
  1. If you’re adding a new page/screen, wire it into routing in apps/portal/src/main.tsx (see Frontend Routing).
Example pattern (add a new Route under the right layout):
  1. Verify:

What not to do

If you remember one thing, remember these boundaries while working on the frontend GraphQL + caching stack. ❌ Never manually edit apps/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: If you want the quick “what’s already wired up” tour first, start with What you get.