miti99bot/plans/260415-1010-d1-cron-infra/phase-06-docs.md

Phase 06 — Docs

Priority: P1 (last) Status: Complete Depends on: All prior phases (✓ complete)

Overview

Document D1 + Cron usage for module authors. Update existing architecture + module-authoring docs. Update CLAUDE.md module contract snippet.

Deliverables

Create

• docs/using-d1.md — how to add a D1-backed feature to a module

  • When to choose D1 vs KV (query patterns, relational needs, scans)
  • Writing migrations (src/modules/<name>/migrations/NNNN_name.sql)
  • sql.prepare/run/all/first/batch API reference
  • Table naming convention ({module}_{table})
  • Accessing sql from init and command handlers
  • Testing with Miniflare D1 (tests/fakes/fake-d1.js)
  • Running migrations: npm run db:migrate

• docs/using-cron.md — how to add a scheduled job to a module

  • Declaring crons: [{ schedule, name, handler }]
  • Cron expression syntax + Cloudflare limits
  • Registering schedule in wrangler.toml [triggers] crons
  • Handler signature (event, { db, sql, env })
  • Local testing: curl "http://localhost:8787/__scheduled?cron=0+17+*+*+*"
  • Error isolation (one handler fail ≠ others fail)
  • Execution time limits

Update

• docs/adding-a-module.md — add sections:

  • Optional crons[] field
  • Optional init({ sql }) for D1
  • Migration file placement
  • Link to using-d1.md + using-cron.md

• docs/architecture.md — add:

  • scheduled() flow diagram alongside existing fetch flow
  • D1 store layer in storage section
  • Migration runner role in deploy

• docs/codebase-summary.md — reflect new src/db/cf-sql-store.js, src/modules/cron-dispatcher.js, src/types.js

• docs/code-standards.md — JSDoc expectations (when to add, ESLint rules enforced)

• CLAUDE.md (project) — update module contract code block:

  {
    name: "mymod",
    init: async ({ db, sql, env }) => { ... },
    commands: [ /* ... */ ],
    crons: [{ schedule: "0 1 * * *", name: "daily", handler: async (event, { sql }) => { ... } }],
  }
  

• CLAUDE.md — add D1/cron bullets in "Commands" (npm run db:migrate)

• README.md — light touch: mention D1 + cron in "Why" bullets + update architecture snapshot tree

Plan Output Docs

• Update plans/260415-1010-d1-cron-infra/plan.md — mark all phases Complete

Todo List

• Draft docs/using-d1.md
• Draft docs/using-cron.md
• Update docs/adding-a-module.md
• Update docs/architecture.md
• Update docs/codebase-summary.md
• Update docs/code-standards.md
• Update project CLAUDE.md
• Update README.md
• Mark plan phases complete

Success Criteria

• A dev unfamiliar with Cloudflare Workers can follow using-d1.md + using-cron.md to add a persistent scheduled feature without reading framework internals.
• Internal docs reflect shipped state (no stale references to KV-only).