Build Feedly

The build, in order

1. 1

   OPML and feed list

   hideshow

   Import with folders, idempotently, and export back.

   1. 1.1Create the project and the tables

      feeds (id, url, title, folder, site_url, etag, last_modified, last_fetched_at, last_status, consecutive_failures, disabled), items (id, feed_id, guid, link, title, author, published_at, content, read, starred, fetched_at), unique (feed_id, guid).

      terminalcopy

      mkdir reader && cd reader && git init && npm init -y && npm pkg set type=module
      npm install express@4 better-sqlite3@13 rss-parser@3 node-cron@3
      mkdir data && cp .env.example .env

   2. 1.2Import OPML preserving folders; export on demand

   done when · tick each as it passes

   • A real Feedly OPML imports with folders intact
   • Re-importing adds nothing
   • The export re-imports into an identical tree

   next phase
2. 2

   Polite fetching

   hideshow

   Conditional GETs, a real User-Agent, timeouts, per-host courtesy, backoff.

   1. 2.1Send If-None-Match and If-Modified-Since; handle 304 by doing nothing

      Skipping this re-downloads every feed forever, which is how a reader becomes a nuisance.

   2. 2.2Set USER_AGENT, a timeout, per-host concurrency of 1 with a delay
   3. 2.3Back off failing feeds and disable after enough failures

   done when · tick each as it passes

   • A second fetch of an unchanged feed returns 304 and writes nothing
   • A feed returning 500 backs off
   • A timeout does not delay the others
   • Malformed XML is logged without killing the loop

   next phase
3. 3

   Item ingestion

   hideshow

   Dedupe that survives bad GUIDs, and HTML that cannot hurt you.

   1. 3.1Dedupe by guid, fall back to link, treat a rotating guid as absent
   2. 3.2Sanitize content against an allowlist, strip tracking pixels, absolutize URLs
      terminalcopy

      npm install sanitize-html@2

   done when · tick each as it passes

   • Refetching produces zero new items
   • A feed with rotating guids does not duplicate
   • A script tag in content is stripped
   • A relative image renders correctly

   next phase
4. 4

   Reader UI

   hideshow

   Folders with counts, a list, a reading pane, keyboard everything.

   1. 4.1Build the three panes: folder tree with unread counts, article list, reading pane
   2. 4.2Add keyboard shortcuts j/k/o/m/s/A and dark mode

      Mark-as-read on scroll-past is a preference, not the default.

   done when · tick each as it passes

   • Unread counts stay correct through every action
   • Keyboard focus survives list re-renders
   • A 5,000-item list scrolls without lag

   next phase
5. 5

   Starred and search

   hideshow

   Starred forever, FTS5 via triggers.

   1. 5.1Add the starred view
   2. 5.2Add an FTS5 table over titles and content, synced by triggers

   done when · tick each as it passes

   • Search finds a phrase inside an article body
   • Deleting an item removes it from the index

   next phase
6. 6

   Optional summaries

   hideshow

   A button that exists only when a key does, cached per item.

   1. 6.1Render the summarize button only when ANTHROPIC_API_KEY is set

      A dead button is worse than no button.

   2. 6.2Cache the summary on the item so reopening does not re-bill

   done when · tick each as it passes

   • With no key there is no trace of the feature
   • With a key a summary generates once and is reused

   next phase
7. 7

   Retention and deploy

   hideshow

   Prune read items, keep starred, back up, run as a service.

   1. 7.1Nightly prune of read items older than 90 days, never starred
   2. 7.2Nightly backup, a systemd unit, and the README

      README: how to add a feed (edit the OPML) and export it back, the polite-fetching behaviour as a promise, where the database lives.

      Files README.md

   done when · tick each as it passes

   • Pruning never deletes a starred item
   • Unread counts survive a restart

   next phase