Files
2026-10-21 15:25:33 +02:00

5.1 KiB

Knowledge library: Pocket source review and design

Reviewed 2026-10-20 before implementing the library data layer. Source inspected at Pocket/pocket-monorepo, commit 5e5268fd92e997bb3350eaeafb54285238178a8e.

Verified upstream patterns

License and reuse boundary

The monorepo root LICENSE is Apache-2.0, but servers/client-api/LICENSE is an MIT notice credited to Apollo Graph, Inc. Dependencies retain their own licenses. Apache-2.0 copying would require preserving license and applicable notices, marking changes, and observing its patent terms. Third-party article text and images are not granted by a source-code license. Pocket names and marks are not licensed as product branding. No upstream code or assets are copied here; the implementation uses independently written Django models and services based on general patterns. The Pocket iOS repository contains a Share extension, but that native code is unnecessary for an Apple Shortcut sending a POST.

Proposed local schema and pipeline

Use a separate knowledge app. SavedItem has owner, original URL, conservative URL key, optional canonical URL, user title, extracted title/description/thumbnail, notes, tags, saved and deferral reasons, status, read date, metadata state, and exposure dates. Enforce (owner, url_key) uniqueness and index (owner, status, created_at) and (owner, last_surfaced_at). CaptureToken stores only a hash, owner, scope, creation/revocation dates. RediscoveryEvent records attempted/delivered resurfacing and feedback. Do not model project cards as saved items. Optional project association can come later through an explicit link.

Save must commit without network access. A separate bounded worker may fetch metadata after validating each DNS resolution and redirect target against private, loopback, link-local and reserved addresses; cap redirects, time, response bytes and content type. Never render fetched HTML. Keep metadata pending until the separately invoked bounded worker runs. A failed fetch becomes an explicit error state. No arbitrary URL is fetched in the capture request. The current checkout uses SQLite, so local search uses indexed owner filtering plus simple text matching; PostgreSQL SearchVector and a GIN index are a deployment upgrade, not an assumed current capability. Do not add pgvector until relevance tests show a need.

MCP contextual retrieval uses only the authenticated owner's records, a relevance threshold, a maximum of three results, and a recent-exposure cooldown. A tool description can invite proactive calls, but the MCP server cannot compel ChatGPT to invoke it. ntfy scheduling must be opt-in with quiet hours, a low weekly budget, delivery history and duplicate suppression. The TasksNest ntfy implementation is outside this checkout and must be inspected before reusing its exact transport conventions.