PRD for RSS Reader - Shayon Pal | Digital Product Consultant

# PRD for RSS Reader PWA > [!info] Current Version > This PRD reflects the current development-only architecture as of August 2025. > Production environment was removed per RR-92 to optimize for single-user setup. > > **Updated:** 2025-08-14 > **Status:** Active - Development Environment Only --- ## Product Overview ### Product Name **RSS News Reader** (formerly Shayon's News) ### Description A Progressive Web Application (PWA) for aggregating and summarizing news articles synchronized from the user's Inoreader account. The system emphasizes clean readability, AI-powered summarization, and efficient feed management. Designed for a single user on a local network, running in development mode only with direct access via Tailscale VPN. ### Access - **URL**: <http://100.96.166.53:3000/reader> - **Environment**: Development only (production removed per RR-92) - **Port**: 3000 (port 3147 no longer in use) - **Network**: Requires Tailscale VPN connection ## Goals & Key Features 1. **Feed Management**: - Bi-directional synchronization with Inoreader account - Feed management (add, rename, remove feeds) handled through Inoreader - Real-time sync server on port 3001 for immediate updates - PM2-managed cron job for scheduled synchronization 2. **Article Handling**: - Parse and store articles with readability-enhanced content - Content detection for partial vs. full articles - AI-powered summarization using Anthropic Claude API - Deduplication by URL matching - Retention limit of 1000 articles (configurable via ARTICLES_RETENTION_LIMIT) 3. **UI/UX**: - Responsive and accessible design - Dark/light mode support - Simple navigation using Lucide React icons - Human-readable date formats - PWA features for iOS/iPad installation 4. **Data Management**: - Supabase PostgreSQL database with RLS policies - Automatic pruning during sync operations - OAuth tokens stored locally at ~/.rss-reader/tokens.json 5. **Filtering**: - Filter articles by read/unread status - Filter articles by feed source - Search and sort capabilities ## Target Environment - Runs on Mac Mini (M2), accessed via Tailscale network - Single user, OAuth authentication with Inoreader - Development server only - no production deployment - PM2 process management for all services - Supabase cloud database (PostgreSQL) ## Architecture Changes (2025) ### Production Environment Removal (RR-92) **Decision Date**: July 31, 2025 **Implementation**: August 1, 2025 **Before**: - Dual environment (Dev on 3000, Prod on 3147) - Caddy reverse proxy - Memory usage at 87.5% - Frequent service instability **After**: - Single development environment at port 3000 - Direct Next.js access (no proxy) - Memory usage reduced to ~71% - Stable operation with PM2 ### Auto-Fetch Feature Removal (RR-162) **Removed**: Automatic article fetching functionality **Reason**: Sync issues at 92% completion **Current**: Manual and scheduled sync only via bi-directional sync server ## Tech Stack ### Frontend - Next.js 14 (React 18) - TailwindCSS with typography plugins - Lucide React for icons - Framer Motion for animations - React Markdown for content rendering - Next-themes for dark/light mode ### Backend - Next.js API Routes (development mode) - Node.js runtime - Inoreader API integration - Mozilla Readability for content extraction - PM2 for process management - TypeScript for type safety ### Database - Supabase (PostgreSQL) - Row Level Security (RLS) policies - Real-time subscriptions capability ### AI Integration - Anthropic Claude API for summarization - Model: claude-3-haiku-20240307 - Configurable summary length and style ### Infrastructure - PM2 ecosystem for service management - Uptime Kuma for external monitoring - Development-only deployment - No Docker/containerization needed ## Service Architecture ### PM2 Managed Services | Service | Port | Purpose | Status | |---------|------|---------|---------| | rss-reader-dev | 3000 | Main Next.js application | Active | | rss-sync-server | 3001 | Bi-directional sync | Active | | rss-sync-cron | - | Scheduled sync job | Active | ### Removed Services - ❌ rss-reader-prod (port 3147) - Removed per RR-92 - ❌ Caddy reverse proxy - Removed per RR-104 - ❌ Auto-fetch service - Removed per RR-162 ## API Endpoints All endpoints use `/reader` base path: - `/reader/api/health/app` - Application health - `/reader/api/health/db` - Database connectivity - `/reader/api/sync` - Manual sync trigger - `/reader/api/oauth/authorize` - OAuth flow - `/reader/api/oauth/callback` - OAuth callback ## Error Handling - Comprehensive logging via PM2 - Service auto-restart on failure - User-friendly error notifications - Sync retry with exponential backoff ## Testing Strategy - Unit tests for components and utilities - Integration tests for API routes - End-to-end tests with Playwright - Test credentials stored in .env ## Monitoring - Uptime Kuma on port 3080 (Docker) - PM2 status dashboard - Health endpoint monitoring - Sync status tracking ## User Stories [Original 50 user stories remain valid with these updates:] - All references to port 3147 now use port 3000 - All "production" references now specify "development" - Perplexity API replaced with Anthropic Claude API - MongoDB references updated to Supabase/PostgreSQL - Feed limit increased from 500 to 1000 articles ## Maintenance Notes ### Daily Operations - PM2 services run continuously - Automatic sync via cron job - Log rotation handled automatically ### Access Requirements - Tailscale VPN must be connected - Direct browser access to port 3000 - OAuth tokens must be valid ### Known Limitations - Single environment only (development) - Single user design - Requires constant Mac Mini uptime - No external/public access ## References - [Current Documentation](/Users/shayon/DevProjects/rss-news-reader/docs/) - [Linear Project](https://linear.app/agilecode-studio/project/rss-reader) - [Production Removal Documentation](docs/infrastructure/production-removal-2025-08.md)