saltbo
310e4950b3
Replace pnpm workspace monorepo (packages/server, packages/web, packages/shared) with a flat single-package layout following Hono's pages-stack pattern. Switch from pnpm to npm and from Workers+Assets to CF Pages Functions deployment model. - Move source: packages/server/src/ → server/, packages/web/src/ → src/, packages/shared/src/ → shared/ - Add functions/api/[[route]].ts as CF Pages Functions entry (replaces entry-cloudflare.ts) - Update 22 import paths: server uses relative, web uses @shared/@server aliases - Merge three package.json into one, switch to npm - Update wrangler.toml: remove main/assets (Pages auto-detects functions/ dir) - Add per-directory tsconfig.json for VS Code type resolution - Simplify Dockerfile for flat layout - Fix react-pdf CSS import path (dist/esm/ → dist/) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2.2 KiB
CLAUDE.md
Project Overview
ZPan v2 is an open-source, S3-native file hosting platform written in TypeScript. Cloudflare Pages is the primary deployment target, Node.js (Docker) is backup.
Core architecture: clients upload directly to S3-compatible storage via presigned URLs, bypassing server bandwidth.
Key Context
- Single package:
server/(Hono API),src/(React SPA),shared/(types/schemas) - CF Pages Functions:
functions/api/[[route]].ts(CF Pages + D1) andserver/entry-node.ts(Node + SQLite) - Tests are co-located:
*.test.ts(Node),*.cf-test.ts(CF Workers) - Migrations: drizzle-kit generates SQL → wrangler manages D1 state
Docs Index
- CONTRIBUTING.md — setup, commands, quality gates, migration workflow, deployment
- docs/architecture.md — system architecture, tech decisions, platform abstraction
- V2_ROADMAP.md — product positioning, release plan (v2.0–v2.9)
- docs/roadmap/ — per-version technical specs (v2.0.md–v2.9.md)
Commit Convention
Conventional Commits (feat:, fix:, docs:, etc.). PRs target master.
Pre-commit Hooks
Husky runs pnpm typecheck + lint-staged (biome auto-fix) on every git commit. Never bypass with --no-verify. Never run pnpm install --ignore-scripts — the prepare script must run so hooks are installed. If a hook fails, fix the underlying issue and re-commit.
API Client (Hono RPC)
The frontend must use Hono RPC client for all API calls. Never use raw fetch() with hardcoded URL strings.
// ✅ Correct — type-safe, compile-time path validation
import { hc } from 'hono/client'
import type { AppType } from '@server/app'
const client = hc<AppType>('/')
const res = await client.api.admin.storages.$get()
// ❌ Wrong — hardcoded path, no type safety
const res = await fetch('/api/admin/storages')
Exception: uploadToS3() calls external S3 presigned URLs, not our API — raw fetch is OK there.
Types
All shared types live in shared/. Never create duplicate type definitions in src/ or server/. Import from @shared/types and @shared/constants.