tefter/SPEC.md

Tefter — Self-Hosted Notational Velocity Clone

Spec version: 1.0 · Audience: Claude Code (implementation agent)

1. Overview

Tefter is a personal, self-hosted note-taking system that replicates the Notational Velocity (NV) interaction model — a single search/create field, instant incremental filtering, and modeless keyboard-driven editing — with Markdown support and offline-first sync across Linux, macOS, Windows, Android, and web.

It replaces Simplenote + Notational Velocity for a single user who hosts their own data.

Goals

• Pixel-faithful NV interaction model (not pixel-faithful visuals): one omnibar that searches AND creates, zero modal dialogs, zero save buttons, everything reachable by keyboard.
• Markdown editing with optional preview.
• Offline-first on every client; sync when connectivity returns.
• Single-user, single-server, trivial deployment: one Go binary + one SQLite file.
• Import of an existing Simplenote export archive.

Non-Goals

• Multi-user accounts, sharing, collaboration, realtime co-editing.
• End-to-end encryption (TLS in transit + disk encryption at rest is the model).
• Rich text, attachments, images (v1 is plain Markdown text; attachments may come in v2).
• Native Android app (PWA is the Android client).

2. Architecture

┌─────────────────────────────── your data center ───────────────┐
│  tefterd  (single Go binary)                                     │
│  ├─ REST sync API        /api/v1/...                           │
│  ├─ static web app (PWA) embedded via go:embed  →  /           │
│  └─ SQLite database      (modernc.org/sqlite, CGO-free)        │
└─────────────────────────────────────────────────────────────────┘
            ▲ HTTPS (reverse proxy: Caddy/nginx, user-provided)
            │
   ┌────────┼─────────────┬───────────────────┐
   │        │             │                   │
 Web      Android       Desktop (Win/mac/Linux)
 browser  (installed    tefter-desktop: Wails v2 binary
 (PWA)     PWA)         wrapping the SAME frontend bundle

Key decision — one frontend, three shells. The web app is the product. It runs:

1. In a browser (PWA, served by tefterd).
2. Installed on Android (PWA install prompt).
3. Inside a Wails v2 webview window on desktop (frontend bundle embedded in the desktop binary; works fully offline, no tefterd needed to launch).

Offline storage and the sync engine live in the frontend (TypeScript + IndexedDB), so the exact same offline/sync code runs on all five platforms. The Wails Go layer is a thin shell: window, tray, global shortcut, single-instance lock.

Components / repo layout

tefter/
├─ server/                 # tefterd
│  ├─ main.go
│  ├─ api/                 # HTTP handlers
│  ├─ store/               # SQLite access layer
│  ├─ importer/            # Simplenote import
│  └─ webdist/             # go:embed of ../frontend/dist
├─ frontend/               # TypeScript + Svelte, Vite build
│  ├─ src/
│  │  ├─ ui/               # omnibar, list, editor, preview
│  │  ├─ db/               # IndexedDB local store
│  │  └─ sync/             # sync engine
│  └─ dist/                # built bundle (embedded by server & desktop)
├─ desktop/                # Wails v2 app
│  ├─ main.go
│  └─ wails.json
├─ Makefile
└─ .github/workflows/release.yml

Tech choices (fixed — do not substitute)

• Server: Go ≥1.22, stdlib net/http (Go 1.22 routing), modernc.org/sqlite (pure Go, no CGO → painless cross-compilation and static binaries).
• Frontend: Svelte 4 + TypeScript + Vite. Keep dependencies minimal. Markdown rendering: marked + DOMPurify. Editor: CodeMirror 6 (markdown language package, minimal setup).
• Desktop: Wails v2.
• No ORM, no heavy frameworks, no CSS framework — hand-written CSS, this UI is small.

3. Data Model

Server SQLite schema

CREATE TABLE notes (
    id          TEXT PRIMARY KEY,          -- UUIDv4, client-generated
    content     TEXT NOT NULL DEFAULT '',  -- full markdown; title = first line
    tags        TEXT NOT NULL DEFAULT '[]',-- JSON array of strings
    created_at  INTEGER NOT NULL,          -- unix ms, client clock at creation
    modified_at INTEGER NOT NULL,          -- unix ms, client clock at last edit
    deleted     INTEGER NOT NULL DEFAULT 0,-- tombstone
    version     INTEGER NOT NULL           -- server-assigned, globally monotonic
);
CREATE INDEX idx_notes_version ON notes(version);

CREATE TABLE meta (k TEXT PRIMARY KEY, v TEXT);  -- schema_version, next_version counter

• Title is derived, never stored: first non-empty line of content, markdown heading markers stripped for display.
• version is a single global monotonically increasing counter (like a Lamport clock per server). Every accepted write bumps the global counter and stamps the note. This makes "give me everything changed since cursor X" trivial.
• Tombstones are kept forever (personal scale; millions of notes are not expected). A tefterd compact subcommand may purge tombstones older than N days.

Client store (IndexedDB)

Object store notes: same fields as server, plus:

• dirty: boolean — locally modified, not yet pushed.
• baseVersion: number — server version this local copy was derived from (0 for never-synced).

