Personalized Newsletter App Overview

Complete architecture overview, repository links, high-level flow diagram, and prerequisites for the newsletter reference app.

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:

connect-sdk-examples/newsletter-app at main · humanity-developers/connect-sdk-examplesGitHub

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 for this tutorial.

2. Humanity Sandbox Access

1. Go to 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 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:

# 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