# Cloud Compiler

Quickback offers two supported compiler modes. The hosted service at
`https://compiler.quickback.dev` is the zero-setup default; the same compiler
image can run locally in Docker when a project needs an entirely local trust
boundary or compile availability independent of the hosted service.

| Mode | Best for | Source path |
|---|---|---|
| Hosted compiler | Fast onboarding, CI without compiler infrastructure, automatic compiler updates | Authenticated HTTPS to `compiler.quickback.dev` |
| Local compiler | Restricted-source environments, offline development, self-managed availability | Loopback-only Docker + `QUICKBACK_API_URL` |

## How It Works

```
┌──────────────┐         ┌──────────────────────┐
│  quickback   │  POST   │  compiler.quickback   │
│  CLI         │────────▶│  .dev/compile         │
│              │         │                       │
│  Sends:      │         │  Returns:             │
│  - config    │         │  - Hono routes        │
│  - source    │◀────────│  - Drizzle migrations │
│  - DB meta   │         │  - TypeScript SDK     │
└──────────────┘         └──────────────────────┘
```

1. The CLI reads your `quickback.config.ts` and feature definitions.
2. It sends them to the cloud compiler as a JSON payload.
3. The compiler generates all backend files (routes, migrations, SDK, OpenAPI spec).
4. The CLI writes the generated files to your project.

## What the hosted compiler receives

The compile payload contains the source material needed to generate the
backend: Quickback config, feature/table definitions, authored actions and
selected project-local helpers, plus Quickback-owned Drizzle migration metadata
on incremental compiles.

That material describes application structure and behavior; it is not the
production dataset. The compiler does **not** connect to your deployed database
or receive customer rows, uploaded files, or live Worker environment values.
Keep runtime credentials in Worker secrets and reference their environment
variable names from config—do not hard-code secret values in source sent to
either compiler mode.

For most applications, schema names and access declarations are ordinary source
metadata rather than the business's core proprietary dataset. Authored action
and helper code can still contain proprietary business logic, so organizations
whose policy classifies that source as restricted can use the local compiler
without changing their definitions or generated output.

## Processing, analytics, and AI use

- Compile payloads are processed for the request. Full compiles use an isolated
  temporary work directory that is deleted in a `finally` cleanup on success or
  failure; validation compiles run in memory.
- Quickback does not retain request source or generated output as a project
  artifact on the compiler service.
- The hosted edge records operational analytics: user/organization identifiers,
  app and feature names, provider/service choices, status, counts, timing, and
  compiler version. It does **not** write source bodies or generated file
  contents to analytics. These metrics use Cloudflare Workers Analytics Engine,
  whose documented retention window is currently [three
  months](https://developers.cloudflare.com/analytics/analytics-engine/limits/#data-retention).
- The compile path does not invoke an AI model, and compile payloads or outputs
  are not used to train models.

If your policy requires that source never cross a network boundary, use the
[local compiler](/tooling/cloud-compiler/local-compiler). It uses the same
Docker image and output path as hosted compilation.

## Availability

Hosted compilation removes compiler setup from normal development. It is not a
required runtime dependency: a deployed Quickback backend continues operating
without the compiler, and builds can switch to the local compiler by setting
`QUICKBACK_API_URL=http://localhost:3000`. Teams with strict build-availability
requirements can keep the local Docker path in CI or their release runbook.

## Quick Start

```bash
# 1. Scaffold + compile interactively
mkdir my-app && cd my-app
npx @quickback-dev/cli start
```

`start` walks through template selection, scaffolding, login (only when needed), and the first compile in one flow. Or do it scriptably:

```bash
npm install -g @quickback-dev/cli
quickback create cloudflare my-app
cd my-app
quickback compile   # prompts for login on the first run
```

## Existing Databases

When recompiling an existing project, the CLI automatically sends your Drizzle meta files so the compiler generates **incremental** migrations instead of fresh `CREATE TABLE` statements.

Meta files are loaded from `<project>/quickback/drizzle/` only — Quickback owns this state and never reads from a project-root `drizzle/` folder:
- `quickback/drizzle/auth/meta/`
- `quickback/drizzle/features/meta/`
- `quickback/drizzle/files/meta/`
- `quickback/drizzle/webhooks/meta/`
- `quickback/drizzle/audit/meta/`
- `quickback/drizzle/meta/` (single-database mode)

Migration and report artifacts are written to the `quickback/` state directory:
- `quickback/drizzle/...` for Drizzle migration SQL/meta artifacts
- `quickback/reports/...` for security contract report artifacts

No extra configuration needed — the CLI handles this automatically.

## Next Steps

- [CLI Reference](/tooling/cli) — All CLI commands
- [Authentication](/tooling/cloud-compiler/authentication) — Login flow and API keys
- [Endpoints](/tooling/cloud-compiler/endpoints) — Compiler API reference
- [Troubleshooting](/tooling/cloud-compiler/troubleshooting) — Common issues
- [Local Compiler](/tooling/cloud-compiler/local-compiler) — Use the same compiler image locally or in restricted-source environments