WordPress CPT-Backed Module Pattern

Several workspace modules (industries, use-cases, videos) follow a single, shared pattern: a private WordPress Custom Post Type stores the data, the workspace app exposes a CRUD admin UI, and the public website reads the same REST endpoint to render the marketing surface.

This page is the canonical blueprint. If you're adding a new module that looks like "editorial content with its own page on the marketing site," follow this exactly.

Why this pattern#

The pattern intentionally does not use ACF for the main content — see ACF guidance for the line between this pattern and ACF.

Architecture at a glance#

┌──────────────────────────────────────────────────────────────────────┐
│                       WordPress (mattersai.wpcomstaging.com)         │
│   Private CPT registered via Simple CPT — Show UI: No, REST: Yes     │
│   Per-entry: title, slug, status, excerpt ([ORDER:NNN]),             │
│              content.raw (JSON blob: hero, sections, …)              │
└──────────────────────────────────────────────────────────────────────┘
                                ▲                       ▲
                                │ REST (auth: Basic)    │ REST (auth: Basic)
                                │                       │
┌───────────────────────────────┴───┐   ┌───────────────┴──────────────────┐
│  Workspace (workspace.matters.ai) │   │  Public site (matters.ai)        │
│                                   │   │                                  │
│  /workspace/<module>/             │   │  /<module>/                      │
│    page.tsx                       │   │    page.tsx                      │
│    client-page.tsx (list + reorder)│  │    Component renders cards/grid │
│    [slug]/page.tsx                │   │                                  │
│    [slug]/client-page.tsx (edit)  │   │  /api/<module>/list/route.ts     │
│                                   │   │    Paginated public list         │
│  /api/workspace/<module>/         │   │                                  │
│    route.ts (GET, POST)           │   │  /<module-singular>/[slug]/      │
│    [id]/route.ts (GET, PUT, DEL)  │   │    page.tsx (detail page)        │
│    reorder/route.ts (drag)        │   │                                  │
└───────────────────────────────────┘   └──────────────────────────────────┘

Existing modules following this pattern#

See the per-module deep dive for Videos — that's the most recent and cleanest implementation; copy it for a new module.

File-by-file blueprint#

For a new module <module> (kebab-case for the URL; snake_case for the WP slug):

WordPress side — Simple CPT registration#

Register the CPT in WP admin via the Simple CPT plugin (already installed) with these exact settings:

The three ⭐ marked rows are critical: Show UI: No is what keeps marketing/sales out of the WP admin for this CPT. Show in REST: Yes is what lets the workspace and public site read/write via REST.

The shared service — lib/services/cpt.service.ts#

All the WordPress REST plumbing (fetch, auth headers, [ORDER:NNN] parse/sort, slug→id resolution, JSON (de)serialization, revalidateTag, error mapping) lives in one audited module: lib/services/cpt.service.ts. The route files are now thin — they do RBAC + validation, then call the service.

A CPT is described by a CptConfig, and each module exports one:

export interface CptConfig {
  postType: string;        // WP REST slug, e.g. "industry"
  tag: string;             // revalidateTag key, e.g. "industries"
  defaultExcerpt: string;  // fallback excerpt
  // Per-CPT excerpt rule. When set, excerpt = excerptFrom(content) || defaultExcerpt
  // (the shared hero-eyebrow heuristic is skipped). CPTs store this differently:
  //   industries → content.hero[0].eyebrow   use cases → content.hero.promptText
  //   videos     → content.category
  excerptFrom?: (content: unknown) => string | undefined | null;
}

// Canonical configs (also: KEY_FEATURE_CPT, PLATFORM_CPT)
export const INDUSTRY_CPT: CptConfig = { postType: "industry", tag: "industries", defaultExcerpt: "…", excerptFrom: … };
export const USE_CASE_CPT: CptConfig = { postType: "use_case", tag: "use-cases", defaultExcerpt: "…", excerptFrom: … };
export const VIDEO_CPT:    CptConfig = { postType: "video",    tag: "videos",    defaultExcerpt: "…", excerptFrom: … };

