Twitch Stream Toolkit
A config-driven Twitch bot with a real-time OBS overlay system and a Twitch-authenticated web admin panel, built on Node with zero web dependencies and deployed on AWS behind automatic HTTPS. Built for a live channel (internally “bob-a-bot”), then generalized into a reusable, secret-free template.
Runs 24/7 for a live Twitch channel. Overlays are public; the admin panel sits behind Twitch login.
Project Overview
One self-hosted app that covers counters, song requests, alerts, moderation, and on-stream overlays, fully controllable by the streamer and their mods from chat or a web dashboard.
Streamers usually stitch together several paid third-party services to cover these features. This replaces them with a single app the streamer owns and controls.
Built for one specific channel, then generalized into a config-driven template so the same platform can be stood up for anyone.
Channels It Runs For
bobavillain
Runs 24/7 as “bob-a-bot” on the Twitch channel bobavillain, the channel it was originally built for.
Ready for More
Because the whole platform is config-driven, the same bot can be stood up for additional channels from a single JSON file, with no code changes.
Core Features
Chat & Channel Points
- Counters via Channel Points, bit cheers, and chat commands
- Custom commands matched on the first word
- Timers and timed challenges
- Clips and stream title / category controls
Moderation & Community
- Shoutouts (/announce plus native Twitch popup)
- Follower thanks and follow-age lookups
- Chat moderation: timeout, ban, and unban
- Redeem logs and a game backlog
OBS Overlays
- Three independent, movable browser sources
- Countdown timer that cycles through multiple timers
- Live counters ticker
- Spotify now-playing card that auto shows / hides
Web Admin Panel
- Twitch login, gated to broadcaster, allowlist, and mods
- Live counters and command / quote / game management
- Timeout, ban, unban, and redeem history
- Diagnostics page that fires overlay tests
External Services
- Spotify song requests
- DeepL live translation
- Weather (Open-Meteo) and other no-key APIs
- Each integration stays off until it's configured
Live Events (EventSub)
- Channel Point redemptions
- Raids and go-live notifications
- New follows
- Delivered over an EventSub WebSocket listener
How It Works
One Long-Lived Node Process
A single process connects to Twitch chat and EventSub and starts an embedded web server in the same process, with no separate services to orchestrate.
One Server, Three Jobs
The embedded server serves the OBS overlays (pushing live state over SSE), serves the Twitch-OAuth admin panel, and exposes a small JSON API the panel calls.
Reverse Proxy
Caddy sits in front on port 443 for HTTPS and proxies to the bot on an internal port, keeping the Node process off the public interface.
Flat-File Persistence
Counters, commands, quotes, and timers persist to JSON files on disk, one file per feature. Simple, transparent, and trivially backed up, with no database to run.
Tools + Build
Decisions Worth Calling Out
Config-Driven, Not Hard-Coded
Around 40 features toggle and tune through a single JSON file, so a non-developer can reconfigure the bot and it generalizes cleanly into a template. This is the core architectural bet.
Zero Web Dependencies
Routing, SSE, sessions, OAuth, and CSRF are all built on Node built-ins plus fetch: no Express, no framework, no build step. Tiny footprint and minimal supply-chain surface.
SSE-Driven Overlays
Overlay updates are one-directional, so Server-Sent Events beat WebSockets here: simpler, auto-reconnecting, no library. Countdowns tick locally in the browser from a server-sent end timestamp, so they stay smooth and network-light.
Security by Least Exposure
Overlays are gated by a secret key; the admin panel is Twitch-OAuth gated to an allowlist and mods, with HMAC-signed SameSite=Lax session cookies and a custom-header CSRF check. No secrets ever reach the client.
Deployment & Reliability
Self-Hosted on AWS
Runs on an AWS EC2 instance (Amazon Linux) with pm2 for process management and reboot persistence, on a static Elastic IP with DNS via a subdomain.
Automatic TLS
A Caddy reverse proxy provisions and renews Let's Encrypt certificates automatically, so HTTPS is hands-off.
Backups & Monitoring
Nightly cron backups protect the flat-file data, and UptimeRobot health-checks a /health endpoint so outages surface immediately.
Reusable Template
Extracted a generic, secret-free template from the live bot without taking the running instance down, genericizing hard-coded labels into config along the way.
Engineering Challenges
Multi-Timer Reconciliation
Several timers can run at once (challenge redeems plus reminders). The overlay reconciles a live list over SSE and cycles through them (~15s each), giving each its own style and an independent local countdown.
Readable Over Any Scene
Overlays have to read over arbitrary gameplay footage. Solved with solid tile backings and text outlines (no drop shadows), tested against both bright and dark scenes.