> ## 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.

# 01 CACHE KEY REGISTRY

# Cache Key Registry

## Objective

Create a single, typo-safe place for root cache key names and a shared factory for all TanStack Query keys.

## Files

* `lib/cache-keys.ts`
* `lib/query-keys.ts`

## Rules

### Root key names

* every root key name must come from `CACHE_KEYS`
* keys must be uppercase in the registry
* no hard-coded root key strings outside `lib/cache-keys.ts` and `lib/query-keys.ts`

Example:

```ts theme={null}
export const CACHE_KEYS = {
  ACCOUNTS: 'accounts',
  MANUAL_ACCOUNTS: 'manual-accounts',
  HOLDINGS: 'holdings',
  NET_WORTH: 'net-worth',
  TRANSACTIONS: 'transactions',
  CHAT_SESSIONS: 'chat-sessions',
  USER_INFO: 'user-info',
} as const
```

### Query key composition

* all query key arrays must be created in `lib/query-keys.ts`
* every user-scoped key must include `userId` at index `[1]`
* every domain should expose an `.all` key for prefix invalidation

Example:

```ts theme={null}
import { CACHE_KEYS } from '@/lib/cache-keys'

export const globalKeys = {
  marketIndexes: {
    all: [CACHE_KEYS.MARKET_INDEXES] as const,
  },
  marketSummary: {
    all: [CACHE_KEYS.MARKET_SUMMARY] as const,
  },
} as const

export function userKeys(userId: string) {
  return {
    accounts: {
      all: [CACHE_KEYS.ACCOUNTS, userId] as const,
      list: () => [CACHE_KEYS.ACCOUNTS, userId, 'list'] as const,
    },
    holdings: {
      all: [CACHE_KEYS.HOLDINGS, userId] as const,
      list: () => [CACHE_KEYS.HOLDINGS, userId, 'list'] as const,
    },
    transactions: {
      all: [CACHE_KEYS.TRANSACTIONS, userId] as const,
      unified: () => [CACHE_KEYS.TRANSACTIONS, userId, 'unified'] as const,
    },
  } as const
}
```

## Naming Guidelines

* use singular domain groups in the factory object when it reads well, but keep root strings aligned with existing cache language
* prefer `list`, `detail`, `summary`, `stats`, `byId`, `byDate`, `unified` as stable suffix conventions
* avoid inventing multiple suffix names for the same pattern

## Migration Steps

1. Create `CACHE_KEYS` with every root query key currently in use.
2. Build `globalKeys` and `userKeys(userId)`.
3. Replace local factories such as `createQueryKeys`.
4. Replace inline key arrays with factory helpers.
5. Leave no orphaned root key string arrays behind.

## Review Checklist

* does the domain have an `.all` key?
* is `userId` at index `[1]` for user-scoped data?
* does the new factory preserve existing cache segmentation where needed?
* are there any inline arrays left in the touched files?


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