5. Smart Tag Generation 🏷️

Intelligent categorization with contextual tags for improved discoverability and navigation.

6. Geographic Entity Recognition 🌍

Location extraction and mapping for geographical context awareness.

7. Social Media Captions 📱

AI-generated platform-specific captions optimized for Twitter, LinkedIn, and Facebook engagement.

8. Interactive Q&A System ❓

Intelligent question generation for deeper engagement and context-aware question answering using article content.

9. News Insights Analysis 🔍

Advanced contextual analysis, including stakeholder impact, timeline connections, and theme identification.

10. Multi-language Translation 🌐

Google Translate integration supporting 100+ languages for global accessibility.

11. Content Classification 🗂️

Non-news content detection with an intelligent strike system for quality control.

📰 Multi-Source Aggregation

• 70+ News Sources: NewsAPI.org, The Guardian, NY Times, 130+ RSS feeds
• Multi-Language Support: English, Bengali, Hindi content + 26 AI languages
• Smart Deduplication: URL-based article deduplication
• Real-Time Processing: Background AI enhancement pipeline

🎯 Personalization Engine

• Reading History Tracking: Engagement analytics
• Custom Feeds: User-defined categories and sources
• Bookmark Management: Save and organize articles

🔒 Enterprise-Grade Security

• 3 Authentication Methods: Email/Password, Google OAuth 2.0, Magic Links
• JWT Token Management: Access + Refresh token rotation
• Strike System: Abuse prevention with auto-recovery
• Rate Limiting: Endpoint-specific quotas
• API Quota Management: Per-user usage tracking

📊 Analytics & Monitoring

• 21 Health Checks: Database, AI services, external APIs
• Source Performance: Quality scoring and tracking
• User Engagement Metrics: Reading patterns and preferences
• Real-Time Monitoring: System health dashboard

🏗️ Architecture

┌─────────────────────────────────────────────────────┐
│              CLIENT APPLICATIONS                     │
│        (Web, Mobile, Desktop, etc.)                  │
└───────────────────┬─────────────────────────────────┘
                    │ HTTP/REST
                    ▼
┌─────────────────────────────────────────────────────┐
│           EXPRESS API SERVER (PORT 4000)             │
├─────────────────────────────────────────────────────┤
│  • CORS & Security Middleware                        │
│  • JWT Authentication                                │
│  • Rate Limiting                                     │
│  • Request Logging                                   │
└───────────┬────────────┬────────────┬───────────────┘
            │            │            │
      ┌─────▼────┐ ┌────▼────┐ ┌────▼─────┐
      │   News   │ │   AI    │ │   Auth   │
      │ Services │ │Services │ │ Services │
      └─────┬────┘ └────┬────┘ └────┬─────┘
            │           │           │
      ┌─────▼───────────▼───────────▼─────┐
      │         EXTERNAL SERVICES          │
      │  • NewsAPI, Guardian, NYTimes      │
      │  • 130+ RSS Feeds                  │
      │  • Google Gemini AI (3 models)     │
      │  • Google Translate API            │
      └────────────────┬───────────────────┘
                       │
                 ┌─────▼─────┐
                 │  MongoDB  │
                 │ Database  │
                 └───────────┘

🚀 Quick Start

Prerequisites

• Node.js 18+
• MongoDB 8.16.5+
• npm (comes with Node.js)

Installation

1. Clone the repository

git clone https://github.com/chayan-1906/PulsePress-Node.js.git
cd PulsePress-Node.js

2. Install dependencies

npm install

3. Configure environment variables

cp .env.example .env

Edit .env with your credentials (see Environment Variables)

4. Start the server

# Development mode with hot reload
npm run dev

# Production mode
npm run build
npm start

Server runs at http://localhost:4000

🔧 Environment Variables

Create a .env file in the root directory with the following variables:

Core Configuration

# Server
PORT=4000
NODE_ENV=development

# Database
MONGO_URI=mongodb://localhost:27017/pulsepress
# Or MongoDB Atlas: mongodb+srv://<username>:<password>@cluster.mongodb.net/pulsepress

Authentication

# JWT Secrets (generate with: openssl rand -base64 32)
JWT_SECRET=your_jwt_secret_here
JWT_REFRESH_SECRET=your_refresh_secret_here
JWT_EXPIRES_IN=15m
JWT_REFRESH_EXPIRES_IN=7d

# Google OAuth 2.0
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
GOOGLE_REDIRECT_URI=http://localhost:4000/api/v1/auth/google/callback

News API Keys

