Quickback Docs

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 issues

Table 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.

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.

On this page