@quickback-dev/cli 0.10.15 → 0.10.20

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (249) hide show
  1. package/dist/commands/compile.d.ts.map +1 -1
  2. package/dist/commands/compile.js +40 -2
  3. package/dist/commands/compile.js.map +1 -1
  4. package/dist/docs/content.js +6 -6
  5. package/dist/docs/content.js.map +1 -1
  6. package/dist/index.js +1 -1
  7. package/dist/skill/SKILL.md +142 -1051
  8. package/dist/skill/agents/quickback-specialist/AGENT.md +36 -0
  9. package/dist/skill/docs/changelog.md +1192 -0
  10. package/dist/skill/docs/compiler/claude-code-skill.md +312 -0
  11. package/dist/skill/docs/compiler/cloud-compiler/authentication.md +63 -0
  12. package/dist/skill/docs/compiler/cloud-compiler/cli.md +307 -0
  13. package/dist/skill/docs/compiler/cloud-compiler/endpoints.md +78 -0
  14. package/dist/skill/docs/compiler/cloud-compiler/index.md +65 -0
  15. package/dist/skill/docs/compiler/cloud-compiler/local-compiler.md +115 -0
  16. package/dist/skill/docs/compiler/cloud-compiler/troubleshooting.md +76 -0
  17. package/dist/skill/docs/compiler/config/agents.md +144 -0
  18. package/dist/skill/docs/compiler/config/auth.md +109 -0
  19. package/dist/skill/docs/compiler/config/bindings.md +176 -0
  20. package/dist/skill/docs/compiler/config/domains.md +149 -0
  21. package/dist/skill/docs/compiler/config/index.md +419 -0
  22. package/dist/skill/docs/compiler/config/output.md +338 -0
  23. package/dist/skill/docs/compiler/config/providers.md +248 -0
  24. package/dist/skill/docs/compiler/config/security.md +255 -0
  25. package/dist/skill/docs/compiler/config/single-tenant.md +128 -0
  26. package/dist/skill/docs/compiler/config/variables.md +157 -0
  27. package/dist/skill/docs/compiler/definitions/access.md +445 -0
  28. package/dist/skill/docs/compiler/definitions/actions.md +884 -0
  29. package/dist/skill/docs/compiler/definitions/concepts.md +52 -0
  30. package/dist/skill/docs/compiler/definitions/feature.md +164 -0
  31. package/dist/skill/docs/compiler/definitions/firewall.md +285 -0
  32. package/dist/skill/docs/compiler/definitions/guards.md +241 -0
  33. package/dist/skill/docs/compiler/definitions/index.md +219 -0
  34. package/dist/skill/docs/compiler/definitions/masking.md +241 -0
  35. package/dist/skill/docs/compiler/definitions/read.md +220 -0
  36. package/dist/skill/docs/compiler/definitions/schema.md +697 -0
  37. package/dist/skill/docs/compiler/definitions/validation.md +35 -0
  38. package/dist/skill/docs/compiler/definitions/views.md +292 -0
  39. package/dist/skill/docs/compiler/getting-started/claude-code.md +126 -0
  40. package/dist/skill/docs/compiler/getting-started/full-example.md +431 -0
  41. package/dist/skill/docs/compiler/getting-started/hand-crafted.md +178 -0
  42. package/dist/skill/docs/compiler/getting-started/index.md +192 -0
  43. package/dist/skill/docs/compiler/getting-started/patterns.md +225 -0
  44. package/dist/skill/docs/compiler/getting-started/template-blog.md +280 -0
  45. package/dist/skill/docs/compiler/getting-started/template-cloudflare.md +260 -0
  46. package/dist/skill/docs/compiler/getting-started/template-empty.md +112 -0
  47. package/dist/skill/docs/compiler/getting-started/templates.md +111 -0
  48. package/dist/skill/docs/compiler/index.md +85 -0
  49. package/dist/skill/docs/compiler/targets/hono-api/cloudflare.md +94 -0
  50. package/dist/skill/docs/compiler/targets/hono-api/database/d1.md +246 -0
  51. package/dist/skill/docs/compiler/targets/hono-api/database/index.md +16 -0
  52. package/dist/skill/docs/compiler/targets/hono-api/database/neon.md +144 -0
  53. package/dist/skill/docs/compiler/targets/hono-api/database/using-d1.md +39 -0
  54. package/dist/skill/docs/compiler/targets/hono-api/index.md +37 -0
  55. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +323 -0
  56. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +357 -0
  57. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/caching.md +105 -0
  58. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +652 -0
  59. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +224 -0
  60. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/index.md +37 -0
  61. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +203 -0
  62. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +199 -0
  63. package/dist/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +161 -0
  64. package/dist/skill/docs/compiler/targets/index.md +47 -0
  65. package/dist/skill/docs/compiler/targets/supabase-rls/index.md +55 -0
  66. package/dist/skill/docs/compiler/targets/supabase-rls/limitations.md +48 -0
  67. package/dist/skill/docs/compiler/targets/supabase-rls/mappings.md +99 -0
  68. package/dist/skill/docs/compiler/targets/supabase-rls/setup.md +88 -0
  69. package/dist/skill/docs/compiler/troubleshooting.md +120 -0
  70. package/dist/skill/docs/index.md +77 -0
  71. package/dist/skill/docs/stack/account-ui/customization.md +378 -0
  72. package/dist/skill/docs/stack/account-ui/environment-variables.md +325 -0
  73. package/dist/skill/docs/stack/account-ui/features/admin.md +76 -0
  74. package/dist/skill/docs/stack/account-ui/features/api-keys.md +22 -0
  75. package/dist/skill/docs/stack/account-ui/features/avatars.md +37 -0
  76. package/dist/skill/docs/stack/account-ui/features/cli-authorize.md +21 -0
  77. package/dist/skill/docs/stack/account-ui/features/index.md +291 -0
  78. package/dist/skill/docs/stack/account-ui/features/organizations.md +29 -0
  79. package/dist/skill/docs/stack/account-ui/features/passkeys.md +31 -0
  80. package/dist/skill/docs/stack/account-ui/features/passwordless.md +28 -0
  81. package/dist/skill/docs/stack/account-ui/features/sessions.md +20 -0
  82. package/dist/skill/docs/stack/account-ui/hooks.md +209 -0
  83. package/dist/skill/docs/stack/account-ui/index.md +147 -0
  84. package/dist/skill/docs/stack/account-ui/library-usage.md +257 -0
  85. package/dist/skill/docs/stack/account-ui/standalone.md +149 -0
  86. package/dist/skill/docs/stack/account-ui/with-quickback.md +160 -0
  87. package/dist/skill/docs/stack/account-ui/worker.md +362 -0
  88. package/dist/skill/docs/stack/auth/api-keys.md +15 -0
  89. package/dist/skill/docs/stack/auth/device-auth.md +14 -0
  90. package/dist/skill/docs/stack/auth/index.md +64 -0
  91. package/dist/skill/docs/stack/auth/jwt-optimization.md +245 -0
  92. package/dist/skill/docs/stack/auth/plugins/aws-ses.md +127 -0
  93. package/dist/skill/docs/stack/auth/plugins/combo-auth.md +74 -0
  94. package/dist/skill/docs/stack/auth/plugins/index.md +228 -0
  95. package/dist/skill/docs/stack/auth/plugins/upgrade-anonymous.md +155 -0
  96. package/dist/skill/docs/stack/auth/security.md +455 -0
  97. package/dist/skill/docs/stack/auth/using-auth.md +39 -0
  98. package/dist/skill/docs/stack/cms/actions.md +199 -0
  99. package/dist/skill/docs/stack/cms/components.md +479 -0
  100. package/dist/skill/docs/stack/cms/connecting.md +199 -0
  101. package/dist/skill/docs/stack/cms/dashboard.md +39 -0
  102. package/dist/skill/docs/stack/cms/index.md +158 -0
  103. package/dist/skill/docs/stack/cms/inline-editing.md +136 -0
  104. package/dist/skill/docs/stack/cms/pages.md +275 -0
  105. package/dist/skill/docs/stack/cms/record-layouts.md +151 -0
  106. package/dist/skill/docs/stack/cms/schema-format.md +437 -0
  107. package/dist/skill/docs/stack/cms/schema-registry.md +200 -0
  108. package/dist/skill/docs/stack/cms/security.md +203 -0
  109. package/dist/skill/docs/stack/cms/table-views.md +142 -0
  110. package/dist/skill/docs/stack/index.md +65 -0
  111. package/dist/skill/docs/stack/queues/handlers.md +317 -0
  112. package/dist/skill/docs/stack/queues/index.md +56 -0
  113. package/dist/skill/docs/stack/queues/using-queues.md +192 -0
  114. package/dist/skill/docs/stack/realtime/durable-objects.md +488 -0
  115. package/dist/skill/docs/stack/realtime/index.md +67 -0
  116. package/dist/skill/docs/stack/realtime/using-realtime.md +211 -0
  117. package/dist/skill/docs/stack/storage/index.md +17 -0
  118. package/dist/skill/docs/stack/storage/kv.md +204 -0
  119. package/dist/skill/docs/stack/storage/r2.md +232 -0
  120. package/dist/skill/docs/stack/storage/using-kv.md +70 -0
  121. package/dist/skill/docs/stack/storage/using-r2.md +55 -0
  122. package/dist/skill/docs/stack/vector/embeddings.md +554 -0
  123. package/dist/skill/docs/stack/vector/index.md +44 -0
  124. package/dist/skill/docs/stack/vector/using-embeddings.md +186 -0
  125. package/dist/skill/docs/stack/webhooks/inbound.md +186 -0
  126. package/dist/skill/docs/stack/webhooks/index.md +36 -0
  127. package/dist/skill/docs/stack/webhooks/outbound.md +281 -0
  128. package/package.json +1 -1
  129. package/src/skill/SKILL.md +142 -1051
  130. package/src/skill/agents/quickback-specialist/AGENT.md +36 -0
  131. package/src/skill/docs/changelog.md +1192 -0
  132. package/src/skill/docs/compiler/claude-code-skill.md +312 -0
  133. package/src/skill/docs/compiler/cloud-compiler/authentication.md +63 -0
  134. package/src/skill/docs/compiler/cloud-compiler/cli.md +307 -0
  135. package/src/skill/docs/compiler/cloud-compiler/endpoints.md +78 -0
  136. package/src/skill/docs/compiler/cloud-compiler/index.md +65 -0
  137. package/src/skill/docs/compiler/cloud-compiler/local-compiler.md +115 -0
  138. package/src/skill/docs/compiler/cloud-compiler/troubleshooting.md +76 -0
  139. package/src/skill/docs/compiler/config/agents.md +144 -0
  140. package/src/skill/docs/compiler/config/auth.md +109 -0
  141. package/src/skill/docs/compiler/config/bindings.md +176 -0
  142. package/src/skill/docs/compiler/config/domains.md +149 -0
  143. package/src/skill/docs/compiler/config/index.md +419 -0
  144. package/src/skill/docs/compiler/config/output.md +338 -0
  145. package/src/skill/docs/compiler/config/providers.md +248 -0
  146. package/src/skill/docs/compiler/config/security.md +255 -0
  147. package/src/skill/docs/compiler/config/single-tenant.md +128 -0
  148. package/src/skill/docs/compiler/config/variables.md +157 -0
  149. package/src/skill/docs/compiler/definitions/access.md +445 -0
  150. package/src/skill/docs/compiler/definitions/actions.md +884 -0
  151. package/src/skill/docs/compiler/definitions/concepts.md +52 -0
  152. package/src/skill/docs/compiler/definitions/feature.md +164 -0
  153. package/src/skill/docs/compiler/definitions/firewall.md +285 -0
  154. package/src/skill/docs/compiler/definitions/guards.md +241 -0
  155. package/src/skill/docs/compiler/definitions/index.md +219 -0
  156. package/src/skill/docs/compiler/definitions/masking.md +241 -0
  157. package/src/skill/docs/compiler/definitions/read.md +220 -0
  158. package/src/skill/docs/compiler/definitions/schema.md +697 -0
  159. package/src/skill/docs/compiler/definitions/validation.md +35 -0
  160. package/src/skill/docs/compiler/definitions/views.md +292 -0
  161. package/src/skill/docs/compiler/getting-started/claude-code.md +126 -0
  162. package/src/skill/docs/compiler/getting-started/full-example.md +431 -0
  163. package/src/skill/docs/compiler/getting-started/hand-crafted.md +178 -0
  164. package/src/skill/docs/compiler/getting-started/index.md +192 -0
  165. package/src/skill/docs/compiler/getting-started/patterns.md +225 -0
  166. package/src/skill/docs/compiler/getting-started/template-blog.md +280 -0
  167. package/src/skill/docs/compiler/getting-started/template-cloudflare.md +260 -0
  168. package/src/skill/docs/compiler/getting-started/template-empty.md +112 -0
  169. package/src/skill/docs/compiler/getting-started/templates.md +111 -0
  170. package/src/skill/docs/compiler/index.md +85 -0
  171. package/src/skill/docs/compiler/targets/hono-api/cloudflare.md +94 -0
  172. package/src/skill/docs/compiler/targets/hono-api/database/d1.md +246 -0
  173. package/src/skill/docs/compiler/targets/hono-api/database/index.md +16 -0
  174. package/src/skill/docs/compiler/targets/hono-api/database/neon.md +144 -0
  175. package/src/skill/docs/compiler/targets/hono-api/database/using-d1.md +39 -0
  176. package/src/skill/docs/compiler/targets/hono-api/index.md +37 -0
  177. package/src/skill/docs/compiler/targets/hono-api/using-the-api/actions-api.md +323 -0
  178. package/src/skill/docs/compiler/targets/hono-api/using-the-api/batch-operations.md +357 -0
  179. package/src/skill/docs/compiler/targets/hono-api/using-the-api/caching.md +105 -0
  180. package/src/skill/docs/compiler/targets/hono-api/using-the-api/crud.md +652 -0
  181. package/src/skill/docs/compiler/targets/hono-api/using-the-api/errors.md +224 -0
  182. package/src/skill/docs/compiler/targets/hono-api/using-the-api/index.md +37 -0
  183. package/src/skill/docs/compiler/targets/hono-api/using-the-api/openapi.md +203 -0
  184. package/src/skill/docs/compiler/targets/hono-api/using-the-api/query-params.md +199 -0
  185. package/src/skill/docs/compiler/targets/hono-api/using-the-api/views-api.md +161 -0
  186. package/src/skill/docs/compiler/targets/index.md +47 -0
  187. package/src/skill/docs/compiler/targets/supabase-rls/index.md +55 -0
  188. package/src/skill/docs/compiler/targets/supabase-rls/limitations.md +48 -0
  189. package/src/skill/docs/compiler/targets/supabase-rls/mappings.md +99 -0
  190. package/src/skill/docs/compiler/targets/supabase-rls/setup.md +88 -0
  191. package/src/skill/docs/compiler/troubleshooting.md +120 -0
  192. package/src/skill/docs/index.md +77 -0
  193. package/src/skill/docs/stack/account-ui/customization.md +378 -0
  194. package/src/skill/docs/stack/account-ui/environment-variables.md +325 -0
  195. package/src/skill/docs/stack/account-ui/features/admin.md +76 -0
  196. package/src/skill/docs/stack/account-ui/features/api-keys.md +22 -0
  197. package/src/skill/docs/stack/account-ui/features/avatars.md +37 -0
  198. package/src/skill/docs/stack/account-ui/features/cli-authorize.md +21 -0
  199. package/src/skill/docs/stack/account-ui/features/index.md +291 -0
  200. package/src/skill/docs/stack/account-ui/features/organizations.md +29 -0
  201. package/src/skill/docs/stack/account-ui/features/passkeys.md +31 -0
  202. package/src/skill/docs/stack/account-ui/features/passwordless.md +28 -0
  203. package/src/skill/docs/stack/account-ui/features/sessions.md +20 -0
  204. package/src/skill/docs/stack/account-ui/hooks.md +209 -0
  205. package/src/skill/docs/stack/account-ui/index.md +147 -0
  206. package/src/skill/docs/stack/account-ui/library-usage.md +257 -0
  207. package/src/skill/docs/stack/account-ui/standalone.md +149 -0
  208. package/src/skill/docs/stack/account-ui/with-quickback.md +160 -0
  209. package/src/skill/docs/stack/account-ui/worker.md +362 -0
  210. package/src/skill/docs/stack/auth/api-keys.md +15 -0
  211. package/src/skill/docs/stack/auth/device-auth.md +14 -0
  212. package/src/skill/docs/stack/auth/index.md +64 -0
  213. package/src/skill/docs/stack/auth/jwt-optimization.md +245 -0
  214. package/src/skill/docs/stack/auth/plugins/aws-ses.md +127 -0
  215. package/src/skill/docs/stack/auth/plugins/combo-auth.md +74 -0
  216. package/src/skill/docs/stack/auth/plugins/index.md +228 -0
  217. package/src/skill/docs/stack/auth/plugins/upgrade-anonymous.md +155 -0
  218. package/src/skill/docs/stack/auth/security.md +455 -0
  219. package/src/skill/docs/stack/auth/using-auth.md +39 -0
  220. package/src/skill/docs/stack/cms/actions.md +199 -0
  221. package/src/skill/docs/stack/cms/components.md +479 -0
  222. package/src/skill/docs/stack/cms/connecting.md +199 -0
  223. package/src/skill/docs/stack/cms/dashboard.md +39 -0
  224. package/src/skill/docs/stack/cms/index.md +158 -0
  225. package/src/skill/docs/stack/cms/inline-editing.md +136 -0
  226. package/src/skill/docs/stack/cms/pages.md +275 -0
  227. package/src/skill/docs/stack/cms/record-layouts.md +151 -0
  228. package/src/skill/docs/stack/cms/schema-format.md +437 -0
  229. package/src/skill/docs/stack/cms/schema-registry.md +200 -0
  230. package/src/skill/docs/stack/cms/security.md +203 -0
  231. package/src/skill/docs/stack/cms/table-views.md +142 -0
  232. package/src/skill/docs/stack/index.md +65 -0
  233. package/src/skill/docs/stack/queues/handlers.md +317 -0
  234. package/src/skill/docs/stack/queues/index.md +56 -0
  235. package/src/skill/docs/stack/queues/using-queues.md +192 -0
  236. package/src/skill/docs/stack/realtime/durable-objects.md +488 -0
  237. package/src/skill/docs/stack/realtime/index.md +67 -0
  238. package/src/skill/docs/stack/realtime/using-realtime.md +211 -0
  239. package/src/skill/docs/stack/storage/index.md +17 -0
  240. package/src/skill/docs/stack/storage/kv.md +204 -0
  241. package/src/skill/docs/stack/storage/r2.md +232 -0
  242. package/src/skill/docs/stack/storage/using-kv.md +70 -0
  243. package/src/skill/docs/stack/storage/using-r2.md +55 -0
  244. package/src/skill/docs/stack/vector/embeddings.md +554 -0
  245. package/src/skill/docs/stack/vector/index.md +44 -0
  246. package/src/skill/docs/stack/vector/using-embeddings.md +186 -0
  247. package/src/skill/docs/stack/webhooks/inbound.md +186 -0
  248. package/src/skill/docs/stack/webhooks/index.md +36 -0
  249. package/src/skill/docs/stack/webhooks/outbound.md +281 -0
