Skip to content
Start

Start

Developer Setup

Architecture overview and local setup notes for contributors to ItsBagelBot.

On this page

Setting up the bot on your channel? Follow the streamer guide instead. This page is for contributors.

Welcome to ItsBagelBot, a cloud-native, high-performance ecosystem designed for Twitch.

This guide covers the core concepts and steps needed to spin up the environment locally for development.

Architecture Overview

ItsBagelBot uses a decoupled, microservice-oriented architecture:

  • Backend Services: Powered by Go and Elixir (the Twitch ingress).
  • Event Driven: NATS JetStream carries events and NATS request-reply carries RPC between services.
  • Real-Time Communication: Twitch events arrive over EventSub WebSocket shards. Tebex purchase webhooks are the one inbound webhook, and they land on the transactions service.
  • Web apps:
    • Dashboard and Admin: SvelteKit apps in web/dashboard and web/admin, served by the cluster.
    • Marketing and Docs: Astro apps in web/marketing and web/docs.
  • Infrastructure: Runs on k3s with Cilium, default-deny network policies, Cloudflare Tunnel for public ingress and Tailscale for operator access.

See the system overview and CONTEXT-MAP.md at the repository root for service ownership.

Prerequisites

  • Go 1.26.5 (go.mod).
  • Bun 1.4.4 (packageManager in web/package.json).
  • Elixir 1.17 or newer, only for the Twitch ingress (app/twitch/ingress/mix.exs).

Local Setup

Go services, from the repository root:

go test ./...

Web apps, from web/:

bun install --frozen-lockfile
bun run dev:dashboard
bun run dev:admin
bun run check
bun run test

Docs, from web/docs/:

bun run dev

Twitch ingress, from app/twitch/ingress/:

mix deps.get
mix test

Each app’s context.md lists its focused checks.