“Building Civic Infrastructure with Serverless APIs and Region-Aware Routing” Ideal for remixers, journalists, and technologists exploring public-facing deployments.

📡 hashtag-rotator-service

Modular serverless microservice for rotating region-aware hashtags, logging GitHub events, and powering public dashboards. Ideal for civic technologists, journalists, and remixers.

🛠️ API Endpoints • 🔐 Cron Scheduling • 🌍 Geo Routing • 📡 Webhook Logging • 🧪 Diagnostics • 🧩 Remixable Infrastructure

🧠 About This Project

This project fetches real-time trending hashtags from Trends24 and serves them via region-specific API endpoints. It includes scheduled cron tasks, GitHub webhook logging, and geo-aware routing — all deployed seamlessly on Vercel.

• 🏛️ Civic dashboards
• 📰 Media headline rotators
• 🧩 Remixable region-aware tools

🛠️ Features

Capability	Details
💬 API Endpoints	/api/trends, /api/cron, /api/github-webhook, /api/diagnostics, /api/index, /api/hashtag-rotator-service
⏰ Cron Scheduling	Vercel triggers /api/cron daily at 10:00 UTC (1PM Nairobi)
📡 GitHub Webhook	Verifies HMAC signature and logs events to /api/diagnostics
🌍 Geo Routing	Kenya visitors rerouted to /kenya-trends using IP headers
🧪 Diagnostics API	/api/diagnostics returns delivery logs, verification status, and timestamps
🛡️ Crash Protection	All handlers use try/catch blocks for resilience
🔍 Testing Script	test.sh validates endpoint response and logs headers

🚀 Quick Start Guide

git clone https://github.com/pmmutiti/hashtag-rotator-service.git
cd hashtag-rotator-service

This project includes a preconfigured vercel.json file for instant deployment.

🧾 Deployment Config

This file defines build targets, scheduled tasks, and geo-aware rewrites for Vercel deployment. It ensures modular routing, public observability, and remixable behavior across all endpoints.

🔧 Build Targets

"builds": [
  { "src": "api/cron.js", "use": "@vercel/node" },
  { "src": "api/trends.js", "use": "@vercel/node" },
  { "src": "api/github-webhook.js", "use": "@vercel/node" },
  { "src": "api/diagnostics.js", "use": "@vercel/node" },
  { "src": "api/index.js", "use": "@vercel/node" },
  { "src": "api/hashtag-rotator-service.js", "use": "@vercel/node" }
]

⏰ Cron Job

"crons": [
  {
    "path": "/api/cron",
    "schedule": "0 10 * * *"
  }
]

🌍 Geo-Aware Rewrites

"rewrites": [
  {
    "source": "/kenya-trends",
    "has": [
      {
        "type": "header",
        "key": "x-vercel-ip-country",
        "value": "KE"
      }
    ],
    "destination": "/api/trends?region=kenya"
  },
  {
    "source": "/kenya-trends",
    "destination": "/api/trends?region=global"
  },
  {
    "source": "/trends/:region",
    "destination": "/api/trends?region=:region"
  }
]

📁 File Structure

hashtag-rotator-service/
├── api/
│   ├── cron.js
│   ├── trends.js
│   ├── github-webhook.js
│   ├── diagnostics.js
│   ├── index.js
│   └── hashtag-rotator-service.js
├── test.sh
├── README.md
├── civic-preview.html
├── vercel.json

🧪 Validation Tools

Use test.sh to manually confirm that endpoints like /api/webhook respond correctly.

If payload snapshots are growing under diagnostics/webhook-payloads, your webhook is live.

🧩 Remix Notes

“Civic infrastructure should be transparent and traceable.”

This repo is designed for

Author: Peter M. Mutiti | Investigative Journalist & Civic Technologist

MIT License © 2025 Peter M. Mutiti · View License