@@ -1,240 +1,104 @@
1
1
  ---
2
2
  name: quickback
3
- description: Quickback API engine documentation - use when working with Quickback projects, defining resources, schemas, security pillars (Firewall, Access, Guards, Masking), actions, webhooks, or deployment
4
- allowed-tools: Read, Grep, Glob
3
+ description: Quickback documentation - use when working with Quickback projects, defining resources, schemas, security pillars (Firewall, Access, Guards, Masking), actions, the Stack runtime services, or deployment
4
+ allowed-tools: Read, Grep, Glob, Edit, Write
5
5
  ---
6
6
 
7
7
  # Quickback
8
8
 
9
- Quickback is two things:
9
+ Quickback is a **backend compiler**. Define your database schema and security rules in TypeScript; compile them into either a Hono API or PostgreSQL Row Level Security policies. Pair the output with the Quickback Stack for a complete Supabase alternative on Cloudflare.
10
10
 
11
- 1. **Compiler** — Transforms declarative TypeScript definitions into secure, production-ready APIs
12
- 2. **Stack** — A Supabase alternative running entirely on Cloudflare (D1, R2, KV, Durable Objects, Queues, Workers AI)
11
+ It's two products:
13
12
 
14
- The output is standard TypeScript (Hono, Drizzle, Better Auth) running on your own infrastructure. Not a managed platform — real code you own and control.
13
+ ## 1. Quickback Compiler — the build tool
15
14
 
16
- ## Accessing Documentation
15
+ Define schema + security in TypeScript. Compile to one of two targets:
17
16
 
18
- The fastest way to look up detailed docs is via the CLI:
17
+ - **Quickback for Hono API** — Cloudflare D1 or Neon. Full Hono application with CRUD, batch endpoints, OpenAPI, and an MCP server.
18
+ - **Quickback for Supabase** — PostgreSQL Row Level Security policies. Keep Supabase Auth, Storage, and Realtime; Quickback adds the security layer.
19
19
 
