From 1a3dc948a8b8fe91f3973cb1af5d2f04c5f465e0 Mon Sep 17 00:00:00 2001 From: lethdat Date: Sat, 21 Feb 2026 00:18:52 +0700 Subject: [PATCH] feat: Add CLAUDE.md with project architecture documentation Add comprehensive documentation for Claude Code including: - Common development commands (dev, build, deploy) - SSR architecture with custom Vite plugin - State management patterns (Pinia Colada) - API client auto-generation setup - Routing structure and auth flow - Styling system with UnoCSS configuration Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 157 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 157 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..4531638 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,157 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +Holistream is a Vue 3 streaming application with Server-Side Rendering (SSR) deployed on Cloudflare Workers. It provides video upload, management, and streaming capabilities. + +## Technology Stack + +- **Framework**: Vue 3 with JSX/TSX support +- **Router**: Vue Router 5 with SSR-aware history +- **Server**: Hono framework on Cloudflare Workers +- **Build Tool**: Vite 7 with custom SSR plugin +- **Styling**: UnoCSS (Tailwind-like utility-first CSS) +- **UI Components**: PrimeVue 4 with Aura theme +- **State Management**: Pinia + Pinia Colada for server state +- **HTTP Client**: Auto-generated from OpenAPI spec via swagger-typescript-api +- **Package Manager**: Bun + +## Common Commands + +```bash +# Development server with hot reload +bun dev + +# Production build (client + worker) +bun run build + +# Preview production build locally +bun preview + +# Deploy to Cloudflare Workers +bun run deploy + +# Generate TypeScript types from Wrangler config +bun run cf-typegen + +# View Cloudflare Worker logs +bun run tail +``` + +## Architecture + +### SSR Architecture + +The app uses a custom SSR setup (`ssrPlugin.ts`) that: +- Builds the client bundle FIRST, then the Worker bundle +- Injects the Vite manifest into the server build for asset rendering +- Uses environment-based module resolution for `httpClientAdapter` and `liteMqtt` + +Entry points: +- **Server**: `src/index.tsx` - Hono app that renders Vue SSR stream +- **Client**: `src/client.ts` - Hydrates the SSR-rendered app + +### Module Aliases + +- `@/` → `src/` +- `@httpClientAdapter` → `src/api/httpClientAdapter.server.ts` (SSR) or `.client.ts` (browser) +- `@liteMqtt` → `src/lib/liteMqtt.server.ts` (SSR) or `.ts` (browser) + +### State Management Pattern + +Uses **Pinia Colada** for server state with SSR hydration: +- Queries are fetched server-side and serialized to `window.__APP_DATA__` +- Client hydrates the query cache on startup via `hydrateQueryCache()` +- Pinia state is similarly serialized and restored via `PiniaSharedState` plugin + +### API Client Architecture + +The API client (`src/api/client.ts`) is auto-generated from OpenAPI spec: +- Uses `customFetch` adapter that differs between client/server +- Server adapter (`httpClientAdapter.server.ts`): Forwards cookies, merges headers, calls `api.pipic.fun` +- Client adapter (`httpClientAdapter.client.ts`): Standard fetch with credentials +- API proxy route: `/r/*` paths proxy to `https://api.pipic.fun` + +### Routing Structure + +Routes are defined in `src/routes/index.ts` with three main layouts: +1. **Public** (`/`): Landing page, terms, privacy +2. **Auth** (`/login`, `/sign-up`, `/forgot`): Authentication pages (redirects if logged in) +3. **Dashboard**: Protected routes requiring auth + - `/overview` - Main dashboard + - `/upload` - Video upload + - `/video` - Video list + - `/video/:id` - Video detail/edit + - `/payments-and-plans` - Billing + - `/notification`, `/profile` - User settings + +Route meta supports `@unhead/vue` for SEO: `meta: { head: { title, meta: [...] } }` + +### Styling System (UnoCSS) + +Configuration in `uno.config.ts`: +- **Presets**: Wind4 (Tailwind), Typography, Attributify, Bootstrap buttons +- **Custom colors**: `primary` (#14a74b), `accent`, `secondary` (#fd7906), `success`, `info`, `warning`, `danger` +- **Shortcuts**: `press-animated` for button press effects +- **Transformers**: `transformerCompileClass` (prefix: `_`), `transformerVariantGroup` + +Use `cn()` from `src/lib/utils.ts` for conditional class merging (clsx + tailwind-merge). + +### Component Auto-Import + +Components in `src/components/` are auto-imported via `unplugin-vue-components`: +- PrimeVue components resolved via `PrimeVueResolver` +- Vue/Pinia/Vue Router APIs auto-imported via `unplugin-auto-import` + +### Auth Flow + +- `useAuthStore` manages auth state with cookie-based sessions +- `init()` called on every request to fetch current user via `/me` endpoint +- `beforeEach` router guard redirects unauthenticated users from protected routes +- MQTT client connects on user login for real-time notifications + +### File Upload Architecture + +Upload queue (`src/composables/useUploadQueue.ts`): +- Supports both local files and remote URLs +- Presigned POST URLs fetched from API +- Parallel chunk upload for large files +- Progress tracking with speed calculation + +### Type Safety + +- TypeScript strict mode enabled +- `CloudflareBindings` interface for environment variables (generated via `cf-typegen`) +- API types auto-generated from backend OpenAPI spec + +### Environment Variables + +Cloudflare Worker bindings (configured in `wrangler.jsonc`): +- No explicit secrets in code - use Wrangler secrets management +- `compatibility_date`: "2025-08-03" +- `compatibility_flags`: ["nodejs_compat"] + +## Important File Locations + +| Purpose | Path | +|---------|------| +| Server entry | `src/index.tsx` | +| Client entry | `src/client.ts` | +| App factory | `src/main.ts` | +| Router config | `src/routes/index.ts` | +| API client | `src/api/client.ts` | +| Auth store | `src/stores/auth.ts` | +| SSR plugin | `ssrPlugin.ts` | +| UnoCSS config | `uno.config.ts` | +| Wrangler config | `wrangler.jsonc` | +| Vite config | `vite.config.ts` | + +## Development Notes + +- Always use `customFetch` from `@httpClientAdapter` for API calls, never raw fetch +- The `honoContext` is provided to Vue app for accessing request context in components +- MQTT client in `src/lib/liteMqtt.ts` handles real-time notifications +- Icons are custom Vue components in `src/components/icons/` +- Upload indicator is a global component showing queue status