Skip to content

feat(web): a guild directory in the armory, with member counts and a summary on guild pages - #1339

Draft
CDVolvik wants to merge 1 commit into
mainfrom
srdev/guilds-20261116
Draft

CDVolvik wants to merge 1 commit into
mainfrom
srdev/guilds-20261116

Conversation

@CDVolvik

Copy link
Copy Markdown
Collaborator

Part of #1272 (the Guilds part).

What changed

  • Guild directory at /armory/guilds. Every armory guild with its roster size (Blizzard's count), the characters the armory has read in it, their average item level, how many are level 60 and the last read. It searches by name with the armory's character search rule (2 to 24 letters, from the start of the name). It filters by region and ruleset and sorts by members read (the default), average item level or level 60. All of it stays in the address: q, region, ruleset, sort, page. The pager shows 50 a page. Rows carry a region chip.
  • Guild page (/armory/<region>/guilds/<slug>). A summary is added above the roster: region chip and ruleset, roster size, members read, average item level of members read ("53.7 (2 read)"), roster read date, class mix and a level spread in six bands. Members already link to their character pages once read. The trail is now Armory › Guild directory › guild.
  • Hides. Hidden characters stay out of the roster and every count, as before. A guild hidden through /guilds/hide now also leaves the armory: the guild page 404s, and the directory and the /armory guild search drop it. The hide form keys a guild by realm and the armory keys it by region, so a hide on any realm whose name carries the region (… US1 …) hides the armory guild of that name in that region. That can hide more than asked, never less. If the hide list can't be read, the directory and guild page show storage as unreachable rather than an unchecked list.
  • Migration 20261117140000_armory_guild_directory.sql, not applied. It adds armory_guild_directory(prefix, region, ruleset_id, sort, limit, offset), which is service-role only, security definer, with search_path='' and lock_timeout 3s, written in the style of the other armory functions. It also adds a partial covering index armory_characters(region, guild_slug) include (slug, level, item_level, fetched_at). The migration checks its prerequisites (the armory and guilds migrations) and is safe to apply twice. Readback and rollback are in the file.
  • Before the migration is applied. PostgREST answers 404 PGRST202 for the missing function, and the store turns that into "not ready". The page then says counts and sorting start once the database update is applied. A search still lists matching guilds by name through the existing armory_search_guilds. No crash and no empty "unreachable" state.
  • /guilds. The old "rosters are in the armory" line now links the directory and offers "Search it for “x”" when the typed search fits the armory rule. The ladder, its search and its URL params are unchanged.
  • Rankings rows (/armory/rankings/*) show the region as a coloured chip next to the ruleset. Two new colour tokens, region-us and region-eu, are in the contrast-tested TEXT_TOKENS.

Why the directory is not a section of /guilds

The brief asked for the armory directory to be merged into /guilds. I linked the two instead, for two reasons:

  1. Ads. Blizzard's Developer API Terms allow no ad on a page that shows its data. /armory is on data/ad-free-paths.json; /guilds is not. Showing armory rows on /guilds would mean adding /guilds to that list, which also turns analytics off there and marks it private in cf-edge-cache. I left that decision to the maintainer.
  2. No reliable join. Uploads key a guild by realm and name, the armory by region and slug, so the rows can't be merged reliably. One merged table would either list a guild twice or fold two different guilds into one.

/guilds keeps its ladder and its search over uploads, and it links the directory with the search carried over.

How you tested it

  • web: npx vitest run --maxWorkers=4 --testTimeout=60000. Test files: 523 passed, 5 skipped. Tests: 5988 passed, 30 skipped, 0 failed.
  • web: npm run typecheck is clean. npm run lint shows the 4 warnings that are already on main. npx next build succeeds, with /armory/guilds as a dynamic route.
  • kb: npm test. Test files: 185 passed. Tests: 2201 passed, 1 skipped. npm run typecheck is clean.
  • SQL on PGlite (kb/test/armory-guild-directory-sql.test.ts runs supabase/tests/armory_guild_directory.sql). It applies the players, guilds and armory migrations, then the new one twice, then checks:
    • each sort order
    • nulls sort last
    • prefix rules (case, a one-letter prefix, a %)
    • ruleset filter, offset paging and total on a later page
    • the 100-row cap
    • a hidden character dropping out of the counts
    • a US guild hide not reaching an EU guild of the same name
    • grants, security definer and config, and the index
  • I made one assertion fail on purpose to confirm the SQL checks actually catch errors.
  • New web tests:
    • web/src/lib/armory-guilds.test.ts: address parsing and round trip, the search rule, hide matching, sort, filter and paging, hidden members and guilds, the fallback before the migration (404 PGRST202 is "not ready", a 500 is unreachable), the cloud row parsing and the roster summary.
    • web/src/app/armory/guild-directory.test.tsx: the directory page (switch off, sort and filter links, search, paging, hides, before the migration, storage down), the guild page summary, the hidden member and hidden guild cases, and the ranking chip.
    • web/src/app/guilds/guilds.test.tsx: the /guilds link line.

Not done / decisions for Carlos

  • Apply the migration (20261117140000_armory_guild_directory.sql). Until then the directory has no counts or sorting, only name search.

  • Progression. The directory sorts by the level 60 count, not raid progression: the armory stores no raid progression yet, and raids open December 9.

  • Scale. The function aggregates armory_characters per request, with a covering index. That is fine at today's ~350 characters. At the millions Census and character pages: find any Forever character by full name and give it an armory-style sheet #1270 talks about it would want a rollup table that the crawler refreshes.

  • Guilds the crawler hasn't read. A guild that characters name but that has no row in armory_guilds is not listed. The guild page needs that row, and the crawler queues the guild when it reads one of its characters.

  • /guilds ad-free? If you want armory rows shown directly on /guilds, the first step is adding /guilds to ad-free-paths.json (see "Why the directory is not a section of /guilds").

  • I didn't touch the header, web/src/data/tools.ts (feat(web): restructure the header into Lookup, Database, Tools, Guides, Chat and Profile #1336's files), the rankings page layout or the crawler.

  • Title reads type(scope): plain sentence

  • Commits are signed off

  • No scraped, datamined or spoiler data; test fixtures are invented

  • CHANGELOG.md has one Site: line under [Unreleased]

  • Area label set (web)

…summary on guild pages

/armory/guilds lists every armory guild with its roster size, the
characters read in it, their average item level and how many are level
60. It searches by name (the armory's character search rule), filters by
region and ruleset, sorts by members read, item level or level 60, and
keeps all of it in the address. It reads a new service-role function,
armory_guild_directory (migration 20261117140000, not applied); until it
is applied the page says counts are not ready and a search still finds
guilds by name.

Guild pages add the class mix, a level spread, the average item level of
members read and the roster read date. A guild hidden through
/guilds/hide now leaves the armory too (guild page, directory and hub
search), matched by name within the region its realm names. /guilds
links the directory and carries its search over. Ranking rows show the
region as a coloured chip.

Signed-off-by: CDVolvik <cjimenez@r21digital.com>
@CDVolvik CDVolvik added enhancement New feature or request web everloot.app needs-decision Waiting for a maintainer decision labels Nov 18, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request needs-decision Waiting for a maintainer decision web everloot.app

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant