Reference: State

Unwrap splits state between TanStack Query (server state) and Zustand (client state). This page is a navigational index. For the rationale, see Architecture: state management.

TanStack Query (server state)

Hooks live in src/hooks/. Each hook wraps a service from src/services/api.ts with a TanStack Query cache key.

Hook	Service	Cache key
useTopTracks()	fetchTopTracks	['top-tracks', TimeRange, limit, offset]
useTopArtists()	fetchTopArtists	['top-artists', TimeRange, limit, offset]
useTopGenres()	fetchTopGenres	['top-genres', TimeRange, limit, offset]
useTopSkips()	fetchTopSkips	['top-skips', TimeRange, limit, offset]
useTopReplays()	fetchTopReplays	['top-replays', TimeRange, limit, offset]
usePeakHour()	fetchPeakHour	['peak-hour', TimeRange]
useMostActiveDay()	fetchMostActiveDay	['most-active-day', TimeRange]
useTimeListened()	fetchTimeListened	['time-listened', TimeRange]
useConnectedServices()	fetchConnectedServices	['connected-services']
useUploadHistory()	uploadHistory	(mutation; invalidates dashboard queries on success)

Conventions

• Cache keys are arrays starting with the resource name, then any parameters that affect the response.
• Components consume { data, isLoading, isError } and never reach into the QueryClient directly.

Zustand (client state)

Two stores in src/stores/. Each owns one concern.

authStore

Holds the currently authenticated user, derived from the session cookie at app load time.

Field	Type	Purpose
user	User | null	Cached user object. null when not signed in.
isAuthenticated	boolean	Convenience derived flag.
isLoading	boolean	True while useInitAuth is fetching on app load.
setUser()	action	Sets the user. Used after login.
clearUser()	action	Clears the user. Used after logout.
updateUser(u)	action	Patches user fields. Used by the Settings page.

dashboardStore

Holds dashboard display preferences. Persists to localStorage under the key unwrap-dashboard-preferences.

Field	Type	Purpose
timeRange	TimeRange	The selected time window.
categories	DashboardCategory[]	Visible categories, in display order.
setTimeRange()	action	Updates the time range.
toggleCategory()	action	Adds or removes a category. Refuses to remove the last one.
setCategories()	action	Replaces the full category list.
resetToDefaults()	action	Restores the out-of-the-box dashboard.

CATEGORY_LABELS

A single Record<DashboardCategory, string> mapping category IDs to display labels. Source of truth for both the picker UI and the dashboard rendering. Add a new category here and the picker, persistence, and UI all pick it up automatically.