Entities

The snake_case table name (e.g. blog_posts). This is the source of truth — backend route paths are derived as camelCase (/blogPosts) and the FE endpoint key as UPPER_SNAKE (GET_BLOG_POSTS) automatically.

When true, Nucleus prepends six standard system columns so you don't repeat them: a uuid id primary key (gen_random_uuid()), created_at / updated_at timestamptz timestamps (now()), an is_active boolean flag (defaults true) you can use as a soft-delete/active marker, and created_by / updated_by uuid audit columns that the write routes populate from the request's x-user-id. Note: the generic DELETE is a HARD delete — the framework does not auto-filter or soft-delete on is_active.

A logical grouping label used to organise entities in admin UIs and generated docs. Purely organisational.

Expose batch create/update/delete routes for this entity. Bulk-operation claims are only seeded when this is true, keeping the claims table clean for entities that don't need them.

Mark the entity as accepting multipart/form-data (file uploads) rather than JSON — relevant for entities that carry binary payloads.

Tags an entity as belonging to a framework feature (authentication, authorization, audit, payment, storage…). Used internally for the built-in system tables; you rarely set this on your own entities.

Names the backend service that physically owns this entity. The FE endpoint generator uses it to route calls to the right service in a multi-service deployment. Omit for the default/IDP service.

Example: "blog-api"

Runtime dependencies that must be configured for this entity's routes to mount (currently 'email'). Lets system entities stay dormant until their provider exists.

Inherit a built-in system table instead of replacing it. A config entity that shares a system table's table_name normally REPLACES the built-in definition entirely (dropping its columns, indexes and route policy — resolveEntities warns when you do this). With extends: true the built-in is the base and your entry may only ADD columns and indexes; only table_name, columns and indexes are read (every other field is inherited, and supplying one logs a warning). Invalid extends entries fail boot with typed errors: a column name that collides with a built-in/base column (E1), a notNull column with no DB default (E2 — the fixed-column framework inserts can't supply it), extending an auth table in consumer mode (E3), extends: true naming a table that is not a system table (E4), or extending a table whose feature is disabled (E5).

Example: { "table_name": "users", "extends": true, "columns": [ ... ] }

Per-table opt-in that suppresses author attribution on CREATE only. It stops created_by from being stamped and detaches the CREATE audit entry (actor + IP + user agent) from the new row — for channels that promise the writer anonymity like a suggestion box, whistleblowing form, or unsigned survey. true applies to every insert; { column: 'is_anonymous' } applies only when that payload boolean is truthy, so users who choose to sign stay attributable. Only CREATE is affected — later updates (e.g. an admin changing status) are attributed as normal. This is a deliberate trade: an anonymous submission cannot be traced back to its author afterwards.

Example: { "column": "is_anonymous" }

Per-method public access. { "GET": true } makes reads reachable without auth while writes stay protected — exactly what public-facing list/detail pages need.

Example: { "GET": true }

Methods to NOT generate for this entity. Use ["DELETE"] for append-only tables, or omit POST for read-only reference data.

Declarative metadata only: intended to name the Postgres schemas an entity belongs to, but as of the current release nucleus-core has NO mounting/provisioning logic that reads it. It is declared on the type and carried on the built-in system tables as documentation; tenant provisioning applies every table to every active schema (createAllTablesForSchema) and the schema generator emits all tables unconditionally, so setting this does NOT gate which tenants receive the table. Treat it like available_app_ids — inert in this version.

The declared inverse of available_schemas — schemas that should NOT receive this entity — but it is equally inert as of the current release: no runtime or generation code reads it, and every active tenant schema still receives every table. Do not rely on it for tenant isolation; use it only as documentation until schema-gating is actually implemented.

Declarative metadata only: it tags which appIds an entity belongs to, but as of the current release nucleus-core has NO mounting/filtering logic that reads it (unlike serviceId, which the FE endpoint generator actually consumes). Carried on the built-in system tables as documentation; setting it on your own entity does not currently gate anything.

Each entity's columns are compiled into Elysia TypeBox schemas — a request-body schema (notNull → required, types mapped to t.Number/t.Boolean/t.String{format} / t.Unknown for json) and matching response, list, bulk, delete and error schemas. These power both runtime request validation and the auto-generated Swagger/OpenAPI page, so the documented contract and the enforced contract are the same object.

Before a write hits the database the payload is type-checked per column and format-checked against built-in patterns (email, url, uuid, date, datetime, time, uri, ipv4, ipv6), then sanitised to strip server-managed keys, the hardcoded auth-secret list, and columns flagged readOnly so they can't be mass-assigned. Note: a `sensitive` column is NOT write-protected here — sanitizePayload only checks readOnly, so `sensitive` remains writable. `sensitive` is a READ-side control instead: the column is stripped from list/detail responses and from GET /auth/me, blocked in filter/search/sort/select/distinct, and added to the audit/log redaction set — all unless the caller holds the explicit per-column read claim (get.<table>.<column>). Malformed values (wrong types/formats) are rejected by per-column validation; extra/unknown keys are NOT rejected (the body schema allows additionalProperties) but are ignored by the ORM at insert, so they aren't stored.

Your entities don't start from an empty database. Nucleus ships a full set of system tables (users, sessions, roles, claims, role_claims, user_roles, tenants, tenant_features, audit_logs, notifications, verification flows, …) that the auth, RBAC, audit, verification and tenant subsystems own. Your tables are generated alongside them, and feature_set marks an entity as belonging to one of these framework features. Note (0.9.746+): generic entity WRITES (POST/PUT/PATCH/DELETE) to the RBAC tables (roles/claims/user_roles/role_claims) and to the sensitive money/tenant-routing/auth-secret system tables (domain_hostnames, payment/marketplace tables, verifications, api_keys, magic_link_tokens, user_sessions, trusted_devices) are hard-locked to godmin as defense-in-depth — use the dedicated feature routes, not generic CRUD, to mutate them.

Internally tables are looked up in the schemaTables map by a camelCase key derived from the snake_case table_name (blog_posts → blogPosts). resolveSchemaTable tries the given key, then the normalised form, and warns if neither resolves — preventing the silent undefined that used to bypass role checks.

The field definitions for the table.

Declarative input rules enforced on create/update.

Transforms applied to incoming values before persistence: trim, lowercase, uppercase, escapeHtml, stripTags, normalizeEmail, toNumber, toBoolean, slugify. Chain several to clean input deterministically.

Example: ["trim", "lowercase", "normalizeEmail"]

Each index has columns plus optional name, unique, using (btree | hash | gist | spgist | gin | brin), a partial where clause, and concurrently for non-blocking creation.

Example: { "columns": ["email"], "unique": true, "using": "btree" }

Table-level constraints: a composite primaryKey (string[]), named unique constraints over multiple columns, and check constraints with arbitrary SQL expressions.