Service functions (all throw NotFoundError / ExternalServiceError from @/lib/errors/exceptions, log via logger, and revalidateTag on writes):

Input is validated with the exported Zod schemas: cptUpsertSchema (create), its .partial() (update), and cptReorderSchema ({ orders: [{ id, menuOrder }] }).

Workspace API routes (CRUD + reorder)#

Three thin route files under apps/workspace/app/api/workspace/<module>/, all on the standard wrapper — createApiHandler (uniform error handling, logging, CORS) + validateInput (Zod) + checkRole (RBAC) + the service:

route.ts — GET (list), POST (create)

import { NextRequest, NextResponse } from "next/server";

import { createApiHandler } from "@/lib/api/wrapper";
import { checkRole } from "@/lib/auth/rbac";
import { ForbiddenError } from "@/lib/errors/exceptions";
import { VIDEO_CPT, createCptItem, cptUpsertSchema, listCptItems } from "@/lib/services/cpt.service";
import { validateInput } from "@/lib/utils/validation";

export const GET = createApiHandler(
  async () => {
    const videos = await listCptItems(VIDEO_CPT);
    return NextResponse.json({ success: true, videos });
  },
  { rateLimit: { enabled: false } }, // admin dashboard refetches freely
);

export const POST = createApiHandler(async (req: NextRequest) => {
  if (!(await checkRole("org:content:edit")))
    throw new ForbiddenError("You do not have permission to create videos.");
  const input = validateInput(cptUpsertSchema, await req.json());
  const video = await createCptItem(VIDEO_CPT, input);
  return NextResponse.json({ success: true, video });
});

[id]/route.ts — GET (single), PUT (update), DELETE

type RouteCtx = { params: Promise<{ id: string }> };

export const GET = createApiHandler(async (_req, ctx: RouteCtx) => {
  const { id } = await ctx.params;
  return NextResponse.json({ success: true, video: await getCptItem(VIDEO_CPT, id) }); // throws NotFoundError → 404
});

export const PUT = createApiHandler(async (req: NextRequest, ctx: RouteCtx) => {
  const { id } = await ctx.params;
  if (!(await checkRole("org:content:edit"))) throw new ForbiddenError("…");
  const input = validateInput(cptUpsertSchema.partial(), await req.json());
  return NextResponse.json({ success: true, video: await updateCptItem(VIDEO_CPT, id, input) });
});

export const DELETE = createApiHandler(async (_req, ctx: RouteCtx) => {
  const { id } = await ctx.params;
  const canDelete = (await checkRole("org:content:delete")) || (await checkRole("org:content:edit"));
  if (!canDelete) throw new ForbiddenError("…");
  await deleteCptItem(VIDEO_CPT, id);
  return NextResponse.json({ success: true });
});

reorder/route.ts — POST (drag-to-reorder)

export const POST = createApiHandler(async (req: NextRequest) => {
  if (!(await checkRole("org:content:edit"))) throw new ForbiddenError("…");
  const { orders } = validateInput(cptReorderSchema, await req.json());
  await reorderCptItems(VIDEO_CPT, orders);
  return NextResponse.json({ success: true });
});

Response keys are per-module. The list/single keys mirror the module noun — industries/industry, useCases/useCase, videos/video. Keep them; the client pages read data.<key> then refetch.

Reference implementations (industries, use-cases, videos are all on this exact shape — copy any of them):

• apps/workspace/app/api/workspace/videos/route.ts
• apps/workspace/app/api/workspace/videos/[id]/route.ts
• apps/workspace/app/api/workspace/videos/reorder/route.ts

Workspace UI (list + edit)#

Four files under apps/workspace/app/(workspace)/<module>/:

The list page expects an API shape of:

{ success: true, <module>: [{ id, title, slug, status, lastModified, menuOrder }] }

The edit page expects:

{ success: true, <module-singular>: { id, title, slug, status, content: {/* JSON */} } }

Public site (read-only consumption)#

Pick the right surface for the module:

For either, add a shared API route at app/api/<module>/list/route.ts that the public site calls (server-side, with next.revalidate). This same route can be hit by external systems later if needed.

