Mockup Backend Plugin

The Mockup Backend provides persistence and version management for UI mockups created in the Mockup frontend plugin.

Overview

Property	Value
Package	@internal/plugin-mockup-backend
Type	Backend
Plugin ID	mockup
Database	PostgreSQL via Knex

Architecture

API Endpoints

Mockup Operations

Method	Endpoint	Description
GET	/mockups	List mockups
POST	/mockups	Create new mockup
GET	/mockups/:id	Get mockup with latest
PATCH	/mockups/:id	Update mockup metadata
DELETE	/mockups/:id	Delete mockup

Version Operations

Method	Endpoint	Description
POST	/mockups/:id/versions	Save new version
GET	/mockups/:id/versions	List versions
GET	/mockups/:id/versions/:vid	Get specific version

Database Schema

mockups

Column	Type	Description
id	UUID	Primary key
name	VARCHAR	Mockup name
description	TEXT	Optional description
owner	VARCHAR	Owner user reference
created_at	TIMESTAMP	Creation time
updated_at	TIMESTAMP	Last update time

mockup_versions

Column	Type	Description
id	UUID	Primary key
mockup_id	UUID	Foreign key to mockup
version_tag	VARCHAR	Optional version tag
layout_data	JSONB	Layout configuration
created_by	VARCHAR	Creator user ref
created_at	TIMESTAMP	Creation time

Request/Response Schemas

Create Mockup

// POST /mockups
interface CreateMockupRequest {
  name: string;
  description?: string;
}

interface CreateMockupResponse {
  id: string;
  name: string;
  description?: string;
  owner: string;
  createdAt: string;
  updatedAt: string;
}

Save Version

// POST /mockups/:id/versions
interface SaveVersionRequest {
  layoutData: LayoutItem[];
  versionTag?: string;
}

interface SaveVersionResponse {
  id: string;
  mockupId: string;
  versionTag?: string;
  layoutData: LayoutItem[];
  createdBy: string;
  createdAt: string;
}

Layout Item Structure

interface LayoutItem {
  i: string; // Unique identifier
  x: number; // X position (grid units)
  y: number; // Y position (grid units)
  w: number; // Width (grid units)
  h: number; // Height (grid units)
  component: string; // Component type
  props: Record<string, any>; // Component properties
}

MockupStore Service

interface MockupStore {
  // Mockup operations
  list(owner?: string): Promise<Mockup[]>;
  get(id: string): Promise<Mockup | null>;
  create(input: CreateMockupInput, owner: string): Promise<Mockup>;
  update(id: string, input: UpdateMockupInput): Promise<Mockup>;
  delete(id: string): Promise<void>;

  // Version operations
  saveVersion(
    mockupId: string,
    input: SaveVersionInput,
    createdBy: string,
  ): Promise<Version>;
  listVersions(mockupId: string): Promise<Version[]>;
  getVersion(mockupId: string, versionId: string): Promise<Version | null>;
  getLatestVersion(mockupId: string): Promise<Version | null>;
}

Validation

All inputs are validated using Zod schemas:

const createMockupSchema = z.object({
  name: z.string().min(1).max(255),
  description: z.string().max(1000).optional(),
});

const saveVersionSchema = z.object({
  layoutData: z.array(
    z.object({
      i: z.string(),
      x: z.number().int().min(0),
      y: z.number().int().min(0),
      w: z.number().int().min(1),
      h: z.number().int().min(1),
      component: z.string(),
      props: z.record(z.any()),
    }),
  ),
  versionTag: z.string().max(50).optional(),
});

Usage Examples

Create Mockup

curl -X POST http://localhost:7007/api/mockup/mockups \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dashboard Design",
    "description": "Main dashboard layout"
  }'

Save Version

curl -X POST http://localhost:7007/api/mockup/mockups/xxx/versions \
  -H "Content-Type: application/json" \
  -d '{
    "layoutData": [
      {"i": "1", "x": 0, "y": 0, "w": 12, "h": 2, "component": "text", "props": {"content": "Title"}},
      {"i": "2", "x": 0, "y": 2, "w": 6, "h": 4, "component": "card", "props": {"title": "Stats"}}
    ],
    "versionTag": "v1.0"
  }'

Get Mockup with Latest Version

curl http://localhost:7007/api/mockup/mockups/xxx

Response:

{
  "id": "xxx",
  "name": "Dashboard Design",
  "description": "Main dashboard layout",
  "owner": "user:default/john.doe",
  "createdAt": "2024-01-15T10:00:00Z",
  "updatedAt": "2024-01-15T12:00:00Z",
  "latestVersion": {
    "id": "yyy",
    "mockupId": "xxx",
    "versionTag": "v1.0",
    "layoutData": [...],
    "createdBy": "user:default/john.doe",
    "createdAt": "2024-01-15T12:00:00Z"
  }
}

Related Documentation

• Mockup Frontend - Frontend plugin
• Plugins Overview