dzql 0.1.0-alpha.2 → 0.1.0-alpha.3

package/GETTING_STARTED.md

@@ -1,34 +1,71 @@
-# Getting Started with DZQL
+# Getting Started with DZQL - Practical Guide
 
-DZQL is a PostgreSQL-powered framework that provides automatic CRUD operations via WebSocket RPC with zero boilerplate. This guide walks you through setting up your first DZQL project.
+DZQL is a PostgreSQL framework that gives you **atomic real-time updates** via WebSocket. Every database change broadcasts instantly to all connected clients. Zero boilerplate.
+
+## The Core Pattern
+
+1. **Schema = API**: Define a table → DZQL auto-creates CRUD endpoints
+2. **Atomic Updates**: Every change is one transaction, broadcasts to all clients
+3. **Real-time Sync**: Listen to broadcasts, update local state, re-render
+4. **No Polling**: Changes propagate instantly, no stale data
+
+```javascript
+// Listen to broadcasts
+ws.onBroadcast((method, params) => {
+  if (method === "todos:insert") state.todos.push(params.data)
+  else if (method === "todos:update") {
+    const idx = state.todos.findIndex(t => t.id === params.data.id)
+    if (idx !== -1) state.todos[idx] = params.data
+  }
+  else if (method === "todos:delete") {
+    state.todos = state.todos.filter(t => t.id !== params.data.id)
+  }
+  render()  // One render function, called on every change
+})
+```
+
+That's the entire pattern. All clients stay in sync automatically.
 
 ## Prerequisites
 
-- **Bun** 1.0+ (Node.js not required!)
-- **Docker** and **Docker Compose** (for PostgreSQL)
+- **Bun** 1.0+ (Node.js not required)
+- **Docker** and **Docker Compose**
 - A code editor
 
-## Quick Start (5 minutes)
+## Quick Start (10 minutes)
 
-### 1. Create a New Project
+### 1. Create Project
 
 ```bash
 mkdir my-dzql-app
 cd my-dzql-app
 bun init
+bun add dzql
+
+# Create directories
+mkdir -p public init_db
 ```
 
-### 2. Install DZQL
+### 2. Project Structure
 
-```bash
-bun add dzql
+```
+my-dzql-app/
+├── index.js                    # DZQL server
+├── public/
+│   ├── index.html             # HTML markup
+│   ├── index.css              # Styles
+│   └── app.js                 # JavaScript
+├── init_db/
+│   └── 001_domain.sql         # Your schema
+├── compose.yml                # PostgreSQL config
+├── package.json
+└── app.test.ts                # Tests (optional)
 ```
 
-### 3. Set Up PostgreSQL with Docker
+### 3. Docker Setup
 
-Create a `docker-compose.yml`:
+Create `compose.yml`:
 
-**For standalone projects (using npm/bun):**
 ```yaml
 services:
   postgres:
@@ -38,232 +75,677 @@ services:
       POSTGRES_PASSWORD: dzql
       POSTGRES_DB: dzql
     volumes:
-      # DZQL Core System migrations
-      - node_modules/dzql/src/database/migrations/001_schema.sql:/docker-entrypoint-initdb.d/001_schema.sql:ro
-      - node_modules/dzql/src/database/migrations/002_functions.sql:/docker-entrypoint-initdb.d/002_functions.sql:ro
-      - node_modules/dzql/src/database/migrations/003_operations.sql:/docker-entrypoint-initdb.d/003_operations.sql:ro
-      - node_modules/dzql/src/database/migrations/004_search.sql:/docker-entrypoint-initdb.d/004_search.sql:ro
-      - node_modules/dzql/src/database/migrations/005_entities.sql:/docker-entrypoint-initdb.d/005_entities.sql:ro
-      - node_modules/dzql/src/database/migrations/006_auth.sql:/docker-entrypoint-initdb.d/006_auth.sql:ro
-      - node_modules/dzql/src/database/migrations/007_events.sql:/docker-entrypoint-initdb.d/007_events.sql:ro
-      - node_modules/dzql/src/database/migrations/008_hello.sql:/docker-entrypoint-initdb.d/008_hello.sql:ro
-      - node_modules/dzql/src/database/migrations/008a_meta.sql:/docker-entrypoint-initdb.d/008a_meta.sql:ro
-      # Your domain-specific migrations
-      - ./init_db:/docker-entrypoint-initdb.d/init_db:ro
+      - ./node_modules/dzql/src/database/migrations/001_schema.sql:/docker-entrypoint-initdb.d/001_schema.sql:ro
+      - ./node_modules/dzql/src/database/migrations/002_functions.sql:/docker-entrypoint-initdb.d/002_functions.sql:ro
+      - ./node_modules/dzql/src/database/migrations/003_operations.sql:/docker-entrypoint-initdb.d/003_operations.sql:ro
+      - ./node_modules/dzql/src/database/migrations/004_search.sql:/docker-entrypoint-initdb.d/004_search.sql:ro
+      - ./node_modules/dzql/src/database/migrations/005_entities.sql:/docker-entrypoint-initdb.d/005_entities.sql:ro
+      - ./node_modules/dzql/src/database/migrations/006_auth.sql:/docker-entrypoint-initdb.d/006_auth.sql:ro
+      - ./node_modules/dzql/src/database/migrations/007_events.sql:/docker-entrypoint-initdb.d/007_events.sql:ro
+      - ./node_modules/dzql/src/database/migrations/008_hello.sql:/docker-entrypoint-initdb.d/008_hello.sql:ro
+      - ./node_modules/dzql/src/database/migrations/008a_meta.sql:/docker-entrypoint-initdb.d/008a_meta.sql:ro
+      - ./init_db/001_domain.sql:/docker-entrypoint-initdb.d/010_domain.sql:ro
     ports:
       - "5432:5432"
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U dzql"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
 ```
 
-**For monorepo projects (like the venues example):**
+**For monorepo projects** (like the venues example), use relative paths:
 ```yaml
