# qk-hierarchical-organization: Organize Keys Hierarchically

## Priority: CRITICAL

## Explanation

Structure query keys from general to specific: entity type first, then ID, then modifiers/filters. This enables efficient invalidation at any level of specificity and creates predictable cache organization.

## Bad Example

```tsx
// Flat, inconsistent key structures
const { data: todos } = useQuery({
  queryKey: ['all-todos-list'],
  queryFn: fetchTodos,
})

const { data: todo } = useQuery({
  queryKey: ['single-todo-5'],
  queryFn: () => fetchTodo(5),
})

const { data: comments } = useQuery({
  queryKey: ['todo-5-comments'],
  queryFn: () => fetchTodoComments(5),
})

// Can't easily invalidate all todo-related queries
```

## Good Example

```tsx
// Hierarchical: entity → id → sub-resource → filters
const { data: todos } = useQuery({
  queryKey: ['todos'],
  queryFn: fetchTodos,
})

const { data: todo } = useQuery({
  queryKey: ['todos', 5],
  queryFn: () => fetchTodo(5),
})

const { data: comments } = useQuery({
  queryKey: ['todos', 5, 'comments'],
  queryFn: () => fetchTodoComments(5),
})

const { data: filteredTodos } = useQuery({
  queryKey: ['todos', { status: 'done', page: 1 }],
  queryFn: () => fetchTodos({ status: 'done', page: 1 }),
})

// Now we can invalidate at any level:
queryClient.invalidateQueries({ queryKey: ['todos'] })        // All todos
queryClient.invalidateQueries({ queryKey: ['todos', 5] })     // Todo 5 and its sub-resources
queryClient.invalidateQueries({ queryKey: ['todos', 5, 'comments'] }) // Just comments
```

## Recommended Hierarchy Pattern

```
['entity']                              // List
['entity', id]                          // Single item
['entity', id, 'sub-resource']          // Related data
['entity', { filters }]                 // Filtered list
['entity', id, 'sub-resource', { filters }] // Filtered sub-resource
```

## Context

- Essential for applications with related data
- Enables efficient cache management
- Works with prefix-based invalidation
- Consider using query key factories (see `qk-factory-pattern`) for consistency