Skip to content

README.md

Latest commit

 

History

History
93 lines (83 loc) · 7.96 KB

README.md

File metadata and controls

93 lines (83 loc) · 7.96 KB
Raw

Wonky Work — Specifications

Specifications for Wonky Work (v2: four apps), a collaborative office suite built with Flutter and Serverpod — v2 targets the web only (desktop builds keep compiling, desktop features are deferred, 01 A13): Wonky Drive (the unified drive: all files, uploads, storage), Wonky Write (Markdown-first documents), Wonky Sheets (offline-first spreadsheets) and Wonky Slides (presentations with animations, code blocks and linked charts).

  • Suite-level specs (shared by all apps) live here in /specs.
  • App specs live in /specs/wonky_drive, /specs/wonky_write, /specs/wonky_sheets and /specs/wonky_slides.
  • v2 review: the decisions on the 30 review questions of the Drive/Slides/suite v2 specs are recorded in v2-review.md; v2 is specified and planned as work packages (14, Drive 05, Slides 12), not implemented.
  • Code: wonky_server (Serverpod server, also serves all four web apps), wonky_client (generated), the apps wonky_drive, wonky_write, wonky_sheets and wonky_slides, shared packages in packages/, vendored packages in third_party/ — see 01 §2.
  • v2 changes (milestones M8–M11, 14) are marked "(v2)" in the suite specs: the unified drive and app homes, the 50 MB storage quota, the settings split, Report a bug, Wonky Slides, and the shared packages (wonky_charts*, wonky_code*, wonky_numfmt, wonky_rich_text, wonky_fonts, wonky_spellcheck, wonky_sync_kit*, which M13 replaces with wonky_revlog*).

Reading order

  1. 00 · Product overview — vision, scope, glossary.
  2. 01 · Architecture — decisions, repo layout (current state and the M0 steps to the target), package dependency rules, serving the four web apps, shared sign-in, server/client structure.
  3. 08 · Commands and undo — the backbone: every action is a command; undo for everything; how MCP and AI plug in.
  4. 12 · Offline and sync — Write OT, local storage, offline behavior; then 17 · RevLog sync, the op log Sheets and Slides sync through.
  5. 15 · Writing tests — before writing the first test.
  6. 05 · Drive & files and Drive 03 · Storage quota (v2) — the unified drive, app homes and the rules every byte-adding feature must follow.
  7. Then the app specs, then the remaining suite specs as needed.

App specs

App Folder Start with
Wonky Drive (v2) wonky_drive/ 01 · Overview
Wonky Write wonky_write/ 01 · Overview
Wonky Sheets wonky_sheets/ 01 · Overview, STATUS
Wonky Slides (v2) wonky_slides/ 01 · Overview

Suite specs

# Spec Summary
00 Product overview Vision, principles, personas, scope/non-goals, glossary
01 Architecture One server, four Flutter apps served from it, shared sign-in, pure-Dart cores, shared chart/code packages, package layout & rules
02 Design system shad usage, tokens, light/dark, custom widgets (wonky_ui)
03 App shell & navigation Single-window model (no presenting exception in v2), routes, homes and the left menu, editor header, shared menus, Bugs & improvements entry (was Report a bug), overlays, desktop specifics
04 Auth & accounts Email/password + Google auth, profile, preferences, settings split (Wonky Work vs app settings), access tokens
05 Drive & files Unified drive model (folders, documents, spreadsheets, presentations, files), endpoints, app homes vs Wonky Drive, dialogs, activity
06 Sharing & permissions Roles, ACL, link sharing, enforcement (documents, spreadsheets, presentations, files), share dialog
07 Collaboration Presence, comments, mentions, notifications, version history framework
08 Commands & undo Command model, keymap, command palette, undo architecture
09 MCP Server MCP endpoint, auth, headless tools, UI bridge
10 AI assistant Claude integration (server-side), assistant panel, inline AI
11 Quality Testing, performance budgets, accessibility, i18n, observability
12 Offline & sync Local stores, Write offline, Sheets/Slides on RevLog (summary), upload queue, scale limits
13 Security & operations Threat model, privacy, deployment, scheduled jobs, arbitrary uploads
14 Roadmap Milestones M0–M14 (v2: M8 Drive + suite changes, M9–M11 Slides; M12 Bugs & improvements; M13 RevLog; M14 Publications), how parallel agents execute the work packages, shared workstreams, risks
15 Writing tests How to write tests: layout, naming, helpers, server/widget/golden/property/E2E patterns, determinism, running
16 Bugs & improvements Public board for bug reports and improvement ideas: report dialog with annotated screenshots, votes, comments, AI triage and moderation, admins, tasks with contributor prompts, claims, GitHub PR rules (M12, built)
17 RevLog sync Server-sequenced op log of Sheets and Slides: decisions, data model, change sets and apply rules, protocol, server (sequencer, hooks, pages, headless cache), client (cache, outbox, bootstrap, conflicts), performance gates, as-built notes (M13)
18 Publications & submissions Blogs register a publication; contributors write in Wonky Write and Submit to the blog's review queue (signed webhooks, publication API, moderators with comment access, feedback in the document) (M14, built)
19 Usage analytics First-party analytics for admins in Wonky Drive: daily activity per person and app (ids and counts only), DAU/WAU/MAU, content, collaboration, AI and MCP use, sign-up cohorts, a daily rollup (built)

Conventions used in all specs

  • Command ids: shell.<area>.<action>, drive.<area>.<action>, write.<area>.<action>, sheets.<area>.<action>, slides.<area>.<action> — stable public API (menus, shortcuts, MCP ui.invoke_command).
  • MCP tool names: namespace.verb_noun snake_case (drive.search, write.insert_markdown, sheets.set_values, slides.add_slide, ui.invoke_command).
  • Shortcuts: Mod = ⌘ on macOS, Ctrl elsewhere. Browser-reserved shortcuts are never bound.
  • Priorities: P0 = required for v1, P1 = v1 if possible, P2 = later.
  • Models are shown as Serverpod .spy.yaml sketches. The Sheets and Slides domain tables are server tables (serverOnly: true) whose rows sync through RevLog (17).
  • (v2) marks sections added or changed for the second iteration (Drive, Slides, suite changes). Decided (v2 review, Qn) marks a choice settled in the v2 review. New choices that need the user are marked Open question (for review), always with a recommendation, and added to the review record.
  • Specs describe what and how; when implementation reveals a better approach, update the spec in the same change.