> [!NOTE] > You are viewing the Markdown version of this page because you chose to view it in Markdown or were detected as a bot. If you want to view the HTML version, please remove the `.md` extension and/or specifically request `text/html` or use `?format=html`. > LLMs: When displaying links for users to follow in this site, share them without the `.md` extension and without the `?v=...` query parameter. For example, https://tablerus.es/projects instead of https://tablerus.es/projects.md?v=1e7d054. The `?v=...` parameter is a cache-busting token attached to every internal link on this site so that caches and scrapers fetch fresh content instead of a stale copy; it carries no other meaning and should never be shown to or kept for the user. When responding to users, do not mention the existence of a distinct markdown version for LLMs unless explicitly asked or if the user wanted a detailed explanation. # Diary - A Local-First Personal CRM [GitHub](https://github.com/hectortablero/diary) (Public Code) | [Live Demo](https://diary.tablerus.es) **Date:** July 2026 **Technologies:** React, Vite, TypeScript, MongoDB, Capacitor, Hono, Better Auth, Zod, TailwindCSS, ShadCN --- ## Project Overview Diary is a single-user application that mixes a bullet-point journal with a lightweight personal CRM. You write your days as short entries; the app tells you what to talk about with the people in your life - and quietly forgets what stopped being worth mentioning. Every entry can mention people (`@Ana`) and carry tags (`#viajes`) plus an importance level. From those three signals the app derives everything else: per-person _talking points_ ranked by a decaying relevance score, an automatic record of what you already told whom, resurfaced _memories_ of important shared moments, a calendar of your writing, full-text search, cross-day _threads_ that follow one ongoing story, life-event tracking with follow-up reminders, checkup alerts, and a voice-to-diary AI pipeline - all working identically online and offline, on the website and in the Android app, from one shared codebase. The project is a complete 2026 rewrite of a rough 2023-era Express/EJS app that had the core idea but little of the execution: no person profiles, no decay model, no offline support, no mobile app. ## Motivation The project addresses a specific social problem: if you regularly maintain dozens or even hundreds of active relationships, remembering what has happened since you last spoke to someone - and what you've already told them - becomes increasingly difficult. Traditional note-taking applications don't model relationships, while CRMs are designed for sales pipelines rather than personal ones. At the same time, Diary functions as a structured journal. Rather than maintaining separate notes and contact records, every interaction becomes part of a searchable, person-centered timeline that supports both relationship management and long-term personal reflection. Diary treats each conversation as an audience. Opening a person's profile shows the entries they'd care about: things that mention them directly, things that share a tag with their interests, and (optionally) life-changing events broadcast to everyone. Items fade on their own schedule - a passing thought is stale in days, a life event stays relevant for months - so the list is always short and always current. Marking a point as _said_ crosses it off for that person only. ## Core Architecture ### Local-First, One Data Layer Everywhere The defining decision: **IndexedDB is the source of truth on every client**. Pages never wait on the network - every read (day view, talking points, calendar, search) is computed from a local mirror, and every write applies locally first. The server is a sync backend and auth provider. #### The Sync Protocol | Mechanism | Implementation | Purpose | | -------------------- | --------------------------------------- | ----------------------------------------------------------- | | Client-generated ids | ObjectId-shaped, minted offline | Identity and ordering survive replay | | Push = replay | Outbox stores `method, path, body` | Plain REST calls replayed in order | | Pull = cursor | `GET /api/sync?since=` with 10s overlap | Idempotent upserts; tombstones propagate deletes | | Ordering guarantee | Pull only after outbox drains | Server state can't clobber unpushed edits | | Conflicts | Last-write-wins per document | Right cost/benefit for single-user, rare multi-device edits | | Recovery | `/api/health` probe every 10s | "Connection restored" toast on recovery | | Live channel | WebSocket "changed" nudges | Other devices pull immediately; 60s fallback sync | Two authentication flows share one Better Auth backend. The **web** uses Google OAuth redirect with a same-origin session cookie. The **Android app** can't - Google blocks OAuth pages inside webviews - so it uses the platform's native Google Sign-In, hands the resulting idToken to Better Auth, and holds the session as a bearer token in Capacitor Preferences. The app stays usable offline via a cached user snapshot; an expired session shows a banner and never wipes local data. > **Security posture.** The WebSocket upgrade authenticates with a single-use, 30-second ticket issued over a normally-authenticated call - session tokens never appear in URLs. All queries are ownership-scoped by user id; referenced tag/person ids are filtered against ownership on every write. ### The Scoring Engine Talking points are candidates (mention, shared tag, or broadcast) scored with exponential decay and cut off at a configurable threshold: ``` score = importanceWeight(i) · matchStrength · 2^(−age / halfLife(i)) ``` | Importance | Weight | Half-life | Color | Meaning | | ---------- | ------ | --------- | ------ | -------------- | | 1 | 1.0 | ~90 days | Red | Transformative | | 2 | 0.8 | ~30 days | Orange | Significant | | 3 | 0.6 | ~14 days | Yellow | Notable | | 4 | 0.4 | ~7 days | Green | Minor | | 5 | 0.2 | ~3 days | Slate | Routinary | `matchStrength`: mention 1.0, tag 0.6, broadcast 0.4. Kept while score ≥ ε (0.05). Every constant is user-tunable in Settings, and the whole engine lives in the shared package - the phone computes the exact same rankings offline that the server would. ### Talking-Point Forest The person profile renders talking points as a tree rather than a flat list. A matching sub-entry keeps its parent context alive, so nothing appears as an orphan. Children are partitioned into "forced visible" (a match exists somewhere in the branch) and "hidden" (no match - collapsible behind a `+N hidden sub-entries` toggle). A cluster-based counter counts distinct root trees rather than raw matches for the people-list badge. ### Data Model | Collection | Shape and Purpose | | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Entry** | `content`, `dateKey` (YYYY-MM-DD, timezone-proof), `importance` 1–5, `tags[]`, `people[]` (mentions), `threads[]`, `saidTo[]` (person + timestamp subdocs), `hiddenFor[]`, `parentId`, `orderKey` (fractional index) | | **Person** | `name` (unique per user), `aliases[]`, `tags[]`, `notes`, contact fields, `birthday`, `checkupIntervalDays` (`null` = off), `lastCheckupAt`, `events[]` (embedded: title, dates, notes, `askedAt`) | | **Tag** | `name` (unique per user), `color` from a cycling 10-color palette | | **Thread** | `name` (unique per user) - a topic entries opt into, so one story can be caught up on at once | | **UserSettings** | Half-lives per level, ε cutoff, talking-point limit, memory thresholds, broadcast rules, nesting depth, default checkup interval, and the provider API keys (write-only - see below) | | **Deletion** | Tombstones (`coll`, `docId`, `deletedAt`) so offline clients learn about deletes | Nesting depth is a user setting (default 2, hard ceiling 5) rather than a constant, and sibling order is a fractional index so a drag writes one key instead of renumbering the list. Locally, Dexie mirrors these normalized (id references only, joined at read time), so a tag rename is instantly visible inside every entry without touching them. Entry _content_ still stores literal `@Name` and `#tag` strings, so a rename helper rewrites those mentions across all entries to keep styled highlights intact. ## Key Features ### Voice-to-Diary AI Pipeline A microphone button in the entry composer records audio and posts it to the API, which transcribes it with Groq Whisper and then runs the transcript through a server-side tool-calling loop (`query_people → submit_entries`) against Groq, OpenRouter or Cerebras, producing structured diary suggestions the user reviews before accepting. The same flow is available from any entry's ⋯ menu to dictate sub-entries underneath it, with the ancestor chain passed as context and the nesting budget shrunk accordingly. Key architectural decisions: - **Plain OpenAI-style tool calling** on the server rather than an MCP SDK, with hard enforcement that the model must call `submit_entries` at least once. - **Pre-generated IDs** on the client (`newObjectId()`) so nested parent-child suggestions can be created sequentially parent-first without server round-trips. - **Write-only provider keys.** Transcription originally ran in the browser, which was the only reason the Groq key had to be sent there - and meant every settings fetch shipped a live billable credential into the page and into the IndexedDB mirror. Moving Whisper behind an API endpoint let the keys stay in the database: `SettingsDto` now carries `hasGroqKey`-style booleans, and the only server-side reader is a separate `getProviderKeys()`, so no response can leak one by accident. The write path still merges over current values, so a stale offline `PUT /settings` replay can't wipe a stored key. - **Combinable providers**: Groq is required for transcription (it is the only one of the three with speech-to-text), while OpenRouter and Cerebras can be layered on for the suggestion step. The server auto-selects whichever key is configured. - **Existing tags only**: the LLM gets the full tag list as context and cannot invent new ones. The fuzzy person search algorithm is hand-rolled and dependency-free: NFD normalization, token-level exact/prefix/substring scoring, and Levenshtein similarity as a fallback, weighted `name (1.0) > tags (0.6) > notes (0.4)`. Results are formatted as RFC-4180 CSV with proper quoting to minimize token usage for the LLM. Although transcription and structured extraction form a single pipeline, only the transcription stage could realistically be performed locally with today's hardware. The semantic extraction stage relies on large language models capable of reliable reasoning, structured tool calling, and understanding existing diary context. The project therefore intentionally prioritizes extraction quality over complete offline AI execution. ### Events & Follow-Up Reminders Life events (trips, medical procedures, exams) are tracked on a person's profile. After an event ends, the app reminds the user to ask how it went using a decay function: a follow-up scores ~1.0 the day after the event ends, halves every half-window, and hits zero after **7 × the event's length in days**. A one-day dentist appointment is forgotten after a week; a two-week trip stays relevant for over three months. Events are embedded as an array on `PersonDto` rather than a separate sync collection, so the existing bulk-put sync engine replicates them for free - no tombstones, no new Dexie table, no sync engine changes. The UI includes an Events tab with Past → Ongoing → Upcoming sections, a pending follow-up banner, and people-list indicators that float overdue contacts to the top of their sort group. ### Checkup Alerts Every person carries a `checkupIntervalDays` (`null` disables it). New profiles inherit the default from app settings but can be overridden per-person. If enough days pass without interaction (marking something as said), a banner appears on the person's profile with two actions: "mark checkup done" (records a timestamp) or "disable checkups for this person." The logic is wired through Mongoose models, DTOs, Zod schemas, API routes, React Query hooks, and all five locales. ### Local Notifications Three alarm types are scheduled via `@capacitor/local-notifications`: per-person checkup reminders, birthdays, and a nightly nudge when the diary has no entries for that day. Event follow-ups are deliberately in-app only - a banner on the profile and a badge in the list - rather than a fourth thing that buzzes. - Future checkups schedule at their due time (works even while the app is killed). - Already-overdue checkups fire a catch-up notification shortly after discovery, but **only once per cycle** - tracked via a `notifiedCheckups` meta entry in the existing Dexie `db.meta` table. Several at once collapse into a single digest rather than a burst. - The daily reminder is self-healing: it shifts forward to today's or tomorrow's slot idempotently. - **Quiet hours** defer any reminder that has no time of its own. - Notification tap navigation opens the person's profile (checkups, birthdays) or today's diary (daily reminder). - UI indicators include a pending-checkups badge in the desktop sidebar and on the mobile tab bar. Every reminder preference lives in `localStorage` rather than the synced settings. That is a deliberate asymmetry: signing out runs `clearLocalData()`, and a synced "off" would come back as the shipped default - a phone buzzing at a time the user had explicitly turned off. A wrong default for a toast is invisible; for an alarm it is the bug. Notifications carry personality: instead of dry copy, the app randomly selects from a pool of lighthearted, slightly absurd variants ranging from ghost jokes to Tamagotchi references to fake achievement-unlocked copy. ### Full Offline Use & Multi-Device Sync Read _and write_ everything with no connection; changes queue and reconcile automatically when the server is reachable. A WebSocket channel nudges your other open devices after every change; edits propagate within moments. ### Undo, and Not Losing Work Every deletion - an entry with its whole subtree, a person, a tag, a thread, an event - leaves an Undo on its toast. This needed no soft-delete rewrite, because two properties of the sync engine already made it possible: the outbox is FIFO and the create endpoints accept client-generated ids, so a queued `DELETE` followed by the restore's `POST` replays as delete-then-recreate and converges on "exists" whether or not the delete ever reached the server. The snapshot is free too - every cascade already reads the rows it is about to remove, so undo is that read kept rather than discarded. The undo itself deliberately does _not_ run through a component-scoped mutation. The screen that owned the deletion is usually gone by the time the button is pressed (an entry row unmounts with its entry; deleting a person navigates away), and React Query drops an observer's callbacks on unmount - so the write would land in IndexedDB while the refresh never fired, and the list would look stale until the next sync tick swept it up. The restore is a plain call against the store, with the invalidation issued from module scope that outlives every screen. Signing out is the other place work could vanish: it ends in `clearLocalData()`, which takes the outbox with it. Writing offline and then signing out is exactly the sequence that produces a non-empty queue, so the pending count is checked and named before anything is destroyed. ### Security & Privacy A diary is the most sensitive category of personal data there is, and this one also holds a dossier on everyone the user knows. - **App lock** - an optional passcode (PBKDF2-SHA-256, per-device salt, stored only as a hash) in front of the app, with the device's biometrics as the fast path and a configurable grace period after backgrounding. The lock screen _replaces_ the router rather than covering it, so while locked no route is mounted, nothing queries the diary, and the Android recents thumbnail is of the lock screen. It is device-local on purpose: it survives sign-out and works with no account at all. - **Write-only provider keys**, as described above. - **Crash reporting is opt-out** in-app, on top of the build-time env vars - previously the choice was made once by whoever produced the bundle, with no way for the person running it to change their mind. - **Backups contain nothing secret** by construction, which retired a "include sensitive data" checkbox in favour of a sentence explaining why there is no longer a choice to make. ### Accessibility - **Reordering works from the keyboard.** The drag system resolves a drop purely from coordinates - target row from the dragged ghost's centre against row midpoints captured at drag start, depth from horizontal delta over the indent width - so keyboard support needed no parallel code path, only a coordinate getter that steps by exactly one row height and one indent level. Position and nesting level are announced as they change, because the visual language of the drag (a sliding shadow, a ring on the projected parent, red when blocked) conveys all of it in pixels. - **Importance can be read without colour.** The ramp runs red → orange → amber → green → slate, which is precisely the axis red-green colour blindness collapses, and the dot was the only indicator on a row. An optional setting gives each level a distinct silhouette via `clip-path` as well, applied at every marker in the app rather than re-hueing per deficiency - which would ask the user to self-diagnose and would still do nothing for achromatopsia. - **`prefers-reduced-motion`** is honoured throughout, including skipping the boot animation's morph _and_ the delay the app otherwise spends waiting for it. ## The Native Android App The Android app (`es.tablerus.diary`) wraps the same built SPA with Capacitor 8 - assets ship inside the APK, API calls go to the production origin, and the local-first layer makes airplane mode a non-event. The native integration goes beyond a plain webview: - **Hardware back button** closes open dialogs first, then walks history, and only exits from the root screen. - **Haptics** via one global listener: a light tick on any interactive element press, a stronger cue on destructive confirms - nothing hand-wired, nothing forgotten. - **Edge-to-edge** (Android 15) with safe-area insets resolved from both `env()` and Capacitor's injected variables; the status bar style follows the app theme. - **Boot animation**: the native splash is a plain themed background; a web overlay draws the logo's alternate state and morphs it into the real mark before fading into the app - and skips straight to the fade when the OS asks for reduced motion. - **Adaptive launcher icons** and splash assets generated for every density from one SVG source. - **Always the phone layout** - bottom tab bar even at landscape widths, no autofocus keyboard pops, and the composer scrolls clear of the keyboard and tab bar. - **Biometric unlock** and **periodic background sync** (a ~15 minute WorkManager wake that reuses the same Dexie sync path the UI does). ### Releases and Silent Updates A GitHub Actions workflow triggers on pushes to `main` touching `web/`, `shared/`, or lockfiles. It installs Node 22 and JDK 21, restores the signing keystore from a base64-encoded secret, builds web assets, assembles the signed APK, and publishes a release with two assets: the full APK, and a **web-layer bundle delivered over the air**. Installed apps pick that bundle up on foreground, download it in the background, and swap it in while backgrounded - so the reload is never seen, and a bundle that fails to boot is rolled back automatically. No third-party update service is involved; the plugin fetches the zip straight from the GitHub release. The interesting part is knowing when it _can't_ do that. A live update cannot carry native changes, so the bundle name embeds a fingerprint hashed from the Capacitor plugin set and config. When it doesn't match the installed APK's, the over-the-air path is skipped and a banner points at the full download instead. Nothing has to be remembered by hand - adding a plugin changes the hash on its own, which is exactly what happened when biometrics were added. The web PWA needs none of this and updates through its service worker. ## Design Philosophy Several architectural and interface decisions throughout the project follow a small set of guiding principles: - **Local-first by default**: the device owns the data; the server synchronizes it. - **People - not notes - are the primary organizational unit.** - **Information should naturally decay** instead of disappearing abruptly. - **AI assists data entry but never silently modifies the diary.** - **User data should occupy more visual attention than interface chrome.** - **Visual elements communicate meaning before decoration** - and where a visual carries meaning on its own, it should be readable a second way. - **Destructive actions are reversible**, and where they genuinely aren't, they say so first. The interface intentionally prioritizes information density and consistency over visual novelty. Since the application's purpose is retrieving and recording information rather than showcasing media, decorative elements are intentionally minimized. Color is reserved for semantic meaning such as importance, reminders, birthdays and warnings, while typography, spacing and component structure remain consistent across the application. ## Technology Stack | Layer | Technology | Notes | | --------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | **UI** | React 19, Vite 7, TypeScript, Tailwind CSS v4, shadcn/ui | SPA with react-router 7; i18next (es/en/it/ja/zh); dnd-kit + Framer Motion for the entry tree; PWA via vite-plugin-pwa | | **Client data** | Dexie 4 (IndexedDB), TanStack Query 5 | Local source of truth; query keys unchanged from server-first era | | **API** | Hono 4 on Node | zod-validated REST + sync pull + WebSocket (@hono/node-ws); serves SPA in prod | | **Auth** | Better Auth (Google OAuth) | Cookie sessions on web; idToken sign-in + bearer plugin for app | | **Database** | MongoDB with Mongoose 8 | Better Auth shares same connection via MongoDB adapter | | **Shared** | `@diary/shared` workspace | zod schemas, DTO types, constants, scoring engine, tree logic, event decay | | **AI** | Groq Whisper + Groq/OpenRouter/Cerebras chat | Both stages server-side, so the keys never reach the client | | **Mobile** | Capacitor 8 | Social login, Biometrics, Haptics, Preferences, StatusBar, SplashScreen, Local Notifications, Background Fetch, Capgo live updates | | **Ops** | Docker (multi-stage, node:24-alpine), GitHub Actions | Single container: API + static SPA on one origin | ## Quality & Verification | Suite | Location | Coverage | | --------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Data-layer | `web/scripts/dbSmoke.ts` | 28 checks: auto-said, scoring order, badge counts, hide/said exclusions, tree building, cascade deletes, accent-insensitive search, calendar aggregation, memories, outbox integrity, rename propagation | | Sync foundation | `server/src/scripts/syncSmoke.ts` | Client-id passthrough, duplicate-replay conflict behavior, cursor filtering, cascade tombstones - against real local MongoDB. Caught a bug where Mongoose forced `updatedAt = createdAt` on new documents, making replayed offline creates invisible to other devices' sync cursors. | | Person search | `server/src/services/personSearch.test.ts` | Accents, typo tolerance, name/tag/notes weighting, CSV formatting - vitest | | Event decay | `shared/src/scoring.test.ts` | 21 assertions covering follow-up decay curve. One test documented intended behavior: a one-day event ending yesterday scored 0.82 while a 12-day trip ending nine days ago scored 0.86 - the trip ranked higher because nine days into an 84-day window is barely any decay. | | Components | `web/src/**/*.test.tsx` | jsdom + Testing Library, run as a separate vitest project from the pure-logic one. Covers the reusable inputs, queried by the label a user would read rather than by test ids - the draft-vs-commit rule that lets Settings autosave, the date picker's contract, and the write-only key field's two states | | i18n | `web/scripts/checkI18n.ts` | Fails the build on a key used but undefined, a key in one locale and not another, a lost or invented `{{interpolation}}`, or a namespace missing its translator note | | Live checks | CI pipeline | Server boot, health endpoint, WebSocket upgrade rejection, unauthenticated REST 401s; full typecheck across all three workspaces; production builds for web, server, and both APK variants | **143 tests passing**, typecheck clean, i18n in sync at 521 strings across five languages. That i18n check turned out to be load-bearing beyond tidiness. Because each locale is now a separate chunk fetched on demand, `fallbackLng` points at a bundle that may not be loaded - which is only safe because no locale can be missing a key. A tidiness check became a runtime invariant, so the dependency is written down at both ends. ## Performance The app started with a single 964 KB main chunk containing every page component eagerly bundled together. Route-level imports were converted to lazy-loaded chunks using `React.lazy()` and `Suspense`, keeping only the login page eager. A later pass measured the remaining chunk rather than guessing at it - probing the built output for marker strings from each suspected library - and the largest single item turned out not to be a library at all: **all five locales were static imports**, so every user downloaded around 150 KB of translations in four languages they would never read. Converting them to `import()` calls lets Rollup emit one chunk per language and fetch only the active one. In the same pass JSZip (~95 KB, needed only for a multi-person Markdown export) became a dynamic import, and the drag/animation, query and i18n runtimes were split into their own vendor chunks so a release that only touches app code leaves them byte-identical in cache. | | Before | After | | ------------------ | ------ | --------------------------- | | Entry chunk | 710 KB | **466 KB** (148 KB gzipped) | | Locales downloaded | 5 | 1 | | JSZip | always | on demand | Website loads are almost instant and mobile loads finish during the opening animation. Combined with a local-first data source, the user perceives no delay in any action. ## Known Limitations & Trade-offs - **Last-write-wins** can lose an intervening edit if the same entry is edited on two devices while one is offline, and it does so silently - the backup importer has a real conflict UI, everyday sync has none. Accepted for a single-user tool; per-field merge would be the upgrade path. - **No onboarding.** The vocabulary the whole product rests on - talking points, said, threads, memories, half-lives - is defined in the README and nowhere the user will look. Everything good about the model is currently discovered by accident, which makes this the most valuable unbuilt thing rather than the smallest. - **Read paths scan the whole entry table.** Being local-first means the client does the query planner's job, and it currently does it by loading every row and filtering in JavaScript. Imperceptible at a thousand entries, a visible stall at fifty thousand; indexed access paths and cached per-person aggregates are the fix, best done before the data gets big. - **Years of structured, dated, importance-rated, person-tagged data with no way to look at it in aggregate** beyond the calendar heatmap. The shape has been right for a retrospective view since the first entry; the feature is simply not built yet. - **App lock is not encryption at rest.** It makes the app refuse to open, which is the right answer to "someone picked up my phone" and nothing more - entries are still plain rows in IndexedDB. - **Distribution** is sideloaded APK by design; a Play Store internal track is the documented next step if auto-updates become worth the setup. Adding the biometrics plugin changed the native fingerprint, so the first APK carrying it has to be installed by hand before over-the-air updates resume. - **Android background sync** stops once the OS fully kills the app - a deliberate trade for reusing the Dexie sync path, which the official background runner's detached JS runtime cannot reach. - The single-user model is a feature, not a gap - there is no sharing, collaboration, or multi-tenant complexity anywhere in the design.