# Glossary

Quick reference for terms used across the Quickback documentation.

## Core Concepts

| Term | Definition |
|------|-----------|
| **Feature** | A directory in `quickback/features/` containing related tables and actions. Example: a `candidates` feature with `candidates.ts`, `candidate-notes.ts`, and `actions.ts`. |
| **Resource** | A table with a `defineTable()` default export. Each resource gets its own CRUD API endpoints (`GET`, `POST`, `PATCH`, `DELETE`, plus batch operations). Example: `candidates.ts` with `defineTable()` generates `/api/v1/candidates`. |
| **Internal Table** | A Drizzle table exported WITHOUT `defineTable()`. Used as supporting data (junction tables, lookup tables) — no API routes generated. |
| **Definition** | A TypeScript file in `quickback/features/` that defines a table schema and/or security configuration. |
| **Compilation** | The process of transforming your definitions into production-ready code: routes, middleware, types, and migrations. |

## Security Layers

| Term | Definition |
|------|-----------|
| **Firewall** | Row-level data isolation. Automatically adds WHERE clauses (e.g., `WHERE organizationId = ?`) to every query so users only see data they should. |
| **Access** | CRUD operation permissions. Controls which roles can perform list, get, create, update, and delete operations. |
| **Guards** | Field-level write protection. Controls which fields can be set on create (`createable`), modified on update (`updatable`), changed only via actions (`protected`), or never changed after creation (`immutable`). |
| **Masking** | Field-level read protection. Redacts sensitive values (SSN, email, phone) in API responses based on the user's role. |
| **Views** | Column-level projections. Named subsets of fields (e.g., "summary", "full") with their own access control. Accessed via `GET /api/v1/{resource}/views/{name}`. |

## Actions

| Term | Definition |
|------|-----------|
| **Action** | Custom business logic endpoint beyond CRUD. Defined with `defineActions()` in an `actions.ts` file. |
| **Record Action** | An action that operates on a specific record (`POST /api/v1/{resource}/:id/{action}`). Receives the record in the handler. Example: `POST /api/v1/applications/:id/advance-stage`. |
| **Standalone Action** | An action not tied to a specific record (`POST /api/v1/{resource}/{action}`). Used for hiring reports, AI resume screening, bulk candidate imports. |
| **Scoped DB** | The security-filtered database handle passed to action handlers. Automatically applies firewall, soft-delete, and org isolation. |
| **Unsafe Mode** | When an action enables `unsafe` (prefer object form), it receives `rawDb` for explicit admin/cross-tenant operations. Cross-tenant mode requires admin role + audit trail. |

## Configuration

| Term | Definition |
|------|-----------|
| **`defineTable()`** | The function that combines a Drizzle schema with security configuration. Imported from `@quickback/compiler`. |
| **`defineActions()`** | The function that defines custom actions for a table. Imported from `@quickback/compiler`. |
| **`defineConfig()`** | The function that configures your Quickback project (runtime, database, auth providers). Lives in `quickback/quickback.config.ts`. |
| **Audit Fields** | Auto-injected columns: `createdAt`, `createdBy`, `modifiedAt`, `modifiedBy`, `deletedAt`, `deletedBy`. You don't define these — the compiler adds them. |
| **Soft Delete** | Default delete behavior. Sets `deletedAt` instead of removing the row. Soft-deleted records are filtered from queries automatically. |
| **Hard Delete** | Permanent row removal. Configured per-resource with `delete: { mode: "hard" }`. |

## Infrastructure

| Term | Definition |
|------|-----------|
| **Cloud Compiler** | The remote compilation service at `compiler.quickback.dev`. The CLI sends your definitions and receives generated code back. |
| **Stack** | The runtime infrastructure (Cloudflare Workers, D1, KV, R2, Better Auth) where your compiled API runs. |
| **Template** | A pre-configured project starter (`cloudflare`, `bun`, `turso`) created by `quickback create`. |
