Common Patterns

Recipes for common Quickback scenarios — public/private data, user-scoped resources, multi-table features, and more.

Quick recipes for common scenarios. Each pattern shows the complete defineTable configuration.

Team-Wide Read, Manager-Only Write

A job board where all team members can browse open positions but only hiring managers can create or edit jobs:

// quickback/features/jobs/jobs.ts
export default defineTable(jobs, {
  firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
  guards: {
    createable: ["title", "department", "status", "salaryMin", "salaryMax"],
    updatable: ["title", "department", "status"],
  },
  read: {
    access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] },
  },
  create: { access: { roles: ["owner", "hiring-manager"] } },
  update: { access: { roles: ["owner", "hiring-manager"] } },
  delete: { access: { roles: ["owner", "hiring-manager"] } },
});

User-Scoped Personal Data

Interview notes that belong to a specific interviewer. Each interviewer only sees their own notes:

// Schema includes both organizationId AND ownerId (q DSL)
import { q, defineTable } from "@quickback/compiler";

export const interviewNotes = q.table("interview_notes", {
  id:             q.id(),
  candidateId:    q.text().required(),
  content:        q.text().required(),
  rating:         q.int().optional(),
  organizationId: q.scope("organization"),
  ownerId:        q.text().required(),
});

export default defineTable(interviewNotes, {
  firewall: [
    { field: 'organizationId', equals: 'ctx.activeOrgId' },
    { field: 'ownerId',        equals: 'ctx.userId' },  // Only the interviewer can see their own notes
  ],
  guards: {
    createable: ["candidateId", "content", "rating"],
    updatable: ["content", "rating"],
  },
  read: {
    access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] },
  },
  create: { access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] } },
  update: { access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] } },
  delete: { access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] } },
});

The owner predicate ({ field: 'ownerId', equals: 'ctx.userId' }) means even hiring managers can only see notes they authored. To let hiring managers see all notes regardless of author, drop the owner predicate from the firewall and gate per-id access via record conditions instead.

Multi-Table Feature with Internal Tables

A feature with a main table exposed via API and a junction table used only in actions:

// quickback/features/applications/applications.ts — exposed via API
export default defineTable(applications, {
  firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
  guards: {
    createable: ["candidateId", "jobId", "stage", "notes"],
    updatable: ["notes"],
  },
  read: {
    access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] },
  },
  create: { access: { roles: ["owner", "hiring-manager", "recruiter"] } },
  update: { access: { roles: ["owner", "hiring-manager", "recruiter"] } },
  delete: { access: { roles: ["owner", "hiring-manager"] } },
});

// quickback/features/applications/interview-scores.ts — internal, no API routes
// No default export = no routes generated
export const interviewScores = sqliteTable("interview_scores", {
  applicationId: text("application_id").notNull(),
  interviewerId: text("interviewer_id").notNull(),
  score: integer("score").notNull(),
  feedback: text("feedback"),
  organizationId: text("organization_id").notNull(),  // Always scope junction tables
});

// quickback/features/applications/actions.ts — uses the internal table
import { z } from "zod";
import { defineActions } from "@quickback/compiler";
import { applications } from "./applications";
import { interviewScores } from "./interview-scores";

export default defineActions(applications, {
  // No `path:` → record-based action, mounted at POST /applications/:id/submitScore
  submitScore: {
    input: z.object({ score: z.number().min(1).max(5), feedback: z.string() }),
    access: { roles: ["owner", "hiring-manager", "interviewer"] },
    execute: async ({ db, record, input, ctx }) => {
      // The scoped db auto-injects organizationId (and audit fields) on insert.
      await db.insert(interviewScores).values({
        applicationId: record.id,
        interviewerId: ctx.userId,
        score: input.score,
        feedback: input.feedback,
      });
      return record;
    },
  },
});

Referencing Users / Org Members (Assignees)

Assignee-style features need to validate that a submitted userId is actually a member of the caller's organization. The scoped db only sees feature tables — reach the Better Auth tables via c.get("authDb") and the generated getOrgMemberRole helper:

