diff --git a/wiki/_master-index.md b/wiki/_master-index.md index 8182b7e..cbf06d1 100644 --- a/wiki/_master-index.md +++ b/wiki/_master-index.md @@ -35,7 +35,7 @@ This 3-hop pattern works for hundreds of articles without vector search. | [[wiki/reports/_index\|reports/]] | Weekly and monthly summaries — generate: `uv run python scripts/report-generator.py --weekly` | 1 | | [[wiki/infrastructure/_index\|infrastructure/]] | Server inventory: all 10 SSH hosts — optical, optical-dev, optical-prod, baic, librechat, modocmms, box-cli, aimpress, pve | 12 | | [[wiki/testing/_index\|testing/]] | Web app testing: functional, performance, security, UI types; TDD/BDD/Agile methodologies; Selenium/Cypress/Playwright/JMeter/OWASP ZAP tools | 1 | -| [[wiki/payloadcms/_index\|payloadcms/]] | Full Payload CMS reference — getting started, config, database (Postgres/MongoDB/SQLite), all 22 field types, access control, hooks, authentication (cookies, JWT, API keys, custom strategies, token data), admin UI, custom components, Lexical rich text, live preview, versions/drafts, Local/REST/GraphQL APIs, queries, plugins, jobs queue, upload, ecommerce, production deploy, TypeScript, migration guides, i18n, localization | 86 | +| [[wiki/payloadcms/_index\|payloadcms/]] | Full Payload CMS reference — getting started, config, database (Postgres/MongoDB/SQLite), all 22 field types, access control, hooks, authentication (cookies, JWT, API keys, custom strategies, token data), admin UI, custom components, Lexical rich text, live preview, versions/drafts, Local/REST/GraphQL APIs, queries, plugins, jobs queue, upload, ecommerce, production deploy, TypeScript, migration guides, i18n, localization | 87 | | [[wiki/shared-patterns/_index\|shared-patterns/]] | Oliver Agency standard library patterns: httpx, structlog, pydantic-settings, alembic — reuse before writing from scratch | 4 | | [[wiki/mistakes/_index\|mistakes/]] | Anti-patterns extracted from sessions — per-stack running lists (fastapi, react, docker, postgres, general) — injected at session start | 5 | diff --git a/wiki/payloadcms/_index.md b/wiki/payloadcms/_index.md index 525bfc1..64197d4 100644 --- a/wiki/payloadcms/_index.md +++ b/wiki/payloadcms/_index.md @@ -87,3 +87,4 @@ | [[wiki/payloadcms/fields-textarea\|Textarea Field]] | Multiline string field — identical to Text but with larger input; `rows` (default 2), RTL, no `hasMany`, same validation/virtual/JWT options | raw/fields__textarea.md | 2026-05-15 | | [[wiki/payloadcms/fields-ui\|UI Field]] | Presentational-only field — inject arbitrary React components into Admin Panel Edit/List views; no data stored; use for action buttons, context text, custom controls | raw/fields__ui.md | 2026-05-15 | | [[wiki/payloadcms/fields-upload\|Upload Field]] | Reference upload-enabled Collection docs as thumbnail — hasMany, polymorphic multi-collection, filterOptions, bi-directional via Join | raw/fields__upload.md | 2026-05-15 | +| [[wiki/payloadcms/concepts-overview\|Core Concepts]] | Config, Collections, Globals, Fields, Hooks, Auth, Access Control, Admin Panel; Local/REST/GraphQL APIs; package structure | raw/getting-started__concepts.md | 2026-05-15 | diff --git a/wiki/payloadcms/concepts-overview.md b/wiki/payloadcms/concepts-overview.md new file mode 100644 index 0000000..7a4c75f --- /dev/null +++ b/wiki/payloadcms/concepts-overview.md @@ -0,0 +1,107 @@ +--- +title: "Payload CMS — Core Concepts" +aliases: [payload-concepts, payload-overview-concepts] +tags: [payloadcms, concepts, getting-started, api, collections, fields] +sources: [raw/getting-started__concepts.md] +created: 2026-05-15 +updated: 2026-05-15 +--- + +## Core Concepts at a Glance + +| Concept | What it is | +|---------|-----------| +| **Config** | Central `buildConfig()` object — fully-typed, infinitely extensible | +| **Database** | Adapter-agnostic layer (Postgres, MongoDB, SQLite, Vercel Postgres) | +| **Collections** | Groups of Documents sharing a common schema; stored per DB table/collection | +| **Globals** | Single-document singletons (site settings, nav, banners) | +| **Fields** | Schema building blocks; drive both DB storage and Admin UI | +| **Hooks** | Side effects on Document lifecycle events (before read, after create, …) | +| **Authentication** | Built-in user auth with cookies, JWT, API keys, or custom strategies | +| **Access Control** | Per-document/field read/write rules; also controls Admin Panel visibility | +| **Admin Panel** | Auto-generated Next.js (App Router) React UI | + +--- + +## Three APIs — All Share the Same Query Language + +``` +Local API ──► direct DB (Node.js, no HTTP overhead) +REST API ──► /api/ (standard HTTP) +GraphQL ──► /api/graphql (+ /api/graphql-playground) +``` + +### Local API (fastest) +- Direct-to-database access from any server-side context +- Fully typed TypeScript, works in RSC, Hooks, Access Control +```tsx +import { getPayload } from 'payload' +import config from '@payload-config' + +const payload = await getPayload({ config }) +const result = await payload.find({ collection: 'pages' }) // PaginatedDocs +``` + +### REST API +- Auto-mounted at `/api` — zero config required +- Full CRUD + auth routes out of the box +```ts +fetch('https://localhost:3000/api/pages').then(r => r.json()) +``` + +### GraphQL API +- Auto-generated queries/mutations at `/api/graphql` +- Playground at `/api/graphql-playground` +- Compatible with `graphql-request`, `@apollo/client`, etc. + +--- + +## Package Structure + +| Package | Responsibility | +|---------|---------------| +| `payload` | Core ORM + business logic (find/create/update/delete, hooks, access, validation) | +| `@payloadcms/next` | Admin Panel (React/Next.js) + HTTP layer (REST + GraphQL) | +| `@payloadcms/graphql` | GraphQL — optional, bundled with `@payloadcms/next`; needs `graphql` in package.json | +| `@payloadcms/ui` | UI component library; re-exportable for custom extensions | +| `@payloadcms/db-postgres` | PostgreSQL adapter | +| `@payloadcms/db-vercel-postgres` | Vercel Postgres adapter | +| `@payloadcms/db-mongodb` | MongoDB (Mongoose) adapter | +| `@payloadcms/db-sqlite` | SQLite (Drizzle/libSQL) adapter | +| `@payloadcms/richtext-lexical` | Lexical rich text — optional | + +> **Version sync rule:** All official `@payloadcms/*` packages must always be on the same version. + +--- + +## Key Takeaways + +- **Config is the single source of truth** — collections, globals, fields, auth, plugins all live there +- **Payload is database-agnostic** — swap adapters without changing business logic +- **Collections = many docs, Globals = one doc** — both use the same Fields + Hooks system +- **Local API is the go-to for server-side code** — faster than REST, fully typed, no HTTP overhead +- **All three APIs use the same query language** — learn once, apply everywhere +- **Package is modular** — only pay (in bundle size/deps) for what you use; GraphQL and rich text are opt-in +- **Admin Panel is auto-generated** but fully customizable via slots, custom components, and custom views + +--- + +## Related Articles + +- [[wiki/payloadcms/getting-started|Getting Started — What is Payload]] +- [[wiki/payloadcms/configuration|Payload Config — Overview]] +- [[wiki/payloadcms/collection-config|Collection Config]] +- [[wiki/payloadcms/globals-config|Globals Config]] +- [[wiki/payloadcms/fields-overview|Fields Overview]] +- [[wiki/payloadcms/hooks|Hooks]] +- [[wiki/payloadcms/authentication-overview|Authentication — Overview]] +- [[wiki/payloadcms/access-control|Access Control]] +- [[wiki/payloadcms/local-api|Local API]] +- [[wiki/payloadcms/rest-api|REST API]] +- [[wiki/payloadcms/admin-panel-overview|Admin Panel Overview]] + +--- + +## Sources + +- `raw/getting-started__concepts.md` (https://payloadcms.com/docs/getting-started/concepts)