numolus/CLAUDE.md

CLAUDE.md

numolus: spreadsheet à la Apple Numbers (free canvas with table/chart/text/button objects) with a hand-written formula engine. Branch with-server = Rails 8 app with the Vue 3 frontend in app/frontend/; accounts, sharing, live collaboration. Details for users and architecture: README.md, chapter "Speichern, Konten & Zusammenarbeit".

Branches

• main (tag client-only): browser-only app, documents in IndexedDB. Keep it free of server code; fixes that apply to both go in their own commit so they can be cherry-picked.
• with-server: everything below.

Commands

bin/setup                  # gems, npm packages, database
bin/dev                    # Rails :3000 + Vite dev server :3036 (open localhost:3000)
npm test                   # Vitest (engine, store, io, collab)
bin/rails test             # Minitest (models, API, auth, sharing, DocumentChannel)
npx vue-tsc --noEmit -p .  # typecheck
npm run lint               # ESLint
npm run build              # typecheck + production build into public/vite
bin/brakeman -q --no-pager

Run all of them before committing. Mails in development: localhost:3000/letter_opener.

Layout

• app/frontend/engine/ formula engine (framework-agnostic, own README)
• app/frontend/store/document.ts the document store (~3300 lines, one open document)
• app/frontend/store/library.ts which document is open, local (IndexedDB) vs server, URLs
• app/frontend/store/session.ts signed-in user; io/api.ts REST client; io/library.ts IndexedDB
• app/frontend/collab/ live collaboration: ydoc.ts (store ↔ Yjs), session.ts (ActionCable, undo, awareness)
• app/channels/document_channel.rb stores/relays Yjs updates, checks access
• app/models/document.rb role_for(user:, token:) is the one access check

Rules that are easy to break

• Cell addressing stays positional: TableObject.cells["col,row"] in store, engine and file format (.num/.json). Stable row/column ids exist only in the Yjs layer (collab/ydoc.ts); don't change the file format for them.
• Every content-changing store function calls markDirty() (selection-only changes call scheduleSave()), and must be listed in READ_ONLY_GUARDED in document.ts, else viewers of a shared document can change it locally.
• Mid-table row/column insert/delete must call collabHooks?.onStructure(...) (as insertRow/deleteRow/insertColumn/deleteColumn do). Edge growth/shrink needs nothing. Without it, concurrent edits land in the wrong row.
• View state is per person: selection, activeSheetId, activeObjectId, sheet zoom are not synced. applyExternalState keeps them when others' changes arrive.
• Remote changes: flush pending local changes into Yjs first, then apply, then rebuild the store (see CollabSession.process). Keep that order.
• Local documents persist via setPersistHandler (IndexedDB); server documents only via the collab session. Undo: snapshots locally, Y.UndoManager for server docs.
• Solid Queue/Cache/Cable live in the same PostgreSQL database as the app data (plain migrations in db/migrate), no separate databases (user decision).
• Settings and secrets come from .env (gem dotenv, template .env.example), never committed.
• Share link tokens are stored in plain text on purpose (owner can copy the link again); magic link tokens/codes only as SHA-256.

Conventions

• UI text and user-facing messages in German; code, comments, commit messages in English. Comments explain why, in the surrounding (fairly thorough) style.
• Commit messages: short imperative subject, body with the reasons.
• The user sometimes commits on their own: check git status/git log fresh before committing; don't push unless asked.

Environment gotchas

• vite-plugin-ruby makes app/frontend the Vite root: Vitest include patterns in vite.config.ts are relative to it (**/*.spec.ts).
• Vite is pinned to v5 (Vitest 2 and @vitejs/plugin-vue 5 don't support newer); vite install/vite upgrade may bump it again.
• Gems install into vendor/gems (global BUNDLE_PATH), ignored by git.
• Node comes from mise; outside the project directory scripts may need MISE_NODE_VERSION=22.21.1.
• Browser checks: there is no Playwright in the repo; drive Chrome (/Applications/Google Chrome.app) with playwright-core from a scratch directory against bin/dev.