Data Fetching & State Management
Relevant source files
The following files were used as context for generating this wiki page:
Data fetching and state management in Kocteau are built on a hybrid architecture that leverages Next.js Server Components for initial data loading and TanStack Query for client-side state, caching, and optimistic updates. The system is designed to prioritize "perceived speed" and stable layouts, particularly for the core music review feed and discovery surfaces.
The project utilizes Supabase as the primary backend, providing Auth, Postgres, and Row Level Security (RLS). Client-side interactions such as liking, bookmarking, and following are managed via TanStack Query to ensure the UI remains responsive and reflects the latest server state without full page reloads.
Sources: README.md:95-103, AGENTS.md:120-125, AGENTS.md:267-275
Architecture and Data Flow
Kocteau follows a strict separation between server and client boundaries. Server components handle the initial fetch of critical data (like the "For You" feed) to ensure fast First Contentful Paint and SEO optimization. Client components take over for interactive elements, infinite scrolling, and real-time state updates.
Server-to-Client Hydration
For the main home feed, the server initializes a QueryClient, fetches the initial page of the feed, and dehydrates the state into a HydrationBoundary. This allows the client-side TanStack Query instance to "wake up" with existing data, preventing unnecessary loading spinners on the first mount.
Client-Side State Transitions
The system utilizes standard hooks from @tanstack/react-query to manage complex UI states such as infinite scrolling and mutations.
| Component/Feature | Logic | Tooling |
|---|---|---|
| Feed Scrolling | useInfiniteQuery with intersection observers for cursor-based pagination. | TanStack Query |
| Mutations | useMutation for writes like saving reviews or creating tags. | TanStack Query |
| Global UI | Local React state for temporary UI toggles; URL state for shareable filters. | React / Next.js |
| Optimistic UI | Immediate UI updates on user action before server confirmation. | TanStack Query |
Sources: apps/web/components/feed-review-list.tsx:112-120, apps/web/components/starter-studio-client.tsx:210-220, AGENTS.md:120-125
Core Implementation Details
Feed State Management
The FeedReviewList component manages the state of the primary discovery surface. It filters duplicate reviews and integrates "Starter Tracks" when user data is sparse.
Studio and Curation Mutations
The "Starter Studio" demonstrates complex state management for editorial workflows, including searching external catalogs (Deezer) and committing changes to the Supabase database.
- Deezer Search: Handled via a custom hook
useDeezerSearchfor live results. - Composite Mutations:
addMutationhandles track creation while simultaneously updating candidate queue statuses. - Query Invalidation: Success handlers trigger
queryClient.invalidateQueriesto refresh the "Starter Catalog" and "Saved Queue" lists immediately.
Sources: apps/web/components/starter-studio-client.tsx:243-260, apps/web/components/starter-studio-client.tsx:431-481
Configuration and Defaults
The project defines strict defaults for data fetching to maintain the "editorial" and "minimal" feel.
| Option | Value / Description | Source |
|---|---|---|
| Stack Defaults | Next.js App Router, Supabase, TanStack Query. | AGENTS.md:38-45 |
| Write sensitive flows | Server routes and Supabase RPCs. | AGENTS.md:46-47 |
| Loading States | Structural skeletons mirroring final layout; no full-page spinners. | AGENTS.md:288-300 |
| Cache Strategy | TanStack Query for client cache and optimistic updates. | README.md:100-101 |
Sources: AGENTS.md:38-47, AGENTS.md:288-300, README.md:100-101
Conclusion
Data fetching and state management in Kocteau are optimized for a "quiet, human-led" experience. By combining server-side hydration for speed with client-side TanStack Query for interactivity, the system ensures that music discovery remains fluid. The heavy reliance on Supabase RPCs and RLS provides a secure and structured way to handle complex relational data like recommendation feeds and editorial collections.
Sources: AGENTS.md:10-15, AGENTS.md:38-45