-services:
-  postgres:
-    image: postgres:latest
-    environment:
-      POSTGRES_USER: dzql
-      POSTGRES_PASSWORD: dzql
-      POSTGRES_DB: dzql
-    volumes:
-      # DZQL Core System migrations (relative path from monorepo root)
-      - ../../dzql/src/database/migrations/001_schema.sql:/docker-entrypoint-initdb.d/001_schema.sql:ro
-      - ../../dzql/src/database/migrations/002_functions.sql:/docker-entrypoint-initdb.d/002_functions.sql:ro
-      - ../../dzql/src/database/migrations/003_operations.sql:/docker-entrypoint-initdb.d/003_operations.sql:ro
-      - ../../dzql/src/database/migrations/004_search.sql:/docker-entrypoint-initdb.d/004_search.sql:ro
-      - ../../dzql/src/database/migrations/005_entities.sql:/docker-entrypoint-initdb.d/005_entities.sql:ro
-      - ../../dzql/src/database/migrations/006_auth.sql:/docker-entrypoint-initdb.d/006_auth.sql:ro
-      - ../../dzql/src/database/migrations/007_events.sql:/docker-entrypoint-initdb.d/007_events.sql:ro
-      - ../../dzql/src/database/migrations/008_hello.sql:/docker-entrypoint-initdb.d/008_hello.sql:ro
-      - ../../dzql/src/database/migrations/008a_meta.sql:/docker-entrypoint-initdb.d/008a_meta.sql:ro
-      # Your domain-specific migrations
-      - ./init_db:/docker-entrypoint-initdb.d/init_db:ro
-    ports:
-      - "5432:5432"
+volumes:
+  - ../../dzql/src/database/migrations/001_schema.sql:/docker-entrypoint-initdb.d/001_schema.sql:ro
+  # ... etc
 ```
 
 Start PostgreSQL:
-
 ```bash
 docker compose up -d
 ```
 
-### 4. Initialize Database
+### 4. Database Schema
 
-The docker-compose.yml automatically runs DZQL core migrations from `node_modules/dzql/src/database/migrations/`.
-
-Create your domain-specific migrations in `database/init_db/001_domain.sql`:
+Create `init_db/001_domain.sql`:
 
 ```sql
