buzz/README.md

Buzz Events

Next.js 16 application running multiple community events for YouTuber Buzz. Built with TypeScript, Bun, PostgreSQL, and Redis.

Branches

Donation

Payment-processing and stream-overlay system with two payment methods:

• TrueMoney (TMN): Voucher gift link redemption via Sastify API
• PromptPay (SlipOK): Slip image upload verified by SlipOK API

Key features:

• Real-time overlay widget (OBS-ready): SSE-driven animated popup with donor image, name, amount, message; plays SFX + Gemini TTS audio announcement ("<name> โดเนทมา <amount> บาท")
• Top donors leaderboard at /donate/top — podium (1st–3rd) + table (4th–10th)
• Admin panel at /donate/admin — view donations, re-send popups, test popup, force-reload all widgets, copy artifact UIDs, view donor images
• Heartbeat system: Widget health monitoring with auto-recovery after 6+ missed heartbeats
• Sub-10 THB donations skip overlay but update leaderboard
• Queue-skip for artifact submissions (promoted queue)

Artifact

Moderator-supervised character showcase ID review system:

• Public submission at /artifact — UID + character + comment form
• Enka Network integration: Auto-fetches showcase characters from UID
• Free queue: FIFO, 1 character reviewed per submission
• Donation skip-queue: Promoted submissions (queue = NULL), up to 8 characters, visually distinct in admin (yellow border, bitcoin icon)
• Admin panel: Sidebar with sorted submission list (special queue first), checkmark toggle, Enka card browser (iframe + rendered card), random picker, wipe/reset
• Queue management: Lock toggle, configurable capacity limit (-1 = unlimited)
• Card generation: External MTS service renders character cards; cached as bytea in DB with revalidation support
• Widget: /widget/artifact-count — OBS overlay displaying count/limit

Rubgram (รับกรรมแทนทางบ้าน)

Paid endgame content service where Buzz plays on your account:

• Discord OAuth2 required — auto-joins guild, session persisted via cookie token
• Service selector: Multiple configurable service types with real-time price estimation; "all services" discount
• Free queue counter: Admin-configurable free slots (price = 0)
• 20-minute payment window with PromptPay QR code and slip upload
• SlipOK verification with deduplication by transRef
• Expiration system: Unpaid submissions auto-expire with queue rebalancing; expired users can restore and pay
• Admin panel: Lock/limit/free controls, manual submission creation, Discord ping ("ถึงคิวแล้ว"), slip archive viewer by round, monthly archive
• Widget: /widget/rubgram-count — OBS overlay displaying count/limit

Tierlist

Community character tier rankings:

• Multi-type, multi-version: Browse by category (e.g. Endgame Content) and patch
• Drag-and-drop via dnd-kit — place characters into SS/A/B/C/D tiers within On-Field DPS / Off-Field DPS / Support columns
• Real-time collaboration via SSE — all connected clients sync instantly
• Comments & badges assignable to individual placements
• Admin edit mode at /:type/:ver/admin
• Data sourced from Project Amber

Guide

Character build guide directory:

• Searchable grid with debounced ilike search
• Each card links to an external Google Sheet
• Admin hide/unhide controls

Admin

Centralized management panel at /admin (guarded by better-auth):

• Dashboard: Random Nod-Krai welcome messages, health monitor (DB, Enka, Amber, Redis/SSE)
• Character manager: CRUD for Genshin characters (element, weapon, stars, CDN image, Amber ID)
• CDN file manager: Upload, rename, import from URL
• Guide admin: Hide/unhide guides
• Settings: Enka Network toggle, manual Amber sync, account (WIP)
• Audit log: Last 1000 admin actions with user info
• Section shortcuts: Links to artifact, rubgram, donate, and tierlist admin

Architecture Diagram has been moved to DIAGRAM.md

Architecture

• Framework: Next.js 16 (App Router), Turbopack, React 19 — hybrid SSR/RSC/CSR
• Runtime: Bun (1.3.14-alpine) — development, production, and backend
• Language: TypeScript (strict, bundler module resolution)
• UI: shadcn/ui (Radix primitives), Tailwind CSS 4, motion, lucide-react, @tanstack/react-table, recharts
• Forms: react-hook-form, zod validation
• Auth: better-auth (email/password, admin role), Discord OAuth2 (Rubgram), internal Redis-backed tokens (service-to-service)
• Database: PostgreSQL via Drizzle ORM (5 schemas). All IDs are UUIDv7. Binary data stored as bytea.
• Real-time: Redis pub/sub → Server-Sent Events (SSE) — auto-reconnecting EventSource client with 90s heartbeat, 30min timeout
• Analytics & Errors: PostHog (cloud, proxied via Next.js rewrites)
• TTS: Google Gemini 2.5 Flash Preview TTS — randomized voices, WAV output, Redis-cached (7d), 1000-char limit
• Background: Canvas-based star renderer (~500 stars + shooting stars, capped at 30fps)
• Font: Anuphan (Thai-optimized)

Real-Time System (SSE)

Endpoint	Events	Clients
artifact	submit, toggleCheck, toggleLock, setLimit, wipe	Admin panel, artifact widget
rubgram	submit, paid, toggleCheck, toggleLock, setLimit, setFree, cancel, uploadSlip	Admin panel, rubgram widget
donate	ping, heartbeat, update, refresh	Donate widget, top widget, admin
active	version (deploy), live (YouTube status)	All pages
log	update (audit log)	Admin log viewer
tl.{name}	update_states, update_placements	Tierlist per-type

Embeddable Widgets (OBS Browser Source)