Permissions#

Defined in lib/auth/rbac-shared.ts. Already wired for the existing three modules.

Dashboard card#

Add an entry to the coreModules array in apps/workspace/app/(workspace)/page.tsx so the module shows up on the Command Center.

canViewContent && {
  href: "/<module>",
  title: "<Module Name>",
  description: "<one-liner>",
  icon: <LucideIcon>,
  gradient: "from-sky-500 to-blue-600",  // pick fresh colours
  glowColor: "shadow-sky-500/25",
  ringColor: "ring-sky-500/30",
  badge: "Content",
},

Step-by-step: adding a new module#

1. Register the CPT in WordPress via Simple CPT with the settings table above.
2. Verify the REST endpoint is reachable:

   curl -u "$USER:$APP_PASSWORD" \
     "$WORDPRESS_URL/wp-json/wp/v2/<wp_slug>?per_page=1&status=any&context=edit"
   

   Should return [] (empty array, HTTP 200).
3. Add a CptConfig for the CPT in lib/services/cpt.service.ts (postType, tag, defaultExcerpt, plus an excerptFrom if its content shape differs from the hero-eyebrow default), then copy the three thin route files from apps/workspace/app/api/workspace/videos/* and swap VIDEO_CPT for your config. There's no WP plumbing to rewrite — the service owns it.
4. Copy the workspace UI from apps/workspace/app/(workspace)/videos/* into apps/workspace/app/(workspace)/<module>/. Rename videos → <module> and adjust field labels.
5. Customise the edit form in [slug]/client-page.tsx — keep title/slug/status as-is, replace the data sections with your fields. Keep the save payload as { title, slug, status, content: {...} }.
6. Build the public list API at app/api/<module>/list/route.ts. Reuse the server-side helper pattern from lib/data/videos-server.ts (with optional static fallback if you have a hardcoded backup).
7. Build the public page(s) at app/<module>/page.tsx (and/or app/<module-singular>/[slug]/page.tsx).
8. Add the dashboard card in apps/workspace/app/(workspace)/page.tsx.
9. Add a navbar link if the module is user-facing (components/nav/Navbar.tsx).
10. Add to the sitemap: create or extend the relevant entry in app/(sitemaps)/.
11. Update Workspace Modules to list the new module.
12. Document the module-specific schema under apps/webdocs/app/website/<module>/ (or workspace/<module>/ if it's purely internal).

Gotchas to avoid#

• Don't use menu_order — Simple CPT and some WP setups override it. We standardise on the excerpt-marker pattern ([ORDER:NNN]) which is durable.
• Don't expose Show UI in WP — non-dev users will see a duplicate edit surface and the data shape will drift. The workspace edit form is the only sanctioned editor.
• Don't store dozens of small fields in ACF for these modules. This pattern intentionally uses one JSON blob in content.raw. ACF is for cross-cutting per-entity metadata, not for module-specific schemas.
• Don't forget revalidateTag on writes. The service does this for you in create/update/delete/reorder — if you ever bypass the service, you must call it yourself or the public site's cache won't notice the change for up to an hour.
• Don't re-derive the excerpt inline. Each CPT's excerpt rule belongs in its CptConfig.excerptFrom, not scattered in routes — otherwise the create/update/reorder paths drift (this is exactly what happened before the service: use-cases read hero.promptText, videos read category, industries read hero[0].eyebrow).
• WordPress credentials come from typed env. getWPHeaders() (lib/api/wp-headers.ts) reads env.WORDPRESS_USERNAME / env.WORDPRESS_APP_PASSWORD (declared in the env schema) — never inline process.env or hand-roll the Basic-auth header in a route.
• Don't ship without rate-limiting if the API can be called by unauthenticated paths. The workspace routes are gated by RBAC; the public list endpoints are read-only with WP caching, which is generally fine.

Related#

• ACF Usage & Audit — where ACF does belong, and where it doesn't.
• Videos Module — full worked example of this pattern.
• Workspace Modules — catalog of every module.
• Snippet Generators — adjacent pattern for reusable WP block snippets (not a CRUD module).