SPB Git

Repository Public

AUDIT.md 4.6 KB

# 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 .pkdrawing attachment (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.
Files main
Menu

Theme