Definitions Overview

Before diving into specific features, let's understand how Quickback's pieces connect. This page gives you the mental model for everything that follows.

The Big Picture

Quickback is a backend compiler. You write definition files, and Quickback compiles them into a production-ready API.

1. You write definitions - Table files with schema and security config using defineTable
2. Quickback compiles them - Analyzes your definitions at build time
3. You get a production API - GET /jobs, POST /jobs, PATCH /jobs/:id, DELETE /jobs/:id, batch operations, plus custom actions

File Structure

Your definitions live in a quickback/features/ folder organized by feature:

my-app/
├── quickback/
│   ├── quickback.config.ts    # Compiler configuration
│   └── features/
│       └── {feature-name}/
│           ├── candidates.ts       # Table + config (defineTable)
│           ├── applications.ts     # Secondary table + config
│           ├── interview-scores.ts # Internal table (no routes)
│           ├── actions.ts          # Custom actions (optional)
│           └── handlers/           # Action handlers (optional)
│               └── advance-stage.ts
├── src/                       # Generated code (output)
└── package.json

Table files use defineTable to combine schema and security config:

// features/candidates/candidates.ts
import { sqliteTable, text } from "drizzle-orm/sqlite-core";
import { defineTable } from "@quickback/compiler";

export const candidates = sqliteTable("candidates", {
  id: text("id").primaryKey(),
  organizationId: text("organization_id").notNull(),
  name: text("name").notNull(),
  email: text("email").notNull(),
  phone: text("phone"),
  source: text("source"),
});

export default defineTable(candidates, {
  firewall: [{ field: 'organizationId', equals: 'ctx.activeOrgId' }],
  guards: {
    createable: ["name", "email", "phone", "source"],
    updatable: ["name", "phone"],
  },
  masking: {
    email: { type: 'email', show: { roles: ['owner', 'hiring-manager', 'recruiter'] } },
    phone: { type: 'phone', show: { roles: ['owner', 'hiring-manager', 'recruiter'] } },
  },
  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"] } },
});

export type Candidate = typeof candidates.$inferSelect;

Key points:

• Tables with export default defineTable(...) → resource routes generated
• Tables without default export → internal/junction tables (no routes)
• Route path derived from filename: applications.ts → /api/v1/applications

The Four Security Layers

Every API request passes through four security layers, in order:

Request → Firewall → Access → Guards → Masking → Response
            │          │        │         │
            │          │        │         └── Hide sensitive fields
            │          │        └── Block field modifications
            │          └── Check roles & conditions
            └── Isolate data by owner/org/team

1. Firewall (Data Isolation)

The firewall controls which records a user can see. It automatically adds WHERE clauses to every query based on your schema columns:

No manual configuration needed - Quickback applies smart rules based on your schema.

For relationship-based row visibility (e.g. "user can see this event because they have a confirmed event_guests row pointing at it"), declare the relationship under authz.relationships and reference it from the firewall with a via: predicate. See Firewall → Relationship-based scoping.

Learn more about Firewall →

2. Access (CRUD Permissions)

Access controls which operations a user can perform. It checks roles and record conditions. Reads (GET / and GET /:id) live under read:; writes live under top-level create:, update:, delete:, and upsert:.

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"] } },

Learn more about Access →

3. Guards (Field Modification Rules)

Guards control which fields can be modified in each operation.

Learn more about Guards →

4. Masking (Data Redaction)

Masking hides sensitive fields from users who shouldn't see them.

masking: {
  email: { type: 'email' },       // Shows: j***@e******.com
  phone: { type: 'phone' },       // Shows: ******4567
  salary: { type: 'redact' },     // Shows: [REDACTED]
}

Learn more about Masking →

How They Work Together

Scenario: An interviewer requests GET /candidates/cnd_123

1. Firewall checks: Is candidate cnd_123 in the user's organization?

   • Yes → Continue
   • No → 404 Not Found (as if it doesn't exist)

2. Access checks: Can interviewers perform GET?

   • Yes → Continue
   • No → 403 Forbidden

3. Guards don't apply to GET (they're for writes)

4. Masking applies: User is an interviewer, not recruiter or hiring-manager

   • Email: jane@company.com → j***@c******.com
   • Phone: 555-123-4567 → ******4567

5. Response sent with masked data

Locked Down by Default

Quickback is secure by default. Nothing is accessible until you explicitly allow it.

You must deliberately open each door. This prevents accidental data exposure.

Other Resource Options

Beyond the four security layers, defineTable accepts a handful of declarative hints that shape the generated API and the CMS without touching your security posture.

All options are optional — omit them and Quickback uses sensible defaults (auto-detected display column, auto-grouped layout, no embeddings, no realtime).

Next Steps

1. Database Schema — Define your tables
2. Firewall — Set up data isolation
3. Access — Configure read and write permissions
4. Guards — Control field modifications
5. Masking — Hide sensitive data
6. Views — Column-level security
7. Validation — Field validation rules
8. Actions — Add custom business logic