Papertrail

Next.js 16 static-export notes app for GitHub Pages, with its own Node.js + MariaDB API (server/) for accounts, private notes and image storage.

Run and verify

Use Node.js 24. Run npm ci, configure .env.local from .env.example, then npm run dev. npm run build produces out/, the installable manifest, PNG icons and a versioned offline service worker. Preview using npm start. The development server intentionally does not register a service worker.

Checks:

• npm test: Node regression tests for notes, conflicts, backup validation, safe Markdown and images.
• cd server && npm test: API integration tests against a real MariaDB test database (TEST_DB_NAME, TEST_DB_USER, TEST_DB_PASSWORD, plus TEST_DB_HOST or TEST_DB_SOCKET).
• npm run typecheck: Next.js/client TypeScript.
• npx playwright install chromium, then npm run test:e2e after a build: isolated browser flows against the actual static export.
• GITHUB_ACTIONS=true npm run build && GITHUB_ACTIONS=true npm run test:e2e: GitHub Pages /editor paths, including offline reload.

Browser tests use disposable profiles, not the user's browser data. The sync test doubles only the API HTTP boundary; authentication UI, IndexedDB, guest transfer, conflict handling and the save queue remain real.

Features and data flow

• A single borderless writing surface; titles derive from the first nonempty line. Creating a note focuses its text.
• Autosave to IndexedDB, separate guest/account notebooks, recoverable migration from the former localStorage cache. Closing during an unfinished local save is protected by a warning. Signed-in accounts can be edited from several tabs and devices at once: after each save the API tells the account's other devices through Socket.io (/api/socket.io), other tabs of the same browser are told through a BroadcastChannel (works even if WebSocket is blocked), and a tab also synchronizes when it regains focus. A guest notebook (no account) keeps a browser-wide Web Lock: one writing tab, the others read-only. Offline, tabs of one account share the local cache with last-write-wins.
• Guest notes transfer to the signed-in account in one cancellable, atomic IndexedDB transaction. Cloud writes debounce for 700 ms. Reconnect and a 30-second refresh retry failed saves. Sign-out first flushes local edits; Retry can recover a failed local write too.
• Optimistic concurrency uses a server-generated revision and conditional writes. When another device changed a note, both versions remain as distinct notes; a conflict copy is marked. This is not collaborative editing.
• Trash restores complete notes for 30 days. Expired notes are removed on app loading/refresh and cloud deletion on the next successful synchronization, not by a background server scheduler.
• Up to 50 history checkpoints, at most one per 30 seconds of editing. Restoring a version also preserves the current content.
• Pin, archive, tags, sort by title/creation/modification, highlighted sidebar results, find-in-note and focus mode.
• Full portable JSON backups include notes, trash, metadata, history and embedded local images. Import .txt/.md files or JSON backups in a batch (50 MB maximum). Imports create new IDs and never overwrite existing notes.
• Themes and French/English/Arabic UI, including Auth, account dialogs, errors and RTL layout. Text size uses a numeric field.
• Markdown WYSIWYG tools: headings, bold, italic, underline, strikethrough, lists, tasks, tables, links, quotes, code, dividers and native undo/redo.
• JSON and code syntax coloring in preview; switch back to edit the original source. User-supplied HTML is escaped, link/image protocols are checked.
• Images via file, URL, clipboard or drop: PNG/JPEG/GIF/WebP, 1 MB maximum per file. Large dimensions are reduced to 1600 px for non-animated images. Captions and width are editable. Files use IndexedDB blobs and a private per-account table in MariaDB; Markdown stores stable attachment IDs, never expiring signed URLs. Legacy/backup inline images remain compatible.
• Cloud images are fetched with authenticated requests and cached for offline viewing. Automatic orphan-image deletion is intentionally disabled: a client-side stale snapshot cannot prove an image is unused across devices. Account deletion removes that account's image folder.
• Installable PWA caches only the static shell and same-origin build assets. It never caches API responses or authentication pages. First online installation is required before offline launch.
• Offline account access uses the last locally stored identity even when its server session has expired. This permits reading/editing only that device's account cache; no server authorization is bypassed. Explicit sign-out removes access to that identity, and reconnect asks the API for the current session again.
• Account settings change passwords and delete accounts with a typed confirmation. Deletion removes the account's sessions, notes, images and shares in one cascading database delete.
• Read-only sharing creates a seven-day snapshot, with a high-entropy token stored only as its SHA-256 hash. The owner can revoke links. The link token lives in the URL fragment, not a query string. Anyone with the link can read the snapshot; future edits do not modify it.

Shortcuts: Ctrl/Cmd+K searches notes, Ctrl/Cmd+F searches the open note, Ctrl/Cmd+Alt+N creates a note, Escape exits focus/search. Formatting uses the browser's native commands.

API, database and security

The browser never talks to the database: it calls the API in server/ (Node.js 24, no framework) which stores everything in MariaDB.

• Schema: server/schema.sql, applied automatically on API start (idempotent). Tables: users, sessions, email_tokens, notes, note_images, note_shares.
• Accounts: e-mail + password (bcrypt). Sessions are random opaque Bearer tokens (60 days) stored only as SHA-256 hashes; logout and password change revoke them. Login and sign-up are rate limited.
• Every query is scoped to the authenticated user_id. Notes use a server-side revision for optimistic concurrency: a stale write gets 409 and the client keeps both versions.
• Images: PNG/JPEG/GIF/WebP, 1 MB maximum, private per account.
• E-mail features (password reset, magic link) appear only when the API has SMTP_HOST configured. Links carry a single-use token (1 hour) in the URL fragment.
• Live sync: Socket.io (WebSocket, authenticated with the session token) only carries a payload-free notes ping to the account's other connections; data still flows through the authenticated REST API. The reverse proxy must forward WebSocket upgrades on /api/socket.io (Caddy does by default).
• CORS only allows the origins listed in ALLOWED_ORIGINS.
• Configuration: copy server/.env.example to server/.env. Deploy on the VPS with cd server && docker compose up -d --build; The container serves the static site at https://papertrail.clubika.com and the API under /api (behind Caddy); the site is built inside the Docker image.

Deployment

The Pages workflow runs unit tests, static build, typecheck and Playwright before deployment. The build targets https://papertrail.clubika.com/api by default; set NEXT_PUBLIC_API_URL (.env.local or a repository variable) to use another API. Never commit .env files or database credentials.

Implementation lives in app/components (UI), app/hooks (Auth/autosave), app/lib (note transformations, IndexedDB, attachments, safe rendering), and server (API and MariaDB schema). No new editor, persistence or UI library was added; Playwright is a development-only browser-test dependency.

Automatic deployment

Every commit pushed to main updates the app:

1. GitHub Actions runs the tests (and publishes the GitHub Pages build).
2. The server (papertrail.clubika.com) checks every minute whether main changed (app-deploy.timer, script ~/deploy/auto-deploy.sh): it pulls the commit, rebuilds the Docker image (docker compose up -d --build in server/), probes /api/health, and automatically rolls back to the previous version if the new build fails or does not answer.
3. The log is ~/deploy/deploy.log on the server; a rejected commit is not retried until a new commit arrives.

It usually goes live 1 to 3 minutes after the push.