Widget	Route	Description
Donation alert	/widget/donate	Full-screen animated popup with SFX + TTS
Top donor	/widget/donate/top	Compact real-time #1 donor bar
Artifact queue	/widget/artifact-count	Submission count / capacity
Rubgram queue	/widget/rubgram-count	Submission count / capacity

All widgets are SSE-driven, auto-updating, and designed for streaming overlays.

Payment Processing

• Rubgram: PromptPay only — SlipOK API verifies slip images, deduplicated by transRef. 20-minute payment window with QR code.
• Donation: TrueMoney (Sastify API voucher redemption) + PromptPay (SlipOK). Transactions stored in dedicated endgame.slips table with full SlipOK response.

Authentication & Authorization

• Admin: better-auth email/password with admin role check. Middleware protects /admin/*, /artifact/admin/*, /rubgram/admin/*, /tl/*/admin/*.
• Rubgram users: Discord OAuth2 — session persisted via cookie token (uuidv7).
• Internal: Redis-backed tokens (600s TTL) for backend-to-API auth via X-Internal-Auth header.
• Brute-force protection: 10 failed login attempts triggers a browser-crashing DoS defense (Brash technique) on the client.

External APIs

API	Usage	Endpoint
Project Amber	Character and version data, synced every 14 days	gi.yatta.moe
Enka Network	Character showcase auto-fetch	enka.network
Astral/Enka Embed	Character card rendering	git.dgnr.us/astral/api
SlipOK	PromptPay slip verification	configurable
Sastify	TrueMoney voucher redemption	api.sastify.xyz
Google Gemini	TTS for donation announcements	gemini-2.5-flash-preview-tts
Discord API	OAuth2, guild member list, webhook pings	discord.com
YouTube API	Live stream status	googleapis.com
PostHog Cloud	Analytics and error tracking	us.i.posthog.com

Database Schemas (PostgreSQL)

Schema	Tables	Domain
public	characters, versions, settings, guides, cdn, auditLog, user, session, account, verification	Core data (characters, auth, CDN, settings)
artifact	submissions, cards, settings	Artifact review queue
endgame	submissions, sarchive, expired, slips, settings, discord, types	Rubgram service ordering
tierlist	types, tiers, columns, badges, versions, states	Tier rankings
donate	donations	Donation records

Contributing

Prerequisites

• Bun, Docker & Docker Compose

Setup

1. Clone the repo.
2. Copy .env.example to .env and fill in secrets (or use dev/.env.development for local defaults).
3. Start the dev environment:

   bun dev
   

   This spins up PostgreSQL, Redis, the backend, and the Next.js dev server with Turbopack — hot reload via Docker sync.
4. Access at http://localhost:3000.
5. Seeded admin account: [email protected] / youshallnotpass (set via INITIAL_ADMIN_PWD).

Useful commands

Command	What it does
bun dev	Start full dev environment
bun ds	Open devshell
bun run lint	oxlint
bun run format	oxfmt
bun run build	Production build (Turbopack)
bun dr	drizzle-kit (generate, push, studio)
bun ba	better-auth CLI

Code style

• Linting: oxlint (with tailwind and tsgo plugins), oxfmt
• All row IDs are UUIDv7
• PostgreSQL schemas for domain separation (public, artifact, endgame, tierlist, donate)
• New features should follow existing patterns: SSE for real-time, Zod for validation, server actions for mutations

Project structure

Path	Contents
app/(ui)/	Public pages (donate, artifact, rubgram, tierlist, guide, admin, login)
app/api/	API routes (auth, payments, TTS, Amber sync, card rendering)
app/widget/	Embeddable OBS overlays
app/sse/	Server-Sent Events streaming endpoints
backend/	Standalone Bun backend (cron jobs, Discord webhooks, DB seeding)
lib/db/	Database schema, SSE endpoint definitions, Redis client
components/	Shared UI primitives (shadcn/ui)

Deployment

CI/CD (Gitea Actions)

Push to main or dev triggers .github/workflows/build.yml:

1. Build frontend Docker image (multi-stage: deps → drizzle push → builder → runner)
2. Build backend Docker image (compiled to Bun bytecode via bun build --target bun --bytecode)
3. Push both images to private registry at registry.neko-piranha.ts.net
4. Rolling update of Docker Swarm services (buzz_app, buzz_backend)

Production stack (Docker Swarm)

Service	Replicas	Resources	Notes
Frontend	2	1 CPU / 1 GB RAM	Healthcheck on :3000, autoscaling label
Backend	1	1 CPU / 512 MB RAM	NO_AUTH_CHECK=true env, auto-rollback on failure

Infrastructure dependencies:

• PostgreSQL database (managed externally)
• Redis instance for SSE pub/sub and caching
• Nginx reverse proxy with SSE optimizations (buffering off, 200s read timeout)
• Private Docker registry at registry.neko-piranha.ts.net

Environment

Required variables (~30 total, see .env.example):

Category	Variables
Database	DATABASE_URL, REDIS_URL
Auth	BETTER_AUTH_SECRET
Rubgram payments	SLIPOK_API_URL, SLIPOK_API_KEY
Donation payments	TMN_DEST_PHONE_NUM, SASTIFY_API_PRIVKEY
TTS	GEMINI_TTS_API_KEY
Widget	DONATE_WIDGET_KEY
Discord	DISCORD_BOT_TOKEN, DISCORD_CLIENT_*, DISCORD_GUILD_ID, DISCORD_WEBHOOK_URL
YouTube	YOUTUBE_CHANNEL_ID, YOUTUBE_API_KEY
Analytics	NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN

Developers

Lead Developer: @dmgnr

Project Coordinator: @gunshiz

Consultant Developer: @s4msh1ne