Files

T

haopengzhan 3742dbdce4 feat: scaffold initial RSS reader project with Go backend and React frontend

2026-08-24 08:08:31 -07:00

30 KiB

Raw Blame History

RSSPipe: Product Requirements Document (PRD)

Document Version: 1.0.0
Status: Approved / Ready for Implementation
Target Audience: Engineering, Architecture, Product
Replaces: Miniflux Deployment
Deployment Target: k3s / Kubernetes (Single Container Architecture with Separate or Embedded DB)

1. Executive Summary & Product Vision

1.1 Overview

RSSPipe is a self-hosted, RSS-driven Information Gateway and intelligent reading platform built to replace traditional RSS aggregators (such as Miniflux).

Rather than serving purely as a passive feed bucket, RSSPipe combines:

Google Reader & Gmail UX Philosophy: Rapid, keyboard-first triaging (j/k, o, v, s, e), "Inbox Zero" workflow, dual view modes (expanded scrolling stream vs. compact list/split-pane), and Gmail-style search syntax.
Dual-Tier Feed Hooks Engine:
- Single-Feed Enrichment: Real-time readability full-text scraping, AI summarization/takeaways, relevance scoring, auto-tagging, TTS generation, and automatic public share-page publishing.
- Multi-Feed AI Digest Synthesis: Scheduled or threshold-based multi-document synthesis that rolls up unread items into clean "Virtual Digest Feeds" (e.g., Daily Morning Briefing, Topic Radar) with synthesized audio podcasts, automatically archiving raw individual items.
Single-User Security with Public Sharing: Single admin user model protecting the private gateway, with frictionless unauthenticated public sharing via tokenized URLs (/share/<uuid>.html).
Offline-Capable PWA & Native Ecosystem Support: Installable Progressive Web App (PWA) with responsive mobile/desktop interfaces, alongside a Fever / Google Reader API compatibility layer for native mobile clients (e.g., NetNewsWire, Reeder).
Unified K3s-Ready Architecture: High-performance Go backend with embedded React/Vite PWA frontend, packaged as a single lightweight Docker container targeting k3s/Kubernetes.

2. Core Architecture & System Tenets

               ┌────────────────────────────────────────────────────────┐
               │                     RSSPipe Web App                    │
               │   (React + Vite PWA / Google Reader & Gmail UX)        │
               └───────────┬────────────────────────────────┬───────────┘
                           │ REST / SSE Events              │ Fever / GReader API
                           ▼                                ▼
┌───────────────────────────────────────────────────────────────────────┐
│                          Go Unified Server                            │
│                                                                       │
│  ┌────────────────────┐  ┌────────────────────┐  ┌─────────────────┐  │
│  │   Auth & Session   │  │   Ingestion Pool   │  │ Public Share    │  │
│  │  (Single Admin)    │  │ (Cron & Web Crawl) │  │ (/share/<uuid>) │  │
│  └────────────────────┘  └─────────┬──────────┘  └─────────────────┘  │
│                                    ▼                                  │
│  ┌─────────────────────────────────────────────────────────────────┐  │
│  │                     Rules & Hook Engine (DAG)                   │  │
│  │  ┌───────────────────────────────┐ ┌──────────────────────────┐ │  │
│  │  │   Single-Feed Enrichment      │ │   Multi-Feed Aggregation │ │  │
│  │  │ (Readability/LLM/TTS/Webhook) │ │ (Digest Synthesis/Audio) │ │  │
│  │  └───────────────────────────────┘ └──────────────────────────┘ │  │
│  └─────────────────────────────────┬───────────────────────────────┘  │
│                                    ▼                                  │
│  ┌─────────────────────────────────────────────────────────────────┐  │
│  │     Data Layer (PostgreSQL / SQLite WAL + FTS5 Full-Text)       │  │
│  └─────────────────────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────────────────────┘

2.1 Design Tenets

