/Data Fetching

Description

Data fetching patterns with tRPC and real-time SSE

alwaysApply

true

## Data Fetching

Use [tRPC](https://trpc.io/docs) for data fetching and check our [schema.prisma](mdc:packages/db/prisma/schema.prisma) file for database models.

### tRPC Patterns

```tsx
// Server component - use caller directly
const data = await trpc.session.getById({ sessionId, projectId, organizationId });

// Client component - use useQuery
const { data, isLoading } = useQuery(
  trpc.session.liveUsers.queryOptions({ projectId, organizationId })
);
```

### Best Practices

- Always wrap client requests in `Suspense` with [skeleton.tsx](mdc:packages/ui/src/components/skeleton.tsx) fallbacks
- Avoid `useEffect` for data fetching - prefer React Query's declarative approach
- Use `staleTime` and `refetchInterval` for caching strategy
- Invalidate queries with `queryClient.invalidateQueries({ queryKey: [...] })`

## Real-Time Data

For live/real-time features, use our SSE-based hooks instead of polling:

```tsx
import { useLiveEventStream } from "@/hooks/use-live-event-stream";

// Subscribe to real-time events (pageviews, custom events, session ends)
const { isConnected } = useLiveEventStream(projectId, {
  onPageview: (data) => { /* handle pageview */ },
  onEvent: (data) => { /* handle custom event */ },
  onSessionEnd: (data) => { /* handle session end */ },
});
```

### Real-Time Architecture

```
SDK → Ingestion → Redis Queue → Worker → ClickHouse
                                    ↓
                              Redis Pub/Sub (live-events)
                                    ↓
                        /api/live-stream (SSE endpoint)
                                    ↓
                        Browser EventSource → React hooks → UI
```

### When to Use What

| Use Case | Solution |
|----------|----------|
| Initial data load | tRPC `useQuery` |
| Real-time updates | `useLiveEventStream` hook |
| Form submissions | Server Actions or tRPC mutations |
| Cache invalidation | `queryClient.invalidateQueries()` |

Ref: [use-live-event-stream.ts](mdc:apps/dashboard/src/hooks/use-live-event-stream.ts)