Skip to main content
Sonamu UI is a web-based interface for visually defining and managing Entities. It provides powerful features like auto-completion, validation, and real-time preview.

​
Accessing Sonamu UI

​
Running the Server

cd api
pnpm dev

​
Accessing the UI

When the API server is running, Sonamu UI is automatically served: 
http://localhost:1028/sonamu-ui
Sonamu UI is served at the /sonamu-ui path of the API server without a separate port.

​
Main Tab Structure

Sonamu UI consists of 4 main tabs:
Entity definition and management
  • Create, edit, delete Entities
  • Configure Props, Indexes, Subsets, Enums

​
Creating an Entity

​
1. Entity List Page

Click the Entities tab to see all Entities in the project.
Displayed Information:
  • Entity ID and Title
  • Table name
  • Number of Props
  • Number of Relations

​
2. Creating a New Entity

1

Click Create Entity Button

Click the “Create Entity” button in the top right corner.
2

Enter Basic Information

Enter the following information in the Entity creation form:
  • Entity ID: PascalCase (e.g., User, BlogPost)
  • Table Name: snake_case (e.g., users, blog_posts)
  • Title: Display name (e.g., “User”, “Blog Post”)
  • Parent ID: Optional - used when inheriting from another Entity
Entity ID cannot be changed after creation, so enter it carefully.
3

Save

Click the “Create” button to:
  • Create {entity}.entity.json file
  • Automatically navigate to Entity detail page

​
Editing an Entity

Click an Entity to open the detail editing page. It consists of 4 sheets:

​
Props Sheet

The main sheet for managing Entity properties (columns).

​
Adding Props

1

Click Add Property Button

Click the “Add Property” button in the top right or use shortcut Ctrl+Cmd+Shift+N
2

Enter Property Information

Basic Fields:
  • name: Property name (snake_case)
  • type: Data type (select from dropdown)
  • desc: Description (optional)
  • nullable: Allow NULL (checkbox)
  • dbDefault: Database default value
Type-specific Options:
  • length: String length (default: TEXT)
  • Example: length: 255 → VARCHAR(255)
  • precision: Total digits
  • scale: Decimal places
  • numberType: real | double precision | numeric (default: numeric)
  • Example: precision: 10, scale: 2 → NUMERIC(10, 2)
  • precision: Total digits
  • scale: Decimal places
  • Note: Processed as string type in TypeScript (maintains precision)
  • id: Enum type ID (e.g., UserRole)
  • Enums are defined in a separate Enums section
  • id: JSON schema type ID
  • Define TypeScript type in {entity}.types.ts
  • dimensions: Vector dimensions (e.g., 1536)
  • Requires pgvector extension
  • id: Virtual type ID
  • virtualType: code | query
    • code: Calculated with TypeScript code (default)
    • query: Calculated with SQL query
  • Computed field not stored in database
  • Select and configure Relation type
  • See Relations for details
3

Save

Click “Save” button after completing input

​
Editing and Deleting Props

  • Double-click the row to edit in Props list or press Enter
  • Or select row and click “Edit” button on the right
  • Edit values in form and save
When you delete Props, the column is automatically removed from all Subsets. This cannot be undone, so be careful.

​
Indexes Sheet

Manages database indexes.

​
Adding an Index

1

Click Add Index Button

Click “Add Index” button or use Ctrl+Cmd+Shift+N in Indexes sheet
2

Configure Index

Index Options:
  • type: Index type
    • index: Regular index
    • unique: Unique index (prevents duplicates)
    • hnsw: Vector HNSW index
    • ivfflat: Vector IVFFlat index
  • name: Index name (can be auto-generated)
  • columns: Select columns to include
    • Multiple columns can be selected
    • Column order matters (composite index)
  • using: Index method (optional)
    • btree (default)
    • hash
    • gin
    • gist
Additional Vector Index Options:
  • vectorOps: Distance operator
    • vector_cosine_ops: Cosine distance (recommended)
    • vector_ip_ops: Inner product distance
    • vector_l2_ops: Euclidean distance
  • m: HNSW graph connections (default: 16)
  • efConstruction: HNSW construction quality (default: 64)
  • lists: IVFFlat cluster count (default: 100)