Speed over Friction: Sub-100ms UI responses, instant keyboard navigation, and optimistic UI updates.
Information High Signal-to-Noise: Raw RSS feeds are enriched or distilled into digestible summaries and podcasts so the user stays informed without drowning in unread counts.
Zero Maintenance & Single Container Simplicity: Single binary/image containing backend server, worker pools, and embedded web assets, deployable via simple Helm chart / Kubernetes manifests on k3s.
Cycle-Safe Rule Processing: All feed transformation steps follow a strict Directed Acyclic Graph (DAG) with topological validation to prevent infinite execution loops.

3. End-to-End User Journeys

journey
    title Core User Journeys in RSSPipe
    section 1. Onboarding & Migration
      Import OPML from Miniflux: 5: Admin
      Auto-categorize and test feeds: 4: Admin
    section 2. Daily Triaging (Google Reader / Gmail UX)
      Open PWA (Desktop/Mobile): 5: Admin
      Navigate feeds with 'j'/'k' and expand with 'o': 5: Admin
      Quick triage with 'e' (archive/read) and 's' (star): 5: Admin
      Search with operators 'is:unread tag:ai': 5: Admin
    section 3. Feed Hooks & Enrichment
      Ingest feed & scrape full-text via Readability: 5: System
      LLM summarizes & scores relevance: 5: System
      Generate TTS audio preview: 4: System
    section 4. Multi-Feed Digest Generation
      Accumulate > 15 topic feeds or reach 8:00 AM: 5: System
      Synthesize AI Daily Digest & Audio Podcast: 5: System
      Publish to Virtual Digest Feed & mark raw items read: 5: System
    section 5. Knowledge Sharing
      Click 'Share to Public' on article/digest: 5: Admin
      External visitor views /share/<uuid>.html: 5: Public Reader

Journey 1: One-Click Migration from Miniflux (Onboarding)

Goal: Seamlessly transition existing feeds, categories, and folder hierarchies from Miniflux to RSSPipe in seconds.
Flow:
1. User navigates to Settings -> Migration & OPML.
2. User uploads Miniflux subscriptions.opml.
3. System parses categories and feed URLs, tests connection concurrency in the background, and preserves category folder tree.
4. System prompts option to backfill recent posts (last N days) or start fresh from latest entries.
5. Dashboard immediately renders feeds categorized and organized ready for consumption.

Journey 2: Morning Triage (Google Reader & Gmail Workflow)

Goal: Rapidly process 200+ unread items in under 5 minutes using keyboard shortcuts and split views.
Flow:
1. User opens RSSPipe PWA. The "Inbox Zero" view displays all unread entries grouped by priority or chronological stream.
2. User toggles view:
  - Expanded Stream (Google Reader): Full article body inline, scrolling continuously with Space or j/k.
  - Compact List (Gmail): Single-line item rows displaying Source, Star, Title, AI Summary badge, and Time.
3. User presses j to focus the next item, o or Enter to expand/collapse.
4. User presses s to star for deep reading later, v to open original link in a new tab, m to toggle read/unread, or e to archive/mark read.
5. User presses / to activate search and types is:unread tag:ai score:>80 to filter high-impact items instantly.

Journey 3: Single-Feed Automated Enrichment Hook

