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
    src/
      components/ui/            # application UI primitives
      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, files, jobs, limits
      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 evidence

Where 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/page.tsx` and `preview.tsx`	Languages, mobile menu, disabled billing
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`	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

config owns identity, quotas, gateway choices and catalog, never secrets.
db owns Drizzle schema, D1 queries, atomic ledger writes and migrations. React does not execute SQL.
auth creates Better Auth and its plugins; server/platform.ts injects app bindings.
billing owns provider contracts, signatures and money/adapters; modules/billing/service.ts orchestrates effects.
ai, storage and mail own model/file/mail behavior and binding contracts.
cli owns init, doctor, plan, deploy, verify and ignored target state.
i18n owns base messages, derivative overrides and Paraglide settings.
ui currently exports cn and table helpers. Presentation components are app-local; the removed @musemvp/ui/components is not the customization entry.
shared and testing hold reusable foundations/test support.

Workspace files.tsx calls lib/client.ts. server/api.ts authenticates; 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.

Continue with API and Theme.