Quickback Docs

Connected issue tracker example

A complete feature with tenant-safe foreign keys, reporter-or-assignee editing, validated assignment, transitions, views, and realtime.

This project uses organization roles for workspace membership and a scoped update action for reporter-or-assignee editing. Members edit issues they reported or are assigned to; admins manage all workspace data through the API. The CMS is restricted to platform sysadmins (cms.access: "sysadmin"); "admin" is not a CMS access mode. The reporter is the verified createdBy, never a client-selected identity. Workflow advancement and assignment are admin operations in this example. Every FK shares its organization with its target. Better Auth users stay in AUTH_DB; no feature-table SQL FK points there.

Copy the files below together. The configuration is applied to the following multi-file feature by the doc compile gate, including its actual imports. The update action uses a strict input contract and persists the change; it is not a no-op authorization stub.

// quickback.config.ts
import { defineConfig } from "@quickback/compiler";
export default defineConfig({
  name: "issue-tracker", template: "hono", account: true,
  cms: { access: "sysadmin", sysadmin: true },
  features: { organizations: true },
  auth: { roleHierarchy: ["member", "admin", "owner"] },
  providers: {
    runtime: { name: "cloudflare", config: {} },
    database: { name: "cloudflare-d1", config: { splitDatabases: true, authBinding: "AUTH_DB", featuresBinding: "DB" } },
    auth: { name: "better-auth", config: { emailAndPassword: { enabled: true } } },
  },
});
// features/projects/projects.ts
import { feature, q } from "@quickback/compiler";

export default feature("projects", {
  columns: {
    id: q.id(), organizationId: q.scope("organization"),
    ...q.audit(), ...q.softDelete(),
    name: q.text().required(),
  },
  guards: { createable: ["name"], updatable: ["name"] },
  read: { access: { roles: ["member+"] } },
  create: { access: { roles: ["admin+"] } }, update: { access: { roles: ["admin+"] } }, delete: { access: { roles: ["admin+"] } },
  displayColumn: "name",
});

// features/projects/issues.ts
import { feature, q } from "@quickback/compiler";
import projects from "./projects";
export default feature("issues", {
  columns: {
    id: q.id(), organizationId: q.scope("organization"),
    ...q.audit(), ...q.softDelete(),
    projectId: q.text().required().references(() => projects.id, { match: { source: "organizationId", target: "organizationId" } }),
    title: q.text().required(), description: q.text().optional(),
    status: q.enum(["backlog", "ready", "in_progress", "done"]).default("backlog").required(),
  },
  guards: { createable: ["projectId", "title", "description"], updatable: ["title", "description"],
    protected: { status: ["ready", "start", "finish"] } },
  read: { access: { roles: ["member+"] }, defaultView: "summary", views: {
    summary: { fields: ["id", "projectId", "title", "status", "createdBy"], access: { roles: ["member+"] } },
    admin: { fields: ["id", "projectId", "title", "description", "status", "createdBy", "createdAt", "modifiedAt"], access: { roles: ["admin+"] } },
  } },
  create: { access: { roles: ["member+"] } },
  update: { access: { roles: ["member+"] }, action: "edit" },
  delete: { access: { roles: ["admin+"] } },
  transitions: {
    ready: { field: "status", from: "backlog", to: "ready", access: { roles: ["admin+"] } },
    start: { field: "status", from: "ready", to: "in_progress", access: { roles: ["admin+"] } },
    finish: { field: "status", from: "in_progress", to: "done", access: { roles: ["admin+"] } },
  },
  realtime: { enabled: true, emitFromActions: true, access: { roles: ["member+"] } },
  displayColumn: "title",
});

// features/projects/comments.ts
import { feature, q } from "@quickback/compiler";
import issues from "./issues";
export default feature("comments", {
  columns: {
    id: q.id(), organizationId: q.scope("organization"),
    ...q.audit(), ...q.softDelete(),
    issueId: q.text().required().references(() => issues.id, { match: { source: "organizationId", target: "organizationId" } }),
    body: q.text().required(),
  },
  guards: { createable: ["issueId", "body"], updatable: ["body"] },
  read: { access: { roles: ["member+"] } },
  create: { access: { roles: ["member+"] } },
  update: { access: { or: [{ roles: ["admin+"] }, { roles: ["member+"], record: { createdBy: { equals: "$ctx.userId" } } }] } },
  delete: { access: { roles: ["admin+"] } },
  realtime: { enabled: true, emitFromActions: true, access: { roles: ["member+"] } }, displayColumn: "body",
});

// features/projects/labels.ts
import { feature, q } from "@quickback/compiler";

export default feature("labels", {
  columns: {
    id: q.id(), organizationId: q.scope("organization"),
    ...q.audit(), ...q.softDelete(),
    name: q.text().required(),
  },
  guards: { createable: ["name"], updatable: ["name"] },
  read: { access: { roles: ["member+"] } },
  create: { access: { roles: ["admin+"] } }, update: { access: { roles: ["admin+"] } }, delete: { access: { roles: ["admin+"] } },
  displayColumn: "name",
});