Goal: Automatically convert truncated RSS feeds into readable, summarized, and categorized entries with voice synthesis.
Flow:
1. Ingestion engine fetches a newly published feed item.
2. Content Extraction: System detects truncated content and runs the backend Readability scraper to fetch the full clean article markdown.
3. AI Enrichment: Configured rule triggers LLM prompt:
  - Generates a 3-bullet executive summary.
  - Assigns relevant topic tags (#llm, #k8s).
  - Scores article relevance from 1 to 100 based on user interest profile.
4. TTS Audio Hook: High-scoring items automatically trigger Edge-TTS / OpenAI TTS generation, attaching an audio player to the feed header.
5. Notification Hook: If relevance score >= 90, sends a webhook alert to user's Telegram/Discord channel with the summary and direct link.

Journey 4: Multi-Feed AI Digest Synthesis & "Inbox Zero" Auto-Rollup

Goal: Eliminate RSS fatigue by condensing tens of high-volume feeds into a single curated morning/evening brief.
Flow:
1. User sets a Multi-Feed Aggregation Rule: "Every day at 7:30 AM (or whenever unread items in #tech exceed 20), synthesize a 5-minute Executive Digest and mark source items as read."
2. At the scheduled time / threshold, the Multi-Feed Engine queries all eligible unread items.
3. The Engine passes all article snippets/full-text into the LLM with a structured synthesis prompt:
  - Grouping into major themes / top headlines.
  - Highlighting key takeaways, contradictions, or trends across sources.
  - Linking back to source items.
4. An AI TTS audio briefing is synthesized and attached.
5. The resulting synthesis is injected as a new entry into a Virtual Digest Feed (e.g., 📰 Daily Tech Executive Briefing).
6. The 20+ raw underlying source feeds are automatically marked as read / archived.
7. When user opens the PWA, they see 1 high-quality digest episode instead of 20 fragmented articles.

Goal: Share an insightful article or AI digest with friends, colleagues, or social followers without granting access to the private RSS reader.
Flow:
1. In the PWA reader view, user clicks the "Share to Public" icon (or an automated rule publishes high-scoring digests automatically).
2. Backend generates an immutable, non-guessable UUID share route: https://rss.domain.com/share/550e8400-e29b-41d4-a716-446655440000.html.
3. The generated page is a standalone, beautifully styled, mobile-friendly HTML view containing:
  - Article/Digest Title, Source attribution, and publication date.
  - Audio player (if TTS generated).
  - AI Summary & Full Markdown Body.
4. External readers can access the link without any login or authentication prompts.

Journey 6: Multi-Device Sync & Third-Party Native App Support

Goal: Read on mobile (e.g., NetNewsWire / Reeder on iOS/macOS) while traveling, and continue on desktop PWA at work.
Flow:
1. User configures NetNewsWire using the built-in Fever API or Google Reader API endpoint credentials (https://rss.domain.com/api/greader).
2. Mobile app synchronizes unread states, starred articles, and folders in real time.
3. Read state changes on mobile reflect instantly on the web PWA via Go backend sync.

4. Functional Requirements & Feature Specifications

4.1 Single-User Authentication & Security

Requirement ID	Feature	Description
AUTH-01	Single Admin Entry	Database stores single admin user account with hashed password (Argon2id / bcrypt).
AUTH-02	Session & JWT Auth	Secure, HTTP-only Cookie-based session for Web PWA, plus persistent API Tokens for third-party apps and CLI access.
AUTH-03	Public Share Isolation	Endpoints under `/share/*` bypass authentication entirely; all administrative, ingestion, and reader endpoints require valid admin credentials.
AUTH-04	Security Headers & Rate Limiting	Built-in rate limiting on login/API endpoints, CSRF protection, and customizable CORS headers.

4.2 Ingestion & Feed Management

Requirement ID	Feature	Description
FEED-01	Multi-Format Parsing	Supports RSS 0.9x/1.0/2.0, Atom 1.0, and JSON Feed 1.0/1.1 formats.
FEED-02	Concurrency Worker Pool	Background worker pool in Go with configurable concurrency, rate limits per domain, and exponential backoff retry.
FEED-03	Conditional GET / ETag	Utilizes `If-Modified-Since` and `ETag` headers to minimize network traffic and server load.
FEED-04	OPML Import / Export	Full OPML 2.0 import and export support, maintaining folder hierarchy and feed settings.
FEED-05	Category & Tag Hierarchy	Supports nesting feeds under Categories/Folders as well as applying multi-dimensional Tags.

4.3 Content Processing & Scraper Engine

Requirement ID	Feature	Description
PROC-01	Readability Full-Text Scraper	Built-in readability engine (extracts clean article HTML/Markdown from original URL for truncated feeds).
PROC-02	HTML Sanitization & Media Proxy	Strict XSS sanitization (DOMPurify / Bluemonday) and optional image caching/proxying to avoid mixed-content and tracking pixels.
PROC-03	Content Deduplication	SHA-256 content hashing and URL canonicalization to detect duplicate articles across feeds.

4.4 Dual-Tier Rules Engine & Feed Hooks (DAG Architecture)

graph TD
    subgraph Ingestion Phase
        A[Fetch RSS / Atom] --> B[Parse XML & Normalize]
        B --> C[Readability Full-Text Extraction]
    end

    subgraph Enrichment Phase (Single-Feed Hooks)
        C --> D{Single-Feed Rules Match?}
        D -->|Match| E1[LLM Summarization & Scoring]
        D -->|Match| E2[Edge-TTS / Audio Generation]
        D -->|Match| E3[Auto-Tag / Star / Drop]
        D -->|Match| E4[Outbound Webhook Telegram/Discord]
        D -->|Match| E5[Publish to /share/uuid.html]
    end

    subgraph Storage & Indexing
        E1 & E2 & E3 & E4 & E5 & D -->|Persist| F[(Database & FTS Index)]
    end

    subgraph Aggregation Phase (Multi-Feed Hooks)
        F --> G{Aggregation Trigger Fired?}
        G -->|Threshold > N items OR Schedule Cron| H[Batch Fetch Unread Target Feeds]
        H --> I[LLM Multi-Document Synthesis]
        I --> J[Generate Audio Podcast]
        J --> K[Inject to Virtual Digest Feed]
        K --> L[Batch Mark Source Items as Read]
    end

A. Single-Feed Hooks (Per-Item Pipeline)

Triggers: On Ingestion (on_feed_ingest), On User Star (on_item_star), On Tag Added (on_item_tag).
Conditions: Source Feed / Category, Title/Content Regex, Author, Word Count, Language, Metadata matching.
Actions:
1. ai_summarize: Send article content to configured OpenAI-compatible endpoint with custom system prompt; save summary to metadata.
2. ai_score: Compute relevance score (0–100) and rationale.
3. generate_tts: Synthesize audio via Edge-TTS / OpenAI TTS / ElevenLabs and store media link.
4. auto_tag / auto_star / mark_read / drop_item: Modify feed state automatically.
5. create_public_share: Automatically generate a public share link /share/<uuid>.html.
6. send_webhook: Dispatch JSON payload or message formatting to Telegram, Discord, Slack, or generic HTTP webhook (n8n/Zapier).

B. Multi-Feed Hooks (Batch & Temporal Aggregation)

Triggers:
- schedule: Cron expression (e.g. 30 7 * * * for 7:30 AM daily).
- threshold: When unread items matching criteria \ge N (e.g. > 15 unread articles in Category "AI & ML").
Conditions: Category, Tag filter, Keyword filter, Unread status.
Actions:
1. synthesize_digest: Execute multi-document LLM prompt to generate an editorial digest with categorized trends and citations.
2. create_virtual_digest_feed: Inject the synthesized article into an internal "Virtual Digest Feed" (e.g., "Daily AI Brief").
3. generate_digest_podcast: Synthesize speech for the full digest episode and attach audio file.
4. batch_archive_sources: Automatically mark the individual source articles as read/archived, maintaining Inbox Zero.

C. DAG Safety & Anti-Loop Validation

All rule definitions are validated upon creation/update via Topological Sort.
Cyclic dependencies (e.g., Rule A creates Feed Item that triggers Rule B, which triggers Rule A) are rejected at configuration time.
Hard recursion depth cap (depth = 3) on cascading triggers.

4.5 Reading Experience & UI / UX Specifications

+-----------------------------------------------------------------------------------------------+
| RSSPipe [Logo]       [ Search: is:unread tag:tech / ]           [Theme] [Sync] [Admin Profile]|
+-------------------+---------------------------------------------------------------------------+
| + Add Subscription| (Inbox: 12 unread)  [ Mark All Read ]  [ View: Stream | Compact ]  [Sort] |
| ----------------- +---------------------------------------------------------------------------+
| * Inbox (12)      | [ ] * [Hacker News] Building Local-First PWA with SQLite        10m ago   |
| * Starred (4)     |     AI Summary: Explains sync protocols and CRDTs... (Score: 92)          |
| * Digests (2)     | ------------------------------------------------------------------------- |
|   - Morning Brief | [ ]   [Ars Technica] Quantum Computing Milestone Announced      45m ago   |
|   - Weekly Radar  | ------------------------------------------------------------------------- |
| v CATEGORIES      | [ ] * [Virtual Digest] Morning AI Briefing (5 mins audio)       7:30 AM   |
|   > Tech (8)      |     [ ▶ Play Audio 05:21 ] Full synthesized summary of 18 posts...        |
|   > Science (4)   | ------------------------------------------------------------------------- |
+-------------------+---------------------------------------------------------------------------+

Dual View Modes

Google Reader Expanded Stream View:
- Continuous scroll through full article cards.
- Header with Feed Title, Favicon, Author, Publish Date, AI Summary pill, Audio Player bar (if present), and Actions (Star, Share, Original URL).
- Clean typographical hierarchy with readable line lengths (65–80 characters max for text body), syntax-highlighted code blocks, and responsive image scaling.
Gmail Compact List / Split-Pane View:
- High-density list: Checkbox, Star icon, Source Feed badge, Article Title, 1-line snippet/AI Summary preview, Timestamp.
- Split-pane layout: Clicking an item opens the reading pane on the right or below, retaining the list for fast scanning.

Keyboard Shortcut Matrix (Google Reader & Gmail Paradigm)

Key Binding	Action
`j` / `k`	Navigate to Next / Previous article
`Space` / `Shift + Space`	Page Down / Page Up through stream
`o` or `Enter`	Expand / Collapse current item in compact view
`v`	Open original article URL in a new browser tab
`s`	Star / Unstar current item
`m`	Toggle Read / Unread status
`e` or `Shift + I`	Archive / Mark as Read and advance
`Shift + A`	Mark all items in current view as read (with confirmation modal)
`/`	Focus search bar
`g` then `i`	Go to Inbox
`g` then `s`	Go to Starred
`g` then `d`	Go to Virtual Digests
`?`	Open keyboard shortcuts help modal

PWA & Offline Support

Fully installable PWA with Web App Manifest and Service Worker caching.
IndexedDB client caching (Dexie.js) allowing offline reading of already synced unread/starred articles and summaries.
Offline action queuing (marking read, starring while offline syncs automatically when connection is restored).

4.6 Search & Query Syntax (Gmail-Style Engine)

The search bar supports advanced tokenized queries backed by database Full-Text Search:

is:unread / is:read / is:starred
tag:tech / category:engineering
feed:"Hacker News" / from:author_name
has:summary / has:audio / has:share
score:>80 / score:<50
after:2026-08-01 / before:2026-08-20
Raw keyword and phrase matching: "generative ai" kubernetes

4.7 API & Ecosystem Integrations

Fever API & Google Reader API:
- /api/fever: Implements standard Fever protocol endpoints (?api, ?items, ?feeds, ?groups, ?unread_item_ids, ?saved_item_ids).
- /api/greader: Implements Google Reader API endpoints (/reader/api/0/...) for NetNewsWire, Reeder, and FeedMe.
AI / LLM Integration:
- Generic OpenAI-compatible client (configurable base_url, api_key, model_name, temperature, max_tokens).
- Supports OpenAI (GPT-4o/Mini), Anthropic (via OpenAI proxy/native), Google Gemini, DeepSeek, Ollama, and LocalAI.
TTS Integration:
- Free Microsoft Edge-TTS integration (high-quality neural voices with zero API key requirement).
- Optional OpenAI TTS (tts-1, tts-1-hd) and ElevenLabs API support.
Outbound Notification Webhooks:
- Native Telegram Bot API formatting.
- Discord / Slack incoming webhook formatting.
- Generic HTTP POST with configurable headers and JSON template.

5. Technical Architecture & Data Schema

5.1 Data Models (Relational & Flexible Metadata)

-- 1. Users Table (Single Admin Entry)
CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    username VARCHAR(64) UNIQUE NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

-- 2. Categories Table
CREATE TABLE categories (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    title VARCHAR(128) NOT NULL,
    parent_id UUID REFERENCES categories(id) ON DELETE SET NULL,
    sort_order INT DEFAULT 0,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

-- 3. Feeds Table
CREATE TABLE feeds (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    title VARCHAR(255) NOT NULL,
    feed_url TEXT UNIQUE NOT NULL,
    site_url TEXT,
    category_id UUID REFERENCES categories(id) ON DELETE SET NULL,
    is_virtual_digest BOOLEAN DEFAULT FALSE,
    refresh_interval_minutes INT DEFAULT 30,
    etag VARCHAR(255),
    last_modified VARCHAR(255),
    last_fetched_at TIMESTAMPTZ,
    fetch_error TEXT,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

-- 4. Feed Entries Table
CREATE TABLE feed_entries (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    feed_id UUID NOT NULL REFERENCES feeds(id) ON DELETE CASCADE,
    guid TEXT NOT NULL,
    url TEXT NOT NULL,
    title TEXT NOT NULL,
    author VARCHAR(255),
    content TEXT NOT NULL,          -- Cleaned full-text / readability content
    raw_content TEXT,              -- Original feed snippet
    published_at TIMESTAMPTZ NOT NULL,
    is_read BOOLEAN DEFAULT FALSE,
    is_starred BOOLEAN DEFAULT FALSE,
    share_uuid UUID UNIQUE,        -- Non-null if published to /share/<uuid>.html
    
    -- Dynamic Metadata & Extensibility (JSONB)
    -- Contains: { "aiSummary": "...", "score": 85, "tags": ["ai", "go"], "ttsUrl": "..." }
    metadata JSONB NOT NULL DEFAULT '{}'::jsonb,
    
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    CONSTRAINT unique_feed_guid UNIQUE(feed_id, guid)
);

-- Indexes for Fast Triage and FTS
CREATE INDEX idx_entries_feed_read ON feed_entries(feed_id, is_read);
CREATE INDEX idx_entries_published ON feed_entries(published_at DESC);
CREATE INDEX idx_entries_share_uuid ON feed_entries(share_uuid) WHERE share_uuid IS NOT NULL;
CREATE INDEX idx_entries_metadata_gin ON feed_entries USING GIN (metadata);

-- 5. Rules & Hooks Table
CREATE TABLE rules (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name VARCHAR(128) NOT NULL,
    rule_type VARCHAR(32) NOT NULL, -- 'single_feed' | 'multi_feed_digest'
    is_active BOOLEAN DEFAULT TRUE,
    trigger_type VARCHAR(32) NOT NULL, -- 'on_ingest' | 'schedule' | 'threshold'
    trigger_config JSONB NOT NULL DEFAULT '{}'::jsonb, -- { "cron": "0 8 * * *", "threshold": 15 }
    conditions JSONB NOT NULL DEFAULT '[]'::jsonb,     -- [{ "field": "category", "op": "eq", "value": "tech" }]
    actions JSONB NOT NULL DEFAULT '[]'::jsonb,        -- [{ "action": "ai_summarize" }, { "action": "generate_tts" }]
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

5.2 Deployment & Packaging Specification

Single Docker Container:
- Base Image: golang:1.23-alpine (builder) + alpine:latest (runtime).
- Web Assets: Built using vite build and embedded into the Go binary using //go:embed dist/*.
- Database Support: Built-in driver for PostgreSQL (via pgx) and SQLite3 with WAL mode enabled.
K3s / Kubernetes Manifests:
- Deployment: 1 replica, resource limits ~64MB RAM / 0.1 CPU idle.
- Service & Ingress: Traefik ingress exposing web routes and public /share/* routes.
- PersistentVolumeClaim (optional for SQLite storage or local audio cache).

6. Milestone Roadmap & Implementation Breakdown

gantt
    title RSSPipe Implementation Roadmap
    dateFormat  YYYY-MM-DD
    section M1: Core Foundation
    Go Server, DB & Single-User Auth      :m1_1, 2026-09-01, 7d
    Ingestion Engine & OPML Migration     :m1_2, after m1_1, 7d
    section M2: PWA & Reading UX
    React Vite PWA Setup & Theming        :m2_1, after m1_2, 5d
    Google Reader & Gmail Keyboards / UI  :m2_2, after m2_1, 7d
    Gmail Search Engine & Offline Cache   :m2_3, after m2_2, 5d
    section M3: Single-Feed Hooks
    Readability Full-Text Scraper         :m3_1, after m2_3, 4d
    LLM Summarization & Scoring Hooks     :m3_2, after m3_1, 5d
    Public Share /share/<uuid>.html       :m3_3, after m3_2, 4d
    Outbound Webhooks (Telegram/Discord)  :m3_4, after m3_3, 3d
    section M4: Multi-Feed Digest & Audio
    Multi-Feed Batch Aggregator           :m4_1, after m3_4, 6d
    Virtual Digest Feeds & Auto-Archive   :m4_2, after m4_1, 5d
    Edge-TTS & Audio Player Integration   :m4_3, after m4_2, 5d
    section M5: Ecosystem & Polishing
    Fever / Google Reader API Layer       :m5_1, after m4_3, 6d
    Rules UI Builder & DAG Validation     :m5_2, after m5_1, 5d
    K3s Deployment & E2E Validation       :m5_3, after m5_2, 4d

Milestone 1: Core Foundation & Ingestion Engine

Go backend server skeleton with Chi/Echo router and embedded static server.
Database layer supporting PostgreSQL and SQLite (WAL mode).
Single admin user authentication (Session Cookies, JWT, bcrypt/Argon2id).
Multi-format RSS/Atom/JSON parser with concurrent fetch worker pool.
OPML 2.0 import/export engine for seamless Miniflux migration.
Single Dockerfile packaging backend + frontend ready for k3s deployment.

Milestone 2: PWA Frontend & Google Reader / Gmail UX

React + Vite PWA boilerplate with Tailwind/Vanilla CSS design system, dark/light modes, and responsive layout.
Dual view modes: Google Reader continuous expanded stream + Gmail compact list/split-pane.
Full keyboard navigation workflow (j, k, o, v, s, m, e, Shift+A, /).
Service Worker and IndexedDB (Dexie.js) for local caching and offline reading.
Gmail-style tokenized search bar (is:unread, tag:xxx, score:>80, etc.).

Milestone 3: Single-Feed Hooks & Enrichment

Backend readability scraper to extract clean full-text markdown for truncated feeds.
Single-feed rules engine pipeline with trigger-condition-action execution.
OpenAI-compatible LLM connector for automated 3-bullet summary, key takeaways, and relevance scoring (0–100).
Public share generator creating standalone /share/<uuid>.html accessible without auth.
Outbound webhook dispatcher (Telegram, Discord, Slack, generic HTTP POST).

Milestone 4: Multi-Feed Digest Synthesis & Audio (TTS)

Multi-feed batch scheduler with cron and count-threshold triggers.
Multi-document LLM synthesis engine for creating structured daily/topic briefs.
Virtual Digest Feeds architecture (internal native feeds receiving synthesized articles).
Batch auto-archive / auto-mark read mechanism for processed source articles.
Audio generation engine (Edge-TTS and OpenAI TTS) with embedded audio player in PWA and public share pages.

Milestone 5: Ecosystem Compatibility & Final Polish

Fever API (/api/fever) and Google Reader API (/api/greader) implementation for native mobile app sync (NetNewsWire, Reeder).
Visual Rule Builder in Settings with DAG cycle validator (Topological Sort).
Telemetry & Reading Analytics (dwell time, reading progress).
Complete k3s deployment manifests (Deployment, Service, Ingress, PVC) and comprehensive documentation.

7. Success Metrics & Verification Criteria

Migration Fidelity: 100% of feeds and categories from Miniflux OPML imported cleanly without data loss.
Triaging Speed: Zero-lag keyboard navigation (j/k) with UI frame times strictly < 16\text{ms} (60 FPS).
Resource Efficiency: Single container idling at < 64\text{MB} RAM and < 1\% CPU on k3s cluster.
Hook Reliability: 100% of ingestion hooks executed asynchronously without blocking feed fetch workers; zero DAG execution cycles.
Ecosystem Compatibility: NetNewsWire / Reeder connect and synchronize unread/starred states without errors.

30 KiB Raw Blame History Unescape Escape