Authoring basics
The compact starting contract for a Quickback backend; follow the focused references for advanced capabilities.
Quickback compiles configuration and feature definitions into a backend. Start with the layout and security boundaries here, then retrieve only the references your app needs. The complete schema reference remains available.
One feature, connected tables
quickback/
quickback.config.ts
features/projects/
projects.ts # primary table matches feature directory
issues.ts # sibling table
issueAssignees.ts # sibling junction
actions/issues/assign.ts # record action bound to issuesTable files normally default-export feature("tableName", { columns, ... }).
The directory must have its matching primary table. Flat actions/name.ts
binds to that primary table; actions/issues/name.ts binds to sibling issues.
An action with an explicit path is standalone instead. See Feature.
Columns and writes
Use id: q.id(), organizationId: q.scope("organization"), and visible
...q.audit() / ...q.softDelete() spreads in each soft-deleting table's columns.
The compiler validates managed columns. Their presence in the schema does not
mean you supply their values: scoped inserts populate scope and audit values
from verified context. Provide domain values, not client-chosen tenant or audit
fields. See managed columns.
Declare createable/updatable domain fields through guards. Protect workflow state from ordinary writes and use transitions for compiler-owned state changes. Handwritten actions must persist their own domain changes unless a documented compiler-applied transition performs them.
Rows and callers are separate rules
The firewall limits which rows may be touched. Organization
scope derives tenant isolation. Access decides which caller
may perform each operation within that boundary. Put boolean or/and nodes
on access nodes, not inside a flat record condition.
For reporter-or-assignee editing, keep both branches. A named
relationship role requires the same resource column on
both tables; it does not map issues.id to issueAssignees.issueId. Use the
scoped update action example for that join. Do not
replace the requested policy with reporter-only or all-member editing.
References, parents, and labels
Import a sibling FK target with import projects from "./projects" in
issues.ts. Declare its column with .references(() => projects.id, { match: { source: "organizationId", target: "organizationId" } }) when both
rows must share an org. A chain comments → issues → projects is not a cycle.
See References and parent matches.
The resource references map does not create an FK; it accepts legacy target
strings or explicit diagnostic opt-outs with a reason. It does not accept
{ fkTarget, label, via }. Target displayColumn chooses CMS labels.
Never FK a feature column to Better Auth tables in separate AUTH_DB.
Actions and submitted users
A nested features/projects/actions/issues/assign.ts uses
import { defineAction } from "../../.quickback/define-action.issues".
That helper binds record/whereRecord to issues. Import table values (issues, issueAssignees) from
../../.quickback/define-action, the primary helper that re-exports all tables. Use scoped db.select().from()
and documented builders, not db.query. Record binding or documented refs
loads a target through its firewall. Validate a submitted assignee's membership
with getOrgMemberRole(c.get("authDb"), input.userId, ctx.activeOrgId); scope
stamping alone does not check whether the user belongs to that organization.
See action authoring and scoped DB.
CMS entry modes are cms.access: "member" or "sysadmin"; "admin" is not
a valid mode. Org admins are organization roles, distinct from the platform
sysadmin. Choose the entry mode explicitly and retain per-table access rules.
Read next for your requirements
- Connected tables and assignment: issue tracker example.
- Field types, defaults, uniqueness: schema.
- Lifecycle states: transitions.
- Role-specific projections: views.
- Live updates and audience rules: realtime.
- Admin UI configuration: CMS, then schema registry.
Validate a connected skeleton first, then add the requested capabilities. Before calling the build complete, compare the final files against every requested permission and behavior. Compile success establishes valid definitions; runtime requests establish that the intended behavior actually works.
Definitions Overview
Understand how Quickback's security layers work together. Learn the mental model for firewall, access, guards, masking, and rate limiting to build secure APIs.
feature() — the canonical form
One function call per feature file — declare the table and its security contract together. This is the way to write Quickback features.