Index Naming Convention:
  • Regular index: {table}_{columns}_idx
  • Unique index: {table}_{columns}_unique
  • Example: users_email_unique, posts_created_at_idx

​
Subsets Sheet

Defines field combinations for API responses.

​
Adding Subset Keys

1

Click Add Subset Button

Click “Add Subset” button to add new subset key
2

Enter Subset Key

  • Short keys starting with uppercase are recommended (e.g., A, P, SS)
  • Commonly used keys:
    • A: All - all fields
    • P: Public - for public APIs
    • SS: Simple Short - simple information only

​
Selecting Fields

  • Click checkboxes to include/exclude fields
  • Same field can be selected in multiple subsets
If you select the parent Relation, you cannot individually select child fields. Select either all or specific fields only.

​
Enums Section

Defines Enum type keys and labels.

​
Adding an Enum

1

Click Add Enum Button

Click “Add Enum” button
2

Enter Enum ID

  • Enter in PascalCase (e.g., UserRole, PostStatus)
  • Use {EntityId} pattern to link with Entity ID
    • Example: $ModelRole → UserRole (auto-converted)

​
Adding Enum Values

Each Enum is displayed as a separate tab, composed of key-label pairs. 
{
  "UserRole": {
    "normal": "Normal User",
    "admin": "Administrator",
    "superadmin": "Super Administrator"
  }
}
How to Add Enum Values:
  • Click “Add Row” button
  • Or use Ctrl+Cmd+Shift+N in Enum tab
  • Enter Key and Label
    • Key: Only lowercase letters, numbers, underscores allowed
    • Label: Display text
Common Enum Patterns:
  • {Entity}OrderBy: Sort options (e.g., id-desc, created_at-desc)
  • {Entity}SearchField: Search fields (e.g., email, username)
  • {Entity}Status: Status (e.g., active, inactive, deleted)

​
Keyboard Shortcuts

Sonamu UI provides various shortcuts for efficient work.

​
Global Shortcuts

ShortcutFunction
Cmd+SSave current Entity
Cmd+KEnter search mode
TabMove to next sheet
Shift+TabMove to previous sheet
EscClose dialog / Deselect

​
Props/Indexes Sheet

ShortcutFunction
Ctrl+Cmd+Shift+NAdd new item
EnterEdit selected item
Cmd+BackspaceDelete selected item
↑ ↓Move selection
Cmd+↑ Cmd+↓Change item order

​
Search Mode

ShortcutFunction
Cmd+KStart search
TypingAuto-move to matching item
EnterComplete search
EscCancel search
In search mode, the cursor immediately moves to matching items as you type. Use it for quick navigation!

​
Deleting an Entity

Entity deletion cannot be undone. Always backup before proceeding.
1

Select Entity

Navigate to the detail page of the Entity to delete
2

Click Delete Entity Button

Click the “Delete Entity” button in the top right
3

Confirm

Enter the exact Entity ID in the confirmation dialog to confirm deletion
Impact of Deletion:
  • {entity}.entity.json file deleted
  • Related Model, Types files need to be deleted manually
  • Database table should be deleted separately through migration

​
File Structure

When you save an Entity, the following files are generated:
Highlighted files are auto-generated by Sonamu.

​
Real-time Validation

Sonamu UI validates input immediately:
  • Reserved word check (JavaScript/TypeScript keywords)
  • Type-specific required option check
  • Duplicate name check
Errors are displayed with a red border and error message.

​
Auto-Completion Features

Sonamu UI provides context-appropriate auto-completion:
  • Existing Entity list suggested
  • Filtered as you type
  • Auto-complete available Entity list in with field
  • Type suggestions in id field for JSON, Virtual types
  • Defined Enum list suggested
  • New Enum creation option provided

​
Next Steps

After learning the basics of Sonamu UI, learn the following topics:

Field Types

Detailed options and usage for all field types

Relations

How to define Entity relationships

Migrations

Running generated migrations

Scaffolding

Auto-generating Model and Types files