Object store meta: cursor (last server version pulled), serverUrl, token.

4. Sync Protocol

Design: pull-then-push, last-write-wins with conflict copies (Simplenote-style). Single user across a handful of devices; CRDTs are overkill. Sync must be safe to interrupt at any point.

Endpoints (all under /api/v1, JSON, Authorization: Bearer <token>)

Method	Path	Purpose
GET	/changes?since=<cursor>&limit=500	Pull notes with version > cursor, ordered by version. Returns {notes: [...], cursor: <max version returned>, more: bool}
POST	/notes/batch	Push local changes. Body: {notes: [{id, content, tags, created_at, modified_at, deleted, baseVersion}]}
GET	/health	Liveness + schema version
POST	/import/simplenote	Multipart upload of Simplenote export zip (also available as CLI)

Push conflict rule (server-side, per note)

1. If note id unknown → insert, assign new version. Accepted.
2. If baseVersion == current version → clean fast-forward. Update, assign new version. Accepted.
3. Else conflict: another device changed the note since this client last pulled.
   • Keep the server's current content in the original note.
   • Apply the incoming content as a new note with a new UUID, content prefixed by nothing (content unchanged), and tag conflict added; its first line gets (conflicted copy YYYY-MM-DD HH:MM) appended.
   • Response marks the note {id, status: "conflict", conflictCopyId: ...}.
4. Deletion conflicts: delete vs edit → edit wins (tombstone is overwritten by the edit as a conflict copy is NOT created; the edited version simply survives).

Client sync loop

1. On startup, on network regain, after 3 s of edit inactivity, and every 60 s: run sync if online.
2. Pull: page through /changes from local cursor. For each incoming note: if local copy is not dirty → overwrite; if dirty and incoming version > baseVersion → keep local dirty copy, remember conflict will be resolved by server at push. Update cursor.
3. Push: send all dirty notes in one batch. On accepted, clear dirty, set baseVersion to returned version. On conflict, replace local with server truth and add the returned conflict copy on next pull.
4. All steps idempotent; a crash mid-sync must never lose an edit (edits are persisted to IndexedDB on every debounced change, before any network activity).

Auth

• Single bearer token, generated at first server start (tefterd init prints it), stored hashed (SHA-256) in meta. Rotate with tefterd token rotate.
• No accounts, no sessions, no OAuth. TLS is delegated to the user's reverse proxy; tefterd listens on localhost/HTTP by default (--listen :8420).

5. UI Specification — the Notational Velocity Model

This section is the heart of the product. The NV model must be reproduced exactly.

Layout

┌──────────────────────────────────────────────┐
│  [ omnibar: Search or Create              ]  │  ← always the same field
├──────────────────────────────────────────────┤
│  Note title            ·  modified  · tags   │  ← results list
│  Note title            ·  modified  · tags   │     (selected row highlighted)
│  ...                                         │
├──────────────────────────────────────────────┤
│                                              │
│  editor (CodeMirror, markdown)               │  ← or rendered preview
│                                              │
└──────────────────────────────────────────────┘

• Default: horizontal split (list above editor). Setting for vertical split (list left, editor right). On narrow screens (<640 px, i.e., Android), list and editor become two stacked views with back navigation.
• No toolbar. No save button. No menus except a small ⋯ for settings/sync status.
• A tiny status dot next to the omnibar: green = synced, yellow = syncing, gray = offline with pending changes. Clicking shows last sync time and pending count.

Omnibar behavior (exact)

1. Focus is in the omnibar when the app opens.
2. Typing filters the list on every keystroke (target: <10 ms for 10k notes — filter in memory; all note metadata + content is loaded into RAM from IndexedDB at startup).
3. Ranking: exact title match > title prefix > title contains > body contains. Secondary sort: modified_at desc. Empty query shows all notes by modified_at desc.
4. Matching is case-insensitive, diacritic-insensitive (č/c, š/s, ž/z fold together), across space-separated terms (AND semantics).
5. Enter in the omnibar:
   • If a list row is highlighted → open that note in the editor (focus editor, caret at end).
   • If the query matches nothing → create a note whose first line is the query text, open it in the editor.
6. ↓/↑ from the omnibar moves the list selection without leaving the field; the editor live-previews the selected note (NV behavior).
7. Esc: clear omnibar, deselect, focus omnibar. Pressing Esc in the editor returns focus to the omnibar (query preserved).
8. Search term highlighting in list rows and in the editor.

Keyboard shortcuts (Cmd on macOS, Ctrl elsewhere)

Shortcut	Action
Cmd/Ctrl+L	Focus omnibar (select existing text)
Enter (omnibar)	Open selection / create note
↑ ↓ (omnibar)	Move list selection
Esc	Editor→omnibar; omnibar→clear
Cmd/Ctrl+Delete	Delete selected note (moves to tombstone; brief undo toast, no confirm dialog)
Cmd/Ctrl+Shift+P	Toggle markdown preview for current note
Cmd/Ctrl+K	Cycle tag filter (simple tag dropdown)
Cmd/Ctrl+J / Cmd/Ctrl+Shift+J	Next / previous note in list while in editor

