# Buzz Sheet Structured Guide Platform

## Product

Buzz Sheet is a Thai-first, image-first Genshin guide CMS. The public directory
shows a required cover and Overview for every guide. Each guide exposes only
non-empty Weapons, Artifacts & Stats, Constellations, Team Calc, and optional
Extra sections. Use the English terms “Build” and “Team” throughout the UI.

The admin workflow stays intentionally simple:

1. Sync the latest Lunaris catalog manually or from its Discord announcement.
2. Select one Lunaris character at `/admin/create`.
3. Upload a required Guide Image and write the Overview.
4. Edit one structured section at a time under `/admin/[charid]`.
5. Press Save to update the public website immediately.

There is one guide per Lunaris character key. Empty sections remain private.
Remove Guide moves content to a recoverable Trash before permanent deletion.

## Structured content

- Weapons: catalog weapon, R1–R5, overall percent and/or personal percent.
- Artifacts: multiple named ranking groups, one-set or two-set rows, percent,
  up to two main stats per slot, ordered substats, targets, NA/E/Q priority and
  levels, and an optional note.
- Constellations: C1–C6 description and cumulative performance against C0=100%.
- Team Calc: multiple four-character teams, raw damage, calculated member
  shares, rotation duration, total DPS, and combo text.
- Extra: multiple sections of image-first rows with heading, short body, and an
  optional percentage.

## Catalog and media

The manual Sync button fetches Lunaris `version.json`. A dedicated Discord
worker instead extracts the exact version from followed announcements and
recovers missed announcements from recent channel history. Both paths share a
Redis lock, validate the versioned character, weapon, and artifact lists, filter
placeholder or missing-image records, mirror unique assets and normalized JSON
to Bun S3, then activate the completed version. Failed syncs do not replace the
active catalog.

`S3_ENDPOINT` is the private Garage API used for writes.
`S3_PUBLIC_URL=https://buzz-cdn.astrxl.dev` is the public read base. Browser
uploads go to an authenticated application route, which validates PNG, JPEG,
WebP, or GIF files up to 20 MB and writes them server-side through Bun S3.

## Operations and acceptance

- PostgreSQL migrations run before the ARM64 web and worker rollout.
- Better Auth users and sessions are preserved; the legacy block-editor guide
  content is intentionally reset by migration `0002`.
- Redis outbox events invalidate the directory and guide streams after saves,
  trash, restore, or delete actions.
- Verification requires `bun run test`, `bun run typecheck`, `bun run lint`,
  `kubectl kustomize k8s/`, a successful ARM64 container build, ready health
  checks, CDN reads, authenticated upload, catalog sync, and public rendering.
- Do not use Chromium or Playwright. Use Vitest, HTTP checks, and manual browser
  verification.