Architecture Overview

This is a newsletter aggregator built for Val Town with the following key components:

Core Structure

  • feeds.json: Master configuration file containing feed definitions as [normalizedKey, [categories], feedUrl, optionalDomain?]
  • feed.cron.ts: Cron job that runs every 6 hours to fetch and cache RSS feeds via RSSService.buildAndStore()
  • services/rss.ts: Core RSS processing service that fetches, parses, and stores feed data
  • http.ts: Main HTTP handler for serving the web interface

Frontend (React/TSX)

  • frontend/app.tsx: Main React application component
  • frontend/components/: Reusable UI components for filtering and display
  • frontend/hooks/: Custom React hooks for data fetching and state management
  • frontend/utils/: Utility functions for date formatting and data processing

Data Flow

  1. Cron job (feed.cron.ts) calls RSSService.buildAndStore() every 6 hours
  2. RSS service fetches feeds from URLs in feeds.json and stores processed data in Val Town blob storage
  3. Frontend fetches cached data via useAppData hook and displays with filtering capabilities

Working with this project

  • The main entry points are feed.cron.ts (cron job) and http.ts (web handler)
  • Feed configuration is managed in feeds.json with the format: [normalizedKey, [categories], feedUrl, optionalDomain?]

frontend/components/**

  • FilterContainer.tsx: Manages category and feed-based filtering UI
  • TimeFilter.tsx: Handles time period selection (24h, 48h, 7d, etc.)
  • ListingFilter.tsx: Controls feed-specific filtering
  • CategoryFilter.tsx: Category-based filtering interface
  • FeedsFilter.tsx: Individual feed selection controls
  • Footer.tsx: Application footer component

frontend/hooks/**

  • useAppData.ts: Manages RSS data fetching and state
  • useFeedsConfig.ts: Handles feed configuration loading
  • useTimePeriodFilter.ts: Time-based filtering logic
  • useDateFormatting.ts: Date display utilities