# Takhtabush — Unified Worker Specification **Revision:** 13 · **Date:** 2026-10-30 · **Status:** Phases 1–3 implemented; single tenancy + first-run setup; Phase 4 deferred; Phase 6 mobile host validation in progress **Deployment model:** Single Cloudflare Worker, single tenant by default **Stack:** Preact + Vite, shadcn/ui (Base UI), Tailwind CSS v4, Hono, Cloudflare D1, R2, Email Service, AI Gateway / Workers AI, MCP > **Revision 13** (2026-10-30) finishes the D1 cost follow-ups: a separate `CACHE` Workers KV namespace caches only the derived review streak (10-minute TTL) and global tag summary (5-minute TTL), failing open when absent; a derived `card_tags(card_id, owner_id, deck_id, tag)` table index-makes tag filters and is maintained on every card write; owner-wide front search uses a trigram FTS5 index with a `LIKE` fallback for short or already-bounded queries; and the two per-request auth reads collapse into one `sessions JOIN users` query. **Revision 12** (2026-10-30) adds collections and bounded deck sizes: `folders` becomes a flat `collections` table with `decks.collection_id` (`ON DELETE SET NULL`), and `@caly/shared` exports hard limits (500 cards per deck, 500 import rows, 100 cards per bulk create, 200 decks per collection, 100 collections per user) enforced by every API/MCP write path. The same change removes the remaining query-per-row loops (study-session snapshot, import, bulk create, cleanup), replaces the per-write deck recount with an atomic counter, adds `learning_state.deck_id`, and records the cost model in `docs/developer/d1-cost-model.md`. **Revision 9** (2026-10-21) adds OAuth 2.1 for ChatGPT on `/mcp`: `@cloudflare/workers-oauth-provider` protects OAuth bearers while API keys and sessions bypass it, with CIMD/DCR, PKCE, refresh tokens, and a consent page that reuses the existing magic-link session. `/mcp/oauth` is a path-descendant alias. **Revision 8** (2026-10-20) enforces single tenancy and adds first-run setup. The first user is the owner; later addresses need to be listed in `ALLOWED_EMAILS`, and `OWNER_EMAIL` pins the owner from the start. `SETUP_TOKEN` enables `GET /api/v1/auth/status` plus `POST /api/v1/auth/setup`, which creates the owner before email is configured and recovers owner access later. A partial unique index allows at most one owner row. The production/Appflare config is the root `wrangler.jsonc`; local development uses `wrangler.dev.jsonc`. **Revision 7** (2026-10-14) lets card **definitions** be authored and rendered as Markdown. The `back` field of a `term_definition` (and the answer of `typed`/`image_prompt`) is stored as raw Markdown — the only stored form — and is edited with a tiny inline WYSIWYG editor that parses the source into an ephemeral IR (never persisted) and serializes edits back to raw Markdown. Every read surface renders that Markdown: the study card (webapp and MCP Apps widget via the shared `StudyCardShell`), the deck card table, and the card-details dialog. Typed grading and compact previews flatten Markdown to plain text. **Revision 6** (2026-10-14) adds an optional MCP Apps-compatible study-session UI for chat hosts such as ChatGPT. It uses a decoupled data-tool/render-tool flow: `start_study_session` creates and returns session data, while `render_study_session` returns an MCP Apps UI resource. The widget renders a server-authoritative session snapshot and records reviews through `record_review`. **Revision 5** (2026-10-14) makes card deletion consistent: `DELETE /cards/:id` is a soft delete with in-place confirmation and undo (`POST /cards/:id/restore`), every statistic excludes deleted cards, and the cleanup job hard-deletes cards (with their events, revisions, and state) 30 days after deletion. It also polishes study interaction: multiple-choice options render as a large tappable grid with numbered key hints, prompt and answer share equal emphasis, and the typed input is focused for each new card. The import parser gained a configurable column delimiter and tags separator plus a live preview table. **Revision 4** adds optional API key expiration, SQL keyset pagination for `search_cards`, removal of the dead `learning_state.suspended` column, an explicit pause-vs-abandon choice on session exit, import file uploads with shared client-side validation plus an export menu, and cursor pagination for the deck and card lists. **Revision 3** added the scheduled cleanup job, suspend/resume, performance-based grading (all four responses), selectable goals, and the full session lifecycle. **Revision 2** folded in Cloudflare Email Service magic links, D1-backed auth rate limiting, opaque **API-key** auth for MCP (instead of OAuth), session management, per-mode study screens with **two matching variants**, R2 media upload, and shared grading helpers. New items are tagged **[R2]** / **[R3]** / **[R4]** / **[R5]** / **[R6]** / **[R7]**; see §20 for the changelog. ## 1. Product summary Takhtabush is a self-hosted, lightweight Quizlet-like learning app deployed as one Cloudflare Worker. A user creates, imports, organizes, studies, and analyzes flashcard decks. Content creation is separate from learning intelligence: - Users author flashcards manually or import them. - Clef, through AI Gateway, selects, sequences, prioritizes, and adapts existing cards into dynamic learning journeys. - Clef does not generate flashcard content. - A future optional AI authoring feature may use text models through AI Gateway; generated cards remain drafts until approved. - An MCP layer lets coding agents read learning data, create/import decks, and start sessions. - **[R6] An optional MCP Apps UI lets a compatible LLM chat request and render an actual flashcard study session inline, using the same server-authoritative session and review-event model as the Preact web app.** ### V1 principles - Single tenant by default; one deployment belongs to one user or small trusted group. - One Worker serves the SPA, API, media endpoints, and MCP endpoint. - D1 is the system of record. R2 stores binary media only. - Review events are append-only; learning state is derived and rebuildable. - AI features are optional, bounded, cached, and degrade gracefully. - The scheduler is deterministic, versioned, and independently testable. - No realtime collaboration, multi-tenancy, billing, or marketplace in V1. ## 2. Architecture ### 2.1 Runtime topology ```text Browser / MCP client / ChatGPT MCP App | v Cloudflare Worker ├── Static assets: Preact SPA ├── /api/v1/*: Hono REST API ├── /mcp: MCP Streamable HTTP endpoint (API keys or OAuth) ├── /mcp/oauth: OAuth alias under the canonical /mcp resource ├── /oauth/*: authorization, consent, token, and registration endpoints ├── /.well-known/*: OAuth protected-resource/authorization-server metadata ├── /mcp-apps/study-session/v1.html: MCP Apps UI resource ├── /media/*: authenticated R2 read proxy └── Bindings: D1, R2, KV (OAUTH_KV), EMAIL, AI, ASSETS ``` A single Worker is intentional: it reduces deployment complexity, avoids cross-Worker routing, and keeps local development simple. ### 2.2 Repository layout ```text takhtabush/ ├── package.json / pnpm-workspace.yaml / turbo.json ├── wrangler.jsonc # unified Worker config (root) ├── vitest.config.ts / eslint.config.js / tsconfig.base.json / knip.jsonc ├── .env.example / .dev.vars.example ├── migrations/ │ ├── 0001_init.sql # core tables │ ├── 0002_indexes.sql │ ├── 0003_rate_limits.sql # [R2] │ ├── 0004_api_keys.sql # [R2] │ ├── 0005_drop_learning_state_suspended.sql # [R4] │ ├── 0006_api_keys_expires_at.sql # [R4] │ ├── 0007_single_owner.sql # [R8] │ └── 0008_collections_and_limits.sql # [R12] ├── packages/ │ ├── webapp/ api/ mcp/ study-widget/ ui/ shared/ worker-kit/ ├── docs/ plans/ └── AGENTS.md / CONTEXT.md / README.md / SPEC.md ``` ### 2.3 Package responsibilities | Package | Responsibility | | -------------------- | ------------------------------------------------------------------------------------------- | | `@caly/webapp` | Preact SPA, routes, feature components, API client | | `@caly/api` | Hono routes, services, repositories, D1/R2/EMAIL/AI integrations; unified Worker entrypoint | | `@caly/mcp` | MCP tools, API-key scopes, compact projections, audit events, MCP Apps UI tool | | `@caly/ui` | Generated shadcn/Base UI primitives, shared study components, and shared UI utilities | | `@caly/shared` | Zod schemas, domain types, API contracts, scheduler + grading logic | | `@caly/worker-kit` | CORS, error envelope, request context, id helpers | | `@caly/study-widget` | **[R6]** Small standalone Preact bundle for the MCP Apps study-session widget | Dependency rules: - `webapp` may import `ui`, `shared`, and `worker-kit`. - `study-widget` may import `ui`, `shared`, and `worker-kit`; it must not import `webapp`. - `api` may import `shared`, `worker-kit`, and `mcp` (to mount `/mcp`). - `mcp` may import `shared` and call injected domain services (`McpServices`); it must not import `api` or touch D1/R2. - `ui` and `shared` must not import application packages. - Neither `api` nor `mcp` may import `webapp`. ## 3. Authentication and tenancy ### 3.1 Tenancy model - One deployment has one primary owner; all data stays within the deployment. - `owner_id` is retained on user-owned resources for a future multi-tenant migration. - No organization, workspace, billing, or per-customer isolation in V1. ### 3.2 Auth approach Session-based authentication with secure HTTP-only cookies. V1 supports: - Email magic-link login. - Optional single-user bootstrap mode using an owner invite token. - Logout and session revocation (list/revoke all sessions). - CSRF protection (double-submit cookie) for cookie-authenticated browser mutations. - **[R2] Login delivered through the Cloudflare Email Service `EMAIL` binding** (`send_email`). `wrangler dev` simulates delivery; deployed Workers send from `EMAIL_FROM` (an onboarded domain). - **[R2] Environment-gated dev tokens**: when `ENVIRONMENT !== "production"` the API also returns the raw magic-link token so sign-in works without a mailbox; in production the raw token is never returned and a successful send is required (`502` otherwise). - **[R2] Optional `OWNER_INVITE_TOKEN`** gate: when set, every magic-link request must carry a matching `invite` value. - **[R8] Single tenancy**: the first user becomes `is_owner`; later addresses must be listed in `ALLOWED_EMAILS`. `OWNER_EMAIL` pins the owner from the start. A partial unique index (`0007_single_owner.sql`) allows at most one owner row. - **[R8] First-run setup and recovery**: `SETUP_TOKEN` enables `GET /api/v1/auth/status` and `POST /api/v1/auth/setup`. Setup creates the owner while no users exist and signs the existing owner back in later, so a catalog install works before its email sender domain is configured. The token is rate limited and optional. - **[R2] Auth rate limiting** (D1 fixed window): magic-link per IP (10 / 10 min) and per email (5 / 15 min); verify per IP (20 / 10 min). Exceeded requests return `429` with `Retry-After`. Deferred: password auth, passkeys/WebAuthn, OAuth social login, organizations/RBAC. ### 3.3 Sessions ```text sessions id TEXT PRIMARY KEY user_id TEXT NOT NULL token_hash TEXT NOT NULL UNIQUE user_agent TEXT ip_hash TEXT created_at TEXT NOT NULL expires_at TEXT NOT NULL revoked_at TEXT ``` Rules: - Store only a hashed session token; never store the raw token. - Cookies are `HttpOnly`, `SameSite=Lax`, and `Secure` when the app origin is HTTPS. - Rotate the session id on login; expire inactive sessions after 30 days. - Invalidate sessions on owner revocation or bulk sign-out. - **[R2] Management**: `GET /api/v1/sessions` lists active sessions (with a `current` marker); `DELETE /api/v1/sessions/:id` revokes one (clearing cookies when it is current); `DELETE /api/v1/sessions` revokes all others. ### 3.4 API authentication | Client | Mechanism | | ---------------- | --------------------------------------------------------------------------------------- | | Browser SPA | HTTP-only session cookie + `x-csrf-token` header | | MCP client | **[R2]** API key (`Authorization: Bearer ` or `x-api-key: `) on `/mcp` | | ChatGPT | **[R9]** OAuth 2.1 on `/mcp` (CIMD/DCR, PKCE, refresh tokens); `/mcp/oauth` is an alias | | MCP Apps widget | **[R6]** Same MCP API key/OAuth authorization; calls MCP tools through the host bridge | | Local automation | API key (same as MCP) | All API routes except `/api/v1/health` and the auth endpoints require authentication, and unknown `/api` paths never fall through to the SPA. **[R2] API keys** (`api_keys` table): created from the `/mcp` screen (`POST /api/v1/api-keys`), shown once, stored only as a hash, prefixed `fck_`, and scoped to a subset of the MCP scopes. API keys authenticate **only** the `/mcp` endpoint; the browser session (cookie) manages keys. Optional `x-mcp-scopes` narrows a key's scopes per request. **[R4]** Keys may optionally expire (`expiresInDays`; `expires_at` NULL means never) and can be revoked; expired and revoked keys are rejected. Key rotation and per-key rate limits are intentionally not implemented. **[R9] ChatGPT OAuth.** ChatGPT's web connector cannot send a static API-key header, so `/mcp` is both the API-key endpoint and the canonical OAuth resource, protected by `@cloudflare/workers-oauth-provider`. API keys and session cookies bypass the provider into the existing Hono route; OAuth bearers are validated by the provider. `/mcp/oauth` is a path descendant and works as an alias. The provider publishes RFC 9728/RFC 8414 metadata at both the flat and path-specific well-known URLs, supports CIMD (preferred) and DCR, issues its own access/refresh tokens, and stores grants in `OAUTH_KV`. `/oauth/authorize` reuses the normal magic-link session and shows a consent page. ## 4. Data model ### 4.1 D1 schema Core tables live in `migrations/0001_init.sql`: `users`, `decks`, `cards`, `card_revisions`, `folders`, `media_objects`, `study_sessions`, `review_events`, `learning_state`, `ai_evaluations`, `mcp_audit_events`, plus the auth tables `sessions` and `magic_link_tokens`. **[R12]** `folders` was renamed to `collections` and flattened (see §4.4). **[R2] Added tables** (`0003_rate_limits.sql`, `0004_api_keys.sql`): ```sql CREATE TABLE rate_limits ( bucket TEXT NOT NULL, window_start INTEGER NOT NULL, count INTEGER NOT NULL DEFAULT 0, PRIMARY KEY (bucket, window_start) ); CREATE TABLE api_keys ( id TEXT PRIMARY KEY, user_id TEXT NOT NULL REFERENCES users(id), name TEXT NOT NULL, key_prefix TEXT NOT NULL, key_hash TEXT NOT NULL UNIQUE, scopes_json TEXT NOT NULL DEFAULT '[]', created_at TEXT NOT NULL, last_used_at TEXT, revoked_at TEXT ); ``` **[R2] Change:** `ai_evaluations` gains a `status` column (`succeeded` | `failed` | `skipped`) so failures are recorded, not just successful results. All timestamps are ISO-8601 TEXT; identifiers are prefixed (`deck_…`, `card_…`, `usr_…`). **[R6] No new core tables are required.** The MCP Apps widget operates on the existing `study_sessions`, `cards`, and append-only `review_events` data. It must not introduce a separate widget-side source of truth. **[R12] Collections and bounded decks** (`0008_collections_and_limits.sql`): ```sql collections id TEXT PRIMARY KEY -- col_… owner_id TEXT NOT NULL REFERENCES users(id) name TEXT NOT NULL position INTEGER NOT NULL DEFAULT 0 created_at TEXT NOT NULL updated_at TEXT NOT NULL deleted_at TEXT decks.collection_id TEXT REFERENCES collections(id) ON DELETE SET NULL ``` Collections are flat (no `parent_id`). Deleting one never deletes a deck: the API also detaches decks on soft delete. `decks.card_count` is the authoritative denormalized counter, reserved with one conditional `UPDATE` per write instead of being recounted. `learning_state.deck_id` stores a derived copy of the card's deck so due counts, the due queue, and the forecast use one index range per deck. `0010_collection_positions.sql` renumbers pre-existing collections (0008 added `position` with a default of 0) so the deck library's up/down controls swap distinct values. **[R13] Derived search indexes** (`0009_card_tags_and_fts.sql`): ```sql CREATE TABLE card_tags ( card_id TEXT NOT NULL REFERENCES cards(id) ON DELETE CASCADE, owner_id TEXT NOT NULL REFERENCES users(id), deck_id TEXT NOT NULL REFERENCES decks(id) ON DELETE CASCADE, tag TEXT NOT NULL COLLATE NOCASE, PRIMARY KEY (card_id, tag) ); CREATE VIRTUAL TABLE cards_fts USING fts5( front, back, content='cards', content_rowid='rowid', tokenize='trigram' ); -- INSERT/DELETE/UPDATE triggers keep cards_fts in sync with cards. ``` `cards.tags_json` remains the display source; `card_tags` is a derived, rebuildable projection maintained in the same `db.batch()` as the card write. Soft-deleted cards lose their tag rows immediately, and hard cleanup deletes them before the card row. `cards_fts` is an external-content table, so a future migration that rebuilds `cards` must re-run `INSERT INTO cards_fts(cards_fts) VALUES ('rebuild')`. ### 4.2 Indexes `0002_indexes.sql` (core): ```sql CREATE INDEX idx_decks_owner ON decks(owner_id, deleted_at, updated_at DESC); CREATE INDEX idx_cards_deck ON cards(deck_id, deleted_at, updated_at DESC); CREATE INDEX idx_cards_owner ON cards(owner_id, deleted_at); CREATE INDEX idx_reviews_user_card ON review_events(user_id, card_id, reviewed_at DESC); CREATE INDEX idx_reviews_session ON review_events(session_id, reviewed_at); CREATE INDEX idx_learning_due ON learning_state(user_id, due_at, suspended); CREATE INDEX idx_media_owner ON media_objects(owner_id, status, created_at DESC); CREATE INDEX idx_ai_subject ON ai_evaluations(subject_type, subject_id, created_at DESC); ``` **[R2] Additional** indexes: `sessions(user_id, expires_at)`, `magic_link_tokens(email, expires_at)`, `decks(owner_id, folder_id, deleted_at)`, `study_sessions(user_id, deck_id, status)`, `mcp_audit_events(user_id, created_at DESC)`, `rate_limits(window_start)`, `api_keys(user_id, revoked_at)`, `api_keys(key_hash)`. **[R12] Cost indexes** (`0008`): keyset indexes `decks(owner_id, deleted_at, updated_at DESC, id DESC)` and `cards(deck_id, deleted_at, updated_at DESC, id DESC)` replace the narrower 0002 versions; `collections(owner_id, deleted_at, position, name)`; `decks(owner_id, collection_id, deleted_at, updated_at DESC, id DESC)`; `study_sessions(user_id, started_at DESC)` and `(user_id, status, started_at DESC)`; `review_events(user_id, reviewed_at DESC)`, `(card_id)`, and `(session_id, card_id)`; `card_revisions(card_id)`; `learning_state(card_id)` and `(user_id, deck_id, due_at)`; partial indexes on `cards(image_media_id)` and `cards(audio_media_id)`. Rationale per index: `docs/developer/d1-cost-model.md`. **[R13] Search indexes** (`0009`): `card_tags` primary key `(card_id, tag)`; `idx_card_tags_owner_tag(owner_id, tag, card_id)`; and `idx_card_tags_owner_deck_tag(owner_id, deck_id, tag, card_id)`. The `cards_fts` trigram table indexes `cards(front, back)` through three triggers. Tag filters and owner-wide text search drive from these indexes instead of scanning the owner's cards. ### 4.4 Bounded-work limits **[R12]** Limits live in one place, `packages/shared/src/domain/limits.ts`, and `@caly/shared` re-exports them as `LIMITS` plus named constants. API Zod schemas, MCP tool schemas, the web app, and the service guards all read the same values. | Limit | Value | Enforced by | Error code | | ----------------------- | ----: | ---------------------------------------------------------------------------- | -------------------------------------- | | Cards per deck | 500 | Conditional `card_count` reservation on create, bulk create, import, restore | `DECK_CARD_LIMIT_EXCEEDED` (409) | | Cards per bulk create | 100 | `mcpCreateCardsInputSchema` + service guard | `BULK_CARD_LIMIT_EXCEEDED` (409) | | Import rows per request | 500 | Parser slice + whole-request capacity check | `DECK_CARD_LIMIT_EXCEEDED` (409) | | Import bytes | 1 MB | `importDeckInputSchema` | `VALIDATION_ERROR` (422) | | Tags per card | 20 | `createCardInputSchema`, `updateCardInputSchema`, import | `VALIDATION_ERROR` (422) | | Tag length | 40 | `tagSchema` | `VALIDATION_ERROR` (422) | | Decks per collection | 200 | Collection capacity check on create/move | `COLLECTION_DECK_LIMIT_EXCEEDED` (409) | | Collections per user | 100 | `createCollection` | `COLLECTION_LIMIT_EXCEEDED` (409) | | Collection name | 80 | `createCollectionInputSchema` | `VALIDATION_ERROR` (422) | The deck cap is a **write** limit, not a read filter: decks that predate the cap stay readable and studyable, but cannot accept new or restored cards until they shrink. Server checks are authoritative; the UI and MCP descriptions only explain the limit early. **[R13]** Tag filtering is an equality lookup on `card_tags`, so the 40-character tag limit is a UI/storage bound rather than a `LIKE`-pattern bound. Global tag suggestions are cached in `CACHE` for five minutes; deck-scoped suggestions stay bounded by the 500-card cap and are not cached. ### 4.3 Card types | Type | Required fields | Behavior | | ----------------- | ----------------------------------------- | ----------------------------------- | | `term_definition` | `front`, `back` | Reversible flashcard | | `cloze` | `cloze_text` (tokens in `{{…}}`) | Hidden token(s) in a sentence | | `multiple_choice` | `front`, `choices_json`, `correct_choice` | One correct option | | `typed` | `front`, `back` | Free-text answer with normalization | | `image_prompt` | `image_media_id`, `back` | Image prompt with a text answer | **[R2] Authoring**: all five types are creatable/editable in the webapp (`CardForm`); `image_prompt` requires an uploaded image. Any card may also carry optional image/audio media. Tags are a JSON array; authored as a comma-separated field with display chips and filtering. ## 5. Storage and media ### 5.1 R2 layout ```text media/{userId}/{mediaId}/{filename} ``` ### 5.2 Upload flow **[R2]** (implemented end-to-end): 1. `POST /api/v1/media/intent` validates MIME type and intended size; a `media_objects` row is created (`pending`). 2. The response returns a **same-origin** `uploadUrl` (`/api/v1/media/{id}/content`, `PUT`) and the media object. 3. `PUT /api/v1/media/{id}/content` stores the object in R2 and marks the row `ready`. 4. `POST /api/v1/media/{id}/complete` verifies the object exists and finalizes size/checksum (idempotent). 5. Cards reference `media_objects.id`, never raw R2 keys. `GET /media/intent` is accepted as an alias for clients that follow the original spec verbatim. ### 5.3 Limits | Asset | Maximum size | Allowed types | | ----- | ------------ | -------------------- | | Image | 5 MB | PNG, JPEG, WebP, GIF | | Audio | 10 MB | WebM, MP3, M4A, WAV | ### 5.4 Access - Media is private by default. - `GET /media/:mediaId` (Worker route) checks ownership and streams the R2 object; the SPA uses it directly for ``/`