> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cfosilvia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 03 MUTATION STANDARDIZATION

# Mutation Standardization

## Objective

Move all write-side data changes behind mutation hooks and use one consistent cache-refresh strategy.

## Rules

* all writes belong in `hooks/mutations/`
* no page or component should perform app-data writes with raw `fetch`
* every write should be wrapped by `useMutation`
* prefer `onSuccess` plus `invalidateQueries`
* do not use `setQueryData` or `setQueriesData` for this migration

## Standard Pattern

```ts theme={null}
export function useUpdateAccountType() {
  const queryClient = useQueryClient()
  const { user } = useUser()
  const userId = user?.id ?? ''

  return useMutation({
    mutationFn: updateAccountType,
    onSuccess: async () => {
      await queryClient.invalidateQueries({
        queryKey: userKeys(userId).accounts.all,
      })
    },
  })
}
```

## Why We Are Avoiding `setQueryData`

This migration intentionally favors consistency over local cache patching:

* invalidation is easier to reason about across many domains
* invalidation is easier to audit in code review
* invalidation reduces drift between server truth and local cache assumptions

If we want optimistic updates later, that should be a separate, explicit policy decision.

## Required Refactors

### Move writes out of components/pages

Any write-side `fetch` in `app/` or `components/` should be moved into a descriptive mutation hook.

Examples:

* `hooks/mutations/use-update-account-type.ts`
* `hooks/mutations/use-update-account-tax-treatment.ts`
* `hooks/mutations/use-disconnect-account.ts`
* `hooks/mutations/use-process-snaptrade-connection.ts`

### Update call sites

Pages/components should consume hook APIs only:

```ts theme={null}
const updateAccountType = useUpdateAccountType()

await updateAccountType.mutateAsync(payload)
```

### Replace local cache writes

Remove `queryClient.setQueryData(...)` and `queryClient.setQueriesData(...)` from the codebase and replace them with the standardized mutation + invalidation flow.

## Review Checklist

* is the write implemented in `hooks/mutations/`?
* does the hook own the `fetch` call?
* does `onSuccess` invalidate the narrowest correct key family?
* did we remove any direct page/component `fetch` write logic?
* did we eliminate `setQueryData` or `setQueriesData` from the touched path?


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.