20
- ```bash
21
- quickback docs # List all available topics
22
- quickback docs <topic> # Show docs for a specific topic
23
- quickback docs firewall # Example: firewall docs
24
- quickback docs cms/record-layouts # Example: CMS record layouts
25
- ```
26
-
27
- Full online docs: https://docs.quickback.dev
28
-
29
- ---
30
-
31
- # PART 1: THE COMPILER
32
-
33
- The compiler takes your TypeScript definitions and generates API routes, middleware, migrations, typed SDKs, OpenAPI specs, and AI tool definitions.
34
-
35
- ```
36
- ┌─────────────────────────────────────────────────────────┐
37
- │ YOU DEFINE (in TypeScript) │
38
- │ • Drizzle schema (your data models) │
39
- │ • Security layers (Firewall, Access, Guards, Masking) │
40
- │ • Views, Validation, Layouts │
41
- │ • Actions (your business operations) │
42
- ├─────────────────────────────────────────────────────────┤
43
- │ QUICKBACK COMPILES TO │
44
- │ • Database migrations (via Drizzle) │
45
- │ • API route handlers (Hono) │
46
- │ • Typed client SDK for your frontend │
47
- │ • AI tool definitions │
48
- │ • OpenAPI specification │
49
- └─────────────────────────────────────────────────────────┘
50
- ```
51
-
52
- ## Project Structure
20
+ The same `defineTable()` definitions work for both targets. The compiler runs as a remote service at `compiler.quickback.dev` (override with `QUICKBACK_API_URL`) — the CLI is a thin client that sends config + features and writes the generated files.
53
21
 
54
- ```
55
- my-app/
56
- ├── quickback/
57
- │ ├── quickback.config.ts
58
- │ └── features/
59
- │ └── {feature-name}/
60
- │ ├── {table}.ts # Schema + security (defineTable)
61
- │ ├── actions/ # One file per action — defineAction({...})
62
- │ │ ├── {action}.ts # Binds to primary table (or standalone if path: is set)
63
- │ │ └── {table}/{action}.ts # Binds to sibling <table>.ts (multi-table features)
64
- │ ├── lib/ # Feature-local helpers, copied verbatim (optional)
65
- │ └── pages/ # Custom CMS pages (optional)
66
- │ └── {slug}.ts # definePage() call
67
- ├── src/ # ← compiled output
68
- │ ├── index.ts # API entry (Hono)
69
- │ └── apps/
70
- │ ├── cms/ # ← CMS static assets (when cms: true)
71
- │ │ ├── index.html
72
- │ │ └── assets/
73
- │ └── account/ # ← Account UI assets (when account: true/object)
74
- │ ├── index.html
75
- │ └── assets/
76
- └── ...
77
- ```
78
-
79
- ## quickback.config.ts
80
-
81
- ```typescript
82
- import { defineConfig, defineRuntime, defineDatabase, defineAuth } from '@quickback/compiler';
83
-
84
- export default defineConfig({
85
- name: "my-saas-app",
86
- cms: true, // Embed CMS admin UI in compiled Worker (or { domain: "cms.example.com" })
87
- account: { // Embed Account UI (auth, profile, orgs, admin) in compiled Worker
88
- domain: "auth.example.com", // Optional: custom domain (served at / instead of /account/)
89
- adminDomain: "admin.example.com", // Optional: separate admin domain
90
- name: "My App",
91
- companyName: "My Company",
92
- tagline: "Build faster, ship sooner",
93
- build: true, // Set false to skip SPA rebuild on subsequent compiles
94
- auth: {
95
- password: true, // Email/password login (default: true)
96
- emailOTP: true, // Email OTP login (default: false)
97
- passkey: true, // WebAuthn passkeys (default: false)
98
- signup: true, // User registration (default: true)
99
- organizations: true, // Multi-tenant org management UI (default: false; the orgs plugin itself is enabled by `features.organizations` which defaults true)
100
- admin: true, // Admin panel (default: true)
101
- emailVerification: true, // Require email verification (default: true)
102
- },
103
- },
104
- providers: {
105
- runtime: defineRuntime("cloudflare"),
106
- database: defineDatabase("cloudflare-d1"),
107
- auth: defineAuth("better-auth"),
108
- },
109
- build: {
110
- outputDir: "dist",
111
- dependencies: {
112
- "fast-xml-parser": "^4.5.0", // Third-party packages used in action handlers
113
- },
114
- },
115
- });
116
- ```
22
+ ## 2. Quickback Stack — the runtime services
117
23
 
118
- Minimal: `account: true` enables with all defaults. `account: { build: false }` skips rebuild on subsequent compiles.
24
+ Everything you need around the compiled API for a complete Supabase alternative on Cloudflare:
119
25
 
120
- ### Discoverable options block
26
+ | Service | What it gives you | Implementation |
27
+ |---|---|---|
28
+ | **Auth** | Email OTP, passkeys, password, Google OAuth, organizations, admin | Better Auth |
29
+ | **Storage** | KV (sessions, cache) and R2 (files) | Cloudflare KV + R2 |
30
+ | **Realtime** | WebSocket for live updates | Durable Objects |
31
+ | **Queues** | Background jobs, webhook delivery | Cloudflare Queues |
32
+ | **Vector & AI** | Embeddings, semantic search | Workers AI |
33
+ | **Webhooks** | Signed inbound, retried outbound | Hono + Queues |
34
+ | **CMS** | Schema-driven admin UI | Embedded SPA |
35
+ | **Account UI** | Login, profile, orgs, admin | Embedded SPA |
121
36
 
122
- After the first compile, the file gets a managed comment block bracketed by `// [quickback:options-start]` … `// [quickback:options-end]`. Every option Quickback supports is listed there as a commented-out line. To enable one, lift the line **above** the start sentinel and uncomment — Quickback notices and drops it from the managed block on the next compile to avoid duplicates. Anything outside the sentinels is yours and never touched. Skip with `quickback compile --no-sync-config`.
37
+ Everything runs on the user's own Cloudflare account — no Quickback infrastructure between them and their data.
123
38
 
124
- ### Custom bindings (`config.bindings`)
39
+ ---
125
40
 
126
- Declare additional Cloudflare bindings that flow into `wrangler.toml`. The compiler also auto-wires the `[[send_email]] EMAIL` binding, the `cloudflare-email.ts` helper, and Better Auth's `sendResetPassword` / `sendVerificationEmail` / `sendInvitationEmail` callbacks for any auth surface that needs mail (`emailAndPassword.enabled` OR the `emailOtp` / `magicLink` / `organization` plugins) — you don't need to add `bindings.sendEmail` by hand for the standard cases.
41
+ ## Quickstart
127
42
 