// quickback/features/projects/actions/assign.ts
import { z } from "zod";
import { ActionError } from "@quickback/compiler";
import { defineAction } from "../.quickback/define-action";
import { getOrgMemberRole } from "../../../lib/org-access";
import { projects } from "../projects";

export default defineAction({
  description: "Assign a project to an org member",
  input: z.object({ assigneeId: z.string() }),
  access: { roles: ["member+"] },  // "+" requires auth.roleHierarchy in quickback.config.ts
  async execute({ db, record, input, ctx, c, whereRecord }) {
    const role = await getOrgMemberRole(c.get("authDb"), input.assigneeId, ctx.activeOrgId!);
    if (!role) {
      throw new ActionError("Assignee is not a member of this organization", "NOT_A_MEMBER", 400);
    }
    const [updated] = await db
      .update(projects)
      .set({ assigneeId: input.assigneeId })
      .where(whereRecord!(projects))
      .returning();
    return updated;
  },
});

Store the assignee as a plain text column (e.g. assigneeId: q.text().optional()) — don't name it userId, which the firewall validator treats as an ownership column on feature tables.

Admin-Only Status Field

A field that only hiring managers can modify, but everyone can see:

export default defineTable(applications, {
  firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
  guards: {
    createable: ["candidateId", "jobId", "notes"],
    updatable: ["notes"],                       // Recruiters can only update notes
    protected: { stage: ["advanceStage"] },     // Stage only changes via the named action
  },
  read: {
    access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] },
  },
  create: { access: { roles: ["owner", "hiring-manager", "recruiter"] } },
  update: { access: { roles: ["owner", "hiring-manager", "recruiter"] } },
  delete: { access: { roles: ["hiring-manager"] } },
});

Then create an action that hiring managers use to change stage:

// quickback/features/applications/actions.ts
export default defineActions(applications, {
  advanceStage: {
    input: z.object({ stage: z.enum(["applied", "screening", "interview", "offer", "hired", "rejected"]) }),
    access: { roles: ["hiring-manager"] },
    execute: async ({ db, record, input }) => {
      await db.update(applications).set({ stage: input.stage }).where(eq(applications.id, record.id));
      return { ...record, stage: input.stage };
    },
  },
});

Sensitive Data with Role-Based Masking

A candidate record where PII is masked differently per role:

export default defineTable(candidates, {
  firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
  guards: {
    createable: ["name", "email", "phone", "resumeUrl", "source"],
    updatable: ["name", "phone"],
  },
  masking: {
    email: { type: "email", show: { roles: ["hiring-manager", "recruiter"] } },
    phone: { type: "phone", show: { roles: ["hiring-manager", "recruiter"] } },
  },
  read: {
    access: { roles: ["owner", "hiring-manager", "recruiter", "interviewer"] },
  },
  create: { access: { roles: ["hiring-manager", "recruiter"] } },
  update: { access: { roles: ["hiring-manager", "recruiter"] } },
  delete: { access: { roles: ["hiring-manager"] } },
});

Role	email	phone
hiring-manager	`jane@example.com`	`555-123-4567`
recruiter	`jane@example.com`	`555-123-4567`
interviewer	`j*@e****.com`	`*-*-4567`

External System Sync

An import table for syncing candidates from an external ATS via upsert:

// quickback/features/ats-imports/ats-imports.ts
export default defineTable(atsImports, {
  firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
  guards: {
    createable: ["externalId", "source", "candidateName", "candidateEmail", "rawPayload"],
    updatable: ["candidateName", "candidateEmail", "rawPayload", "syncedAt"],
  },
  read: {
    access: { roles: ["owner", "hiring-manager"] },
  },
  create: { access: { roles: ["owner", "hiring-manager"] } },
  update: { access: { roles: ["owner", "hiring-manager"] } },
  delete: { access: { roles: ["owner"] } },
});