gacha-event-tracker/docs/PRODUCT.md

# Product

<!-- impeccable:product-schema 1 -->

## Platform

web

An installable single-page web app (PWA with a service worker and manifest) that works offline. Native
mobile apps are out of scope: installing to a home screen is enough (`docs/PRD.md` § Out of scope).

## Users

**The repository owner comes first.** Event Clock is the owner's own tool for keeping track of the
gacha games they play. When the owner's use and a public reader's request conflict, the owner's use
wins.

**Public readers come second, and they are welcome.** The app has been posted to r/gachagaming and is
served publicly. The typical public reader matches the PRD persona: someone playing 2–5 gacha games
who checks in a few times a week, usually on a phone. Their situation is a dozen overlapping,
time-limited events spread across as many in-game calendars, and the thing they fear is missing a
limited event by a day. A smaller group plays 6–10 games or more. For those readers, custom games and
events (F13) cover what no list of sources ever will.

The desktop layout is a real layout, not the phone layout stretched, but mobile is the main use case.

## Product Purpose

Event Clock answers three questions in one screen, across every game the reader plays:

1. What is running right now?
2. What ends soonest?
3. Which of these have I already finished, or am I partway through?

It collects live and upcoming events from community wikis, sorts them by end date, and plots them on
a timeline. Readers can mark an event done or in progress, estimate how much effort it takes, and tick
off daily progress on events that repeat.

Success is measured as follows (`docs/PRD.md` § Success criteria):

- A reader can find their next expiring event within 5 seconds of load, on mobile.
- At least 99% of published end dates are correct.
- A new game can be added without a schema migration or a client change.

## Positioning

**One screen for every game, ordered by what runs out next.** Each game publishes its own calendar,
and none of them talk to each other. paimon.moe, Game8 and in-game timers each answer the question
for one game. Event Clock answers it across all of them in a single deadline order. Cross-game
coverage is the core of the product, so the number and range of supported games matter directly.
The most common reason the public thread gave for not using the app was a missing game.

Date discipline is how the product is built rather than the headline claim, but it is never traded
away for more coverage (see Product Principles).

## Operating Context

- Readers check in a few times a week, usually on a phone, often between other things. The dailies
  strip is meant to be answerable in about ten seconds.
- A reader has a game open, sees its in-game timer, and compares it with ours. Countdowns therefore
  resolve on the game's own server reset for the reader's region (Asia, America or Europe), not on
  UTC.
- Readers either work down a checklist of deadlines, or look at a game-by-game timeline in the style
  of paimon.moe, which the public thread named as the reference.
- Some readers are catching up on games they set aside rather than busy with all of them. The app
  serves them through the in-progress status and effort fields, and never nags them about a game they
  stopped playing.
- Data is refreshed twice a day from community wikis. Some sources (the nine Game8 pages) cannot be
  fetched by the scheduled runner and are refreshed by hand. The data's age is therefore a fact the
  reader is shown, not one they have to assume.

## Capabilities and Constraints

**Capabilities.** The full feature set is specified as F1–F16 in `docs/PRD.md`:

- A timeline: one lane per game, or a single queue sorted by soonest end.
- A checklist of everything running, sorted by soonest end.
- Done and in-progress marks, effort estimates and notes.
- Daily checklists, with past days that can still be filled in.
- Ignoring an event, and filters by game or type.
- Focusing on one game at a time.
- Region selection.
- JSON export and import.
- The reader's own games and events, one-off or repeating.
- First-run setup.
- Offline use.
- A notice when a new version of the app is ready.
- Dark or light mode, plus a "follow the system" option.
- The reader's own game order.

The app currently covers twenty games from twenty-two sources.

**Hard constraints** (`AGENTS.md` § Three constraints):

- **No accounts, logins or user records.** All reader state lives in `localStorage`. Moving to
  another device works through export and import, never a server-side user.
