Morning Digest

Everything You Need to Know Today. Synthesized by AI in Seconds.

Real-time RSS news aggregation, executive summaries, glassmorphic web dashboard, and automated HTML email dispatches.

Live App · Next.js 15 + React 19 + Python · Deployed on Vercel

---

🌟 What it Does

Morning Digest is your intelligent morning news assistant. It automatically aggregates raw news from 40+ top-tier global and local media outlets, filters for stories published in the last 24 hours, and transforms overwhelming news feeds into clean, digestible executive briefings.

• 📚 AI Executive Summaries — Crisp bullet points breaking down what happened and why it matters without clickbait.
• 🌐 40+ Trusted News Outlets — Aggregates feeds from Reuters, Associated Press, BBC, Bloomberg, TechCrunch, The Verge, Dawn, Financial Times, ESPN, and more.
• 🏷️ 7 Curated Categories — Top Trending News, Tech & AI, Pakistan News, Global News, Markets & Economy, Sports, and Movies & Entertainment.
• 🖼️ Smart Open Graph Scraping — Extracts high-resolution publisher thumbnails (og:image, twitter:image) using Cheerio and BeautifulSoup with category fallback imagery.
• ✉️ Automated HTML Email Briefing — A dedicated Python dispatcher synthesizes daily news into responsive HTML emails delivered straight to your inbox via Gmail SMTP.
• 🌓 Glassmorphic Interactive Dashboard — Light & Dark theme toggle, category tab navigation, expandable bullet details, markdown export, and real-time refresh capability.
• ⚡ High-Performance Caching — Intelligent in-memory caching for API responses to ensure sub-second response times for repeat visits.

---

🏗️ Architecture

System Architecture Diagram

---

🛠️ Tech Stack

Layer	Tech
Frontend UI	Next.js 15 (App Router), React 19, TypeScript, Lucide React, Custom Glassmorphic CSS Engine
Backend API	Next.js Serverless API (/api/digest), Node.js 20+, rss-parser, cheerio
Python Service	Python 3.11+, feedparser, beautifulsoup4, python-dotenv, smtplib
AI Synthesis	Google GenAI SDK (@google/genai & google-genai), Gemini 2.5 Flash / Gemini 3.6 Flash
Automation	GitHub Actions (daily-digest.yml workflow), Gmail SMTP API
Deployment	Vercel (Web Application), GitHub Actions (Cron/Dispatch Email Engine)

---

⚡ Engineering Problems Solved

Problem	Root Cause	Fix
Vercel Serverless Function Timeout	Processing 40+ RSS feeds and AI synthesis exceeded default 10s serverless timeout limits.	Configured export const maxDuration = 60 and implemented concurrent Promise.allSettled feed requests with strict article caps (MAX_ARTICLES_PER_FEED = 20).
Hanging / Dead RSS Endpoints	Unresponsive third-party RSS servers blocked network sockets indefinitely.	Implemented global socket timeouts (socket.setdefaulttimeout(5) in Python) and custom AbortController signal timeouts in Node.js.
Missing Article Thumbnails	Standard RSS feeds often omit direct image tags (<enclosure>) or supply tiny low-res icons.	Built an automated Open Graph scraper using cheerio / bs4 to parse og:image and twitter:image meta tags directly from story URLs.
Gemini Output JSON Formatting Errors	AI model occasionally added markdown code fences (```json) or conversational text around JSON output.	Strict system prompt instruction specifying explicit JSON structure, coupled with regex-based JSON extraction fallback before parsing.
Stale / Duplicate News Overlap	High-volume publishers repeatedly issue minor updates for the same breaking story under different links.	Enforced strict 24-hour timestamp filtering (HOURS_FRESH = 24) and headline string normalization deduplication.

---

🚀 Run It Locally

Prerequisites

• Node.js: v20 or higher
• Python: v3.11 or higher (for email dispatcher script)
• Google Gemini API Key: Get one for free from Google AI Studio

---

1. Web Application (frontend)

# Clone the repository
git clone https://github.com/musama-dev/Morning-Digest.git
cd "Morning Dijest/frontend"

# Install Node dependencies
npm install

# Create environment file
# Add your GEMINI_API_KEY to frontend/.env.local

# Start development server
npm run dev

Open http://localhost:3000 in your browser to view the interactive web dashboard.

---

2. Python Automated Email Briefing (backend)

cd "Morning Dijest/backend"

# Set up Python virtual environment (optional but recommended)
python -m venv venv
# On Windows:
venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate

# Install Python requirements
pip install -r requirements.txt

# Run the digest generator
python digest.py

---

⚙️ Environment Variables

Web App (frontend/.env.local)

Variable	Required	Description
GEMINI_API_KEY	Yes	Your Google Gemini AI Studio API key.

Python Automation (backend/.env)

Variable	Required	Description
GEMINI_API_KEY	Yes	Your Google Gemini AI Studio API key.
GMAIL_ADDRESS	Optional	Your sender Gmail address for email briefings.
GMAIL_APP_PASSWORD	Optional	Gmail App Password generated from Google Account Security.
RECIPIENT_EMAIL	Optional	Recipient email address(es) to receive daily news digests.

---

📡 API Overview

Method & Endpoint	Parameters	Purpose
GET /api/digest	None	Returns cached or fresh multi-category daily digest JSON.
GET /api/digest?refresh=true	refresh=true	Bypasses in-memory cache and forces live re-fetch & AI synthesis.

---

🌐 Deployment Notes

• Vercel (Web Dashboard): Connect your GitHub repository to Vercel. Set Root Directory to frontend and add GEMINI_API_KEY under Environment Variables.
• GitHub Actions (Scheduled Briefings): Workflow file located at .github/workflows/daily-digest.yml. Configure repository secrets (GEMINI_API_KEY, GMAIL_ADDRESS, GMAIL_APP_PASSWORD, RECIPIENT_EMAIL) to enable automated email dispatches.

---

🗺️ Roadmap

• Custom RSS Feed Subscriptions — Allow users to add custom RSS feed URLs per category.
• Voice / Audio Digest (Text-to-Speech) — Generate 3-minute morning audio podcasts using ElevenLabs or Google TTS.
• WhatsApp & Telegram Bots — Push instant bullet briefings to messaging apps.
• Personalized Filtering — Filter stories based on user-defined keyword interests and muted topics.

---

Built with Passion ❤️ by Muhammad Usama