Project Structure

A high-level map of what lives where and why.

• Directorysrc/

  • Directoryapp/ Next.js App Router — frontend, admin, and API routes

    • …
  • Directoryblocks/ Page block components and their Payload configs

    • …
  • Directorycollections/ PayloadCMS collection definitions

    • …
  • Directorycomponents/ Shared React components

    • …
  • Directoryfields/ Reusable Payload field configs

    • …
  • Directoryglobals/ PayloadCMS global definitions

    • …
  • Directoryguards/ TypeScript type guards

    • …
  • Directorylib/ Utilities and helpers

    • …
  • Directoryplugins/ PayloadCMS plugin configs

    • …
  • Directoryroles/ Access control — role definitions and permissions

    • …
  • Directorystyles/ SCSS styles

    • …
  • payload.config.ts Main Payload configuration
  • payload-types.ts Generated TypeScript types (do not edit manually)
  • env.ts Environment variable validation

---

app/

Next.js App Router. Routes are split across three route groups so frontend, admin, and API concerns stay separate.

• Directoryapp/

  • Directory(frontend)/ Public-facing pages — uses the site’s design system

    • Directory[slug]/ Dynamic page routes

      • …
    • Directoryposts/ Blog/post routes

      • …
    • layout.tsx Frontend layout
    • page.tsx Homepage
  • Directory(payload)/ PayloadCMS routes

    • Directoryadmin/ Admin panel

      • …
    • Directoryapi/ REST and GraphQL endpoints

      • …
  • Directory(sitemap)/ Sitemap generation

    • …
  • robots.ts

---

blocks/

Each block is a self-contained content module — a Payload field config and a React component in the same folder.

• Directoryblocks/

  • Directoryimage/ Image block

    • …
  • Directorytext/ Text block

    • …

See the Blocks guide for how to create a new block.

---

collections/

PayloadCMS collection definitions. Each file exports a collection config that is registered in payload.config.ts.

• Directorycollections/

  • media.ts Media collection
  • pages.ts Pages collection
  • posts.ts Posts collection
  • users.ts Users collection (also used for admin authentication)

See the Collections guide for how to add a collection.

---

lib/

Shared utilities. Split into sub-folders by concern.

• Directorylib/

  • Directorycollections/ Helpers for fetching collection data

    • …
  • Directoryconfig/ App configuration files

    • …
  • Directorypayload/ Payload-specific utilities and admin components

    • …
  • get-url.ts URL helpers
  • revalidate.ts ISR revalidation helpers
  • slug.ts Slug utilities

Where does new code go?

What you’re building	Folder
Fetching or querying a collection	lib/collections/
A Payload admin component	lib/payload/components/
A shared utility	lib/

---

roles/

Role definitions and access control functions used across collections and globals.

• Directoryroles/

  • roles.ts Role definitions
  • permissions.ts Permission constants
  • access-control.ts Access control functions

See Roles & Permissions for how the access model works.

---

Type generation

Payload generates TypeScript types from your config automatically:

ddev pnpm generate:types

This writes src/payload-types.ts with interfaces for every collection and global. Run it after any config change — do not edit the file manually.