Audit of the existing project (2026-11-18)
Read on the backend node (M4M64c:~/apps/note-spboucher-ai, commit 2c18f85, never modified from here) and on this Mac.
Backend — note.spboucher.ai
| Subject | Finding |
|---|---|
| Stack | Next.js 16 route handlers, PostgreSQL 17 + pgvector, pg-boss worker, PM2, public route through the MacLustr tunnel (BHS64). |
| Data model | A note is a row of pages (tree by parent_id, section notes/documents/databases/projects/research, type page/database/research, pinned, archived, deleted_at, inbox_at, properties JSONB, version). Tags (tags, page_tags), attachments (attachments, files on disk by SHA-256), tasks, page history (page_versions, 200 per page), links/backlinks, Notion-like databases, research references, AI tables. |
| Note format | ProseMirror JSON (Tiptap 3): paragraph, heading 1–3, bullet/ordered/task lists (nested), blockquote, callout, details (toggle), code block (language), table, image, file block, block/inline math (LaTeX), mention (link to a page), footnote, YouTube embed, horizontal rule, AI block; marks bold, italic, underline, strike, code, highlight, subscript, superscript, link. Stable block ids on 14 node types. Schema recorded in SPNotesCore/docs/reference/web-editor-schema.txt. |
| Saving | PATCH /api/pages/<id> with baseVersion; a stale base is refused with 409 and the server copy; /resolve settles a conflict keeping both copies in the history. Idempotency keys on mutations. |
| Folders | There is no folder entity: the tree of pages and the sections play that role. |
| Favourites | Not in the model (pinned only). |
| Search | Server side, hybrid (tsvector + pgvector + trigram), online only. |
| AI | POST /api/ai/action (20 inline actions + free instruction, SSE, text only — the client applies the result) and POST /api/ai/chat (grounded assistant with sources). Providers OpenAI and Anthropic are routed by the server; keys never leave it. |
| Authentication | Passkeys only (WebAuthn, SimpleWebAuthn 14), relying party note.spboucher.ai, revocable server-side sessions in an HttpOnly cookie, step-up (5 min) for permanent deletion and security changes, same-origin check on mutations. Enrollment windows are opened from the node CLI only. |
| Synchronisation | None for native clients before this project: the web client keeps one draft per open page in IndexedDB. No change feed, no tombstones, server-generated ids. |
| Administration | Settings (AI routing, budget, jobs, audit log, security), import/export (Markdown, HTML, JSON, ZIP), backups. Web only. |
| Production data | 4 pages, 1 attachment, 3 tasks at the time of the audit (structure inspected, no content copied). |
What had to be added to the backend (branch native-sync, written by the macOS session, additive)
Change feed GET /api/sync?since=<rev> (revision sequence maintained by database triggers, tombstones for purges), client-chosen ids
for POST /api/pages and POST /api/attachments (offline creation, stable internal links), /.well-known/apple-app-site-association
(webcredentials for the two apps), a readable session label for the native apps. Contract: SPNotesCore/docs/reference/BACKEND_CONTRACT.md.
Nothing existing was changed or removed.
SP Notes macOS
Did not exist when this work started (nothing on this Mac, no repository on spbgit). It is being built at the same time by another
session (~/Desktop/Cluster/apple/SPNotes). The two sessions agreed on a split: the macOS session owns the backend additions; this
session owns the shared Swift core, ~/Desktop/Cluster/apple/SPNotesCore (SPNotesDocument, SPNotesStore, SPNotesAPI,
SPNotesSync), consumed by both apps. The interfaces (SwiftUI/UIKit here, AppKit there) are distinct.
Decisions that follow from the audit
- The editor is native (UITextView on TextKit 2) and works on the ProseMirror document without loss: node types and attributes this app does not edit (details, YouTube, footnotes, AI blocks, unknown future nodes) are kept untouched and shown as neutral blocks.
- Folders = pages flagged
properties.folder = true(a plain page with sub-pages on the web). Favourite =properties.favorite = true. Reminder = a task{pageId, dueAt}. PencilKit drawing = an image (visible everywhere) + a companion.pkdrawingattachment (editable source). Same conventions in the macOS app. - Search is local (SQLite FTS5) so it works offline; the server search is not required.
- Web-only features not rebuilt natively are listed in
PARITY_MATRIX.md.