# NewsAPI.org (https://newsapi.org)
NEWS_API_KEY=your_newsapi_key

# The Guardian (https://open-platform.theguardian.com)
THE_GUARDIAN_API_KEY=your_guardian_key

# NY Times (https://developer.nytimes.com)
NY_TIMES_API_KEY=your_nytimes_key

AI Services

# Google Gemini AI (https://ai.google.dev)
GEMINI_API_KEY=your_gemini_api_key

# Google Cloud Translate (https://cloud.google.com/translate)
GOOGLE_TRANSLATE_API_KEY=your_translate_key

# HuggingFace (Optional - https://huggingface.co)
HUGGINGFACE_API_KEY=your_huggingface_key

Email (Magic Links)

# SMTP Configuration (e.g., Gmail)
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USER=your_email@gmail.com
EMAIL_PASSWORD=your_app_password
EMAIL_FROM=noreply@pulsepress.com

Rate Limiting (Optional - Defaults Provided)

# AI Features
AI_WINDOW_MS=300000        # 5 minutes
AI_MAX_REQUESTS=30

# News Scraping
NEWS_SCRAPING_WINDOW_MS=900000  # 15 minutes
NEWS_SCRAPING_MAX_REQUESTS=50

Note: See .env.example for complete configuration options

📚 API Documentation

Complete API documentation with all 75 endpoints is available in API_DOCUMENTATION.md

Quick API Overview

Example: Fetch Enhanced News

Request:

GET /api/v1/news/multisource/enhanced?q=technology&pageSize=10
Authorization: Bearer <your_jwt_token>

Response:

{
  "success": true,
  "message": "Articles fetched and enhancement started",
  "data": {
    "articles": [
      {
        "articleId": "abc123...",
        "title": "AI Breakthrough in Healthcare",
        "url": "https://...",
        "source": "TechCrunch",
        "publishedAt": "2025-01-20T10:30:00Z",
        "enhancements": {
          "processingStatus": "completed",
          "summary": "...",
          "sentiment": {
            "type": "positive",
            "confidence": 0.89,
            "emoji": "😊"
          },
          "tags": ["AI", "Healthcare", "Innovation"],
          "readingTime": "5 minutes"
        }
      }
    ],
    "totalResults": 150,
    "page": 1,
    "pageSize": 10
  }
}

🗂️ Project Structure

pulsepress/
├── src/
│   ├── server.ts                  # Application entry point
│   ├── config/                    # Configuration files
│   │   ├── config.ts              # Environment variables
│   │   └── connectDB.ts           # MongoDB connection
│   ├── controllers/               # Request handlers (10 controllers)
│   │   ├── NewsController.ts
│   │   ├── AIController.ts
│   │   ├── AuthController.ts
│   │   └── ...
│   ├── services/                  # Business logic (25 services)
│   │   ├── NewsService.ts
│   │   ├── ArticleEnhancementService.ts
│   │   ├── ContentRecommendationService.ts
│   │   └── ...
│   ├── models/                    # MongoDB schemas (10 models)
│   │   ├── UserSchema.ts
│   │   ├── ArticleEnhancementSchema.ts
│   │   ├── BookmarkSchema.ts
│   │   └── ...
│   ├── routes/                    # API routes
│   ├── middlewares/               # Auth, rate limiting
│   ├── types/                     # TypeScript interfaces
│   └── utils/                     # Helper functions
├── .env.example                   # Environment template
├── package.json                   # Dependencies
├── tsconfig.json                  # TypeScript config
└── README.md                      # This file

🛠️ Tech Stack

Backend

• Runtime: Node.js 18+
• Framework: Express 5.1.0
• Language: TypeScript 5.8.3
• Database: MongoDB 8.16.5 (Mongoose ODM)

AI

• Google Gemini AI: 2.5 Flash Preview, 2.0 Flash, 1.5 Flash
• Google Translate API: Multi-language support
• HuggingFace Inference: Backup AI models
• Fuse.js: Fuzzy search

News Sources

• NewsAPI.org: Global news headlines
• The Guardian: Premium journalism
• NY Times: Quality news archives
• RSS Feeds: 130+ real-time feeds (English, Bengali, Hindi)

Security & Auth

• JWT: Token-based authentication
• bcryptjs: Password hashing
• Google OAuth 2.0: Social login
• express-rate-limit: API protection

Utilities

• Axios: HTTP client
• Cheerio: HTML parsing
• JSDOM + Readability: Article extraction
• node-cron: Scheduled tasks
• Nodemailer: Email service

📦 NPM Scripts

# Development