Skip to content

admin-guide.md

Latest commit

 

History

History
97 lines (60 loc) · 3.77 KB

admin-guide.md

File metadata and controls

97 lines (60 loc) · 3.77 KB
Raw

Admin Guide

How to use the Next.js authoring UI to build, edit, and ship a server-driven screen.

Pre-flight

The admin needs the API running:

docker compose up -d postgres
pnpm --filter @sdui/api exec prisma migrate dev   # first run only
pnpm dev:api
pnpm dev:admin

Open http://localhost:3001.

The screens list

The landing page lists every screen the API knows about. Each row shows the screen id, the published revision, and (if any) the unpublished draft revision.

Click a row to open the editor.

The editor

Three panes:

  • Palette (left): drag sources for new sections — section header, promo banner, product carousel, category rail, spacer, stack.
  • Layout (center): the live, sortable list of sections. Drag to reorder. Click any row to select it.
  • Properties (right): the form for the selected section. Generated from the same Zod schema the API resolver uses, so anything you can edit here is also something the API can validate.

Above the layout: Preview JSON, Save draft, Publish.

Tasks

Add a new section

  1. Click a card in the Palette.
  2. The new section appears at the bottom of the Layout with a generated id (e.g. pl-9k3a1b).
  3. The new section is selected automatically — fill in the Properties panel.
  4. Click Save draft.

Reorder sections

Drag any section's handle (⋮⋮) up or down. The list reflows live. Click Save draft to persist.

Edit a section's text

  1. Click the section in the Layout.
  2. In Properties, type into Text or Subtext.
  3. To insert a dynamic value (e.g. the user's first name), drop a token like {{user.firstName}} into the field. The catalog of available tokens lives in the same panel — drag-clickable.
  4. Save draft.

Bind a section to a data repository

For sections like productCardList, categoryRail, and promoBanner, the Properties panel exposes a Source group:

  • Repo — a dropdown populated from GET /api/admin/composition/catalog. Choose products, promos, or categories.
  • Segment — for repos that support it (e.g. products: picked | trending | new).
  • Limit — how many items the API should fetch.

The admin UI cannot let you pick an invalid repo or segment — the catalog is the closed set.

Set targeting rules

Targeting limits who sees a section:

  • OS — ios, android, or all.
  • OS version range — minimum and maximum.
  • App version range — minimum and maximum.

Sections that fail their targeting rule are dropped from the response server-side. The mobile client never sees them; the resolver simply doesn't emit them.

Preview the resolved JSON

Click Preview JSON to see exactly what the API will emit for a synthetic user given your current draft. Use this to confirm dynamic-value substitution and source binding before you publish.

Save draft vs Publish

  • Save draft writes to draftRev only. Mobile clients keep seeing the previously published revision.
  • Publish promotes the draft to rev. The API emits an SSE screen-updated event. The next mobile refetch returns the new layout.

The flow is intentional: a half-finished draft never reaches a user.

Delete a screen

Use DELETE /api/admin/screens/:id from the API. There's no delete button in the UI yet — adding one is straightforward but deferred. See Production readiness.

What the admin can't do (yet)

  • Multi-user collaboration / locking.
  • Audit log / undo / version diff between revisions.
  • Scheduled publishes ("publish at 9am tomorrow").
  • WYSIWYG visual preview of the rendered tree (only JSON preview today).
  • Real auth — currently a shared x-admin-secret header.

These are documented in Production readiness as next steps.