# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project overview

`stream-ui` is a Vue 3 SSR frontend deployed on Cloudflare Workers. It uses Hono as the Worker server layer and a custom Vite SSR setup rather than Nuxt.

## Common commands

Run all commands from `stream-ui/`.

```bash
# Install dependencies
bun install

# Start local dev server
bun run dev

# Build client + worker bundles
bun run build

# Preview production build locally
bun run preview

# Deploy to Cloudflare Workers
bun run deploy

# Regenerate Cloudflare binding types from Wrangler config
bun run cf-typegen

# Tail Cloudflare Worker logs
bun run tail
```

Notes:
- This project uses Bun (`bun.lock` is present).
- There is currently no configured `test` script.
- There is currently no configured `lint` script.

## Architecture

### SSR entrypoints
- `src/index.tsx`: Hono Worker entry; registers middleware, proxy routes, merge/display/manifest routes, then SSR routes
- `src/main.ts`: shared app factory for SSR and client hydration
- `src/client.ts`: client-side hydration entry
- `ssrPlugin.ts`: custom Vite SSR plugin that builds the client first, injects the Vite manifest, and swaps environment-specific modules

### Routing and app structure
- Routes live in `src/routes/index.ts`.
- Routing is SSR-aware: `createMemoryHistory()` on the server and `createWebHistory()` in the browser.
- The app is split into:
  - public pages
  - auth pages
  - protected dashboard/settings pages
- Current protected areas include `videos`, `notification`, and `settings/*` routes.

### State and hydration
- Pinia is used for app state.
- `@pinia/colada` is used for server-state/query hydration.
- SSR serializes Pinia state into `$p` and query cache into `$colada`; `src/client.ts` restores both during hydration.
- `src/stores/auth.ts` owns session state and route guards depend on `auth.user`.

### API integration
- `src/api/client.ts` is generated by `swagger-typescript-api`; do not hand-edit generated sections.
- API access should go through the generated client and `@httpClientAdapter`, not raw `fetch`.
- `src/api/httpClientAdapter.server.ts` handles SSR-side API calls by forwarding request headers/cookies and proxying frontend `/r/*` requests to `https://api.pipic.fun`.
- `src/api/httpClientAdapter.client.ts` is the browser-side adapter.

### Notable flows
- `src/stores/auth.ts` initializes the logged-in user from `/me` and opens an MQTT connection after login.
- `src/composables/useUploadQueue.ts` implements the custom upload queue:
  - 90MB chunks
  - max 3 parallel uploads
  - max 3 retries
  - max 5 queued items
- Styling uses UnoCSS (`uno.config.ts`).

## Important notes

- Prefer the actual current code over older documentation when they conflict.
- The previous version of this file contained stale route and dependency details; verify against `src/routes/index.ts` and `package.json` before assuming old pages or libraries still exist.
- Any frontend change that affects API contracts should be checked against the backend repo (`../stream.api`) as well.