# Personalized Newsletter App Overview

## **What You Will Build**

By the end of this walkthrough, you will have a fully functional personalized newsletter application that:

* ✅ **Authenticates users** via Humanity OAuth 2.0 with PKCE
* ✅ **Detects social connections** (LinkedIn, Twitter/X, Discord, GitHub, Telegram)
* ✅ **Verifies credentials** using preset verification (connected accounts, travel preferences)
* ✅ **Personalizes content** based on user's digital identity
* ✅ **Fetches and categorizes news** from external APIs
* ✅ **Provides real-time dev console** showing API calls and responses
* ✅ **Stores user preferences** and news articles in MongoDB
* ✅ **Runs automated sync jobs** for content updates

## **Repository**

The complete source code for this demo is available at:

{% embed url="<https://github.com/humanity-developers/connect-sdk-examples/tree/main/newsletter-app>" %}

## **High-Level Architecture**

```
┌──────────────────────────────────────────────────────────────────┐
│                         Your Next.js App                         │
│                                                                  │
│  ┌─────────────────┐                                             │
│  │  Login Page     │  User clicks "Sign in with Humanity"        │
│  │  (Frontend)     │                                             │
│  └────────┬────────┘                                             │
│           │                                                      │
│           ▼                                                      │
│  ┌─────────────────┐         ┌──────────────────────┐            │
│  │  /api/auth/     │───────▶│  Humanity            │            │
│  │  login          │         │  SDK                 │            │
│  │                 │◀───────│  (OAuth + Presets)   │            │
│  └─────────────────┘         └──────────────────────┘            │
│           │                                                      │
│           ▼                                                      │
│  ┌─────────────────┐         User authorizes                     │
│  │  /callback      │         on Humanity                         │
│  │  (OAuth return) │                                             │
│  └────────┬────────┘                                             │
│           │                                                      │
│           ▼                                                      │
│  ┌─────────────────────────────────────────┐                     │
│  │  Extract User Data:                     │                     │
│  │  • Profile (email, wallet)              │                     │
│  │  • Social connections (LinkedIn, etc.)  │                     │
│  │  • Travel preferences (Query Engine)    │                     │
│  └────────┬────────────────────────────────┘                     │
│           │                                                      │
│           ▼                                                      │
│  ┌─────────────────┐         ┌──────────────┐                    │
│  │   Save User     │────────▶│   MongoDB   │                    │
│  │   + Signals     │         │              │                    │
│  └─────────────────┘         │  • Users     │                    │
│           │                  │  • News      │                    │
│           │                  │  • API Logs  │                    │
│           │                  └──────────────┘                    │
│           ▼                                                      │
│  ┌─────────────────┐         ┌──────────────┐                    │
│  │  Fetch News     │────────▶│  GNews API  │                    │
│  │  (Cron Job)     │◀────────│             │                    │
│  └─────────────────┘         └──────────────┘                    │
│           │                                                      │
│           ▼                                                      │
│  ┌─────────────────────────────────────────┐                     │
│  │  Personalize Feed:                      │                     │
│  │  • Match articles to user signals       │                     │
│  │  • LinkedIn → Professional content      │                     │
│  │  • Twitter → Social/trending            │                     │
│  │  • Discord → Community                  │                     │
│  │  • GitHub → Tech                        │                     │
│  └────────┬────────────────────────────────┘                     │
│           │                                                      │
│           ▼                                                      │
│  ┌─────────────────┐                                             │
│  │  Feed Page      │  Display personalized articles              │
│  │  + Dev Console  │  Show API logs                              │
│  └─────────────────┘                                             │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘

```

## **What You Need Before Starting**

### **1. Development Environment**

* **Node.js**: v22.14.0 or later
* **Package Manager**: npm, yarn, or bun
* **MongoDB**: Docker (recommended) or local installation
* **Git**: For cloning the repository

> ⚠️ **Note for Windows Users**
>
> We strongly recommend using [WSL 2](https://learn.microsoft.com/en-us/windows/wsl/about) for this tutorial.

### **2. Humanity Sandbox Access**

1. Go to [https://developers.humanity.org](https://developers.humanity.org/)
2. Sign in or create an account
3. Click **"Create Application"**
4. Give your app a name (e.g., "Newsletter Demo")
5. Save and copy your sandbox credentials
   * **Client ID** (starts with `app_`)
   * **Client Secret** (starts with `sk_`)
6. Set your **Redirect URI** to: `http://localhost:3100/callback`
7. Select [the scopes](https://docs.humanity.org/build-with-humanity-protocol/build-with-the-sdk-api/sdk-oauth-scopes-and-presets) your application will request
8. Note: This guide uses **Connect SDK v0.1.0** or later

### **3. External API Keys**

**GNews API** (for news content):

* Sign up at <https://gnews.io>
* Get your free API key (100 requests/day)
* Note: GNews is mandatory for this demo to function

### **4. MongoDB Setup**

Install MongoDB locally following the instructions for your OS: <https://www.mongodb.com/docs/manual/installation/>

**Alternative: Use Docker**

If you prefer Docker or encounter system-level compatibility issues:

```bash
# Start MongoDB container
docker run -d -p 27017:27017 --name mongodb mongo:latest

# Verify it's running
docker ps

# Stop MongoDB when needed
docker stop mongodb

# Start MongoDB again
docker start mongodb
```

Your connection string will be: `mongodb://localhost:27017`


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.humanity.org/developer-guides-and-tutorials/sdk-api-guides/personalized-newsletter-app-reference-implementation/personalized-newsletter-app-overview.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.