💻 Hashtag Rotator Service ReadMe

🌍 Hashtag Rotator Service

A public-facing, region-aware microservice that fetches live trending hashtags from verified sources and rotates them in civic dashboards. Built for transparency, diagnostics, and real-time civic engagement.

🚀 Live Deployment

Production URL

🧱 Modules Deployed

Module	Status	Timestamp	Commit ID
.gitignore	✅ Deployed	2 hours ago	84284d29
fallbackHashtags.js	✅ Deployed	14 hours ago	31b106dc
constants.js	✅ Deployed	14 hours ago	3b46b570
diagnostics.js	✅ Deployed	15 hours ago	92e809ed
rotator.js (Kenya)	✅ Deployed	15 hours ago	209e1983
script.js	✅ Deployed	17 hours ago	517b6d79
index.html	✅ Deployed	18 hours ago	38b7174f
server.js	✅ Deployed	18 hours ago	f3fd893e
scrape-trends24.js	✅ Deployed	18 hours ago	01cff475
webhook-diagnostics.js	✅ Deployed	19 hours ago	39e15623
webhook-listener.js	✅ Deployed	19 hours ago	3423140f
cron.js	✅ Deployed	20 hours ago	2eae4d5a
trends24-cache.js	✅ Deployed	20 hours ago	4f78c1f3

📡 Features

• ✅ Live hashtag scraping from Trends24 and CyberKendra
• 🌐 Region toggles: Kenya, Nigeria, USA, UK, India
• 🧪 Diagnostics panel with fallback detection
• 🐦 Tweet CTA generator with civic messaging
• 📊 Rotator module with refresh intervals
• 🔁 Webhook listeners for real-time updates
• 🧾 Audit-ready fallback logic and timestamping

🧠 How It Works

// Fetch hashtags from live endpoint
const res = await fetch('/api/rotator?region=kenya');
const data = await res.json();
const hashtags = data.hashtags || [];

<a href="https://twitter.com/intent/tweet?text=#JusticeforJuliaNjoki%20%23OccupyCBDTuesday%20%23AuditReady" target="_blank">
  Tweet This Civic Signal 📢
</a>

🛠️ Setup

1. Clone the repo:
   git clone https://github.com/pmmutiti/hashtag-rotator-service.git
2. Install dependencies:
   npm install
3. Set environment variables:
   cp .env.example .env
4. Run locally:
   npm run dev

🧪 Diagnostics Endpoint

GET /api/diagnostics

{
  "status": "🧪 Diagnostics OK",
  "fallbackEnabled": false,
  "timestamp": "2025-08-25T11:58:00Z",
  "regionsSupported": ["kenya", "nigeria", "usa", "uk", "india"]
}

📁 File Structure

├── api/
│   ├── rotator.js
│   ├── diagnostics.js
│   ├── scrape-trends24.js
│   ├── webhook-listener.js
│   └── cron.js
├── public/
│   └── index.html
├── utils/
│   ├── constants.js
│   ├── fallbackHashtags.js
│   └── trends24-cache.js
├── .vercelignore
├── .gitignore
├── vercel.json
└── README.md

📢 Civic Hashtags Used

Hashtag	Context
#JusticeforJuliaNjoki	Civic protest signal from Kenya
#ShootFirstSir	Police accountability
#WeAreAllKikuyus	Anti-tribalism solidarity
#OccupyCBDTuesday	Urban protest movement
#DigitalKenya	Civic tech and transparency
#CivicInfra	Infrastructure for public oversight
#AuditReady	Verified, traceable civic modules

🧾 License

MIT — Built for civic clarity, not corporate opacity.

🧠 Author

Peter M. Mutiti
Civic watchdog, dashboard architect, rotator reformer.
📍 Nairobi, Kenya
🛠️ View Live Service