--- Create your tables (after DZQL core is set up)
-CREATE TABLE IF NOT EXISTS users (
+CREATE TABLE IF NOT EXISTS todos (
   id SERIAL PRIMARY KEY,
-  name TEXT NOT NULL,
-  email TEXT NOT NULL UNIQUE,
-  created_at TIMESTAMPTZ DEFAULT NOW()
+  user_id INT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  title TEXT NOT NULL,
+  description TEXT,
+  completed BOOLEAN DEFAULT FALSE,
+  created_at TIMESTAMPTZ DEFAULT NOW(),
+  updated_at TIMESTAMPTZ DEFAULT NOW()
 );
 
--- Register your entities with DZQL
+CREATE INDEX IF NOT EXISTS idx_todos_user_id ON todos(user_id);
+
 SELECT dzql.register_entity(
-  p_table_name := 'users',
-  p_label_field := 'name',
-  p_searchable_fields := array['name', 'email'],
-  p_fk_includes := '{}'::jsonb
+  p_table_name := 'todos',
+  p_label_field := 'title',
+  p_searchable_fields := array['title', 'description']
 );
 ```
 
-**Important:** Your migrations run AFTER the DZQL core migrations, so entity registration functions are available.
+### 5. Server
 
-Start PostgreSQL:
-
-```bash
-docker compose up -d
-```
-
-The Docker Compose file will automatically run all DZQL core migrations first, then your domain migrations.
-
-### 5. Create Your Server
-
-Create `server/index.js`:
+Create `index.js`:
 
 ```javascript
-import { createServer } from 'dzql';
+import { createServer } from "dzql";
+import index from "./public/index.html";
 
 const server = createServer({
   port: process.env.PORT || 3000,
-  // Optional: custom API functions
-  customApi: {},
-  // Optional: static file serving
-  staticPath: './public'
+  routes: {
+    "/": index,
+  },
 });
 
-console.log(`🚀 Server running on port ${server.port}`);
+console.log(`🚀 DZQL Server running on http://localhost:${server.port}`);
 ```
 
-### 6. Start Your Server
-
-```bash
-bun server/index.js
+### 6. HTML
+
+Create `public/index.html`:
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>DZQL Todo App</title>
+    <link rel="stylesheet" href="./index.css" />
+  </head>
+  <body>
+    <div class="container">
+      <h1>✓ Todo App</h1>
+      <div id="status" class="status disconnected">Connecting...</div>
+      <div id="error" class="error hidden"></div>
+
+      <div id="authSection" class="section">
+        <h2>Login or Register</h2>
+        <form id="authForm" onsubmit="handleLoginSubmit(event)">
+          <div class="form-group">
+            <label>Email</label>
+            <input type="email" id="email" placeholder="user@example.com" required />
+          </div>
+          <div class="form-group">
+            <label>Password</label>
+            <input type="password" id="password" placeholder="••••••••" required />
+          </div>
+          <div class="btn-group">
+            <button type="submit" class="btn-primary">Login</button>
+            <button type="button" class="btn-secondary" onclick="handleRegister()">Register</button>
+          </div>
+        </form>
+      </div>
+
+      <div id="appSection" class="section hidden">
+        <button class="btn-secondary" style="width: 100%; margin-bottom: 20px" onclick="handleLogout()">
+          Logout
+        </button>
+
+        <div class="section">
+          <h2>Create Todo</h2>
+          <form id="todoForm" onsubmit="event.preventDefault(); handleAddTodo()">
+            <div class="form-group">
+              <label>Title</label>
+              <input type="text" id="todoTitle" placeholder="What needs to be done?" required />
+            </div>
+            <div class="form-group">
+              <label>Description</label>
+              <textarea id="todoDescription" placeholder="Add details..." rows="2"></textarea>
+            </div>
+            <button type="submit" class="btn-primary" style="width: 100%">Add Todo</button>
+          </form>
+        </div>
+
+        <div class="section">
+          <h2>Todos</h2>
+          <div id="todoList" class="todo-list"></div>
+          <div id="emptyState" class="empty-state">No todos yet</div>
+        </div>
+      </div>
+    </div>
+
+    <script type="module" src="./app.js"></script>
+  </body>
+</html>
 ```
 
-Your DZQL server is now running at `ws://localhost:3000/ws`!
+### 7. CSS
 
-## Project Setup: Standalone vs Monorepo
+Create `public/index.css`:
 
-### Standalone Project (Recommended for Most Users)
-Use `node_modules/dzql/src/database/migrations/` paths in your docker-compose.yml
+```css
+* {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+}
 
-```
-my-app/
-├── database/
-│   ├── docker-compose.yml    # Uses node_modules paths
-│   └── init_db/
-│       └── 001_domain.sql
-├── server/
-├── client/
-└── package.json
-```
+body {
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+  background: #f5f5f5;
+  padding: 20px;
+}
 
-### Monorepo Project (Like the Venues Example)
-Use relative paths `../../dzql/src/database/migrations/` in docker-compose.yml
+.container {
+  max-width: 600px;
+  margin: 0 auto;
+  background: white;
+  padding: 30px;
+  border-radius: 8px;
+  box-shadow: 0 2px 10px rgba(0, 0, 0, 0.1);
+}
 
-```
-monorepo/
-├── packages/
-│   ├── dzql/                 # Framework package
-│   │   └── src/database/migrations/  # Core migrations
-│   └── my-app/               # Your app
-│       ├── database/
-│       │   └── docker-compose.yml   # References ../../dzql/...
-│       ├── server/
-│       └── package.json
+h1 {
+  margin-bottom: 20px;
+  color: #333;
+}
+
+.status {
+  padding: 10px;
+  border-radius: 4px;
+  margin-bottom: 20px;
+  font-weight: 500;
+}
+
+.status.connected {
+  background: #d4edda;
+  color: #155724;
+}
+
+.status.disconnected {
+  background: #f8d7da;
+  color: #721c24;
+}
+
+.error {
+  padding: 10px;
+  background: #f8d7da;
+  color: #721c24;
+  border-radius: 4px;
+  margin-bottom: 20px;
+}
+
+.hidden {
+  display: none;
+}
+
+.section {
+  margin-bottom: 30px;
+}
+
+.form-group {
+  margin-bottom: 15px;
+}
+
+.form-group label {
+  display: block;
+  margin-bottom: 5px;
+  font-weight: 500;
+  color: #333;
+}
+
+.form-group input,
+.form-group textarea {
+  width: 100%;
+  padding: 10px;
+  border: 1px solid #ddd;
+  border-radius: 4px;
+  font-size: 14px;
+}
+
+.btn-group {
+  display: flex;
+  gap: 10px;
+}
+
+button {
+  padding: 10px 20px;
+  border: none;
+  border-radius: 4px;
+  cursor: pointer;
+  font-size: 14px;
+  font-weight: 500;
+}
+
+.btn-primary {
+  background: #007bff;
+  color: white;
+  flex: 1;
+}
+
+.btn-primary:hover {
+  background: #0056b3;
+}
+
+.btn-secondary {
+  background: #6c757d;
+  color: white;
+  flex: 1;
+}
+
+.btn-secondary:hover {
+  background: #545b62;
+}
+
+.btn-danger {
+  background: #dc3545;
+  color: white;
+  padding: 5px 10px;
+  font-size: 12px;
+}
+
+.btn-danger:hover {
+  background: #c82333;
+}
+
+.todo-list {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+
+.todo-item {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 15px;
+  background: #f8f9fa;
+  border-radius: 4px;
+  border: 1px solid #e9ecef;
+}
+
+.todo-item.completed {
+  opacity: 0.6;
+}
+
+.todo-item.completed .todo-title {
+  text-decoration: line-through;
+}
+
+.todo-checkbox {
+  width: 20px;
+  height: 20px;
+  cursor: pointer;
+}
+
+.todo-content {
+  flex: 1;
+}
+
+.todo-title {
+  font-weight: 500;
+  margin-bottom: 5px;
+}
+
+.todo-description {
+  font-size: 14px;
+  color: #666;
+}
+
+.empty-state {
+  text-align: center;
+  color: #999;
+  padding: 40px;
+  font-style: italic;
+}
 ```
 
-## Using DZQL in Your Client
+### 8. JavaScript
 
-### Browser/Frontend
+Create `public/app.js`:
 
 ```javascript
-import { useWs, WebSocketManager } from 'dzql/client';
+import { WebSocketManager } from "dzql/client";
+
+let ws = null;
+let state = {
+  connected: false,
+  loggedIn: false,
+  userId: null,
+  todos: [],
+};
+
+function query(selector) {
+  return document.getElementById(selector);
+}
 
-// Create a fresh WebSocket connection
-const ws = new WebSocketManager();
+function render() {
+  const status = query("status");
+  status.textContent = state.connected
+    ? state.loggedIn
+      ? "✓ Connected"
+      : "✓ Connected (not logged in)"
+    : "✗ Disconnected";
+  status.className = `status ${state.connected ? "connected" : "disconnected"}`;
+
+  query("authSection").classList.toggle("hidden", state.loggedIn);
+  query("appSection").classList.toggle("hidden", !state.loggedIn);
+
+  if (state.loggedIn) {
+    const list = query("todoList");
+    const empty = query("emptyState");
+
+    if (state.todos.length === 0) {
+      list.innerHTML = "";
+      empty.classList.remove("hidden");
+    } else {
+      empty.classList.add("hidden");
+      list.innerHTML = state.todos
+        .map(
+          (todo) => `
+        <div class="todo-item ${todo.completed ? "completed" : ""}">
+          <input type="checkbox" class="todo-checkbox" ${todo.completed ? "checked" : ""}
+            onchange="handleToggleTodo(${todo.id})">
+          <div class="todo-content">
+            <div class="todo-title">${escapeHtml(todo.title)}</div>
+            ${todo.description ? `<div class="todo-description">${escapeHtml(todo.description)}</div>` : ""}
+          </div>
+          <button class="btn-danger" onclick="handleDeleteTodo(${todo.id})">Delete</button>
+        </div>
+      `,
+        )
+        .join("");
+    }
+  }
+}
 
-// Connect to server
-await ws.connect();
+function escapeHtml(text) {
+  const div = document.createElement("div");
+  div.textContent = text;
+  return div.innerHTML;
+}
 
-// Login
-const result = await ws.api.login_user({
-  email: 'user@example.com',
-  password: 'password123'
-});
+function error(msg) {
+  const el = query("error");
+  el.textContent = msg;
+  el.classList.remove("hidden");
+  setTimeout(() => el.classList.add("hidden"), 5000);
+}
 
-// Use DZQL operations - all 5 operations work the same way:
-// GET, SAVE, DELETE, LOOKUP, SEARCH
+async function auth(type) {
+  const email = query("email").value;
+  const password = query("password").value;
+
+  if (!email || !password) {
+    error("Email and password required");
+    return;
+  }
+
+  try {
+    const result = await ws.api[type]({ email, password });
+    if (result.token) {
+      localStorage.setItem("dzql_token", result.token);
+      state.loggedIn = true;
+      state.userId = result.user_id;
+      await loadTodos();
+      render();
+    }
+  } catch (err) {
+    error(err.message || `${type} failed`);
+  }
+}
 
-// GET - Retrieve a single record
-const user = await ws.api.get.users({ id: 1 });
+async function loadTodos() {
+  try {
+    const result = await ws.api.search.todos({
+      filters: { user_id: state.userId },
+      limit: 100,
+    });
+    state.todos = result.data || [];
+  } catch (err) {
+    error("Failed to load todos");
+    throw err;
+  }
+}
 
-// SAVE - Create or update (upsert)
-const newUser = await ws.api.save.users({
-  name: 'John Doe',
-  email: 'john@example.com'
-});
+async function handleAddTodo() {
+  const title = query("todoTitle").value.trim();
+  const description = query("todoDescription").value.trim();
+
+  if (!title) {
+    error("Title required");
+    return;
+  }
+
+  try {
+    await ws.api.save.todos({
+      user_id: state.userId,
+      title,
+      description,
+      completed: false,
+    });
+    query("todoTitle").value = "";
+    query("todoDescription").value = "";
+  } catch (err) {
+    error("Failed to create todo");
+  }
+}
 
-// LOOKUP - Autocomplete/suggestions
-const suggestions = await ws.api.lookup.users({
-  p_filter: 'john'
-});
+async function handleToggleTodo(id) {
+  try {
+    const todo = state.todos.find((t) => t.id === id);
+    if (todo) {
+      await ws.api.save.todos({
+        id,
+        user_id: state.userId,
+        completed: !todo.completed,
+      });
+    }
+  } catch (err) {
+    error("Failed to update todo");
+  }
+}
 
-// SEARCH - Full search with filters and pagination
-const results = await ws.api.search.users({
-  filters: {
-    name: { ilike: '%john%' },
-    email: 'john@example.com'
-  },
-  page: 1,
-  limit: 10
-});
+async function handleDeleteTodo(id) {
+  if (!confirm("Delete this todo?")) return;
+  try {
+    await ws.api.delete.todos({ id });
+  } catch (err) {
+    error("Failed to delete todo");
+  }
+}
 
-// DELETE - Remove a record
-const deleted = await ws.api.delete.users({ id: 1 });
+async function init() {
+  try {
+    ws = new WebSocketManager();
+    await ws.connect();
+    state.connected = true;
+
+    ws.onBroadcast((method, params) => {
+      if (!state.loggedIn) return;
+
+      const data = params.data;
+      if (method === "todos:insert") {
+        state.todos.push(data);
+      } else if (method === "todos:update") {
+        const idx = state.todos.findIndex((t) => t.id === data.id);
+        if (idx !== -1) state.todos[idx] = data;
+      } else if (method === "todos:delete") {
+        state.todos = state.todos.filter((t) => t.id !== data.id);
+      }
+      render();
+    });
+
+    const token = localStorage.getItem("dzql_token");
+    if (token) {
+      try {
+        const payload = JSON.parse(atob(token.split(".")[1]));
+        state.userId = payload.user_id;
+        await loadTodos();
+        state.loggedIn = true;
+      } catch (err) {
+        localStorage.removeItem("dzql_token");
+        state.loggedIn = false;
+        state.userId = null;
+      }
+    }
+
+    render();
+  } catch (err) {
+    state.connected = false;
+    error("Failed to connect");
+    render();
+  }
+}
 
-// When done
-ws.cleanDisconnect();
+window.handleAddTodo = handleAddTodo;
+window.handleToggleTodo = handleToggleTodo;
+window.handleDeleteTodo = handleDeleteTodo;
+window.handleLoginSubmit = (e) => {
+  e.preventDefault();
+  auth("login_user");
+};
+window.handleRegister = () => auth("register_user");
+window.handleLogout = async () => {
+  try {
+    await ws.api.logout();
+    localStorage.removeItem("dzql_token");
+    state.loggedIn = false;
+    state.userId = null;
+    state.todos = [];
+    render();
+  } catch (err) {
+    error("Logout failed");
+  }
+};
+
+init();
 ```
 
-### Bun/Backend
+### 9. Package.json
+
+```json
+{
+  "name": "dzql-todo-app",
+  "module": "index.js",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "dev": "bun --hot index.js",
+    "start": "bun index.js",
+    "db:up": "docker compose up -d",
+    "db:down": "docker compose down",
+    "test": "playwright test"
+  },
+  "dependencies": {
+    "dzql": "latest"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.56.1",
+    "@types/bun": "latest"
+  }
+}
+```
 
-```javascript
-import { db, sql } from 'dzql';
+## Run
 
-// Direct database queries
-const users = await sql`SELECT * FROM users`;
+```bash
+# Start database
+bun run db:up
 
-// DZQL operations (require userId)
-const user = await db.api.get.users({ id: 1 }, userId);
-const saved = await db.api.save.users({ name: 'John' }, userId);
-const searched = await db.api.search.users({ filters: {} }, userId);
+# Start server (with hot reload)
+bun run dev
+
+# In another terminal, run tests (optional)
+bun run test
 ```
 
-## Project Structure
+Access at `http://localhost:3000`
+
+## Testing with Playwright
 
-A typical DZQL project looks like:
+Install Playwright:
+```bash
+bun add -d @playwright/test
+bunx playwright install
+```
 
+Create `app.test.ts`:
+```typescript
+import { test, expect } from "@playwright/test";
+
+test("register and create todo", async ({ page }) => {
+  await page.goto("http://localhost:3000");
+  await page.waitForLoadState("networkidle");
+  
+  // Register
+  await page.locator("#email").fill(`test-${Date.now()}@example.com`);
+  await page.locator("#password").fill("testpass123");
+  await page.locator("button:has-text('Register')").click();
+  await page.waitForLoadState("networkidle");
+  
+  // Create todo
+  await page.locator("#todoTitle").fill("Buy milk");
+  await page.locator("button:has-text('Add Todo')").click();
+  await expect(page.locator(".todo-title:has-text('Buy milk')")).toBeVisible();
+});
 ```
-my-dzql-app/
-├── server/
-│   ├── index.js           # Server entry point
-│   └── api.js             # Custom API functions (optional)
-├── database/
-│   └── init_db/
-│       ├── 001_domain.sql # Your schema & entity registration
-│       └── 002_seed.sql   # Sample data (optional)
-├── public/                # Static files (optional)
-│   └── index.html
-├── docker-compose.yml
-├── bunfig.toml            # Bun config (optional)
-└── package.json
+
+Run tests:
+```bash
+bunx playwright test --headed  # see browser
+bunx playwright test           # headless
 ```
 
+**Testing Tips:**
+- Use unique emails per test: `test-${Date.now()}@example.com`
+- Wait for network: `await page.waitForLoadState("networkidle")`
+- Find elements by id, class, or text: `locator("#id")`, `locator(".class")`, `locator("button:has-text('text')")`
+
+## Key Architecture
+
+### Atomic Updates & Real-time Sync
+
+When user A saves a todo, it:
+1. Updates database atomically
+2. Broadcasts to all connected clients instantly
+3. All users see the change immediately
+
+```javascript
+ws.onBroadcast((method, params) => {
+  const data = params.data;
+  if (method === "todos:insert") {
+    state.todos.push(data);     // Add new
+  } else if (method === "todos:update") {
+    const idx = state.todos.findIndex(t => t.id === data.id);
+    if (idx !== -1) state.todos[idx] = data;  // Replace
+  } else if (method === "todos:delete") {
+    state.todos = state.todos.filter(t => t.id !== data.id);  // Remove
+  }
+  render();  // Re-render UI with new state
+});
+```
+
+That's it. Every user creating/updating/deleting a todo sees it **instantly** on all other clients. No polling, no re-fetching, no race conditions.
+
+### State Management
+- `state.connected` - WebSocket status
+- `state.loggedIn` - Authentication status
+- `state.userId` - Current user (from JWT on reload)
+- `state.todos` - User's todos array
+
+### Authentication Flow
+1. User registers/logs in
+2. Server returns token + user_id
+3. Token stored in localStorage
+4. On page reload, JWT decoded to get user_id
+5. Todos loaded with user filter
+
+### Single Render Function
+- `render()` handles ALL UI updates
+- Called after every state change
+- Also called on every broadcast update
+- No separate update functions needed
+
 ## The 5 DZQL Operations
 
 Every registered entity automatically gets these 5 operations:
@@ -313,9 +795,9 @@ const results = await ws.api.search.tableName({
 
 ## Entity Registration
 
-Before DZQL can work with a table, you must register it with the `dzql.register_entity()` function.
+Before DZQL can work with a table, you must register it with `dzql.register_entity()`.
 
-**Important:** This function is provided by DZQL's core migrations, which run automatically when PostgreSQL starts via docker-compose.
+**Important:** This function is provided by DZQL's core migrations, which run automatically when PostgreSQL starts via compose.yml.
 
 ```sql
 SELECT dzql.register_entity(
@@ -338,45 +820,105 @@ See the [venues example](https://github.com/blueshed/dzql/blob/main/packages/ven
 
 ## Custom API Functions
 
-Add custom functions that work alongside DZQL operations:
+Add custom functions that work alongside DZQL operations.
+
+### PostgreSQL Functions
+
+Create stored procedures that execute server-side:
 
-**PostgreSQL Function:**
 ```sql
 CREATE OR REPLACE FUNCTION my_function(
   p_user_id INT,
-  p_name TEXT
-) RETURNS TABLE (message TEXT) AS $$
+  p_name TEXT DEFAULT 'World'
+) RETURNS JSONB
+LANGUAGE plpgsql
+SECURITY DEFINER
+AS $$
 BEGIN
-  RETURN QUERY SELECT 'Hello, ' || p_name;
+  -- Your logic here
+  RETURN jsonb_build_object('message', 'Hello, ' || p_name);
 END;
-$$ LANGUAGE plpgsql;
+$$;
 ```
 
-**Call from Client:**
+Call from client:
 ```javascript
 const result = await ws.api.my_function({ name: 'World' });
 // Returns: { message: 'Hello, World' }
 ```
 
-**Bun Function:**
+### Bun Functions
+
+Create JavaScript functions that run in the Bun server:
+
 ```javascript
 // server/api.js
-export async function my_function(userId, params = {}) {
+export async function myBunFunction(userId, params = {}) {
+  const { name = 'World' } = params;
+  
+  // Can use db.api for database access
+  // const user = await db.api.get.users({ id: userId }, userId);
+  
   return {
-    message: `Hello, ${params.name}!`,
+    message: `Hello, ${name}!`,
     user_id: userId
   };
 }
 ```
 
-Then pass it to createServer:
+Pass to server:
 ```javascript
-const customApi = await import('./api.js');
+import { createServer } from 'dzql';
+import * as customApi from './server/api.js';
+
 const server = createServer({
+  port: 3000,
   customApi
 });
 ```
 
+Call from client:
+```javascript
+const result = await ws.api.myBunFunction({ name: 'World' });
+```
+
+**Both types:**
+- First parameter is always `user_id` (auto-injected on client)
+- Require authentication
+- Use same proxy API syntax
+- Return JSON-serializable data
+
+### Advanced Server Setup
+
+For routes that need real-time broadcasting:
+
+```javascript
+import { createServer } from 'dzql';
+
+const server = createServer({
+  port: 3000,
+  
+  // Static routes (don't need broadcast)
+  routes: {
+    '/health': () => new Response('OK'),
+    '/': () => new Response('Hello')
+  },
+  
+  // Routes that need broadcasting
+  onReady: async (broadcast) => {
+    // broadcast(method, params) - send to all clients
+    
+    return {
+      '/custom': async (req) => {
+        // Your logic
+        broadcast('custom:event', { data: 'something' });
+        return new Response('Done');
+      }
+    };
+  }
+});
+```
+
 ## Real-time Events
 
 DZQL broadcasts changes in real-time via WebSocket:
@@ -386,12 +928,19 @@ DZQL broadcasts changes in real-time via WebSocket:
 const unsubscribe = ws.onBroadcast((method, params) => {
   console.log(`Event: ${method}`, params);
   // method: "users:insert", "users:update", "users:delete"
+  // params: { table, op, pk, before, after, user_id, at }
 });
 
 // Stop listening
 unsubscribe();
 ```
 
+Event format:
+- `method`: `"{table}:{operation}"` (e.g., "todos:insert")
+- `params.data`: The affected record
+- `params.user_id`: User who made the change
+- `params.at`: Timestamp
+
 ## Authentication
 
 DZQL provides built-in user authentication:
@@ -421,19 +970,24 @@ const ws = new WebSocketManager();
 await ws.connect();  // Automatically uses token from localStorage
 ```
 
-## Error Handling
+## Server-Side API Usage
+
+For backend/Bun scripts:
 
 ```javascript
-try {
-  const user = await ws.api.get.users({ id: 999 });
-} catch (error) {
-  console.error(error.message);
-  // "record not found" - record doesn't exist
-  // "Permission denied: view on users" - access denied
-  // "Function not found" - custom function doesn't exist
-}
+import { db, sql } from 'dzql';
+
+// Direct SQL queries
+const users = await sql`SELECT * FROM users`;
+
+// DZQL operations (require explicit userId)
+const user = await db.api.get.users({ id: 1 }, userId);
+const saved = await db.api.save.users({ name: 'John' }, userId);
+const results = await db.api.search.users({ filters: {} }, userId);
 ```
 
+**Key difference:** Server-side requires explicit `userId` as second parameter; client-side auto-injects from JWT.
+
 ## Environment Variables
 
 ```bash
@@ -452,10 +1006,17 @@ WS_PING_INTERVAL=30000
 WS_PING_TIMEOUT=5000
 ```
 
-## Running Tests
+## Error Handling
 
-```bash
-bun test tests/
+```javascript
+try {
+  const user = await ws.api.get.users({ id: 999 });
+} catch (error) {
+  console.error(error.message);
+  // "record not found" - record doesn't exist
+  // "Permission denied: view on users" - access denied
+  // "Function not found" - custom function doesn't exist
+}
 ```
 
 ## Troubleshooting
@@ -464,9 +1025,11 @@ bun test tests/
 ```bash
 # Check if PostgreSQL is running
 docker ps
+
 # Check logs
 docker compose logs postgres
-# Restart
+
+# Restart database (fresh start)
 docker compose down -v && docker compose up -d
 ```
 
@@ -474,86 +1037,66 @@ docker compose down -v && docker compose up -d
 - Ensure server is running: `http://localhost:3000`
 - Check firewall for port 3000
 - Check browser console for errors
+- Verify WebSocket URL in client code
 
 ### Entity not found errors
 - Verify table is created in database
 - Verify entity is registered with `dzql.register_entity()`
-- Check `p_table_name` matches exactly
+- Check `p_table_name` matches table name exactly
+- Check migrations ran: `docker compose logs postgres`
 
 ### Permission denied errors
 - Implement permission rules in your entity registration
 - Check user authentication status
 - Verify user_id is being passed correctly
+- See venues example for permission path syntax
 
-## Next Steps
-
-1. **Read the full documentation**: Check the framework's README
-2. **Explore graph rules**: Add automation with `p_graph_rules`
-3. **Implement permissions**: Use path-based access control
-4. **Add notifications**: Set up `p_notification_path` for real-time updates
-5. **Build your UI**: Connect to any frontend framework (React, Vue, Svelte, etc.)
-
-## Example: Complete Todo App
+### Migrations not running
+- Check volume mounts in compose.yml
+- Ensure migration files exist in node_modules/dzql/
+- Check PostgreSQL logs: `docker compose logs postgres`
+- Try fresh start: `docker compose down -v && docker compose up -d`
 
-**Database Setup:**
-```sql
-CREATE TABLE todos (
-  id SERIAL PRIMARY KEY,
-  user_id INT NOT NULL REFERENCES users(id),
-  title TEXT NOT NULL,
-  completed BOOLEAN DEFAULT FALSE,
-  created_at TIMESTAMPTZ DEFAULT NOW()
-);
+### Real-time updates not working
+- Verify `onBroadcast` handler is set up
+- Check WebSocket connection status
+- Check browser console for errors
+- Verify entity is registered (triggers events)
 
-SELECT dzql.register_entity(
-  'todos',
-  'title',
-  array['title'],
-  '{"user": "users"}'::jsonb
-);
-```
+## DRY Principles Used
 
-**Server:**
-```javascript
-import { createServer } from 'dzql';
+- **Single `auth()` function** handles both login and register
+- **Single `render()` function** handles all UI updates
+- **`query()` helper** replaces repeated `getElementById()`
+- **Broadcast handler** calls `render()` once instead of separate functions
+- **Combined error handling** with reusable `error()` function
 
-const server = createServer({
-  port: 3000
-});
-```
+## Key Takeaways for Claude
 
-**Client:**
-```javascript
-const ws = new WebSocketManager();
-await ws.connect();
-await ws.api.login_user({ email: 'user@example.com', password: 'pass' });
+When building with DZQL:
+1. **Schema first** - Table definition automatically gives you API
+2. **Broadcasts = Real-time** - Listen to `entity:insert/update/delete` events
+3. **One render function** - Update state, call render(), DOM updates
+4. **User ID filtering** - Always pass `user_id` in queries and mutations
+5. **Token from JWT** - Decode on init: `JSON.parse(atob(token.split(".")[1]))`
+6. **DRY helpers** - Use `query()` for DOM, combine auth logic, single error handler
+7. **Index pattern** - `const idx = state.todos.findIndex(t => t.id === data.id)` for updates
 
-// Create todo
-const todo = await ws.api.save.todos({
-  title: 'Learn DZQL',
-  completed: false
-});
-
-// Get all todos
-const results = await ws.api.search.todos({
-  filters: { completed: false },
-  limit: 100
-});
+The app should feel simple. If it feels complex, something is wrong.
 
-// Update todo
-await ws.api.save.todos({
-  id: todo.id,
-  completed: true
-});
+## Next Steps
 
-// Delete todo
-await ws.api.delete.todos({ id: todo.id });
-```
+1. **Read the full documentation**: Check the framework's README and CLAUDE.md
+2. **Explore graph rules**: Add automation with `p_graph_rules`
+3. **Implement permissions**: Use path-based access control
+4. **Add notifications**: Set up `p_notification_path` for real-time updates
+5. **Build your UI**: Connect to any frontend framework (React, Vue, Svelte, etc.)
+6. **Study the venues example**: See a complete multi-entity application
 
 ## Support
 
 - **GitHub**: https://github.com/blueshed/dzql
 - **Issues**: https://github.com/blueshed/dzql/issues
-- **Documentation**: See README.md in the package
+- **Documentation**: See README.md and CLAUDE.md in the package
 
-Happy building! 🚀
+Happy building! 🚀

package/README.md

@@ -194,7 +194,15 @@ const result = await db.api.myCustomFunction({ param: 'value' }, userId);
 const server = createServer({
   port: 3000,
   customApi: {},           // Optional: add custom functions
-  staticPath: './public'   // Optional: serve static files
+  staticPath: './public',  // Optional: serve static files
+  routes: {                // Optional: standard HTTP routes
+    '/health': () => new Response('OK')
+  },
+  onReady: async (broadcast) => {  // Optional: routes needing broadcast
+    return {
+      '/mcp': createMCPRoute(broadcast)  // Example: MCP integration
+    };
+  }
 });
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dzql",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.3",
   "description": "PostgreSQL-powered framework with zero boilerplate CRUD operations and real-time WebSocket synchronization",
   "type": "module",
   "main": "src/server/index.js",
@@ -25,6 +25,7 @@
     "jose": "^6.1.0",
     "postgres": "^3.4.7"
   },
+
   "keywords": [
     "postgresql",
     "postgres",

package/src/server/index.js

@@ -13,7 +13,8 @@ export function createServer(options = {}) {
     port = process.env.PORT || 3000,
     customApi = {},
     routes = {},
-    staticPath = null  // No default static path - applications should specify
+    staticPath = null,  // No default static path - applications should specify
+    onReady = null      // Optional callback that receives { broadcast, server } after initialization
   } = options;
 
   // Merge default API with custom API
@@ -50,6 +51,14 @@ export function createServer(options = {}) {
 
   routes['/health'] = () => new Response("OK", { status: 200 });
 
+  // Call onReady callback if provided to allow dynamic route setup
+  if (onReady && typeof onReady === 'function') {
+    const additionalRoutes = onReady({ broadcast, routes });
+    if (additionalRoutes && typeof additionalRoutes === 'object') {
+      Object.assign(routes, additionalRoutes);
+    }
+  }
+
   // Create and start the Bun server
   const server = Bun.serve({
     port,