buzz-sheet/README.md

# Buzz Guide

A Thai-first Genshin Impact guide CMS for publishing character builds, teams,
rotations, and comparisons from structured data.

**Live site:** [guide.sudloh.com](https://guide.sudloh.com)

Buzz Guide is an independent community project and is not affiliated with or
endorsed by HoYoverse. The repository and deployment resources retain the
`buzz-sheet` name.

## Features

- **Public guides:** a searchable character directory and responsive guide pages.
- **Visual editing:** structured editors for overviews, weapons, artifacts,
  constellations, teams, and custom sections, with autosave and conflict recovery.
- **Accounts:** Guide email/password sign-in, email verification, local profiles,
  and rolling sessions. Existing users who signed up through Sudloh can set a
  Guide password from the password-reset page.
- **Media:** S3-compatible uploads and publication-aware delivery for staged files.
- **Catalog updates:** Discord-triggered synchronization with Lunaris.
- **Commissions:** PromptPay checkout, Slip2Go verification, ticket attachments,
  and opt-in browser push notifications.
- **Shared state:** PostgreSQL transactions, a retryable outbox, Redis caching,
  and Server-Sent Events across application replicas.

The five reference workbooks are included only as sanitized structural and
formula fixtures. Their guide text and media are not imported or published.

## Contents

- [Local development](#local-development)
- [Commands](#commands)
- [Routes](#routes)
- [How updates and uploads work](#how-updates-and-uploads-work)
- [Verification](#verification)
- [Containers](#containers)
- [Kubernetes](#kubernetes)
- [Acknowledgements](#acknowledgements)

## Local development

### Requirements

- Bun **1.3.14**
- PostgreSQL
- Redis
- S3-compatible object storage

### Setup

```bash
git clone https://git.astrxl.dev/astral/buzz-sheet.git
cd buzz-sheet
bun install --frozen-lockfile
cp .env.example .env
```

Fill in `.env` using the placeholders in `.env.example`. Keep credentials out of
Git; `.env` is ignored by the repository.

| Setting | Purpose |
| --- | --- |
| `BETTER_AUTH_URL` | Must exactly match the application's origin. |
| `BASE_URL` | Public origin used for SEO metadata, the sitemap, and robots.txt. |
| Database, Redis, and S3 settings | Connection details for the required services. |

Apply the committed database migrations, then start the development server:

```bash
bun run db:migrate
bun run dev
```

Visitors can sign in at `/auth/login` or register at `/auth/register`.
For background processing, run the
outbox worker in a separate terminal. Run the Discord worker when using catalog
updates; its configuration is described below.

```bash
bun run worker:outbox
```

```bash
bun run worker:discord
```

Email, commission payments, and push notifications need their corresponding
service credentials. See [External prerequisites](#external-prerequisites) for
the production configuration details.

## Commands

| Command | Purpose |
| --- | --- |
| `bun run dev` | Start the Next.js development server |
| `bun run test` | Run the Vitest unit and integration suite |
| `bun run test:coverage` | Produce V8 coverage output |
| `bun run typecheck` | Run TypeScript without emitting files |
| `bun run lint` | Run ESLint |
| `bun run security:audit` | Check dependency advisories and time-limited exceptions |
| `bun run build` | Compile the production application |
| `bun run db:generate` | Generate a Drizzle migration from schema changes |
| `bun run db:migrate` | Apply committed Drizzle migrations |
| `bun run import:guides` | Preview the one-time Google Sheets guide migration (`-- --apply` to write) |
| `bun run worker:discord` | Listen for Lunaris update announcements |
| `bun run worker:outbox` | Process cache and event outbox records |

## Routes

| Route | Purpose |
| --- | --- |
| `/` | Searchable public character directory |
| `/[character]` | Redirect to the first visible page |
| `/[character]/[page]` | Render a public guide page |
| `/auth/login` | Public account sign-in |
| `/auth/register` | Public account registration |
| `/admin` | Character and page overview |
| `/admin/[character]/[page]` | Visual page editor |
| `/admin/create` | Create a structured guide from the synced character catalog |
| `/media/[id]` | Same-origin media response with publication checks |
| `/api/healthz` | PostgreSQL, Redis, Slip2Go, Discord bot, and Lunaris status |

The comprehensive check returns 503 if any dependency fails. Slip2Go uses a HEAD request to
check reachability without submitting a payment slip; it cannot validate the API secret.
The Discord check requires a heartbeat from the connected catalog worker within 45 seconds.

A page is public only when both its page and character are visible. A visible
character without a visible page returns 404.

## How updates and uploads work

### Editing and live updates

Edits carry an `expectedVersion`. Accepted changes save guide content, media
reference counts, and outbox records in a single PostgreSQL transaction.

The outbox worker invalidates the affected Redis cache tags before publishing
an event containing only `{ type, id, version }`. Clients then fetch the current
state. SSE carries change notifications, never guide content; PostgreSQL remains
the source of truth.

Public guides use a shared Redis-backed Next.js cache. Admin routes stay dynamic.
SSE streams send a heartbeat every 90 seconds and close after 30 minutes so
clients reconnect. Response headers disable Traefik buffering.

### Discord catalog synchronization

The catalog worker watches the private channel set by `DISCORD_CHANNEL_ID`.
Every new message, including one sent by you, triggers a check and synchronization
with the latest version reported by Lunaris.

- Startup connects the listener without replaying history or starting a sync.
- Results go to `DISCORD_LOG_CHANNEL_ID`; start notifications link to the
  triggering message.
- Send `!lunaris stop` in the watched channel to cancel the current fetch and
  clear queued fetches. A later message starts another check.
- Enable the Discord Message Content intent and grant the bot View Channel and
  Send Messages in the configured channels.

### Media visibility

| Upload path | Visibility |
| --- | --- |
| Presigned staged upload | Private in S3. `/media/[id]` allows public access only while a published guide references the object; otherwise administrator authorization is required. |
| Direct guide image upload | Public CDN object, including uploads made for drafts. |
| Commission attachment | Served from `S3_PUBLIC_URL`; anyone with the URL can view it. |

Keep sensitive material out of the direct upload path and commission attachments.

## Verification

Run the complete host-safe verification set with:

```bash
bun install --frozen-lockfile
bun run security:audit
bun run test
bun run typecheck
bun run lint
kubectl kustomize k8s/ >/dev/null
```

The formula suite validates the exact sanitized corpus of 379 extracted formula
cells plus arithmetic edge cases. An optional Redis integration test uses
independent connections for two conceptual replicas:

```bash
REDIS_INTEGRATION_URL=redis://127.0.0.1:6379 \
  bun run test -- tests/redis-replication.integration.test.ts
```

It uses unique key and channel prefixes and removes its cache state afterward.
Without `REDIS_INTEGRATION_URL`, that external-service test is skipped.

## Containers

The application image compiles Next.js in a Node builder stage, then runs the
standalone server and bundled workers on Bun as the unprivileged numeric
UID/GID `1000:1000`. The migration image runs the committed Drizzle migrations
with the same identity.

```bash
docker build \
  --target app \
  --build-arg BASE_URL=https://guide.sudloh.com \
  --build-arg NEXT_DEPLOYMENT_ID=<immutable-revision> \
  --build-arg VCS_REF=<immutable-revision> \
  --tag buzz-sheet:<immutable-revision> \
  .

docker build \
  --target migration \
  --build-arg VCS_REF=<immutable-revision> \
  --tag buzz-sheet:migrate-<immutable-revision> \
  .
```

The runtime images do not contain local `.env` files.
`BASE_URL` is required during the Next.js build and at runtime. CI supplies the
build argument, and the Kubernetes ConfigMap supplies the runtime value. Keep
both values aligned when changing the public site origin.

## Kubernetes

Kustomize resources live in `k8s/` and define:

- Namespace `buzz-sheet`.
- Two rolling web replicas, one outbox worker, and one Discord catalog worker.
- ClusterIP port 3000 and Traefik ingress for `guide.sudloh.com`.
- Cloudflare edge TLS with the cluster's standard HTTP Traefik origin route.
- Startup, liveness, and dependency-aware readiness probes.
- Web requests of 500m CPU/1 GiB and limits of 1 CPU/2 GiB.
- HPA from 2 to 6 web replicas at 70% CPU or 75% memory and a PDB with one available.
- Non-root, read-only containers with dropped capabilities and seccomp.
- Ingress NetworkPolicy allowing the web pods only from Traefik in `kube-system`.
- ARM64 scheduling constraints matching the production hosts and images.
- A versioned migration Job and namespace-scoped CI deployer permissions.

PostgreSQL, Redis, and S3 are external services. The manifests deliberately do
not create in-cluster data stores or credentials.

### External prerequisites

#### Application secrets

Before the first rollout, a cluster administrator must provision a
`buzz-sheet-env` Secret in the `buzz-sheet` namespace containing:

```text
DATABASE_URL
BETTER_AUTH_SECRET
RESEND_API_KEY
REDIS_URL
S3_ENDPOINT
S3_PUBLIC_URL
S3_BUCKET
S3_ACCESS_KEY_ID
S3_SECRET_ACCESS_KEY
NEXT_SERVER_ACTIONS_ENCRYPTION_KEY
TURNSTILE_SITE_KEY
TURNSTILE_SECRET_KEY
COMMISSION_PROMPTPAY_TYPE
COMMISSION_PROMPTPAY_VALUE
COMMISSION_RECEIVER_ACCOUNT_NUMBER
SLIP2GO_VERIFY_URL
SLIP2GO_API_SECRET
WEB_PUSH_PUBLIC_KEY
WEB_PUSH_PRIVATE_KEY
WEB_PUSH_SUBJECT
DISCORD_BOT_TOKEN
DISCORD_CHANNEL_ID
```

`NEXT_SERVER_ACTIONS_ENCRYPTION_KEY` must be generated once and remain stable
across replicas and rolling deployments. Do not place secret values in the
ConfigMap or commit them to this repository.

#### Email verification

Before deploying required email verification, add `sudloh.com` to Resend and
publish the DNS records shown in its domain setup. Verify the domain, create a
sending-only API key restricted to it, and set `RESEND_API_KEY` in the external
Secret. Account verification and password reset emails are sent from
`Buzz Guide <[email protected]>`; this address does not need an inbox. Existing
sessions continue until they expire or the user signs out, after which an
unverified address must be verified before signing in again.

#### Commission payments and attachments

The commission page accepts PromptPay mobile, national ID, or e-wallet identifiers.
For `COMMISSION_PROMPTPAY_TYPE=mobile`, use a real 10-digit Thai mobile number
registered with PromptPay for receiving transfers in `COMMISSION_PROMPTPAY_VALUE`.
For `nationalId` use the registered 13-digit ID; for `ewallet` use its 15-digit ID.
An ordinary bank account number cannot be used as the mobile identifier.
Set `COMMISSION_RECEIVER_ACCOUNT_NUMBER` to the recipient value in the format
Slip2Go expects for its receiver check. Set `SLIP2GO_VERIFY_URL` to the full
image-verification endpoint from your Slip2Go API Connect account. Set
`SLIP2GO_API_SECRET` to the raw secret; the server adds the `Bearer` authorization
prefix when calling Slip2Go. Payment slips and ticket images use the configured
S3 bucket and are served from `S3_PUBLIC_URL`. Anyone with an attachment URL can
view it. Each checkout accepts payment for one hour after creation. The outbox
worker removes expired unpaid checkouts; paid tickets remain available. Apply
the commission database migration before enabling checkout.

#### Browser push notifications

Commission message notifications require a stable VAPID key pair and subject
(`bunx web-push generate-vapid-keys --json`). Set the three `WEB_PUSH_*` values
in the web deployment secret and apply the push-subscription migration before
enabling notifications. Users opt in from a prompt when entering the commission area. Browser push can
arrive after tabs close; on iPhone and iPad, the site must be added to the Home
Screen before the browser offers push permission.

#### Ingress and client IP handling

Traefik must overwrite `X-Real-Ip` for every request, and the web pods must be
reachable only through Traefik before enabling the configured client IP based
rate limits. The NetworkPolicy assumes Traefik runs in `kube-system` with the
`app.kubernetes.io/name=traefik` pod label; verify those labels in the target
cluster before applying it.

#### Deployment notifications

Every page also subscribes to `/api/active`. When a serving pod reports a newer
deployment ID than the browser's current build, a persistent Thai notification
offers a full reload into the new release.

#### Initial bootstrap

The base manifests contain deliberate `replace-me` image and deployment values.
For initial bootstrap, the platform operator applies `k8s/base` through an
environment overlay that supplies an existing immutable image revision. The
aggregate `k8s/` kustomization includes the migration resource for rendering and
validation; normal releases create their own revision-named migration Job.

Use this command for local manifest validation only:

```bash
kubectl kustomize k8s/ >/dev/null
```

### Gitea Actions release

`.gitea/workflows/ci.yml` verifies pushes to `main` and scheduled runs, including a
dependency audit and a Git history secret scan. A time-limited advisory
exception is recorded in `security/audit-exceptions.json`. After the
repository variable `DEPLOY_ENABLED` is explicitly set to `true`, a successful
push to `main` builds and scans ARM64 images at:

```text
registry.neko-piranha.ts.net/astral/buzz-sheet:<git-sha>
registry.neko-piranha.ts.net/astral/buzz-sheet:migrate-<git-sha>
```

Configure the following Gitea secret before enabling deployment:

| Secret | Purpose |
| --- | --- |
| `KUBE_CONFIG_B64` | Base64 kubeconfig for the `ci-deployer` identity |

The kubeconfig must contain a certificate-valid API server address and its CA.
The workflow rejects `insecure-skip-tls-verify` and does not rewrite the
cluster server address.

The deploy job creates a revision-named migration Job, waits for completion,
updates `NEXT_DEPLOYMENT_ID`, and only then rolls out the immutable application
image to the web and both worker deployments. Schema changes must follow an
expand/contract sequence so the previous application revision stays compatible
during a rolling update.

## Acknowledgements

This project would not be possible without the open-source software and
community services it builds on:

- [Lunaris](https://lunaris.moe/) — character, talent, material, and game data
  used by catalog synchronization and guide tools. Buzz Guide links back to
  Lunaris for material references where appropriate.
- [Next.js](https://nextjs.org/) — application framework.
- [React](https://react.dev/) — user interface library.
- [Bun](https://bun.sh/) — JavaScript runtime and package manager.
- [PostgreSQL](https://www.postgresql.org/) — primary database.
- [Redis](https://redis.io/) — cache, event transport, and presence state.
- [Discord.js](https://discord.js.org/) — Discord catalog update worker.
- [Drizzle ORM](https://orm.drizzle.team/) — database schema and migrations.
- [shadcn/ui](https://ui.shadcn.com/), [Tailwind CSS](https://tailwindcss.com/),
  [Lucide](https://lucide.dev/), and [dnd-kit](https://dndkit.com/) — interface
  components, styling, icons, and drag-and-drop interactions.

Special thanks are also available on the site’s [Special Thanks page](https://guide.sudloh.com/thanks).

Genshin Impact and its characters, names, and assets are property of their
respective rights holders. Please review the applicable terms and licenses for
each third-party dependency before redistributing or deploying this project.