Project Structure
Navigate the MuseMVP pnpm workspace, app boundaries, shared packages and customization entrypoints.
MuseMVP is a pnpm workspace with two independently deployable Next.js apps and shared domain packages. This guide describes the MuseMVP starter repository you receive, not the marketing website. The tree shows the main directories, not every file.
Workspace Overview
musemvp/
|-- .agents/skills/ # AI workflows
|-- .github/
|-- .vscode/
|-- apps/
| |-- web/ # Next.js + Node (Vercel / Docker)
| | |-- AGENTS.md # Node-specific agent rules
| |-- web-cloudflare/ # Next.js + Workers (D1 / R2)
| |-- AGENTS.md # Workers-specific agent rules
|-- packages/
| |-- api/
| |-- auth/
| |-- billing/
| |-- cli/
| |-- config/
| |-- db/
| |-- i18n/
| |-- mail/
| |-- shared/
| |-- storage/
| |-- testing/
| |-- tsconfig/
| |-- ui/
| |-- vitest-config/
|-- patches/
|-- scripts/
|-- tests/
|-- AGENTS.md
|-- biome.json
|-- CLAUDE.md
|-- docker-compose.yml
|-- package.json
|-- pnpm-workspace.yaml
|-- tsconfig.json
|-- turbo.jsonapps: Separate Platform Boundaries
| Directory | Responsibility |
|---|---|
apps/web | Next.js + Node.js on Vercel / Docker, using PostgreSQL, S3-compatible storage and Resend. |
apps/web-cloudflare | Next.js + Workers via OpenNext, using D1 (DB), R2 (R2_BUCKET) and Cloudflare Email Sending. |
Each app owns a full copy of its pages; there is no shared page package. Run pnpm apps:parity after changing shared page code. Platform adapters remain app-specific.
Key entrypoints inside either app:
| Path relative to the app | Responsibility |
|---|---|
src/app/(landing-page)/[locale]/ | Public routes and section composition for landing, pricing, blog, docs and legal pages. |
src/app/(saas-page)/ | Signed-in product routes. |
src/modules/ | Feature UI and orchestration. |
src/backend/api/ | Hono middleware and route composition. |
src/backend/auth/ | Better Auth dependency wiring. |
src/backend/database/ | Bind shared queries to the app database driver. |
src/server/ | Platform adapters and composition for services such as mail and storage. |
src/env/ | Application environment schemas. |
content/ | Source MDX for docs, posts and legal content. |
source.config.ts | Fumadocs collections and schemas. |
packages: Shared Logic and Configuration
| Directory | Responsibility |
|---|---|
packages/api | Shared Hono error handling; feature routes are composed inside each app. |
packages/auth | Better Auth factories and client entrypoints; each app supplies its own dependencies. |
packages/billing | One configuration boundary for Stripe, Creem, Dodo Payments and Waffo gateways. |
packages/cli | Environment initialization and doctor checks for local development. |
packages/config | Product, authentication, billing and internationalization settings. |
packages/db | Drizzle schemas, migrations and shared queries for PostgreSQL and D1. |
packages/i18n | Shared messages, locale types and routing helpers for English and Chinese. |
packages/mail | Email templates, sending helpers and environment readiness checks. |
packages/shared | Pure helpers and types that do not belong to a single feature. |
packages/storage | S3-compatible helpers for Node; the Worker uses its own native R2 adapter. |
packages/testing | Shared testing conventions and coverage floors for domain packages. |
packages/tsconfig | Shared compiler settings used by workspace packages and apps. |
packages/ui | Shared class-name and UI helpers; application pages remain app-owned. |
packages/vitest-config | Reusable Vitest presets keep workspace test configuration consistent. |
Packages import other packages through @musemvp/*, never an app's @/ alias. Share factories, pure helpers and types. Database queries belong in packages/db; apps provide the platform driver.
Engineering and Collaboration
.agents/skills/: reusable AI workflows;AGENTS.mddefines repository boundaries and verification conventions.AGENTS.md: canonical architecture, task routing, package/app boundaries and acceptance rules.CLAUDE.md: Claude Code workflow preferences that reference the shared rules rather than duplicating them.apps/web/AGENTS.mdandapps/web-cloudflare/AGENTS.md: platform-specific boundaries and shared-page parity conventions.- The eight actual skill workflows cover task routing, public-surface customization, SaaS layout, SaaS page routing, product behavior, testing, risk review and changelogs. See AI collaboration.
scripts/: initialization, migrations, releases and app parity automation.tests/:unit/,api/,e2e/and shared test helpers. Package-local tests live in each package'stests/folder.patches/: dependency patches managed by pnpm.pnpm-workspace.yaml: workspace membership and dependency catalogs;turbo.json: task graph configuration;biome.json: format and lint;package.json: root scripts;docker-compose.yml: local Postgres for the Node app.packages/testing,packages/tsconfigandpackages/vitest-config: engineering standards live in actual packages, not an inventedtooling/folder.
Where Should I Make a Change?
| Task | Entrypoint |
|---|---|
| Replace homepage sections | The app's src/app/(landing-page)/[locale]/ route and landing modules. |
| Change product, auth or plan configuration | packages/config. |
| Edit translations | packages/i18n/src/translations/{en,zh}/default.json; derivative-product overrides go in the matching mvp.json. |
| Change data and queries | Schemas, migrations and queries in packages/db; driver wiring stays in the app. |
| Integrate payments | Gateway implementations and configuration in packages/billing; routes are composed by the app. |
| Edit docs or blog content | The app's content/, not generated .source/ files. |
.source/ and the Cloudflare app's cloudflare-env.d.ts are generated. Update them through the Fumadocs build and pnpm cf:typegen respectively, rather than editing them by hand.