Contextual News API

This is a backend service built with Go that provides a contextual and personalized news feed. It leverages a MongoDB database for storing and querying news articles and integrates with an LLM service (OpenRouter) to understand natural language search queries and provide AI-generated summaries.

Features

• RESTful API: A clean and simple API for fetching news.
• Multiple Querying Options:
  • Fetch the latest, trending, or nearby news articles.
  • Filter news by category, relevance score, or source.
  • Geospatial search to find news near a specific location.
• AI-Powered Search & Summaries: Utilizes an external LLM (OpenRouter) for advanced capabilities:
  • Natural Language Search: When a user searches with a query phrase, the LLM first processes it to extract key entities and intent. This allows for more intelligent and contextual database searches beyond simple keyword matching.
  • Article Summarization: Each article can be enriched with a concise summary generated by the LLM.
• User Event Simulation: An endpoint to simulate user interactions (like views, clicks) for future personalization features.
• Configuration Driven: Easy to configure through a .env file.
• Structured Logging: For better observability and debugging.
• Data Seeding: A script is provided to easily seed the database with initial news data from a JSON file.

Tech Stack

• Language: Go
• Web Framework: Gin-Gonic
• Database: MongoDB
• AI Service: OpenRouter API
• Configuration: godotenv
• Logging: slog (standard library)

Getting Started

Prerequisites

• Go (version 1.21 or later)
• A MongoDB instance (local or cloud-based like MongoDB Atlas)
• An API token from OpenRouter

Installation & Setup

1. Clone the repository:

   git clone <your-repository-url>
   cd contextual-news-api

2. Configure Environment Variables: Create a .env file in the root of the project by copying the contents from the provided .env file. Update the values for your environment.

   # MongoDB Configuration
   MONGO_CONNECTION_STRING='your_mongodb_connection_string'
   MONGO_DATABASE='contextual_news_api'
   
   # Server Configuration
   SERVER_ADDRESS='localhost'
   SERVER_PORT=8080
   
   # LLM Configuration
   LLM_TOKEN='your_openrouter_api_key'
   LLM_ENDPOINT='https://openrouter.ai/api/v1'
   LLM_MODEL='google/gemini-2.0-flash-exp:free'

3. Install Dependencies:

   go mod tidy

4. Seed the Database: Run the script to upload the news data from data/news_data.json to your MongoDB collection.

   cd scripts/
   go run upload_json.go

5. Run the Application:

   cd cmd/newsApp/
   go run main.go

   The server will start on the address and port specified in your .env file (e.g., http://localhost:8080).

API Endpoints

All endpoints are prefixed with /api/v1.

Method	Endpoint	Query Parameters	Description
GET	/news/latest	articleLimit=<int>	Fetches the most recent news articles.
GET	/news/category	category=<string>&articleLimit=<int>	Fetches news articles for a specific category.
GET	/news/source	source=<string>&articleLimit=<int>	Fetches news articles from a specific source.
GET	/news/score	score=<float>&articleLimit=<int>	Fetches articles with a relevance score greater than the specified value.
GET	/news/search	query=<string>&articleLimit=<int>	Performs an LLM-enhanced search. The query is interpreted to find entities and intent for a more contextual search.
GET	/news/nearby	lat=<float>&lon=<float>&radius=<int>&articleLimit=<int>	Finds news articles within a given radius (in meters) of a location.
GET	/news/trending	lat=<float>&lon=<float>&radius=<int>&articleLimit=<int>	Fetches trending news, optionally filtered by location.
POST	/news/events/simulate	(JSON Body)	Simulates a user event (e.g., view, click).

Example POST /news/events/simulate Body:

{
    "article_id": "19aaddc0-7508-4659-9c32-2216107f8604",
    "event_type": "view", // view or click
    "latitude": 8.8,
    "longitude": 10.5
}

Project Structure

.
├── cmd/                # Main application entry points
├── data/               # Sample data files (e.g., news_data.json)
├── docs/               # Documentation (e.g., Postman collection)
├── internal/           # Private application logic
│   ├── dbInterface/    # Database interaction layer
│   ├── handlers/       # API route handlers (controllers)
│   ├── models/         # Data structures and models
│   ├── server/         # Server setup and initialization
│   └── services/       # Business logic
├── pkg/                # Shared packages
│   ├── constants/      # Application constants
│   ├── logger/         # Logging setup
│   ├── startup/        # Startup helpers (config, db connection)
│   └── utils/          # Utility functions
├── scripts/            # Helper scripts (e.g., data upload)
└── .env                #