// features/projects/issueLabels.ts
import { feature, q } from "@quickback/compiler";
import issues from "./issues";
import labels from "./labels";
export default feature("issueLabels", {
  columns: {
    id: q.id(), organizationId: q.scope("organization"),
    ...q.audit(), ...q.softDelete(),
    issueId: q.text().required().references(() => issues.id, { match: { source: "organizationId", target: "organizationId" } }),
    labelId: q.text().required().references(() => labels.id, { match: { source: "organizationId", target: "organizationId" } }),
  },
  guards: { createable: ["issueId", "labelId"], updatable: [] },
  unique: [{ columns: ["issueId", "labelId"], whereNotDeleted: true }],
  read: { access: { roles: ["member+"] } },
  create: { access: { roles: ["admin+"] } }, update: { access: { roles: ["admin+"] } }, delete: { access: { roles: ["admin+"] } },
  displayColumn: "id",
});

// features/projects/issueAssignees.ts
import { feature, q } from "@quickback/compiler";
import issues from "./issues";
export default feature("issueAssignees", {
  columns: {
    id: q.id(), organizationId: q.scope("organization"),
    ...q.audit(), ...q.softDelete(),
    issueId: q.text().required().references(() => issues.id, { match: { source: "organizationId", target: "organizationId" } }),
    userId: q.text().required(),
  },
  guards: { createable: [], updatable: [], immutable: ["issueId", "userId"] },
  unique: [{ columns: ["issueId", "userId"], whereNotDeleted: true }],
  read: { access: { roles: ["member+"] } },
  create: { access: { roles: ["NONE"] } }, update: { access: { roles: ["NONE"] } },
  delete: { access: { roles: ["admin+"] } }, displayColumn: "id",
});

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

export default defineAction({
  description: "Assign an organization member to this issue",
  input: z.object({ userId: z.string().min(1) }),
  output: row(issueAssignees),
  access: { roles: ["admin+"] },
  async execute({ db, record, input, ctx, c }) {
    const role = await getOrgMemberRole(c.get("authDb"), input.userId, ctx.activeOrgId!);
    if (!role) throw new ActionError("Assignee is not an organization member", "NOT_A_MEMBER", 400);
    // record was loaded through the issue firewall; scope/audit values are stamped.
    const [assignment] = await db.insert(issueAssignees)
      .values({ issueId: record.id, userId: input.userId }).returning();
    return assignment;
  },
  ui: { label: "Assign member", onSuccess: "refresh" },
});
// features/projects/actions/issues/edit.ts
import { z } from "zod";
import { and, eq } from "drizzle-orm";
import { ActionError } from "@quickback/compiler";
import { defineAction } from "../../.quickback/define-action.issues";
import { row, issues, issueAssignees } from "../../.quickback/define-action";

export default defineAction({
  description: "Edit an issue as its reporter, assignee, or workspace admin",
  input: z.object({ title: z.string().min(1).optional(), description: z.string().optional() }).strict(),
  output: row(issues),
  access: { roles: ["member+"] },
  async execute({ db, record, input, ctx, whereRecord }) {
    const admin = ctx.roles?.some((role) => role === "admin" || role === "owner");
    if (!admin && record.createdBy !== ctx.userId) {
      const [assignment] = await db.select({ id: issueAssignees.id }).from(issueAssignees)
        .where(and(eq(issueAssignees.issueId, record.id), eq(issueAssignees.userId, ctx.userId!))).limit(1);
      if (!assignment) throw new ActionError("Only the reporter or an assignee may edit", "ISSUE_EDIT_DENIED", 403);
    }
    const [updated] = await db.update(issues).set(input).where(whereRecord!(issues)).returning();
    return updated;
  },
});

A relationship role currently compares the same named column on the consuming row and relationship table. resource.column: "issueId" does not map issues.id to issueAssignees.issueId; using that role directly here denies assignee edits. The scoped update action above expresses that join explicitly. Keep the edit action’s outer access at member+: a reporter-only record gate would reject assignees before execute can check the junction, and admins need an explicit bypass inside execute. Keep these three cases intact. Use output: row(issues) for a returned row instead of inventing non-null Zod fields for nullable audit values.

Its strict input excludes status, scope, reporter, and audit fields, because a mapped action owns its input contract rather than the generated CRUD guards. It also suppresses batch update routes that would bypass its policy. emitFromActions: true makes scoped action writes publish realtime changes after commit; enabled alone covers generated CRUD broadcasts.

The generated helper exports every table in this feature. The assignment action is bound to sibling issues by its directory, loads the issue through its firewall, validates the submitted user's org membership, and writes the junction through the scoped DB. Direct junction creates/updates are denied so callers cannot skip that validation. A duplicate live assignment returns a uniqueness error; deleting a junction row permits reassignment through the partial index.

The graph comments → issues → projects is acyclic. displayColumn controls labels; column .references() and match control integrity. The resource references map is unnecessary here. See schema, relationship roles, and scoped DB.

Validate runtime behavior independently: reporter and assignee edits succeed; unrelated members and other organizations cannot edit; out-of-org assignees and cross-org parent pointers fail without writes; valid workflow steps persist; direct status changes and invalid transitions fail. CMS/view/realtime settings compiling does not establish a browser or subscription test.