Project Structure
The actual two-app layout, shared packages, and platform composition roots.
MuseMVP is a pnpm workspace. apps/web and apps/web-cloudflare each own full page copies. Shared factories, types, pure helpers, and environment schemas live in packages/*, not a shared page package.
Ownership Map
| Entry point | Responsibility |
|---|---|
apps/web/src/app, src/modules | Routes, UI, and orchestration for Vercel/Docker |
apps/web-cloudflare/src/app, src/modules | Full page copies for Workers |
Each app’s src/server | Platform composition root for database, mail, storage, and runtime dependencies |
Each app’s src/backend/database | Wrappers binding package queries to the app schema and driver |
Each app’s src/backend/auth, src/backend/api | Better Auth and Hono wiring |
Each app’s src/env | Composed package ./env schemas and startup checks |
Each app’s content/, source.config.ts | Source MDX for docs, blog, legal pages, and changelog |
packages/db | Postgres/D1 schemas, migrations, and queries taking db first |
packages/auth, api, billing, mail, storage | Domain factories and reusable implementation |
packages/config, i18n, ui, shared | Config, bilingual messages, UI, and pure helpers |
packages/cli, testing, tsconfig, vitest-config | Initialization, testing, and toolchain |
tests/unit, tests/api, tests/e2e | Logic, HTTP contracts, and browser journeys |
apps/web uses pooled Postgres and S3-compatible storage. apps/web-cloudflare uses D1 DB, R2 R2_BUCKET, and Cloudflare Email Sending. Platform differences belong in composition roots, not a connection-strategy switch.
Extension Flow
package queries → app database wrappers → modules/<feature>/lib → Hono routes → api-client → UI
Packages cannot import @/. Apps use @/*; packages use @musemvp/*. Modules and components do not access the database directly. Validate with Zod at route/form boundaries and preserve TanStack Query invalidation after mutations.
Page Parity
pnpm apps:parity
pnpm apps:parity --writeThe default only checks. --write copies apps/web to apps/web-cloudflare; inspect the diff before using it. Platform-specific files such as src/server, src/env, database schema wrappers, and deployment config are excluded. Never hand-edit generated .source/ or cloudflare-env.d.ts.
You may remove the unused app in a derivative, but also update root scripts, workspace, tests, and documentation. Deleting its directory alone does not preserve every command.