# What is Quickback

You write declarative definitions in TypeScript — schema, security rules, validation,
custom actions — and **the compiler** emits a production Hono application running on
Cloudflare Workers, backed by D1 or Neon.

```
feature()      ─┐
                ├─► quickback compile ─► Hono API on Cloudflare
defineAction() ─┘                       (D1 or Neon)
```

When you run `quickback compile`, it:

1. **Reads your definitions** — every `feature()`, `defineAction()`, and `defineConfig()` in your project
2. **Validates security** — firewall, access, guards, and masking are checked for consistency
3. **Generates output** — Hono routes + middleware + types + OpenAPI spec + MCP server + security artifacts
4. **Emits database migrations** — runs `drizzle-kit generate` for schema changes

A project is a `quickback/` directory:

```
quickback/
├── quickback.config.ts     # Compiler configuration (providers, options)
└── features/
    └── jobs/
        ├── jobs.ts         # feature(...) — schema + security in one call
        └── actions/
            └── close.ts    # one defineAction(...) per file
```

## Where to go next

- **[Quickstart](/start/quickstart)** — scaffold a project and reach a live local API
- **[Deploy](/start/deploy)** — `quickback deploy` provisions D1/KV/R2, applies migrations, and ships the worker in one command
- **[Define](/define)** — the DSL: schema, the security pillars, reads, writes, actions
- **[Configure](/configure)** — `quickback.config.ts`, providers, domains, bindings
- **[Use the API](/api)** — what the generated endpoints look like

The rest of this page is the vocabulary the other pages assume.

## 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 an `actions/` directory. |
| **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. One file per action: `export default defineAction({...})` in `actions/<name>.ts`. |
| **Record Action** | An action that operates on a specific record (`POST /api/v1/{resource}/:id/{action}`). Receives the record in `execute`. Example: `POST /api/v1/applications/:id/advance`. |
| **Standalone Action** | An action not tied to a specific record, signalled by a `path:` field in the action config. 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 `unsafeDb` 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`. |
| **`defineAction()`** | The function that defines one custom action. Imported from the generated per-feature helper `../.quickback/define-action`. |
| **`defineConfig()`** | The function that configures your Quickback project (runtime, database, auth providers). Lives in `quickback/quickback.config.ts`. |
| **Audit Fields** | Compiler-managed columns: `createdAt`, `createdBy`, `modifiedAt`, `modifiedBy` (plus `deletedAt`/`deletedBy` when the resource soft-deletes). You declare them with `...q.audit()` / `...q.softDelete()` in the `columns` object — required by default; the compiler owns their shape and their values. |
| **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 |
|------|-----------|
| **Compiler** | The generator behind `quickback compile`. Use the zero-setup hosted service at `compiler.quickback.dev`, or run the same compiler image locally when source policy or build availability calls for it. |
| **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`. |