128
- ```typescript
129
- export default defineConfig({
130
- // ...
131
- bindings: {
132
- kv: [{ binding: 'CACHE', id: '...' }],
133
- r2: [{ binding: 'UPLOADS', bucketName: 'my-uploads' }],
134
- queues: {
135
- producers: [{ binding: 'JOBS', queue: 'jobs' }],
136
- consumers: [{ queue: 'jobs', maxBatchSize: 10 }],
137
- },
138
- durableObjects: [{ binding: 'CHAT', className: 'ChatRoom' }],
139
- vars: { FEATURE_X: 'true' },
140
- },
141
- });
43
+ ```bash
44
+ npm install -g @quickback-dev/cli
45
+ quickback create cloudflare my-app
46
+ cd my-app
47
+ quickback compile
48
+ wrangler deploy
142
49
  ```
143
50
 
144
- ### CMS access default
145
-
146
- `cms: true` defaults to `access: 'admin'` — only users with `user.role === 'admin'` can enter the CMS. Non-admins are redirected to `/account/profile`. Override with `cms: { access: 'user' }` to open the CMS to all authenticated users.
147
-
148
- ### Account fileUploads
149
-
150
- `account.fileUploads: true` shows the avatar upload UI on the profile page. Defaults to `false`; enabling it requires R2 configured for storage.
151
-
152
- ## Compile Output and State Artifacts
153
-
154
- - Runtime code stays in `build.outputDir` (e.g. `src/`, `wrangler.toml`, `package.json`)
155
- - CMS assets → `src/apps/cms/` (served at `/cms/` or root on custom domain)
156
- - Account UI assets → `src/apps/account/` (served at `/account/` or root on custom domain)
157
- - Drizzle migration SQL and meta files live under `quickback/drizzle/...` — Quickback owns this state and never writes a project-root `drizzle/` folder
158
- - Security contract reports are written to `quickback/reports/...`
159
-
160
- ## Automatic Audit Fields
161
-
162
- Quickback injects four **audit columns** into every table at compile time, and the runtime hard-stamps them on every write:
51
+ Three concept files do most of the work:
163
52
 
164
- - `createdAt`, `createdBy` — set on insert
165
- - `modifiedAt`, `modifiedBy` — set on every insert and every update
53
+ - `quickback.config.ts` — project config (template, providers, account UI, CMS, etc.)
54
+ - `quickback/features/<feature>/<table>.ts` — table schema + security in one file via `feature()` (or `defineTable` for Drizzle interop)
55
+ - `quickback/features/<feature>/actions/<name>.ts` — custom endpoints via `defineAction()` (one file per action)
166
56
 
167
- `deletedAt` / `deletedBy` are **soft-delete fields**, not audit fields. They're a separate per-table mechanism, injected only when the resource uses soft delete (the default). When `crud.delete.mode` and `crud.batchDelete.mode` are both `'hard'`, the columns aren't injected and the soft-delete firewall predicate is dropped.
168
-
169
- **Do NOT add any of these six to your schema files.** They are injected by the compiler.
170
-
171
- ### Caller contract (write through the request-context `db`)
172
-
173
- The wrapper around `db` overwrites all four audit fields on every `.insert().values()` and `.set()` call — caller-supplied values are silently dropped. So in custom actions:
174
-
175
- ✅ INSERT — set `id` and domain fields only:
57
+ ---
176
58
 
177
- ```ts
178
- await db.insert(records).values({ id: createId(), name: input.name });
179
- ```
59
+ ## The security model
180
60
 
181
- ✅ UPDATE — set domain fields only:
61
+ Every API request passes through four pillars (the "Definitions"):
182
62
 
183
- ```ts
184
- await db.update(records).set({ status: 'closed' }).where(...);
185
63
  ```
186
-
187
- ✅ SOFT DELETE — pass `deletedAt` as the *signal* of intent (any value works; the wrapper overwrites with `now`/`ctx.userId`):
188
-
189
- ```ts
190
- await db.update(records).set({ deletedAt: new Date() }).where(...);
64
+ Request → Firewall → Access → Guards → Database → Masking → Response
65
+ │ │ │ │
66
+ │ │ │ └── Hide PII fields
67
+ │ │ └── Block field modifications on writes
68
+ │ └── Check roles & record-level conditions
69
+ └── WHERE-clause data isolation (org / owner / team / soft-delete)
191
70
  ```
192
71
 
193
- ❌ Don't pass `createdAt`, `createdBy`, `modifiedAt`, `modifiedBy`, or `deletedBy` — they're not yours to set.
194
-
195
- ### Actor convention (`ctx.userId` for non-user writes)
196
-
197
- The wrapper throws `audit-wrapper: <op> reached without ctx.userId` if a write reaches it without a userId. For user-driven requests, auth middleware fills it in. For non-user entry points, mint a synthetic actor id at the boundary:
198
-
199
- | Boundary | Actor id |
72
+ | Pillar | Purpose |
200
73
  |---|---|
201
- | Inbound webhook | `system:webhook-<provider>` |
202
- | Cron / scheduled | `system:cron-<job>` |
203
- | Queue worker | `system:queue-<queue>` |
204
- | Quickback platform-internal write | `system:quickback` |
205
- | Out-of-band operator script | `system:script-<name>` |
74
+ | **Firewall** | Compiled WHERE clauses — scope reads/writes to the caller's org, owner, or team. |
75
+ | **Access** | Role-based + record-level permissions; **deny by default**. |
76
+ | **Guards** | Field-write protection: `createable`, `updatable`, `immutable`, `protected` (action-only). |
77
+ | **Masking** | PII redaction; auto-applied for sensitive column names. |
206
78
 
207
- **Inherit before you mint.** A user request that triggers cascades, hooks, or enqueues background jobs should carry the user's id through every downstream write. Only mint when there is genuinely no upstream user.
79
+ Plus **Views** (named projections with their own access) and **Actions** (custom endpoints with declarative access, transitions, unsafe escape hatch).
208
80
 
209
- For migrations / schema repair / backfill scripts that genuinely should not be audited at all, use the unwrapped `createDb` directly instead of the request-context `db`. That bypasses the wrapper entirely; `createdBy`/`modifiedBy` will be `NULL` on those rows.
81
+ **Secure by default.** Nothing is reachable until you explicitly open it. A fresh resource definition produces 401/403 for every caller that isn't an admin.
210
82
 
211
- ---
83
+ For the full reference, run `quickback docs compiler/definitions` (or any specific pillar: `firewall`, `access`, `guards`, `masking`, `views`, `actions`).
212
84
 
213
- ## Feature Definitions
214
-
215
- Features live in `quickback/features/{name}/` with one file per table.
216
-
217
- Quickback offers **three co-equal authoring patterns** — all compile to the same generated runtime, the compiler dispatches per file:
218
-
219
- - **`feature()`** (recommended default) — single default export, one import, everything in one call. Use for new code.
220
- - **`q.table()` + `defineTable()`** — the two-export form. Same `q` DSL, more explicit. Use when you want the table identifier named before the default export.
221
- - **Drizzle `sqliteTable()` / `pgTable()` + `defineTable()`** — interop with existing Drizzle code.
85
+ ---
222
86
 
223
- ### Example: todos.ts (`feature()` — recommended default)
87
+ ## A complete feature
224
88
 
225
- ```typescript
89
+ ```ts
90
+ // quickback/features/todos/todos.ts
226
91
  import { feature, q } from "@quickback/compiler";
227
92
 
228
93
  export default feature("todos", {
229
94
  columns: {
230
95
  id: q.id(),
231
96
  title: q.text().required(),
232
- description: q.text({ maxLength: 1000 }).optional(),
233
97
  completed: q.bool().default(false),
234
98
  ownerId: q.scope("owner"), // → ctx.userId, auto-firewalled, auto-populated
235
99
  organizationId: q.scope("organization"), // → ctx.activeOrgId, same
236
100
  },
237
- // firewall block omitted — q.scope() auto-derives:
101
+ // firewall + soft-delete derived from q.scope() above:
238
102
  // [{ field: 'organizationId', equals: 'ctx.activeOrgId' },
239
103
  // { field: 'ownerId', equals: 'ctx.userId' },
240
104
  // { field: 'deletedAt', isNull: true }]
@@ -245,910 +109,137 @@ export default feature("todos", {
245
109
  delete: { access: { roles: ["admin"] }, mode: "soft" },
246
110
  },
247
111
  guards: {
248
- createable: ["title", "description", "completed"],
249
- updatable: ["title", "description", "completed"],
250
- },
251
- });
252
- ```
253
-
254
- The `feature()` form is compile-time sugar — the compiler expands it to `q.table()` + `defineTable()` internally. Use whichever reads best for the file.
255
-
256
- ### q DSL — column types
257
-
258
- Column names default to snake_case of the JS key (`organizationId` → `organization_id`). Override with the positional name string or the `sqlName` option.
259
-
260
- | Builder | SQL | Zod | Notes |
261
- |---|---|---|---|
262
- | `q.id()` | `text('id').primaryKey()` | `z.string()` | cuid2 by default; ID style follows `database.generateId` |
263
- | `q.text(name?)` / `q.text({ sqlName?, maxLength? })` | `text(...)` | `z.string()` (`.max(n)` if `maxLength`) | options form adds zod max-length only — SQL stays unconstrained |
264
- | `q.url({ sqlName?, maxLength? })` | `text(...)` | `z.string().url()` | rejects `javascript:` / `data:` / non-URL strings at the API edge |
265
- | `q.int(name?)` | `integer(...)` | `z.number().int()` | |
266
- | `q.bool(name?)` | `boolean(...)` (sqlite: integer mode) | `z.boolean()` | |
267
- | `q.uuid(name?)` | `uuid(...)` (sqlite: text) | `z.string().uuid()` | |
268
- | `q.timestamp(name?)` | `timestamp(...)` (sqlite: text ISO) | `z.coerce.date()` | |
269
- | `q.json(zodType?)` | `jsonb(...)` (sqlite: text mode) | `z.unknown()` or your zod | pass a zod schema for typed JSON |
270
- | `q.enum(['a','b'])` | `text(..., { enum })` | `z.enum([...])` | |
271
- | `q.scope(kind)` | `text(...).notNull()` | `z.string()` | tenant-scope column — see Firewall |
272
-
273
- **Chainable modifiers:** `.required()` / `.optional()` / `.default(v)` / `.unique()` / `.index()` / `.filterable(false)` / `.searchable(false)` / `.references(() => other.id, { onDelete: 'cascade' })`.
274
-
275
- `.filterable(false)` and `.searchable(false)` are capability opt-outs — every text column is filter/search-eligible by default; chain `false` to remove a column from `?<col>=` filters or the `?search=` OR'd LIKE scan. Masked columns are always excluded from `?search` regardless (see Masking).
276
-
277
- ### Composite indexes & uniques on `feature()`
278
-
279
- Single-column indexes go on the column (`q.text().index()`). Composite ones go at the top level — the sugar forwards them into the same `q.table` opts:
280
-
281
- ```typescript
282
- export default feature("memberships", {
283
- columns: { userId: q.scope("owner"), organizationId: q.scope("organization"), role: q.text() },
284
- indexes: [{ name: "memberships_user_org_idx", columns: ["userId", "organizationId"] }],
285
- unique: [{ columns: ["userId", "organizationId"] }],
286
- // ... read / crud / guards
287
- });
288
- ```
289
-
290
- **Auto-indexes:** the compiler emits the indexes you'd otherwise author by hand. Don't pre-declare these — they'll be deduped:
291
-
292
- | Trigger | Index emitted |
293
- |---|---|
294
- | Tenant col (`organizationId` / `userId`) + `deletedAt` | composite `(<isolation>, deletedAt)` |
295
- | Any FK (`.references(...)`) | single-col `(<fk>)` (D1/SQLite don't auto-index FKs) |
296
- | Any column in a view's `read.query.sortable` | single-col `(<col>)` |
297
-
298
- ### Example: same todos using the two-export form
299
-
300
- ```typescript
301
- import { q, defineTable } from "@quickback/compiler";
302
-
303
- export const todos = q.table("todos", {
304
- id: q.id(),
305
- title: q.text().required(),
306
- completed: q.bool().default(false),
307
- ownerId: q.scope("owner"),
308
- organizationId: q.scope("organization"),
309
- });
310
-
311
- export default defineTable(todos, {
312
- // firewall auto-derived from q.scope() — same as the feature() example
313
- read: { /* same as above */ },
314
- crud: { /* same as above */ },
315
- guards: { /* same as above */ },
316
- });
317
-
318
- export type Todo = typeof todos.$infer;
319
- ```
320
-
321
- ### Example: same todos with Drizzle (for interop)
322
-
323
- When bringing forward existing Drizzle code, declare a regular column. Auto-detection by **name** (`organizationId`, `ownerId`, `teamId`, `userId`) still picks it up — `q.scope()` semantics (auto-firewall, systemManaged, auto-populate) apply because they key off the firewall predicate, not the column DSL.
324
-
325
- ```typescript
326
- import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
327
- import { defineTable } from "@quickback/compiler";
328
-
329
- export const todos = sqliteTable("todos", {
330
- id: text("id").primaryKey(),
331
- title: text("title").notNull(),
332
- completed: integer("completed", { mode: "boolean" }).default(false),
333
- userId: text("user_id").notNull(),
334
- organizationId: text("organization_id").notNull(),
335
- });
336
-
337
- export default defineTable(todos, {
338
- // firewall auto-derived from column names; declare explicitly only if names don't match
339
- read: { /* same as above */ },
340
- crud: { /* same as above */ },
341
- guards: { /* same as above */ },
342
- });
343
- ```
344
-
345
- ### Internal/Junction Tables (No API)
346
-
347
- Tables without a `defineTable()` / `feature()` default export get no API routes:
348
-
349
- ```typescript
350
- export const roomAmenities = q.table('roomAmenities', {
351
- roomId: q.text().required(),
352
- amenityId: q.text().required(),
353
- });
354
- ```
355
-
356
- The compiler warns once per such table so you confirm the opt-out is intentional.
357
-
358
- ### Action files use `q.*` for query helpers too
359
-
360
- Action `execute` functions query via the same `q` namespace:
361
-
362
- ```typescript
363
- // quickback/features/mail/actions/inbound.ts
364
- import { defineAction } from "../.quickback/define-action";
365
- import { q } from "../../../lib/q";
366
- import { mailboxes } from "../mailboxes";
367
- import { messages } from "../messages";
368
-
369
- export default defineAction({
370
- description: "Process inbound mail",
371
- path: "/inbound",
372
- /* ... */
373
- async execute({ unsafeDb, input }) {
374
- const mailbox = await unsafeDb.query.mailboxes.findFirst({
375
- where: q.eq(mailboxes.address, input.mailboxAddress),
376
- });
377
- // …
112
+ createable: ["title", "completed"],
113
+ updatable: ["title", "completed"],
378
114
  },
379
115
  });
380
116
  ```
381
117
 
382
- Available: `q.and`, `q.or`, `q.not`, `q.eq`, `q.ne`, `q.gt`, `q.gte`, `q.lt`, `q.lte`, `q.like`, `q.ilike`, `q.inArray`, `q.notInArray`, `q.isNull`, `q.isNotNull`, `q.between`, `q.desc`, `q.asc`, `q.sql`. Pure re-export of Drizzle's query builder under the Quickback namespace — users can still `import { eq } from "drizzle-orm"` directly if they prefer.
383
-
384
- ### Explicit scope in unsafe handlers — `unsafeDb.scopeTo(...)`
385
-
386
- When an unsafe handler (webhook, cron, bulk importer) knows its tenant out-of-band, call `scopeTo` instead of hand-rolling `organizationId` on every query. The firewall runs unchanged with a synthesized ctx:
387
-
388
- ```typescript
389
- export const execute = async ({ unsafeDb, input }) => {
390
- const [mailbox] = await unsafeDb.select().from(mailboxes)
391
- .where(q.eq(mailboxes.id, input.mailboxId));
392
- if (!mailbox) return { ok: false };
393
-
394
- const db = unsafeDb.scopeTo({ organizationId: mailbox.organizationId });
395
- await db.insert(messages).values({ mailboxId: mailbox.id, body: input.body });
396
- return { ok: true };
397
- };
398
- ```
399
-
400
- `scopeTo` accepts `{ organizationId?, userId?, teamId? }` — any subset. Missing keys fall back to the ambient `ctx` values. Every downstream `.select/.update/.delete` gets a `WHERE` scope clause; every `.insert().values()` auto-injects the scope columns. Reach for this any time an unsafe handler needs scoped writes — it is the canonical way to keep tenant isolation while the handler bypasses the request ctx.
401
-
402
- ### Import style
403
-
404
- With `feature()`, tables are **default exports** — use default imports:
405
-
406
- ```typescript
407
- // features/applications/actions/advance.ts
408
- import applications from "../applications";
409
- import { defineAction } from "../.quickback/define-action";
410
- ```
411
-
412
- With the two-export form (`defineTable`), tables are **named exports** — use named imports:
413
-
414
- ```typescript
415
- import { applications } from "../applications";
416
- ```
417
-
418
- Both produce the same typed handle.
419
-
420
- ---
421
-
422
- ## Input Hints
423
-
424
- Control how the CMS renders form inputs. Key values:
425
-
426
- | Hint | Renders As |
427
- |------|-----------|
428
- | `richtext` | Tiptap rich text editor (edit) / formatted HTML (view). Stores HTML. |
429
- | `select` | Dropdown select |
430
- | `textarea` | Multi-line text |
431
- | `currency` | Currency input |
432
- | `checkbox` | Checkbox toggle |
433
-
434
- ```typescript
435
- inputHints: { description: "richtext", status: "select" }
436
- ```
437
-
438
- ---
439
-
440
- ## Four Security Layers
441
-
442
- Every API request passes through four layers in order:
443
-
444
- ```
445
- Request → Firewall → Access → Guards → Database → Masking → Response
446
- ```
447
-
448
- | Layer | Purpose | Failure |
449
- |-------|---------|---------|
450
- | **Firewall** | Tenant isolation via automatic WHERE clauses | 404 |
451
- | **Access** | Role-based CRUD permissions (deny by default) | 403 |
452
- | **Guards** | Field modification rules (protected/immutable fields) | 400 |
453
- | **Masking** | PII redaction for unauthorized viewers | — |
454
-
455
- ### 1. Firewall — Data Isolation
456
-
457
- Compiles WHERE clauses to isolate data by ownership. Predicates are AND'd together.
458
-
459
- ```typescript
460
- firewall: [
461
- { field: 'organizationId', equals: 'ctx.activeOrgId' }, // WHERE organizationId = ctx.activeOrgId
462
- { field: 'ownerId', equals: 'ctx.userId' }, // AND ownerId = ctx.userId
463
- { field: 'teamId', equals: 'ctx.activeTeamId' }, // AND teamId = ctx.activeTeamId
464
- { field: 'deletedAt', isNull: true }, // AND deletedAt IS NULL (soft-delete filter)
465
- ]
466
-
467
- // Public/system resources opt out of tenant scoping (soft-delete still applied):
468
- firewall: [{ exception: true }]
469
- ```
470
-
471
- **Recommended: declare scope columns with `q.scope()`** — auto-derives the firewall predicate AND marks the column `systemManaged` (rejected from client input) AND auto-populates from ctx on insert/upsert. Zero ambiguity in the source:
472
-
473
- ```typescript
474
- columns: {
475
- organizationId: q.scope("organization"), // → ctx.activeOrgId
476
- ownerId: q.scope("owner"), // → ctx.userId
477
- teamId: q.scope("team"), // → ctx.activeTeamId
478
- }
479
- ```
480
-
481
- **Auto-derivation by name** (Drizzle interop, when the `firewall:` block is omitted): the compiler scans column names and emits the same predicates.
482
-
483
- | Column name in schema | Predicate emitted |
484
- |---|---|
485
- | `organizationId` / `organisationId` | `{ field: '...', equals: 'ctx.activeOrgId' }` |
486
- | `userId` (or `ownerId`) | `{ field: '...', equals: 'ctx.userId' }` |
487
- | `teamId` | `{ field: 'teamId', equals: 'ctx.activeTeamId' }` |
488
- | `deletedAt` (present whenever the resource uses soft delete, which is the default) | `{ field: 'deletedAt', isNull: true }` |
489
-
490
- - Exactly one isolation column → auto-derived.
491
- - Two or more → compile-time error; declare `firewall: [...]` explicitly OR use `q.scope()` to lock semantics in the source.
492
- - Zero columns AND no PUBLIC route → compile-time error ("missing isolation column").
493
-
494
- **Custom column / context source**: just write the predicate explicitly.
495
-
496
- ```typescript
497
- firewall: [
498
- { field: 'tenantId', equals: 'ctx.activeOrgId' },
499
- { field: 'status', in: ['active', 'pending'] }, // literal value, not ctx-derived
500
- ]
501
- ```
502
-
503
- **Predicate operators**: `equals` (column = ctx.* or literal), `isNull: true` (column IS NULL), `in: [...]` (column IN ...), `{ exception: true }` (opt out of tenant scoping).
504
-
505
- ### 2. Access — Permission Checks
506
-
507
- Role-based and record-based access control. Deny by default.
508
-
509
- DSL v2 separates **reads** (collection + per-id GET) from **mutations**. The unified `read` block owns `GET /` AND `GET /:id` AND views; mutations live under `crud.create/update/delete`.
510
-
511
- ```typescript
512
- read: {
513
- access: { roles: ['member+'] }, // gates GET / and GET /:id
514
- query: {
515
- sortable: ['createdAt', 'status'], // ?sort= allowlist (defaults to all cols)
516
- searchable: ['title', 'body'], // ?search= OR'd LIKE allowlist
517
- filterable: ['status', 'priority'], // ?<col>= allowlist
518
- },
519
- views: {
520
- summary: {
521
- fields: ['id', 'title', 'status'],
522
- access: { roles: ['member+'] },
523
- query: { sortable: ['title'] }, // per-view overrides allowed
524
- },
525
- full: {
526
- fields: ['id', 'title', 'status', 'body', 'internalNotes'],
527
- access: { roles: ['admin+'] },
528
- },
529
- },
530
- },
531
- crud: {
532
- create: { access: { roles: ['admin+'] } },
533
- update: {
534
- access: {
535
- or: [
536
- { roles: ['admin+'] },
537
- { record: { createdBy: { equals: '$ctx.userId' } } },
538
- ],
539
- },
540
- },
541
- delete: { access: { roles: ['owner'] } },
542
- }
543
- ```
544
-
545
- **Generated read endpoints:**
546
- - `GET /api/v1/{resource}` — gated by `read.access`
547
- - `GET /api/v1/{resource}/:id` — gated by `read.access` (single-record GET inherits)
548
- - `GET /api/v1/{resource}?view=summary` — view dispatch under `?view=`
549
- - `GET /api/v1/{resource}/views/summary` — explicit view path
550
-
551
- > **DSL v2 migration:** `crud.list` and `crud.get` are rejected at compile time. Move them to `read.access`. A bare `crud: { list: {} }` becomes `read: {}`.
552
-
553
- **Role hierarchy**: Configure `auth.roleHierarchy` in your config (e.g., `['member', 'admin', 'owner']`) and use the `+` suffix to mean "this role and above". `"member+"` expands to `["member", "admin", "owner"]` at compile time. Roles without `+` are exact matches.
554
-
555
- Record condition operators: `equals`, `notEquals`, `in`, `notIn`, `greaterThan`, `lessThan`
556
-
557
- Context variables: `$ctx.userId`, `$ctx.activeOrgId`, `$ctx.activeTeamId`, `$ctx.roles`, `$ctx.isAnonymous`
558
-
559
- **Special role `PUBLIC`**: Use `roles: ["PUBLIC"]` for unauthenticated access (contact forms, webhooks). Every PUBLIC invocation is mandatory audit logged. The wildcard `"*"` is not supported and will fail at compile time.
560
-
561
- ### 3. Guards — Field Protection
562
-
563
- ```typescript
564
- guards: {
565
- createable: ['name', 'description'], // Allowed on POST
566
- updatable: ['description'], // Allowed on PATCH
567
- immutable: ['invoiceNumber'], // Set once, never change
568
- protected: { status: ['approve'] }, // Only via named actions
569
- }
570
- ```
571
-
572
- System-managed fields (always protected): `createdAt`, `createdBy`, `modifiedAt`, `modifiedBy`, `deletedAt`, `deletedBy`
573
-
574
- PUT/Upsert requires both `generateId: false` and `guards: false`.
575
-
576
- ### 4. Masking — PII Redaction
577
-
578
- ```typescript
579
- masking: {
580
- ssn: { type: 'ssn', show: { roles: ['admin', 'hr'] } },
581
- email: { type: 'email', show: { roles: ['admin'], or: 'owner' } },
582
- }
583
- ```
584
-
585
- Mask types: `email`, `phone`, `ssn`, `creditCard`, `name`, `redact`, `custom`
586
-
587
- Auto-detection warns on unmasked sensitive columns (`email`, `phone`, `ssn`, `password`, etc.).
588
-
589
- **Search/filter gating.** Masked columns are dropped from `?search` by default — letting an unauthorized caller substring-search a masked SSN trivially leaks digit positions. To re-enable search on a masked column for callers who *can* see it unmasked, list it under a view's `read.query.searchable`. The compiler validates the intersection at compile time.
590
-
591
- ---
592
-
593
- ## Views — Column-Level Security
594
-
595
- Named projections that control which fields are visible based on role.
596
-
597
- ```typescript
598
- views: {
599
- summary: {
600
- fields: ['id', 'name', 'email'],
601
- access: { roles: ['member', 'admin'] },
602
- },
603
- full: {
604
- fields: ['id', 'name', 'email', 'phone', 'ssn', 'address'],
605
- access: { roles: ['admin'] },
606
- },
607
- }
608
- ```
609
-
610
- Generated endpoints: `GET /api/v1/{resource}/views/{viewName}`
611
-
612
- ---
613
-
614
- ## Validation
615
-
616
- ```typescript
617
- validation: {
618
- name: { minLength: 1, maxLength: 100 },
619
- capacity: { min: 1, max: 1000 },
620
- roomType: { enum: ['meeting', 'conference', 'breakout'] },
621
- email: { email: true },
622
- code: { pattern: '^[A-Z]{3}$' },
623
- }
624
- ```
625
-
626
- ---
627
-
628
- ## CMS Record Layouts
629
-
630
- Control how fields are grouped on the CMS record detail page.
631
-
632
- ```typescript
633
- layouts: {
634
- default: {
635
- sections: [
636
- { label: "Contact Info", columns: 2, fields: ["name", "email", "phone"] },
637
- { label: "Notes", collapsed: true, fields: ["notes", "internalNotes"] },
638
- ],
639
- },
640
- }
641
- ```
642
-
643
- Section options: `label` (string), `fields` (string[]), `columns` (1|2, default 1), `collapsed` (boolean, default false). Unassigned fields go to "Other Fields".
644
-
645
- ---
646
-
647
- ## Account UI — Authentication & Account Management
648
-
649
- A complete pre-built SPA for login, signup, profile, organizations, and admin. Built from source at compile time (inside Docker) with your config baked in.
650
-
651
- ### What's Included
652
-
653
- | Section | Pages |
654
- |---------|-------|
655
- | **Auth** | Login, signup, email OTP, forgot password, email verification |
656
- | **Account** | Profile, devices/sessions, passkeys, account deletion |
657
- | **Organizations** | Dashboard, org creation, member management, invitations, API keys, org settings |
658
- | **Admin** | User management (search, create, ban/unban, reset passwords, view sessions) |
659
- | **CLI** | Device authorization flow for `quickback login` |
660
-
661
- ### Enabling
662
-
663
- ```typescript
664
- // Minimal
665
- account: true
666
-
667
- // Full config
668
- account: {
669
- domain: "auth.example.com",
670
- adminDomain: "admin.example.com",
671
- name: "My App",
672
- companyName: "My Company",
673
- tagline: "Build faster, ship sooner",
674
- auth: {
675
- password: true, // Email/password (default: false)
676
- emailOTP: true, // Email OTP (default: true)
677
- passkey: true, // WebAuthn passkeys (default: true)
678
- signup: true, // Registration (default: true)
679
- organizations: true, // Multi-tenant orgs (default: true)
680
- admin: true, // Admin panel (default: true)
681
- emailVerification: true, // Require email verification (default: true)
682
- },
683
- }
684
- ```
685
-
686
- ### Compile-Time Feature Gating
687
-
688
- Disabled features are **removed before the Vite build** — route files are excluded from source, so they never appear in the JavaScript bundle. Not runtime checks.
689
-
690
- ### Routing
691
-
692
- - **Unified domain (default):** Served at `/account/` alongside CMS at `/cms/` and API at `/api/`
693
- - **Custom domain:** Served at root `/` on `auth.example.com`
694
- - **Admin domain:** Admin routes served at root `/` on `admin.example.com`
695
- - Cross-subdomain auth cookies auto-configured when multiple custom domains detected
696
-
697
- ### Skip Rebuild
698
-
699
- ```typescript
700
- account: { build: false, /* ...other options */ }
701
- ```
702
-
703
- Skips the SPA build on subsequent compiles — useful when iterating on API features only.
704
-
705
- ### Standalone & Library Usage
706
-
707
- Account UI also works outside the compiler:
708
- - **Template:** Clone repo, configure `.env`, deploy as separate Worker
709
- - **Library:** `npm install quickback-better-auth-account-ui` and import as React component
710
-
711
- Docs: `quickback docs account-ui` | https://docs.quickback.dev/account-ui
712
-
713
- ---
714
-
715
- ## Actions — Custom Business Logic
716
-
717
- Defined with `defineAction()` (singular). Per-action permissions live under `access:` (same shape as resource-level access).
718
-
719
- **One file per action.** Each action is its own module under the feature's `actions/` directory:
720
-
721
- - `actions/<name>.ts` — binds to the feature's primary table (the `<feature>.ts` file at the feature root). If `path:` is set, becomes a standalone action.
722
- - `actions/<table>/<name>.ts` — binds to the sibling table file `<table>.ts` at the feature root. Use this in multi-table features.
723
-
724
- The action's filename (sans `.ts`) is the action name AND the URL segment. Uniqueness is enforced per **`(bound table, name)` pair** — sibling-bound actions on different tables may share a verb (e.g. `actions/episodes/publish.ts` + `actions/shows/publish.ts` mount at `/episodes/:id/publish` and `/shows/:id/publish`). The compiler errors only when two action files would mount at the same URL.
725
-
726
- For shared Zod schemas or helpers, put them under `<feature>/lib/` and import from each action file.
727
-
728
- **Retired layouts** (rejected at load time with migration guidance): `actions.ts` (bundle), `_feature.ts`, `handlers/` directory, `defineActions(table, {...})`, `defineActions(null, {...})`, `*-actions.ts` / `*.actions.ts` filenames.
729
-
730
- `execute:` must be an **async arrow function** (`async (ctx) => { … }`). `async function` declarations and non-async forms are rejected at parse time.
731
-
732
- ```typescript
733
- // features/todos/actions/complete.ts
118
+ ```ts
119
+ // quickback/features/todos/actions/complete.ts
734
120
  import { z } from "zod";
735
121
  import { defineAction } from "../.quickback/define-action";
736
- import { q } from "../../../lib/q"; // generated namespace; same as drizzle-orm
737
- import todos from "../todos"; // default import: feature() exports
738
- // import { todos } from "../todos"; // named import: two-export form
122
+ import todos from "../todos";
739
123
 
740
124
  export default defineAction({
741
125
  description: "Mark todo as complete",
742
- input: z.object({ completedAt: z.string().datetime().optional() }),
743
- access: { roles: ["member", "admin"], record: { completed: { equals: false } } },
744
- sideEffects: "sync",
126
+ input: z.object({}),
127
+ access: {
128
+ roles: ["member", "admin"],
129
+ record: { completed: { equals: false } },
130
+ },
745
131
  async execute({ db, record, whereRecord, auditFields }) {
746
132
  await db.update(todos)
747
133
  .set({ completed: true, modifiedAt: auditFields!.modifiedAt })
748
- .where(whereRecord!(todos)); // firewall + soft-delete + id, in one
134
+ .where(whereRecord!(todos));
749
135
  return { success: true };
750
136
  },
751
137
  });
752
138
  ```
753
139
 
754
- **Record-based** (no `path:`): `POST /api/v1/{resource}/:id/{action}` — record is loaded, firewall + access checks run, then `execute` is called with `record`, `whereRecord`, scoped `db`.
755
- **Standalone** (`path:` set): custom `path` and `method`. No record context, no firewall preload.
756
-
757
- Action options: `path`, `method` (GET/POST/PUT/PATCH/DELETE), `responseType` (json/stream/file), `sideEffects` (sync/async/fire-and-forget), `transition`, `unsafe`, `allowRawSql`, `cms`.
758
-
759
- ### `whereRecord(table)` — explicit, scope-safe WHERE
760
-
761
- In record-based actions, `whereRecord(table)` returns a Drizzle expression that AND-merges the resource's firewall + soft-delete + `eq(table.id, record.id)`. Use it for protected-field writes — even if a future refactor swaps `db` for an unscoped client, the WHERE stays explicit. `whereRecord` is `undefined` for standalone actions.
762
-
763
- ### `transition` — state-machine policy on protected fields
764
-
765
- For protected fields that follow a state machine (status, lifecycle, fulfilment), enforce the *from/to pair*, not just the current state. Without `transition`, an `advance` action whose access allows `status in ['applied', 'screening']` will happily run `applied → offer` (a skip) or `screening → applied` (a regression).
766
-
767
- ```typescript
768
- // features/applications/actions/advance.ts
769
- import { z } from "zod";
770
- import { defineAction } from "../.quickback/define-action";
771
- import { applications } from "../applications";
772
-
773
- export default defineAction({
774
- description: "Move application forward",
775
- input: z.object({ nextStatus: z.enum(['screening', 'interview', 'offer']) }),
776
- access: { roles: ['owner', 'admin'] },
777
- transition: {
778
- field: 'status',
779
- via: 'nextStatus', // read target from input.nextStatus
780
- fromTo: {
781
- applied: ['screening'],
782
- screening: ['interview'],
783
- interview: ['offer'],
784
- },
785
- },
786
- async execute({ db, record, input, auditFields, whereTransition }) { /* … */ },
787
- });
788
- ```
789
-
790
- ```typescript
791
- // features/applications/actions/hire.ts
792
- import { z } from "zod";
793
- import { defineAction } from "../.quickback/define-action";
794
- import { applications } from "../applications";
795
-
796
- export default defineAction({
797
- description: "Finalize an offer",
798
- input: z.object({}),
799
- access: { roles: ['owner'] },
800
- transition: {
801
- field: 'status',
802
- to: 'hired', // fixed target — same value every call
803
- fromTo: { offer: ['hired'] },
804
- },
805
- async execute({ db, record, auditFields, whereTransition }) { /* … */ },
806
- });
807
- ```
808
-
809
- Exactly one of `via` or `to` must be provided. On a bad transition the runtime returns **409 `ACCESS_ACTION_NOT_ALLOWED_FOR_STATE`** with `field`, `current`, `target`, `allowedTargets`. The same 409 fires when a plain `access.record` precondition fails (was 403 before — splitting it lets clients tell *"you can't do this"* from *"you can't do this **yet**"*).
810
-
811
- ### `unsafe` — bypass scoped DB filters (object form, with mandatory audit)
812
-
813
- For platform-level support / cross-tenant operations, opt out of the scoped DB. The object form is required for new code — it makes the policy explicit and forces an audit reason:
814
-
815
- ```typescript
816
- // features/admin/actions/admin-report.ts
817
- import { z } from "zod";
818
- import { defineAction } from "../.quickback/define-action";
819
- import { applications } from "../../applications/applications";
820
-
821
- export default defineAction({
822
- description: "Cross-org hiring report",
823
- path: "/admin/cross-org-report",
824
- input: z.object({ startDate: z.string() }),
825
- access: { roles: ['owner'] },
826
- unsafe: {
827
- reason: "Support investigation for enterprise customer",
828
- adminOnly: true, // default true — gates on ctx.userRole === 'admin'
829
- crossTenant: true, // default true — bypasses firewall
830
- targetScope: 'all', // 'all' | 'organization'
831
- },
832
- async execute({ db, unsafeDb, ctx, input }) {
833
- // db is still scoped (safety net for accidental writes)
834
- // unsafeDb bypasses scoped filters
835
- return await unsafeDb.select().from(applications);
836
- },
837
- });
838
- ```
839
-
840
- Generated runtime auto-injects: Better Auth required, platform admin gate, mandatory audit logging on deny/success/error. Without unsafe mode, `unsafeDb` is `undefined`.
841
-
842
- ### Soft-delete cascade (cross-feature)
843
-
844
- When a parent is soft-deleted, every child table that holds an FK to it — both **same-feature** and **cross-feature** children — receives the same `deletedAt` / `deletedBy` stamp. The cascade UPDATE always AND-merges the child's own firewall, so a delete in one tenant never reaches a child row in another tenant. FKs declared with `onDelete: 'cascade'` or `'set null'` participate; FKs without `onDelete` are cascaded for backwards compat.
845
-
846
- ### Actions-Only Features
847
-
848
- A feature directory with no top-level `*.ts` files is "tableless" — every action under `actions/` must be standalone (have `path:`). Use this for utility endpoints like webhooks, reports, or integrations.
849
-
850
- ```typescript
851
- // quickback/features/utilities/actions/health-check.ts
852
- import { z } from "zod";
853
- import { defineAction } from "../.quickback/define-action";
854
-
855
- export default defineAction({
856
- description: "Health check endpoint",
857
- path: "/health",
858
- method: "GET",
859
- input: z.object({}),
860
- access: { roles: ["member", "admin"] },
861
- async execute() {
862
- return { ok: true };
863
- },
864
- });
865
- ```
140
+ For the schema column types: `quickback docs compiler/definitions/schema`.
141
+ For action shapes (record-based vs standalone, transitions, `unsafe:`): `quickback docs compiler/definitions/actions`.
142
+ For Drizzle interop (existing `sqliteTable` schemas): `quickback docs compiler/definitions/feature`.
866
143
 
867
144
  ---
868
145
 
869
- ## API Reference
870
-
871
- ### CRUD Operations
872
-
873
- | Method | Endpoint | Description |
874
- |--------|----------|-------------|
875
- | `GET` | `/api/v1/{resource}` | List records |
876
- | `GET` | `/api/v1/{resource}/:id` | Get single record |
877
- | `POST` | `/api/v1/{resource}` | Create record |
878
- | `PATCH` | `/api/v1/{resource}/:id` | Update record |
879
- | `DELETE` | `/api/v1/{resource}/:id` | Delete record |
880
- | `PUT` | `/api/v1/{resource}/:id` | Upsert (if enabled) |
881
-
882
- ### Batch Operations
146
+ ## Defaults the compiler applies
883
147
 
884
- `POST|PATCH|DELETE|PUT /api/v1/{resource}/batch` with `{ "records": [...], "options": { "atomic": false } }`
148
+ Before flagging "missing X", check whether a default already covers it:
885
149
 
886
- ### Query Parameters
887
-
888
- | Feature | Syntax |
889
- |---------|--------|
890
- | Pagination | `?limit=50&offset=0` (max 100) |
891
- | Filter | `?status=active`, `?amount.gt=100`, `?status.in=draft,pending` |
892
- | Sort | `?sort=status,-createdAt` (multi-sort, `-` = desc) |
893
- | Fields | `?fields=id,name,status` |
894
- | Total count | `?total=true` |
895
- | Search | `?search=conference` (OR'd LIKE across text columns) |
896
-
897
- Filter operators: `.gt`, `.gte`, `.lt`, `.lte`, `.ne`, `.like`, `.in`
898
-
899
- ### Response Format
900
-
901
- ```json
902
- {
903
- "data": [{ "id": "...", "title": "Todo 1" }],
904
- "pagination": { "limit": 10, "offset": 0, "count": 2, "total": 42 }
905
- }
906
- ```
907
-
908
- ### Error Responses
909
-
910
- | Status | Layer | Meaning |
911
- |--------|-------|---------|
912
- | `401` | Auth | Invalid/expired session |
913
- | `403` | Access | Insufficient permissions |
914
- | `404` | Firewall | Record not found or outside scope |
915
- | `400` | Guards | Invalid field modification |
916
-
917
- ---
918
-
919
- ## Database Dialects
920
-
921
- | Stack | Import | Table Function |
922
- |-------|--------|----------------|
923
- | Cloudflare D1 / SQLite | `drizzle-orm/sqlite-core` | `sqliteTable` |
924
- | Supabase / PostgreSQL | `drizzle-orm/pg-core` | `pgTable` |
925
- | MySQL | `drizzle-orm/mysql-core` | `mysqlTable` |
150
+ - **Soft-delete is the default.** `deletedAt` / `deletedBy` are auto-injected at the SQL layer; firewall auto-AND-merges `deletedAt IS NULL`. Opt out with `crud.delete.mode: 'hard'`.
151
+ - **Audit fields auto-injected.** `createdAt`, `createdBy`, `modifiedAt`, `modifiedBy` — never declare them in user code. The audit-wrapper auto-populates `createdBy` / `modifiedBy` from `ctx.userId`.
152
+ - **Sensitive columns auto-masked.** `email`, `phone`, `ssn`, `password`, `creditCard`, etc. get `show: { or: 'owner', roles: ['admin'] }` by default; falls back to `roles: ['admin']` only when there's no `ownerId` column. Absence of a `masking:` block does NOT mean plain-text — it means the compiler-default is in effect. Declare `masking:` only to override.
153
+ - **Firewall auto-derived** for tables with a single isolation column (e.g., `organizationId` only).
154
+ - **Soft-delete cascade** reaches cross-feature children with each child's own firewall AND-merged.
155
+ - **Reserved keys in `access.record`.** `and`, `or`, `roles`, `userRole` are rejected inside `record:` at compile time — those go on the parent access node.
926
156
 
927
157
  ---
928
158
 
929
- # PART 2: THE QUICKBACK STACK
930
-
931
- The Quickback Stack is a production-ready backend platform built entirely on Cloudflare's edge infrastructure. It's a Supabase alternative where everything runs on your own Cloudflare account — your data, your infrastructure, global edge performance.
932
-
933
- ```
934
- ┌─────────────────────────────────────────────────────────┐
935
- │ QUICKBACK STACK ON CLOUDFLARE │
936
- │ │
937
- │ Workers — API runtime (Hono) │
938
- │ D1 — SQLite database at the edge │
939
- │ R2 — S3-compatible file storage │
940
- │ KV — Distributed key-value store │
941
- │ Durable Objects — Realtime WebSockets │
942
- │ Queues — Background job processing │
943
- │ Workers AI — Embeddings & vector search │
944
- │ Better Auth — Authentication & organizations │
945
- └─────────────────────────────────────────────────────────┘
946
- ```
947
-
948
- ## Authentication (Better Auth)
949
-
950
- Built on Better Auth with multi-tenant organization support.
951
-
952
- - Email/password, magic links, passkeys, email OTP
953
- - Three org roles: `owner`, `admin`, `member`
954
- - Session storage in KV namespace
955
- - All auth routes at `/auth/v1/*`
956
- - Extensible via Better Auth plugins
957
- - **JWT fast-path** — authenticated API requests validate via HMAC-SHA256 JWT (0 DB queries). Tokens mint and rotate automatically; session cookies are the source of truth. Separate from Better Auth's `jwt` plugin (opt-in, for JWKS/external identity). See `quickback docs stack/auth/jwt-optimization`
958
- - **Account UI** — pre-built SPA for login, signup, profile, orgs, admin (see Account UI section above)
159
+ ## The scoped DB — what it does and doesn't do
959
160
 
960
- ```typescript
961
- // Config
962
- providers: {
963
- auth: defineAuth("better-auth"),
964
- }
965
- ```
966
-
967
- Docs: `quickback docs stack/auth/using-auth` | https://docs.quickback.dev/stack/auth
161
+ The action context's `db` is a Drizzle wrapper that:
968
162
 
969
- ## Database (D1)
163
+ - **Does** auto-AND the resource's firewall WHERE clause into every `select` / `update` / `delete`.
164
+ - **Does** route soft-delete `delete()` calls to a `deletedAt` / `deletedBy` UPDATE.
165
+ - **Does NOT** auto-populate insert values. `db.insert(table).values({...})` writes whatever you pass — pass `organizationId` (and any other isolation columns) explicitly. Audit fields ARE auto-populated; tenant-scope columns are not.
970
166
 
971
- SQLite at the edge with zero configuration. Multi-database pattern for independent scaling:
167
+ For unscoped writes (cross-tenant support, platform admin), use the `unsafe:` object form on the action — it forces an audit reason and gates on platform admin role.
972
168
 
973
- | Binding | Purpose |
974
- |---------|---------|
975
- | `DB` | Application data (features) |
976
- | `AUTH_DB` | Auth sessions & users |
977
- | `FILES_DB` | File metadata |
978
- | `WEBHOOKS_DB` | Webhook tracking |
169
+ ---
979
170
 
980
- - Drizzle ORM for type-safe queries
981
- - Auto-generated migrations on compile
982
- - Application-layer security (firewall, access, guards, masking)
983
- - Local dev with `.wrangler/state/`
984
- - Neon Postgres available as alternative
171
+ ## Quickback CLI (commands the user runs)
985
172
 
986
- ```typescript
987
- providers: {
988
- database: defineDatabase("cloudflare-d1", {
989
- splitDatabases: true,
990
- }),
991
- }
173
+ ```bash
174
+ quickback compile # compile project (prompts to log in if not authenticated)
175
+ quickback create <template> # new project from template
176
+ quickback login # authenticate via browser device flow
992
177
  ```
993
178
 
994
- Docs: `quickback docs stack/database/d1` | https://docs.quickback.dev/stack/database/d1
995
-
996
- ## File Storage (R2)
997
-
998
- S3-compatible object storage with built-in access control.
999
-
1000
- - Two-worker architecture: API worker (upload/manage) + Files worker (serve)
1001
- - Bucket-scoped access policies (public, organization, user)
1002
- - File metadata tracked in `FILES_DB`
1003
- - Soft deletes with org-level tenant isolation
1004
- - API at `/storage/v1/*`
1005
-
1006
- Docs: `quickback docs stack/storage/r2` | https://docs.quickback.dev/stack/storage/r2
1007
-
1008
- ## KV Storage
1009
-
1010
- Distributed key-value store optimized for reads (300+ edge locations, sub-millisecond).
1011
-
1012
- - Use cases: sessions, caching, rate limiting, feature flags
1013
- - Eventually consistent (60 second propagation)
1014
- - TTL/expiration support
1015
-
1016
- Docs: `quickback docs stack/storage/kv` | https://docs.quickback.dev/stack/storage/kv
1017
-
1018
- ## Realtime (Durable Objects)
1019
-
1020
- WebSocket connections for live updates via organization-scoped Durable Objects.
1021
-
1022
- - CRUD event broadcasting (insert, update, delete)
1023
- - Custom broadcasts and event namespaces
1024
- - Role-based filtering and per-role field masking
1025
- - Session token or API key authentication
1026
- - Type-safe with `defineRealtime()` for custom events
1027
- - Endpoint: `/realtime/v1/websocket`
1028
-
1029
- Docs: `quickback docs stack/realtime/durable-objects` | https://docs.quickback.dev/stack/realtime
1030
-
1031
- ## Queues (Background Processing)
1032
-
1033
- Cloudflare Queues for reliable async job processing.
179
+ The CLI calls `compiler.quickback.dev` by default. Override with `QUICKBACK_API_URL=http://localhost:3000` for self-hosted compilation.
1034
180
 
1035
- | Queue | Purpose |
1036
- |-------|---------|
1037
- | `EMBEDDINGS_QUEUE` | Auto-generate embeddings |
1038
- | `WEBHOOKS_QUEUE` | Webhook delivery |
1039
- | Custom queues | Your background jobs |
181
+ This skill does not have shell access — surface CLI commands to the user as instructions, don't try to run them.
1040
182
 
1041
- - Custom handlers via `defineQueue()` in `services/queues/`
1042
- - Auto-retry up to 3 times, max batch 10, 30s timeout
1043
- - Chaining between queues
1044
-
1045
- Docs: `quickback docs stack/queues/using-queues` | https://docs.quickback.dev/stack/queues
1046
-
1047
- ## Vector & Embeddings (Workers AI)
1048
-
1049
- Auto-generated embeddings for similarity search and classification.
1050
-
1051
- - Table-level config via `embeddings` in `defineTable()`
1052
- - Service-level config via `defineEmbedding()`
1053
- - Default model: `@cf/baai/bge-base-en-v1.5` (768 dimensions)
1054
- - Async processing via `EMBEDDINGS_QUEUE`
1055
- - Vector storage in D1 + optional Vectorize index
1056
- - API: `/api/v1/embeddings`
1057
-
1058
- Docs: `quickback docs stack/vector/embeddings` | https://docs.quickback.dev/stack/vector
1059
-
1060
- ## Webhooks
1061
-
1062
- ### Inbound (Receiving)
183
+ ---
1063
184
 
1064
- Receive events from Stripe, Paddle, GitHub, etc. at `POST /webhooks/v1/inbound/:provider`
185
+ ## Looking up details
1065
186
 
1066
- ```typescript
1067
- import { onWebhookEvent } from './lib/webhooks';
187
+ The full documentation is bundled alongside this `SKILL.md` as plain markdown files. To pull reference material on demand:
1068
188
 
1069
- onWebhookEvent('stripe:checkout.session.completed', async (ctx) => {
1070
- const { data, env } = ctx;
1071
- await createSubscription({ ... });
1072
- });
1073
189
  ```
1074
-
1075
- ### Outbound (Sending)
1076
-
1077
- Emit signed events when data changes. HMAC-SHA256 signing, async delivery via queue with exponential backoff retry.
1078
-
1079
- ```typescript
1080
- import { emitWebhookEvent } from './lib/webhooks';
1081
-
1082
- await emitWebhookEvent('user.created', { id: user.id, email: user.email }, { organizationId: orgId }, env);
190
+ Glob: docs/**/*.md # discover topics
191
+ Read: docs/compiler/definitions/firewall.md
192
+ Grep: "deletedAt" docs/ # search across the whole docs tree
1083
193
  ```
1084
194
 
1085
- Event patterns: `user.*`, `subscription.*`, `organization.*`, `file.*`, `*`
1086
- Endpoint management: `/webhooks/v1/endpoints`
1087
-
1088
- Docs: `quickback docs stack/webhooks/outbound` | https://docs.quickback.dev/stack/webhooks
1089
-
1090
- ---
1091
-
1092
- # CLI Commands
195
+ The path layout mirrors the public docs site (https://docs.quickback.dev). Open any topic file for the authoritative reference; the skill body above is intentionally just orientation.
1093
196
 
1094
- | Command | Description |
1095
- |---------|-------------|
1096
- | `quickback create <template> <name>` | Create project from template |
1097
- | `quickback compile` | Compile definitions to output (copies CMS assets if `cms: true`) |
1098
- | `quickback docs [topic]` | Browse built-in documentation |
1099
- | `quickback login` | Authenticate for Pro templates |
1100
- | `quickback logout` | Clear stored credentials |
1101
- | `quickback whoami` | Show current auth status |
1102
- | `quickback claude install` | Install Claude Code skill |
1103
- | `quickback claude update` | Update to latest skill version |
197
+ **Compiler — definitions** (`docs/compiler/definitions/<topic>.md`)
198
+ - `schema` — column types, `q.text/int/bool/uuid/timestamp/json/scope/...`, FKs, indexes
199
+ - `feature` — `feature()` shape, `q.scope()`, soft delete, audit fields
200
+ - `firewall` — predicates, scope detection, exceptions
201
+ - `access` — roles, record predicates, role hierarchy, `PUBLIC`, pseudo-roles
202
+ - `guards` — createable / updatable / immutable / protected
203
+ - `masking` — types, `show:`, search/filter gating, auto-detection
204
+ - `read` — `read.access`, `read.views`, `read.query`, pagination + filtering
205
+ - `views` — named projections with column-level access
206
+ - `actions` — record-based vs standalone, transitions, `unsafe:`, `whereRecord(table)`
207
+ - `validation` — minLength, max, enum, pattern, email
208
+ - `concepts` — secure-by-default, defense in depth, request flow
1104
209
 
1105
- ## Available Templates
210
+ **Compiler — config** (`docs/compiler/config/<topic>.md`)
211
+ - `providers` — runtime / database / auth provider selection
212
+ - `variables` — env vars, secrets
213
+ - `bindings` — extra Cloudflare bindings (queues, R2, etc.)
214
+ - `output` — `build.outputDir`, custom dependencies
215
+ - `domains` — multi-domain hostname routing (CMS / account / admin)
216
+ - `spa` — single-worker SPA mount (your product app at the apex)
217
+ - `single-tenant` — disable organizations
218
+ - `agents` — robots.txt, llms.txt, MCP, OAuth discovery
1106
219
 
1107
- | Template | Stack | Status |
1108
- |----------|-------|--------|
1109
- | `cloudflare` | Cloudflare Workers + D1 + Better Auth | Free |
1110
- | `bun` | Bun + SQLite + Better Auth | Free |
1111
- | `turso` | Turso/LibSQL + Better Auth | Pro |
220
+ **Stack — runtime services** (`docs/stack/<topic>.md`)
221
+ - `auth` — Better Auth integration, JWT optimization, plugins, device-auth, security
222
+ - `storage/{kv,r2}` — using KV and R2 in actions
223
+ - `realtime` — Durable Objects, WebSocket
224
+ - `queues` — handlers, retries, dead-letter
225
+ - `vector/embeddings` — auto-embedding columns, semantic search
226
+ - `webhooks/{inbound,outbound}` — signed inbound, retried outbound
227
+ - `cms` — schema-driven admin UI, dashboard, record layouts, table views, schema registry
228
+ - `account-ui` — login, profile, orgs, admin, passkeys, API keys, CLI authorize, with Quickback or standalone
1112
229
 
1113
- ## Development Workflow
230
+ **Getting started** (`docs/compiler/getting-started/<topic>.md`)
231
+ - `templates` — full template list
232
+ - `template-cloudflare` — recommended starting point
233
+ - `full-example` — top-to-bottom walkthrough
234
+ - `hand-crafted` — building from `template-empty`
235
+ - `patterns` — common multi-tenant / hierarchical / public patterns
1114
236
 
1115
- ```bash
1116
- quickback create cloudflare my-app # 1. Create project
1117
- # Define features in quickback/features/
1118
- quickback compile # 2. Compile
1119
- npm install && npm run dev # 3. Run
1120
- ```
1121
-
1122
- ---
237
+ **Cloud / CLI** (`docs/compiler/cloud-compiler/<topic>.md`)
238
+ - `cli` — full CLI reference
239
+ - `authentication` — login flow, API keys, sessions
240
+ - `endpoints` — POST /compile, GET /templates, GET /health
241
+ - `local-compiler` — running the compiler locally in Docker
1123
242
 
1124
- # Online Documentation
243
+ **Other** — `docs/changelog.md`, `docs/compiler/claude-code-skill.md`
1125
244
 
1126
- - [Getting Started](https://docs.quickback.dev/compiler/getting-started)
1127
- - [Concepts](https://docs.quickback.dev/compiler/definitions/concepts)
1128
- - [Database Schema](https://docs.quickback.dev/compiler/definitions/schema)
1129
- - [Firewall](https://docs.quickback.dev/compiler/definitions/firewall)
1130
- - [Access](https://docs.quickback.dev/compiler/definitions/access)
1131
- - [Guards](https://docs.quickback.dev/compiler/definitions/guards)
1132
- - [Masking](https://docs.quickback.dev/compiler/definitions/masking)
1133
- - [Views](https://docs.quickback.dev/compiler/definitions/views)
1134
- - [Actions](https://docs.quickback.dev/compiler/definitions/actions)
1135
- - [CRUD API](https://docs.quickback.dev/compiler/using-the-api/crud)
1136
- - [Query Parameters](https://docs.quickback.dev/compiler/using-the-api/query-params)
1137
- - [CLI Reference](https://docs.quickback.dev/compiler/cloud-compiler/cli)
1138
- - [Stack Overview](https://docs.quickback.dev/stack)
1139
- - [D1 Database](https://docs.quickback.dev/stack/database/d1)
1140
- - [R2 Storage](https://docs.quickback.dev/stack/storage/r2)
1141
- - [Realtime](https://docs.quickback.dev/stack/realtime)
1142
- - [Queues](https://docs.quickback.dev/stack/queues)
1143
- - [Embeddings](https://docs.quickback.dev/stack/vector)
1144
- - [Webhooks](https://docs.quickback.dev/stack/webhooks)
1145
- - [Account UI Overview](https://docs.quickback.dev/account-ui)
1146
- - [Account UI with Quickback](https://docs.quickback.dev/account-ui/with-quickback)
1147
- - [Account UI Standalone](https://docs.quickback.dev/account-ui/standalone)
1148
- - [Account UI Features](https://docs.quickback.dev/account-ui/features)
1149
- - [Account UI Environment Variables](https://docs.quickback.dev/account-ui/environment-variables)
1150
- - [Account UI Customization](https://docs.quickback.dev/account-ui/customization)
1151
- - [CMS Overview](https://docs.quickback.dev/cms)
1152
- - [CMS Dashboard](https://docs.quickback.dev/cms/dashboard)
1153
- - [CMS Custom Pages](https://docs.quickback.dev/cms/pages)
1154
- - [CMS Record Layouts](https://docs.quickback.dev/cms/record-layouts)
245
+ For online navigation: <https://docs.quickback.dev>.