A practical frontend architecture for sharing API contracts, validating responses, fetching during SSR, caching in React, forwarding authentication through a BFF, and keeping mutations synchronized with Symfony.
…
July 21, 2026
A complete authentication flow from a type-safe login form to Symfony Security, rotating refresh tokens, server-side web sessions, protected API requests, logout, recovery, and federated login.
July 21, 2026
Modeling structured domain values in PHP, persisting them as PostgreSQL JSONB through custom Doctrine types, and validating the same contract in TypeScript with Zod.
July 24, 2026
How to build a durable payment workflow around FlexPay using Orders, Payment Transactions, signed webhooks, idempotent fulfillment, and a migration path from a legacy billing model.
Send the goal, stack, and timeline. I'll reply with a next step.
A React component can easily accumulate an API call, access token, hard-coded URL, unchecked as SomeType assertion, and several loading flags. Once that pattern spreads, components no longer have one clear job.
It often starts innocently:
Then the application grows.
The same resource is fetched from a route loader and a component. Filters need to be serialized. Two screens invent different cache keys. A mutation succeeds, but the list still displays stale data. The access token expires. The backend changes a nullable field, TypeScript remains happy, and the UI crashes in production.
At that point, the problem is no longer how to send an HTTP request. The problem is how the frontend and backend agree on a contract and keep that agreement consistent across every request.
While building a Symfony API consumed by React applications, I introduced a dedicated data-fetching layer. Its responsibilities are to:
expose only the operations each application is allowed to call;
define request and response contracts with Zod;
centralize endpoints, serialization, and HTTP configuration;
generate TanStack Query options and stable cache keys;
work during both server-side rendering and browser navigation;
route browser requests through a same-origin Backend for Frontend, or BFF;
normalize backend errors without hiding useful validation details;
and make cache invalidation an explicit part of every write workflow.
As a co-founder, I care about this boundary beyond code organization. It lets the team ship product features without making each one rediscover how the backend works.
The generic examples below build the same boundary for a React and Symfony project.
The UI should express intent:
api.identity.admin.listUsers.queryOptions(filters);It should not need to know:
whether the request uses Axios or fetch;
the exact Symfony route;
how nested filters become a query string;
where the access token is stored;
how the response is validated;
or which other cached resources become stale after a write.
Think of the data layer as an adapter between two models:
This boundary is deliberately more opinionated than a generic HTTP client. Axios knows how to send a request. It does not know that a user list and a user detail are related, that one route is admin-only, or that a successful update invalidates both projections.
My application has two paths to the same Symfony API.
During browser navigation:
During server-side rendering:
The transport changes, but the operation, response schema, query key, and cache behavior do not.
That is important. If SSR uses one API abstraction and browser components use another, the server may preload data under a different key or return a different shape. The browser then ignores the prefetched result and immediately fetches everything again.
I keep API concerns in a shared package instead of distributing them across features:
packages/api/src/
├── platforms/
│ ├── admin.ts
│ └── main.ts
├── contracts/
│ └── identity/
│ ├── admin.ts
│ └── account.ts
├── core/
│ ├── client.ts
│ └── errors.ts
├── endpoints/
│ └── index.ts
└── internal/
├── client/
│ ├── http-client.ts
│ └── request.ts
└── identity/
├── contracts.ts
├── endpoints.ts
└── index.tsThe domain identifies the capability. The API namespace identifies which actor-specific endpoint group provides it.
For example:
admin.identity.admin.listUsers;
admin.identity.account.getSettings;
main.identity.account.getSettings;
main.identity.auth.login;An administrative user list and a self-service account endpoint may both belong to identity, but they do not have the same authorization rules or response projections. Naming the API namespace at the call site keeps that difference visible instead of hiding it behind api.users.list().
Each frontend application imports a platform facade:
// platforms/admin.ts
export const admin = {
identity: {
account: identityAccountApi,
admin: identityAdminApi,
auth: identityAuthApi,
},
billing: {
admin: billingAdminApi,
public: billingPublicApi,
},
};// platforms/main.ts
export const main = {
identity: {
account: identityAccountApi,
auth: identityAuthApi,
},
billing: {
public: billingPublicApi,
selfService: billingSelfServiceApi,
},
};Notice that the main application does not expose identity.admin at all.
This is not backend security. Symfony must still authorize every request. The facade is a design constraint for frontend engineers: an unavailable capability cannot be imported accidentally through the normal public interface.
The public call remains readable:
import { admin as api } from "@app/api/platforms/admin";
api.identity.admin.listUsers.queryOptions(filters);The application chooses a platform. The feature chooses a domain and API namespace. The shared package owns the request details below that decision.
A TypeScript type disappears at runtime. This code does not validate anything:
const data = response.data as ListUsersResponse;It only asks the compiler to trust me.
Instead, define the transport contract as a Zod schema and infer the TypeScript type from it:
import { z } from "zod";
export const userSchema = z.object({
userId: z.string().uuid(),
name: z.string(),
email: z.email(),
status: z.enum(["active", "suspended", "disabled"]),
roles: z.array(z.string()),
createdAt: z.string().datetime(),
lastLoginAt: z.string().datetime().nullable(),
});
export const paginationSchema = z.object({
current: z.number().int().positive(),
limit: z.number().int().positive(),
pages: z.number().int().min(0),
total: z.number().int().min(0),
});
export const listUsersResponseSchema = z.object({
items: z.array(userSchema),
pagination: paginationSchema,
});
export type User = z.infer<typeof userSchema>;
export type ListUsersResponse = z.infer<typeof listUsersResponseSchema>;Now an unexpected backend response fails at the boundary where it entered the application.
Zod can also adapt transport details into a frontend-friendly model:
export const loginResponseSchema = z
.object({
token: z.string().min(1),
refreshToken: z.string().min(1),
user: userSchema,
})
.transform(({ token, refreshToken, user }) => ({
accessToken: token,
refreshToken,
user,
}));The transformation belongs beside the contract, not in every consumer.
This gives me runtime-validated frontend contracts. Because PHP and TypeScript are compiled separately, it does not magically guarantee that Symfony and React can never drift. I protect that seam with contract tests and can add OpenAPI generation later if automatic cross-language synchronization becomes worth the cost.
Endpoints should not be copied into components:
export const identityEndpoints = {
users: "/identity/admin/users",
user: ({ userId }: { userId: string }) =>
`/identity/admin/users/${userId}`,
updateUserProfile: ({ userId }: { userId: string }) =>
`/identity/admin/users/${userId}/profile`,
};An endpoint may be a string or a function of path parameters:
type Endpoint<TParams> = string | ((params: TParams) => string);
function resolvePath<TParams>(endpoint: Endpoint<TParams>, params: TParams) {
return typeof endpoint === "function" ? endpoint(params) : endpoint;
}Centralization gives route changes one owner. It also makes endpoint maps testable without mounting React components.
The low-level client owns transport defaults:
import axios, { AxiosHeaders } from "axios";
type ApiClientConfiguration = {
baseURL?: string;
clientPlatform: "admin" | "main";
getRequestConfig?: () =>
| Promise<AxiosRequestConfig>
| AxiosRequestConfig;
onUnauthorized?: () => void;
};
let configuration: ApiClientConfiguration;
export const httpClient = axios.create({
baseURL: "/api",
headers: {
Accept: "application/json",
"Content-Type": "application/json",
},
withCredentials: true,
});
export function configureApiClient(next: ApiClientConfiguration) {
configuration = next;
httpClient.defaults.baseURL = next.baseURL || "/api";
}
httpClient.interceptors.request.use(async (request) => {
const dynamicConfig = await configuration.getRequestConfig?.();
request.baseURL = dynamicConfig?.baseURL ?? request.baseURL;
request.withCredentials = true;
request.headers = AxiosHeaders.from({
...dynamicConfig?.headers,
...request.headers,
});
request.headers.set("X-Client-Platform", configuration.clientPlatform);
if (request.data instanceof FormData) {
request.headers.delete("Content-Type");
}
return request;
});
httpClient.interceptors.response.use(
(response) => response,
(error) => {
if (axios.isAxiosError(error) && error.response?.status === 401) {
configuration.onUnauthorized?.();
}
throw error;
},
);There are a few important details here:
withCredentials lets the browser send the opaque BFF session cookie.
The platform header tells Symfony which frontend client initiated the request.
FormData removes the manually configured JSON content type so the browser can add the correct multipart boundary.
getRequestConfig is dynamic because server-rendered and browser requests need different base URLs and headers.
401 behavior is centralized instead of being repeated by every screen.
I can also add request observers for analytics or diagnostics, but observability must never be able to break a request.
TanStack Query works best when the query key and query function are defined together. I use a factory that also knows how to serialize parameters and validate responses:
import {
type QueryKey,
queryOptions,
} from "@tanstack/react-query";
import qs from "qs";
import type { z } from "zod";
type QueryBuilder<TParams, TResult> = {
enabled?: (params: TParams) => boolean;
key: (params: TParams) => QueryKey;
keyPrefix?: QueryKey;
path: Endpoint<TParams>;
query?: (params: TParams) => unknown;
responseSchema: z.ZodType<TResult>;
staleTime?: number;
};
const DEFAULT_STALE_TIME = 10 * 60 * 1000;
function appendQueryString(path: string, params: unknown) {
const queryString = qs.stringify(params, {
encodeValuesOnly: true,
skipNulls: true,
});
return queryString ? `${path}?${queryString}` : path;
}
export function createQuery<TParams, TResult>(builder: QueryBuilder<TParams, TResult>) {
const request = async (params: TParams, signal?: AbortSignal) => {
const path = appendQueryString(
resolvePath(builder.path, params),
builder.query?.(params),
);
const response = await httpClient.get<unknown>(path, { signal });
return builder.responseSchema.parse(response.data);
};
return {
endpoint: builder.path,
queryKey: (params: TParams) => builder.key(params),
queryKeyPrefix: () => builder.keyPrefix ?? [],
queryOptions: (params: TParams) =>
queryOptions({
enabled: builder.enabled?.(params) ?? true,
queryFn: ({ signal }) => request(params, signal),
queryKey: builder.key(params),
staleTime: builder.staleTime ?? DEFAULT_STALE_TIME,
}),
request,
};
}This factory gives every read operation four useful interfaces:
queryOptions(params) for React components and route loaders;
queryKey(params) for exact cache operations;
queryKeyPrefix() for invalidating a family of results;
request(params) for controlled use outside TanStack Query.
Passing TanStack Query's AbortSignal to Axios also means abandoned navigations can cancel requests instead of leaving irrelevant work running.
The user list now becomes declarative:
const usersQueryKeyPrefix = ["identity", "users"] as const;
export const identityAdminApi = {
listUsers: createQuery<PaginationFilters, ListUsersResponse>({
key: (filters) => [...usersQueryKeyPrefix, filters],
keyPrefix: usersQueryKeyPrefix,
path: identityEndpoints.users,
query: (filters) => filters,
responseSchema: listUsersResponseSchema,
}),
};The filters are part of the query key. That is not optional bookkeeping; it is the identity of the cached value.
These are different resources:
["identity", "users", { page: { current: 1, limit: 20 } }]
["identity", "users", { page: { current: 2, limit: 20 } }]
["identity", "users", { filters: { search: { query: "Ada" } } }]If I used only ["users"], navigating between pages could display data belonging to a different request.
Query keys must be serializable and deterministic. Normalize dates to strings, omit meaningless empty values, and avoid putting class instances or functions in them.
Tables usually combine pagination, sorting, column filters, ranges, and search. Define that structure as data:
export const paginationFiltersSchema = z.object({
filters: z
.object({
columns: z
.array(
z.object({
field: z.string().min(1),
value: z.union([
z.string(),
z.number(),
z.boolean(),
z.array(z.string()),
]),
}),
)
.optional(),
search: z
.object({
fields: z.array(z.string().min(1)),
query: z.string().min(1),
})
.optional(),
sort: z
.object({
field: z.string().min(1),
direction: z.enum(["asc", "desc"]),
})
.optional(),
})
.optional(),
page: z.object({
current: z.number().int().positive(),
limit: z.number().int().positive(),
}),
});The table adapter converts UI state into this transport-neutral structure. Only the request builder decides how it becomes a URL:
?page[current]=2
&page[limit]=20
&filters[search][query]=Ada
&filters[search][fields][0]=name
&filters[search][fields][1]=emailThis separation lets the table change without rewriting endpoint definitions, and lets the backend query language evolve without leaking serializer logic into React components.
With TanStack Router, a protected route can validate the session and load its primary data before rendering:
export const Route = createFileRoute("/identity/users/")({
beforeLoad: async ({ context }) => {
await requireGrantedSession(context, ["ROLE_USER_MANAGER"]);
},
loader: async ({ context }) => {
const filters = buildInitialUserFilters();
await context.queryClient.ensureQueryData(
api.identity.admin.listUsers.queryOptions(filters),
);
},
component: UsersPage,
});ensureQueryData returns cached data when it is still valid and fetches when necessary. The router's SSR integration dehydrates the query cache into the response and hydrates it in the browser.
Each router instance must receive its own QueryClient:
export function createQueryClient() {
return new QueryClient({
defaultOptions: {
queries: { retry: false },
mutations: { retry: false },
},
});
}
export function getRouter() {
const queryClient = createQueryClient();
return createRouter({
context: { queryClient },
routeTree,
Wrap: ({ children }) => (
<QueryClientProvider client={queryClient}>
{children}
</QueryClientProvider>
),
});
}Never share one server-side QueryClient between users. Its cache contains request data, and a global instance can leak one user's response into another user's render.
I disable automatic retries by default because retries are a product decision. Repeating a 404, 422, or permission failure creates latency without value, and silently retrying a mutation can duplicate side effects. Individual idempotent reads can opt in when appropriate.
The component uses the same options object:
import { useQuery } from "@tanstack/react-query";
function UsersTable({ filters }: { filters: PaginationFilters }) {
const users = useQuery(
api.identity.admin.listUsers.queryOptions(filters),
);
if (users.isPending) {
return <UsersTableSkeleton />;
}
if (users.isError) {
return <ErrorState error={users.error} />;
}
return <DataTable rows={users.data.items} />;
}If the loader already fetched the same key, useQuery consumes the hydrated cache. If the user changes filters, the key changes and TanStack Query fetches the corresponding resource.
The component knows the domain result and UI states. It does not know the URL or transport.
Writes need input validation, path resolution, optional body mapping, response validation, and TanStack mutation options:
type MutationBuilder<TParams, TVariables, TResult> = {
body?: (variables: TVariables) => unknown;
method: "post" | "put" | "patch" | "delete";
path: Endpoint<TParams>;
variablesSchema?: z.ZodType<TVariables>;
responseSchema: z.ZodType<TResult>;
};
export function createMutation<TParams, TVariables, TResult>(
builder: MutationBuilder<TParams, TVariables, TResult>,
) {
const request = async (params: TParams, variables: TVariables) => {
const validVariables = builder.variablesSchema
? builder.variablesSchema.parse(variables)
: variables;
const body = builder.body?.(validVariables) ?? validVariables;
const path = resolvePath(builder.path, params);
const response =
builder.method === "delete"
? await httpClient.delete<unknown>(path, { data: body })
: await httpClient[builder.method]<unknown>(path, body);
return builder.responseSchema.parse(response.data);
};
return {
endpoint: builder.path,
mutationOptions: (params: TParams, overrides = {}) =>
mutationOptions({
mutationFn: (variables: TVariables) => request(params, variables),
...overrides,
}),
request,
};
}Define the operation:
export const updateUserProfileSchema = z.object({
name: z.string().trim().min(1),
phoneNumber: z.string().nullable(),
});
const emptyResponseSchema = z.unknown().transform(() => undefined);
export const updateUserProfile = createMutation<
{ userId: string },
z.infer<typeof updateUserProfileSchema>,
void
>({
method: "patch",
path: identityEndpoints.updateUserProfile,
variablesSchema: updateUserProfileSchema,
responseSchema: emptyResponseSchema,
});The schema can be reused by the form and the request boundary. I infer the payload type instead of maintaining a schema, form type, and transport type separately.
The server is authoritative. After a successful update, mark affected projections stale:
function useUserMutationCallbacks() {
const queryClient = useQueryClient();
return {
onError(error: unknown) {
toast.error(getErrorMessage(error, "Unable to update the user."));
},
async onSuccess() {
await Promise.all([
queryClient.invalidateQueries({
queryKey: api.identity.admin.listUsers.queryKeyPrefix(),
}),
queryClient.invalidateQueries({
queryKey: api.identity.admin.getUserDetails.queryKeyPrefix(),
}),
]);
toast.success("User updated.");
},
};
}Then the component stays small:
function EditUserForm({ user }: { user: User }) {
const mutation = useMutation(
api.identity.admin.updateUserProfile.mutationOptions(
{ userId: user.userId },
useUserMutationCallbacks(),
),
);
return (
<UserForm
error={mutation.error}
pending={mutation.isPending}
onSubmit={(values) => mutation.mutate(values)}
/>
);
}Invalidating a prefix refreshes every cached variant of the user list, including different pages and filters. Invalidating the detail prefix updates any open or revisited detail view.
Do not invalidate the entire cache after every mutation. It hides missing dependency knowledge, causes unnecessary network traffic, and can make unrelated screens flicker. Name the projections the write actually affects.
For simple and low-frequency writes, invalidation is easier to reason about than manually editing every cached list. For latency-sensitive interactions, an optimistic update can be added, but it must snapshot the previous cache and roll back on error.
In the browser, the API client uses a relative base URL:
configureApiClient({
baseURL: "/api",
clientPlatform: "admin",
getRequestConfig: () => ({
baseURL: "/api",
withCredentials: true,
}),
onUnauthorized: redirectToLogin,
});The TanStack Start application owns a catch-all route:
const forward = ({ params, request }: ForwardArgs) =>
session.forwardSymfonyRequest({
path: `/api/${params._splat}`,
request,
});
export const Route = createFileRoute("/api/$")({
server: {
handlers: {
GET: forward,
POST: forward,
PUT: forward,
PATCH: forward,
DELETE: forward,
},
},
});The BFF reads the opaque session cookie, retrieves server-side tokens, removes sensitive browser-controlled forwarding headers, and adds trusted headers:
headers.delete("authorization");
headers.delete("cookie");
headers.delete("host");
headers.delete("x-client-platform");
headers.set("Authorization", `Bearer ${session.accessToken}`);
headers.set("X-Client-Platform", platform);If Symfony returns 401, the BFF can rotate the refresh token once and retry the original request once. If refresh fails, it clears the session.
React components never read, store, refresh, or attach access tokens. From their perspective, they call a same-origin /api endpoint.
The BFF improves credential handling, but it does not replace Symfony authorization. The platform facade, route guard, and BFF are convenience and defense-in-depth. The API remains the final authority.
Server rendering should not call the public browser URL and loop through itself. It can call Symfony directly with trusted session headers:
export const getApiRequestConfig = createIsomorphicFn()
.client(() => ({
baseURL: "/api",
withCredentials: true,
}))
.server(async () => {
const { getServerApiHeaders } = await import("./server-session");
return {
baseURL: process.env.INTERNAL_API_URL,
headers: getServerApiHeaders(),
};
});The shared HTTP interceptor asks for this configuration before every request. The same query operation therefore works in both environments:
Browser: /api/identity/admin/users
Server: http://api.internal/identity/admin/usersOnly transport configuration changes. Do not fork domain clients into browserApi and serverApi unless their capabilities are genuinely different.
Symfony can return errors using a problem-details shape:
{
"type": "https://example.test/problems/validation",
"title": "Validation failed",
"status": 422,
"detail": "The submitted data is invalid.",
"violations": [
{
"propertyPath": "email",
"title": "This email is already used."
}
]
}Parse this boundary too:
const validationViolationSchema = z.object({
propertyPath: z.string(),
title: z.string(),
});
const apiProblemSchema = z.looseObject({
detail: z.string().optional(),
message: z.string().optional(),
status: z.number().optional(),
violations: z.array(validationViolationSchema).optional(),
});
export function getErrorMessage(
error: unknown,
fallback = "Unable to complete the request.",
) {
if (!axios.isAxiosError(error)) {
return error instanceof Error ? error.message : fallback;
}
const problem = apiProblemSchema.safeParse(error.response?.data);
if (problem.success) {
return problem.data.detail ?? problem.data.message ?? fallback;
}
return fallback;
}
export function getValidationViolations(error: unknown) {
if (!axios.isAxiosError(error) || error.response?.status !== 422) {
return [];
}
const problem = apiProblemSchema.safeParse(error.response.data);
return problem.success ? problem.data.violations ?? [] : [];
}The form adapter can map propertyPath to fields, while a toast or error boundary displays the general detail.
Do not flatten every backend failure into Something went wrong. A conflict, validation error, rate limit, authentication failure, and infrastructure outage lead to different user actions. Normalization should create a stable frontend interface without destroying meaning.
Also keep schema-validation failures visible in monitoring. When the HTTP status is successful but the response does not satisfy Zod, the contract has drifted. Treat that as an integration defect, not as an empty state.
Not every read belongs in the query cache. A downloaded report is an action that produces a file:
export function createDownload<TParams>({ path, query }: DownloadBuilder<TParams>) {
return {
async download(params: TParams) {
const response = await httpClient.get<Blob>(
appendQueryString(resolvePath(path, params), query?.(params)),
{ responseType: "blob" },
);
return {
blob: response.data,
filename: parseContentDispositionFilename(
response.headers["content-disposition"],
),
};
},
};
}The download still benefits from the configured transport, BFF session, endpoint ownership, and error behavior, but it does not pretend a browser file save is server state worth caching.
The shared package should have focused tests around the behavior it owns.
Verify valid Symfony payloads parse and malformed payloads fail:
expect(listUsersResponseSchema.parse(validResponse)).toEqual(expected);
expect(() => listUsersResponseSchema.parse(invalidResponse)).toThrow();Use a test adapter and assert:
path parameters resolve correctly;
nested query strings are stable;
query keys include every result-changing parameter;
mutation variables are validated before the network call;
request bodies are transformed correctly;
responses are parsed through their schemas;
and abort signals reach the transport.
Protect the exported platform API:
expect(admin.identity.admin.listUsers).toBeDefined();
expect(main.identity).not.toHaveProperty("admin");At the React level, test user-visible behavior: loading, empty, failure, successful mutation, field violations, and cache refresh. Mock the network boundary rather than duplicating implementation details of the query factory.
Verify that browser credentials cannot override trusted authorization headers, protected requests require a session, a single 401 triggers at most one refresh, and failed refresh clears the session.
as Type as validationA type assertion silences the compiler. Parse unknown network data before allowing it into the application.
If every component invents keys, invalidation becomes guesswork. The operation that defines the query should own its key and prefix.
Every input that changes the result must change the key. Otherwise, distinct resources collide in the cache.
Token storage, attachment, refresh, and logout belong to the session and transport boundary. A table should not know what a refresh token is.
Use one domain operation with an isomorphic transport configuration. This lets SSR hydration and browser rendering share cache identity.
Broad invalidation is easy but expensive. Invalidate the list, detail, summary, or reference projections affected by the command.
A lost response does not mean the server did nothing. Retry only when the operation is idempotent or uses an idempotency key.
A global server cache can mix user-specific data. Create a query client for each router or request lifecycle.
A Zod failure after a 200 response is not "no data." It is evidence that the frontend and backend disagree.
Hiding admin operations from the main application improves design, but an attacker can still construct HTTP requests. Symfony must enforce access independently.
This architecture introduces more code than calling fetch directly:
schemas must be maintained;
operations need keys and prefixes;
platform facades must be composed intentionally;
and mutations must declare their synchronization effects.
That investment pays off when the application has multiple domains, actor-specific APIs, SSR, complex filters, and several engineers adding features in parallel.
For a small public website with three read-only endpoints, this may be too much structure. Start with the boundary you need. The important rule is that transport details should not grow organically inside product components.
A reliable frontend data layer is not an Axios wrapper. It is the place where the browser application and backend agree on behavior.
Platform facades expose intentional frontend capabilities.
Domains and API namespaces keep the call site explicit.
Zod validates inputs and unknown responses at runtime.
Central endpoint maps own route topology.
Query factories keep request functions, keys, serialization, and schemas together.
TanStack Router loaders and React components reuse the same query options.
A per-request query client makes SSR hydration safe.
The BFF keeps tokens away from feature code and browser storage.
Isomorphic configuration sends browser traffic through /api and server traffic directly to Symfony.
Mutations validate variables and explicitly invalidate affected projections.
Problem-details helpers preserve useful errors and field violations.
The useful change was giving data fetching a clear owner, not replacing one HTTP library with another. Components now focus on interface behavior. Route loaders and browser navigation share request rules, authentication stays out of features, and contract drift fails at a boundary that can explain the mismatch.