Project structure

Routes live in src/app/; resource behavior and UI live in src/modules/. Shared infrastructure comes from @zybric/app.

Directory layoutCopy Anchor Link

content/        MDX entries and their images
public/         Static assets outside content
src/
  app/          App Router routes and metadata routes
  db/           Database client, relations, and table aggregation
  env/
    client.ts   Validated browser-visible environment variables
    server.ts   Validated server-only environment variables
  lib/          App infrastructure: auth, content, i18n, and metadata defaults
  modules/      Resource-owned behavior, persistence, calling interfaces, and UI
tests/
  api/          Playwright HTTP contract specs
  e2e/          Playwright journeys named after user goals
  fixtures/     Test resources with setup and teardown
  helpers/      Stateless test utilities and assertions

Resource modulesCopy Anchor Link

Each module uses the directories it needs:

src/modules/<resource>/
  schemas/      Canonical resource schemas and inferred types
  domain/       Resource rules, paths, and persistence contracts
  adapters/     Persistence, tables, and provider implementations
  app/          Commands and queries
  ports/        Server Actions, loaders, MCP tools, and CLI adapters
  ui/           Components, forms, hooks, and email templates

UI belongs to the resource it displays or changes. App-wide UI belongs in src/modules/shared/ui/. Import reusable components through @zybric/app; app-local src/components and src/hooks directories are not used.

Routes and configurationCopy Anchor Link

Locale-addressed public pages live under src/app/[locale]. Home, blog, legal, and author pages share the (marketing) layout; docs use a Fumadocs shell.

The Dashboard uses /dash for every locale. The user's locale preference controls its interface; prefixed paths such as /zh/dash are invalid.

Keep App Router files and matching stylesheets under src/app, such as page.tsx, layout.tsx, loading.tsx, route.ts, page.css, and layout.css. Components, helpers, and schemas belong outside the route tree. Route-specific tests may use the corresponding route filename, such as route.test.ts.

App tooling and configuration live at the app root. workspace.env holds project selectors, gt.config.json defines locales, and source.config.ts defines content collections. Vercel Development values are pulled into the ignored .env.

See Authoring content for entry layout and i18n & SEO for locale routing and metadata.