23 lines
5.1 KiB
Markdown
23 lines
5.1 KiB
Markdown
# Knowledge library: Pocket source review and design
|
|
|
|
Reviewed 2026-10-20 before implementing the library data layer. Source inspected at [Pocket/pocket-monorepo](https://github.com/Pocket/pocket-monorepo/tree/5e5268fd92e997bb3350eaeafb54285238178a8e), commit `5e5268fd92e997bb3350eaeafb54285238178a8e`.
|
|
|
|
## Verified upstream patterns
|
|
|
|
- [`servers/list-api/schema.graphql`](https://github.com/Pocket/pocket-monorepo/blob/5e5268fd92e997bb3350eaeafb54285238178a8e/servers/list-api/schema.graphql) defines `SavedItem` as a user's saved URL with title, tags, archive/favorite state, timestamps and a linked underlying item. That separation is useful: the saved reason and state belong to the user, while fetched page metadata is fallible.
|
|
- [`servers/list-api/src/dataService/savedItemsService.ts`](https://github.com/Pocket/pocket-monorepo/blob/5e5268fd92e997bb3350eaeafb54285238178a8e/servers/list-api/src/dataService/savedItemsService.ts) scopes saved-item queries by `user_id` and looks up `given_url` separately from the resolved item. [`servers/list-api/src/models/SavedItem.ts`](https://github.com/Pocket/pocket-monorepo/blob/5e5268fd92e997bb3350eaeafb54285238178a8e/servers/list-api/src/models/SavedItem.ts) handles archive, tags and soft deletion. The published monorepo does not provide a complete migration history for the legacy list database, so its exact indexes and constraints cannot be inferred from the API alone.
|
|
- [`servers/list-api/src/externalCaller/parserCaller.ts`](https://github.com/Pocket/pocket-monorepo/blob/5e5268fd92e997bb3350eaeafb54285238178a8e/servers/list-api/src/externalCaller/parserCaller.ts) calls a separate parser. [`servers/parser-graphql-wrapper/src/databases/pocketMetadataStore.ts`](https://github.com/Pocket/pocket-monorepo/blob/5e5268fd92e997bb3350eaeafb54285238178a8e/servers/parser-graphql-wrapper/src/databases/pocketMetadataStore.ts) illustrates metadata storage. The many service and cache layers are excessive for this personal Django app.
|
|
- [`lambdas/user-list-search-corpus-parser-hydration`](https://github.com/Pocket/pocket-monorepo/tree/5e5268fd92e997bb3350eaeafb54285238178a8e/lambdas/user-list-search-corpus-parser-hydration) shows separate search hydration. Local title, URL, description, notes and tag search should come first.
|
|
|
|
## License and reuse boundary
|
|
|
|
The monorepo root [`LICENSE`](https://github.com/Pocket/pocket-monorepo/blob/5e5268fd92e997bb3350eaeafb54285238178a8e/LICENSE) is Apache-2.0, but [`servers/client-api/LICENSE`](https://github.com/Pocket/pocket-monorepo/blob/5e5268fd92e997bb3350eaeafb54285238178a8e/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](https://github.com/Pocket/pocket-ios) 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.
|