Editor

• CodeMirror 6, markdown mode, light syntax styling only (bold headings, dim syntax marks). Monospace or user-set font. No WYSIWYG.
• Autosave: debounce 400 ms after last keystroke → write to IndexedDB, mark dirty. Never a save action.
• Preview: Cmd/Ctrl+Shift+P swaps the editor pane for rendered markdown (marked + DOMPurify, GFM: tables, task lists, fenced code, strikethrough). Same shortcut toggles back. Links open in system browser/new tab. Internal [[Note Title]] wiki-links open/create that note (NV Alt behavior — nice-to-have, milestone 4).

Visual style

• Minimal, native-feeling: system font stack for UI chrome, generous line height in the list, thin 1 px separators. Light and dark theme following OS preference. No animation except the undo toast.

6. Simplenote Import

Input: the official Simplenote export zip (contains source/notes.json with activeNotes and trashedNotes, each having id, content, creationDate, lastModified, tags, markdown fields — verify actual field names against a real export at implementation time and adapt).

• CLI: tefterd import simplenote /path/to/export.zip (server-side, direct to SQLite).
• Web: Settings → Import → upload zip (uses POST /api/v1/import/simplenote).
• Mapping: content → content; creationDate/lastModified (ISO 8601) → unix ms; tags → tags; trashedNotes → imported with deleted=1 tombstones (recoverable via a future trash view; v1 just keeps them synced-invisible).
• Idempotent: re-importing the same zip must not duplicate notes (dedupe by Simplenote id stored in a source_id column, or by exact content+creation date hash).
• Print a summary: imported N, skipped M duplicates, T trashed.

7. Desktop Shell (Wails v2)

• One window containing the frontend bundle (same frontend/dist embedded via Wails assets).
• Single-instance lock; second launch focuses the existing window.
• Global OS shortcut (default Cmd/Ctrl+Shift+Space, configurable) shows/hides the window and focuses the omnibar — the classic NV "always at hand" flow.
• Closing the window hides to tray (tray icon: open, sync now, quit). Setting to quit-on-close instead.
• First-run screen: server URL + token fields, "work locally only" option (sync can be configured later).
• Storage is the webview's IndexedDB — the desktop app is fully functional offline and without any server.

8. PWA Requirements (web + Android)

• manifest.json (standalone display, icons 192/512, theme color) + service worker: precache the app shell (cache-first, versioned by build hash); API calls network-only (sync engine handles offline).
• Must pass Lighthouse "installable" check.
• IndexedDB persistence: request navigator.storage.persist() on first run.
• Android keyboard ergonomics: omnibar enterkeyhint="go", no zoom-on-focus (font-size ≥16 px).

9. Build, Release, Deployment

• make server → tefterd binaries for linux/amd64, linux/arm64, darwin/arm64, windows/amd64 (pure Go, CGO_ENABLED=0).
• make desktop → Wails builds per platform (requires per-OS runners; GitHub Actions matrix in release.yml producing: tefter-desktop.exe, Tefter.app zip, linux binary + .desktop file).
• make frontend → Vite build into frontend/dist, embedded by both server and desktop builds.
• Versioning: single version stamp injected via -ldflags into both binaries and the frontend; /health and the About screen show it.
• Server deployment docs (README): systemd unit example, Caddy reverse-proxy example (2 lines), backup = copy one SQLite file (use tefterd backup /path which runs VACUUM INTO for a consistent snapshot).

10. Milestones

1. M1 — Core local app: frontend with omnibar/list/editor per §5, IndexedDB persistence, markdown preview. Runs from vite dev. Acceptance: full NV keyboard flow works offline in a browser.
2. M2 — Server + sync: tefterd with schema, API, token auth; sync engine per §4. Acceptance: two browser profiles converge; conflict copy created on concurrent edit; kill -9 during sync loses nothing.
3. M3 — Import + PWA: Simplenote import (CLI + web), service worker, installable on Android. Acceptance: real export imports idempotently; airplane-mode edit on Android syncs on reconnect.
4. M4 — Desktop: Wails shell with tray, global shortcut, single instance; release pipeline. Acceptance: fresh Windows/macOS/Linux machine runs the single artifact with zero prerequisites.
5. M5 — Polish: diacritic folding, dark mode, tag filter, [[wiki-links]], tefterd compact, undo toast.

11. Acceptance Criteria (global)

• Search latency <10 ms at 10,000 notes on a mid-range laptop.
• Cold start to focused omnibar <1 s (desktop), <2 s (PWA warm cache).
• Zero data loss under: offline edits, mid-sync crash, concurrent edits on two devices (conflict copy, never silent overwrite).
• tefterd runs as one static binary + one .db file; no Docker, no external DB, no config file required (flags/env only).
• Entire frontend bundle <500 KB gzipped.

12. Explicitly Out of Scope for the Agent

Do not add: user registration, e-mail, websockets/realtime, plugins, themes beyond light/dark, mobile-native builds, Electron, ORMs, Redux-style state libraries, CSS frameworks. When in doubt, choose the smaller solution.