📁 Endpoint vs Logic: What Each File in Your Rotator Service Really Does

🧠 API vs Utility Files in Hashtag Rotator

Audit-grade breakdown of endpoint handlers vs functional modules in civic hashtag services…

📁 File Classification Overview

In the hashtag-rotator-service repository, files are either:

• API endpoints: Exposed to HTTP requests, typically under /api
• Utility or functionality modules: Internal logic, helpers, or service layers

✅ API Endpoint Files

File	Why It's an API
diagnostics.js	Handles HTTP diagnostics requests, likely returns system health JSON
health.js	Responds to health checks, uptime pings, or status probes
ping.js	Simple endpoint for latency or availability testing
rotator.js	Serves rotating hashtags, possibly filtered by region
trends.js	Returns trending hashtags from Trends24 or fallback sources
webhook-listener.js	Receives incoming GitHub or external webhook events
webhook-diagnostics.js	Returns webhook status or logs for debugging

These files are designed to be triggered by external requests. They return JSON, status codes, or perform routing logic. They are serverless-ready and often deployed via Vercel or similar platforms.

🧰 Utility & Functionality Files

File	Why It's a Utility
crons.js	Contains scheduled job logic (e.g. TTL refresh, fallback triggers)
fallbackHashtags.js	Provides backup hashtags if Trends24 fails or queue is empty
fetchHashtags.js	Scrapes or fetches hashtags from external sources
github-webhook.js	Processes GitHub webhook payloads internally (not exposed)
hashtag-rotator-service.js	Main orchestrator or entry point for service logic
hashtag-rotator.js	Core rotation logic — selects next hashtag from queue
hashtags.js	Defines hashtag schema, validation, or transformation logic
meta.js	Provides metadata or config values used across modules
node-webhook.js	Handles internal webhook logic for node-based triggers
regions.js	Defines supported regions and region-specific logic
trendingHashtags.js	Processes and ranks hashtags based on freshness or popularity

These files are not exposed to HTTP requests. They contain logic, helpers, and service orchestration used by API endpoints or cron jobs. They are bundled into serverless functions but not serverless themselves.

📚 Glossary (Kid-Friendly)

Term	Meaning
API	A way for software to talk to other software
Endpoint	A specific address where a service listens for requests
Utility	A helper file that does one job behind the scenes
Webhook	A message sent automatically when something happens
Cron	A scheduled task that runs at set times
Fallback	A backup used when the main thing fails
Region	A specific country or area used to filter hashtags
Rotation	Switching between items in a queue one by one