Server-Driven UI with NestJS, Next.js, and React Native

This repository is a production-shaped reference implementation for server-driven UI.

It demonstrates how to author screens in an admin dashboard, store them in PostgreSQL, compose user-specific UI in a NestJS backend, and render the final JSON contract in a React Native mobile app.

Status

This is a strong reference implementation, not a drop-in production system yet.

Implemented:

• Database-backed screen templates and revisions with Prisma/PostgreSQL
• Draft and publish workflow for authored screens
• Shared SDUI contracts with DTOs and Zod schemas
• Backend composition engine with data sources, targeting, dynamic values, actions, and fallbacks
• Admin dashboard for editing layouts, targeting, source bindings, and item actions
• React Native renderer with component registry, navigation actions, caching, and client-side targeting guard
• iOS simulator workflow through Expo dev client

Still needed before real production:

• Real admin authentication and RBAC
• Automated tests and CI
• Observability, audit depth, rollback UX, and alerting
• Hardened action registry and source-query governance
• Production deployment configuration and secrets management

See Production Readiness for the full checklist.

Repository Layout

apps/
  api/       NestJS API, Prisma, composition engine, admin APIs
  admin/     Next.js admin dashboard for authoring screens
  mobile/    Expo React Native app and SDUI renderer

packages/
  sdui-contracts/  Shared schemas, DTOs, template contracts, targeting, composition catalog types

docs/
  architecture/    System and composition architecture

Architecture

flowchart LR
  Admin[Next.js Admin] -->|Save draft / publish| API[NestJS API]
  API -->|Store revisions| DB[(PostgreSQL)]
  Mobile[React Native Mobile] -->|GET screen JSON| API
  API -->|Load published template| DB
  API -->|Compose user-specific ScreenDto| Composer[Composition Engine]
  Composer --> Mobile

Loading

The database stores authored screen templates. The mobile app only receives the currently published screen after the backend resolves:

• user context
• client OS and app version targeting
• data sources such as products, promos, and categories
• dynamic text tokens
• actions and navigation routes
• fallback components

Start with Architecture Overview, then read Composition Engine for the backend internals.

Prerequisites

• Node.js 20 or newer
• pnpm 9 or newer
• Docker Desktop
• Xcode, if running the iOS app
• CocoaPods, installed through the React Native/Expo toolchain

Quick Start

Install dependencies:

pnpm install

Start PostgreSQL:

docker compose up -d postgres

Prepare the API environment:

cp apps/api/.env.example apps/api/.env

Run Prisma migration and seed demo data:

pnpm --filter @sdui/api exec prisma migrate dev
pnpm --filter @sdui/api db:seed

Start the three apps:

pnpm dev:api
pnpm dev:admin
pnpm dev:mobile

Default URLs:

• API: http://localhost:3000/api
• Admin: http://localhost:3001
• Metro: http://localhost:8081
• PostgreSQL: localhost:5432

For iOS, open apps/mobile/ios/SDUIDemo.xcworkspace in Xcode or run:

pnpm --filter @sdui/mobile ios

More detail is in Development Guide.

Common Workflow

1. Open the admin dashboard at http://localhost:3001.
2. Select the home screen.
3. Drag sections, edit fields, targeting, source bindings, and item actions.
4. Save draft.
5. Publish when ready.
6. Open the mobile app and refresh the screen.

Drafts are not visible to mobile clients. Mobile reads only the latest published revision.

Important API Headers

Mobile screen requests send:

x-ui-schema-version: 1
x-user-id: u_42
x-client-os: ios
x-client-os-version: 18.0
x-client-app-version: 1.0.0

Admin API requests use:

x-admin-secret: dev-only-secret

That admin secret is development-only and must be replaced before production.

Dynamic Values

The backend exposes dynamic values through:

GET /api/admin/composition/catalog

Examples:

{{user.firstName}}
{{user.segment}}
{{client.os}}
{{product.id}}
{{category.id}}
{{promo.id}}

Unknown tokens fail admin preview/save with a clear validation error, instead of leaking invalid content into a published mobile screen.

Verification

Useful checks:

pnpm --filter @sdui/contracts build
pnpm --filter @sdui/api build
pnpm typecheck

Smoke-test the screen API:

curl -sS \
  -H 'x-ui-schema-version: 1' \
  -H 'x-user-id: u_42' \
  -H 'x-client-os: ios' \
  -H 'x-client-os-version: 18.0' \
  -H 'x-client-app-version: 1.0.0' \
  http://localhost:3000/api/v1/screens/home

Documentation

• Development Guide
• Architecture Overview
• Composition Engine
• Database-Backed Architecture
• API Reference
• Admin Guide
• Mobile Renderer
• Production Readiness

Current Boundaries

This codebase is intentionally small enough to study and demo. It models production concerns, but some production systems are deliberately simplified:

• Admin auth is a shared secret header.
• The data model uses demo products, promos, categories, and users.
• There is no full CI pipeline yet.
• There is no automated test suite yet.
• Deployment, monitoring, and incident workflows are documented as next steps, not implemented.