- **No LLM in the pipeline.** Event data comes only from deterministic parsers.
- **A Bun server owns fetching and parsing.** The client only ever calls this app's own `/api/*`.
- **Some stored keys must never move.** Event IDs, `dailies:<game>`, game-day keys and the
  reader-authored `mygame:` / `myevent:` IDs are `localStorage` keys. Changing how any of them is
  built silently wipes readers' progress, and there is no server copy to restore from.
- **Scraping conduct is binding:** honour `robots.txt`, refresh each source at most once every six
  hours, space requests to the same host, and never get around an access control.

**Not the product** (`docs/PRD.md`):

- A wiki or event guide
- A notification or push service
- A pull tracker, damage calculator or build planner
- Localised beyond English

**Terminology:**

- The user is a **reader**.
- The two views are **Checklist** (stored id `"soon"`) and **Timeline**.
- An event's states are **untouched**, **doing it** and **done**.
- **Ignore** is not the same as done.
- A **lane** is one game's row or source.
- The daily **reset** is the boundary between game-days.

**Undecided:**

- Whether a month grid is needed in addition to the timeline.
- The formal accessibility standard (see below).
- The SQLite layer and the review queue for quarantined events are specified but not built.

## Brand Commitments

- **Name:** Event Clock.
- **Tagline:** "Live and upcoming gacha events, sorted by what expires next."
- **Unofficial and unaffiliated.** The app says so plainly. It credits the source wikis and the game
  studios on the same screen as the data, and treats the source page as the authority when the two
  disagree (F11).
- **Every event links to its source.** A date the reader typed in is visibly theirs and never
  credited to a source (F13).
- **Game hues are identity.** A game keeps its colour across views and themes (F15).
- **Dark is the default theme.** Light mode and a "follow the system" option are available (F15).
- **Voice:** plain, specific and honest about uncertainty. The app says "end date unknown" rather
  than implying a date, and states what it is holding back ("N live · N upcoming") instead of leaving
  the reader to infer it. Do not use the "AI slop" self-description in promotion (`docs/FEEDBACK.md`
  P3).

## Evidence on Hand

- `docs/FEEDBACK.md`: a reading of the r/gachagaming release thread (26 comments from 15 accounts),
  with verbatim quotes. Readers called the app useful without being asked, one bookmarked it, and no
  one disputed a date. The one design criticism was formed from the promo screenshot alone.
- The promo screenshot is outdated. FEEDBACK.md calls for a reshoot from a wide window, in timeline
  view.
- There are no usage metrics, testimonials beyond that thread, press mentions or user counts. Do not
  invent any.
- Pinned fixtures (`fixtures/<game>/`) and live snapshots (`snapshots/`) hold real event data for
  every supported game.

## Product Principles

1. **Deadline order is the product.** Every sort and grouping falls back to soonest end first.
   Truncating a list hides rows but never reorders them, and "next to expire" always means the
   earliest end date.
2. **Breadth, never at the expense of a true date.** More games is the main growth lever, but a
   wrong end date is worse than a missing event. Unknown ends stay unknown, a stale source is
   disclosed, and a page that is out of date but still parses is treated as a failure.
3. **Showing is not telling.** What the reader can look at is their choice. The headline deadlines
   and the dailies are instructions, so they never point at work that is already done or ignored.
4. **The reader's answers are theirs.** Their view, game order, region and choice of games are asked
   for once and remembered. A game added later arrives switched off, and nothing the reader set is
   overridden by a heuristic.
5. **Nothing is held back silently.** If something is hidden, stale or out of date, the reader is told
   in words, including whose games the notice covers.

## Accessibility & Inclusion

**No formal standard has been chosen yet.** The following rules are already in force and must be
kept:

- Game hues and the urgency colours clear 4.5:1 contrast against the background in both themes.
- No interaction is drag-only. Reordering has arrow buttons, so it works on touch, by keyboard and
  with a screen reader.
- Native `<details>` and `<button>` elements are used, so keyboard and screen-reader access needs no
  second implementation.
- Focus outlines are visible on `summary` elements.
- A list row is a single tap target.
- The interface is in English only. Dates and countdowns are formatted with `Intl`.