SDUI

What is SDUI?

Every SaaS product eventually drowns in its own UI code. Feature one gets a page. Feature two gets a page. Feature forty-seven gets a page. Each page has its own data fetching, its own layout logic, its own conditionals, its own special cases. By the time you have sixty screens, you have sixty separate implementations of roughly the same idea: fetch some data, arrange some components, handle some events.

SDUI (Schema-Driven UI) inverts this. Instead of writing screens, you write schemas — declarative JSON documents that describe what a screen looks like, what data it needs, and what happens when the user interacts with it. A single, deliberately dumb renderer reads the schema and paints whatever it says. The renderer doesn't know what screen it's rendering. It doesn't care. It just follows instructions.

The result: a multi-tenant B2B2C platform serving 62+ screens across 15 feature domains, powered by exactly 3 catch-all route files. No per-screen routes. No per-screen components. No per-screen data fetching logic. One renderer. One component registry. One expression grammar. Schemas are the UI.

How It Works

The Traditional Way vs. SDUI

TRADITIONAL (per-screen code):                SDUI (schema-driven):

Screen 1:  route + page + data + layout       Screen 1:  schema.json
Screen 2:  route + page + data + layout       Screen 2:  schema.json
Screen 10: route + page + data + layout       Screen 10: schema.json
Screen 30: route + page + data + layout       Screen 30: schema.json
Screen 62: route + page + data + layout       Screen 62: schema.json

62 routes, 62 pages, 62 data fetchers         3 catch-all routes, 1 renderer
Shared state: good luck                       Shared state: data loader handles it
New screen: write code, deploy                New screen: write JSON, publish to CDN
AI generates UI: impossible                   AI generates UI: it writes a schema

The Schema

A schema is a complete description of a screen. It declares identity, data requirements, and a component tree:

{
  "id": "coach/clients/[id]/nutrition",
  "version": 2,
  "meta": {
    "module": "nutrition",
    "title": "i18n:nutrition.title"
  },
  "data": {
    "plan": {
      "source": "api",
      "endpoint": "/nutrition/plans/:planId",
      "params": { "planId": "route.params.id" }
    },
    "meals": {
      "source": "api",
      "endpoint": "/nutrition/plans/:planId/meals",
      "params": { "planId": "route.params.id" }
    }
  },
  "root": {
    "component": "page-layout",
    "slots": {
      "default": [
        {
          "component": "section-header",
          "bind": { "title": "plan.name" }
        },
        {
          "component": "stack",
          "slots": {
            "default": [
              {
                "each": "meals",
                "as": "meal",
                "component": "meal-card",
                "bind": {
                  "name": "meal.name",
                  "kcal": "meal.totalKcal"
                }
              }
            ]
          }
        }
      ]
    }
  }
}

{
  "component": "food-row",
  "bind": {
    "name": "food.name || 'Unknown'",
    "kcal": "food.kcal ?? 0",
    "editable": "user.role === 'coach'"
  }
}

{
  "component": "empty-state",
  "props": { "message": "No foods added yet" },
  "showIf": "meal.foods.length === 0"
}

{
  "each": "meal.foods",
  "as": "food",
  "key": "food.id",
  "component": "food-row",
  "bind": { "name": "food.name" }
}

{
  "component": "message-composer",
  "on": {
    "submit": {
      "handler": "sendMessage",
      "params": {
        "conversationId": "route.params.id",
        "content": "event.content"
      }
    }
  }
}

Schema Resolution

The resolution algorithm is deterministic. No ambiguity, no fallback guessing:

coach/clients/123/nutrition     ← exact (preferred)
coach/clients/[id]/nutrition    ← 1 param
coach/clients/[id]/[id]         ← 2 params
coach/[id]/[id]/[id]            ← 3 params (least preferred)

The Data Loader

Schemas declare what data they need. The data loader figures out how to get it.

Each schema has a data block where keys map to requirements — an API endpoint, a route param, or a local value. The loader analyses dependencies between requirements (requirement B needs the result of requirement A), arranges them into execution layers, and runs each layer in parallel.

