264 lines
16 KiB
Markdown
Executable File
264 lines
16 KiB
Markdown
Executable File
# 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:** Slip image upload verified by SlipOK or Slip2Go, selected in admin settings
|
||
|
||
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 / Slip2Go 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 — the selected slip provider verifies images, deduplicated by `transRef`. 20-minute payment window with QR code.
|
||
- **Donation:** TrueMoney (Sastify API voucher redemption) + PromptPay (the same selected provider). Transactions stored in `endgame.slips` with provider identity, verified amount/reference, and the full original response. Historical SlipOK records remain supported.
|
||
|
||
Switch between **SlipOK** (default) and **Slip2Go** in `/admin/settings` → external services → slip verification. The choice is saved globally and read from the primary database for each new check; no restart is needed. Checks already running finish with their original provider. The selector requires valid configuration before saving; there is no automatic fallback or retry.
|
||
|
||
- SlipOK uses the existing `SLIPOK_API_URL` and `SLIPOK_API_KEY`.
|
||
- Slip2Go uses `SLIP2GO_VERIFY_URL` (the full image endpoint URL ending in `/api/verify-slip/qr-image/info`) and `SLIP2GO_API_SECRET` (the exact secret value sent in `Authorization`). See the [image verification guide](https://slip2go.com/guide/rest-api/image) and [authentication guide](https://slip2go.com/guide/authentication).
|
||
- Slip2Go validates the exact payment amount and the account from `PROMPTPAY_TYPE` (`mobile`, `nationalId`, or `ewallet`) and `PROMPTPAY_IDENTIFIER`. Rubgram's static QR must receive into that same account. Provider duplicate checking is omitted; the shared database unique reference prevents reuse across both flows and providers while allowing failed submissions to be retried.
|
||
|
||
Before deploying this change, run `bun dr push` against the deployment database to add `settings.slipCheckProvider` with default `slipok`. No existing slip JSON needs migration. Then configure Slip2Go credentials and PromptPay variables on each app instance before selecting Slip2Go. Revert to SlipOK using the same selector.
|
||
|
||
Verification has a 30-second timeout and returns payment errors for provider failures, invalid responses, or unavailable services. `/api/health` checks the selected provider's origin without uploading a slip or spending verification credits; its cache is separate per provider. This checks reachability, not bank verification or account credits.
|
||
|
||
## 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 |
|
||
| Slip2Go | 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: `admin@dgnr.us` / `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` |
|
||
| Slip verification | `SLIPOK_API_URL`, `SLIPOK_API_KEY`; optional `SLIP2GO_VERIFY_URL`, `SLIP2GO_API_SECRET` |
|
||
| PromptPay account | `PROMPTPAY_TYPE`, `PROMPTPAY_IDENTIFIER` (required for Slip2Go and donation QR) |
|
||
| 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`
|