Project Structure
Find pages, domain logic, deployment configuration and tests without crossing ownership boundaries.
This structure comes from standalone musemvp-flare. The marketing site's Next.js folders are not the starter's source of truth.
Repository map
musemvp-flare/
.agents/skills/ # repository agent workflows
.env.example # committed deployment variable names
apps/web/
components.json # shadcn/Base UI configuration
public/logo.png # product mark
public/showcase/ # sample AI outputs for landing pages
src/
components/ui/ # application UI primitives
components/ai/ # studio composer, controls, media, showcase
components/brand.tsx # brand and locale links
components/theme.tsx # appearance menu
hooks/use-mobile.ts # responsive layout helper
routes/ # TanStack pages and API route
modules/ # public/auth/workbench/billing/ai
server/ # bindings, HTTP router, files, jobs, limits
server/routes/ # one module per API area
content/ # paired en/zh MDX
lib/ # requests, locale, SEO and cn
vite.config.ts
wrangler.jsonc # local Worker configuration
packages/
ai/ auth/ billing/ cli/ config/ db/
i18n/ mail/ shared/ storage/ testing/ ui/
scripts/check-contracts.mjs
tests/api/ tests/e2e/ tests/unit/ tests/fixtures/
docs/ # architecture, billing, deployment evidenceWhere to implement a change
| Requirement | Owner | Also verify |
|---|---|---|
| Name, support address, quotas, plans | packages/config/src/index.ts | Public copy, catalog and validation |
| Home/pricing layout | modules/public/home.tsx, pricing.tsx and copy.ts | Languages, mobile menu, disabled billing |
| AI studio or model | modules/ai/*, packages/ai/src/openai.ts, text.ts, catalog.ts, speech.ts, video.ts | OpenAI defaults, explicit alternative adapters, prices, refusals and mock mode |
| Authentication form | modules/auth/page.tsx | Verification, OAuth, CAPTCHA, redirects |
| Workspace feature | modules/workbench/<feature>.tsx | Invalidation, feedback, roles |
| Shared presentation | components/ui and src/styles.css | Base UI behavior, focus, dark theme |
| HTTP contract | routes/api.$.ts → server/api.ts → server/routes/<area>.ts | Zod, identity, Origin, ownership |
| Data and schema | packages/db/src and migrations | Atomic D1 batches, idempotency, SQL risks |
| Resource identities/local configuration | target-resources.ts / wrangler.jsonc | Target separation and precedence |
App paths in the table are relative to apps/web/src. The full naming file is packages/cli/src/target-resources.ts.
Package ownership
configowns identity, quotas, gateway choices and catalog, never secrets.dbowns Drizzle schema, D1 queries, atomic ledger writes and migrations. React does not execute SQL.authcreates Better Auth and its plugins;server/platform.tsinjects app bindings.billingowns provider contracts, signatures and money/adapters;modules/billing/service.tsorchestrates effects.aiowns model catalogs, provider interfaces and the image, video and speech engines as pure TypeScript;modules/aibinds them to D1, R2 and Queues.storageandmailown file and mail behavior and binding contracts.cliowns init, doctor, plan, deploy, verify and ignored target state.i18nowns base messages, derivative overrides and Paraglide settings.uicurrently exportscnand table helpers. Presentation components are app-local; the removed@musemvp/ui/componentsis not the customization entry.sharedandtestinghold reusable foundations/test support.
Follow a real request
Workspace files.tsx calls lib/client.ts. server/api.ts authenticates and hands the request to server/routes/files.ts; server/files.ts composes @musemvp/storage and queries.addFile. UI must not bypass server ownership, and packages must not import app modules.
For typed internal reads inspect createServerFn in modules/workbench/functions.ts. Page guards live in routes/$.tsx; APIs still need independent authentication.
Generated and local files
Route trees, src/paraglide, Wrangler types and build output are generated. Root .env, app .dev.vars, .muse and .wrangler contain environment/state and stay ignored. Inspect support bundles rather than sharing whole folders.