Layer 0: [client, tenant_config]     ← no dependencies, run in parallel
Layer 1: [plan, preferences]         ← depend on client, run in parallel
Layer 2: [meals, supplements]        ← depend on plan, run in parallel

Results are cached by tenant + key. The data loader doesn't know what it's loading — it sees requirement shapes and dependency edges. It could be nutrition data, calendar events, or training programs. Same execution path every time.

The Component Registry

Components are the vocabulary. Schemas are the grammar.

The platform ships a single component library — primitives (text, button, input, card, stack) and composites (meal-card, workout-row, calendar-grid). Every component is registered by string key. The renderer looks up the key, resolves props via expression evaluation, fills named slots with child component trees, and renders.

New component = app deploy. New screen using existing components = publish a JSON file to the CDN. This separation means the vocabulary grows slowly (components need engineering) while the grammar evolves fast (schemas are just data).

Extensions add namespaced vocabulary — new components, new schemas, new handlers — but they don't change the grammar. Everything still flows through the same renderer. No plugins. No runtime-loaded bundles. No alternative execution paths.

Why Three Routes

This is the part that makes people uncomfortable.

A platform with 62+ screens, 15 feature domains, and both coach and client interfaces has exactly three route files:

Each route does the same thing: resolve tenant context, resolve schema ID from the URL path, load the schema, run the data loader, hand the result to the renderer. That's it. No UI logic. No data fetching. No layout composition. No conditionals for "special screens."

The temptation to add a dedicated route for a complex screen is constant. The answer is always no. If the screen needs special behaviour, the schema needs to be more expressive — not the route.

This constraint is what makes AI composition possible. If every screen had its own route with its own logic, an AI couldn't create a new screen without also creating a new route, a new data fetcher, and a new layout. With SDUI, the AI writes a JSON document that follows the same spec as every other screen. The renderer doesn't know the difference between a human-authored schema and an AI-composed one. It shouldn't.

Multi-Tenancy

The platform is B2B2C — businesses subscribe, each gets a tenant, each tenant serves end users. Tenant isolation is non-negotiable:

• One subdomain, one tenant. {tenant}.platform.io resolves to a dedicated database before the application runtime even starts. No in-app tenant switching. No /t/:tenant routing.
• Per-tenant databases. Every tenant has its own Postgres database. No cross-tenant reads or writes. No shared mutable state.
• Entitlement-gated modules. The module system filters available screens and navigation items by tenant configuration. A tenant that hasn't enabled nutrition never sees nutrition schemas, components, or API endpoints.

Schemas are tenant-agnostic — the same schema works for every tenant. Data is tenant-specific — the data loader always operates within the resolved tenant's database context. This separation means one schema definition serves thousands of tenants without per-tenant forks.

What Makes This Different

Scale

The architecture currently supports:

The previous version of the platform had 138 database tables and per-screen routing. The rewrite consolidated tables through JSONB columns and unified type-discriminated tables, then eliminated per-screen routes entirely. The schema-driven approach didn't just reduce code — it changed the economics of building screens from "engineering effort" to "data entry."

The Expression Grammar

The expression system is intentionally restrictive. It supports enough to be useful and forbids everything that would make schemas unpredictable:

The grammar is small enough that an AI model can learn it completely from a few examples. This is by design — a complex expression language would make AI composition unreliable. A restricted one makes it predictable.

Tech Stack

The Core Insight

The UI layer of most applications is a pile of special cases pretending to be a system. Every screen is hand-built. Every data flow is hand-wired. Every layout is hand-composed. When you want to change something, you change code. When you want AI to help, it has to understand the entire codebase — every route, every component tree, every data dependency — to make a meaningful contribution.

SDUI replaces the pile of special cases with a single, uniform abstraction: schemas in, UI out. The renderer is a function. Schemas are its arguments. The function doesn't change. The arguments do. This means humans and AI operate through the same interface, with the same constraints, producing the same artefacts. Not "AI-assisted development." AI and humans writing the same JSON, validated by the same rules, rendered by the same code.

The renderer is dumb. That's the whole point. Intelligence lives in the schemas, not the infrastructure. And schemas are just data.