Glicko DB

User Interface Help

See the route and integration notes and the English README. You can also open this guide from the ? button in the top navigation or at /help?lang=en.

Accessibility and device support

Table of contents

Public interface

No account is required for /, /rankings, /players, /player/view?id=<player_id>, /matches, /tournaments, /tournaments/<tournament_id>, /reports, /category, and /sgf-library. These pages provide rankings, player profiles, match history, public tournaments, standings, rating information, reports, and SGF viewing or downloads.

Click any screenshot to enlarge it without leaving this guide. Close the preview with Esc, the close button, or by clicking outside the image.

Public home page

The public home page provides navigation, language and theme controls, rankings, statistics, and links to public content.

Pages accept ?lang=es, ?lang=en, or ?lang=pt; use YYYY-MM-DD in date filters and fields.

Rankings and player directory

Public profile for Acuña, Carlos

Public profile with current rating, category, and activity summary for the selected player.

Matches and SGF viewer

Public tournaments

Public tournament details

Tournament details with round selector, board pairings, results, and standings.

Period reports and export

Category converter

The /category page converts a Glicko rating to a Dan/Kyu category and displays the formula, configured constants, and complete scale. Two initially collapsed disclosures show the category conversion formula and the Glicko-2 formula with their current parameters; configurable values are also highlighted on /admin/ratings.

Strength increases from 30 kyu to 1 kyu, then from 1 dan to 9 dan: a smaller kyu number is stronger, but a larger dan number is stronger. On the continuous internal scale, the boundaries are -N for N kyu and N - 1 for N dan (there is no 0 kyu or 0 dan); the integer category uses floor on that value. A rounded decimal display can visually reach the next boundary while the unrounded value is still below it.

The Glicko input fills the available form width. On /admin/categories, the wider GLICKO_K and GLICKO_M fields are centered and stack when they cannot fit side by side on narrow screens.

Public news

The /news/<article_id> page displays a published article and turns player, tournament, and match tags into related links.

SGF library

The public library (/sgf-library) lists SGF files in uploads/sgf, with or without a linked match, subject to visibility rules: - Validates upload size, UTF-8 encoding, and basic SGF structure. - Automatically synchronizes root SGF properties (White/Black players, ranks, event, date, and result) with the linked database match. - If a file disappears, its reference is retained but its link is hidden; it works again if the file returns under the same stored filename. - Unlinking a record or deleting its match retains the file in the library; only administrators can permanently delete physical files.

Administrators can select multiple SGF files and delete them in one action. Matches and pending result submissions are left intact, with their SGF references cleared before the files are removed.

Member interface

Community players can register a personal account to manage preferences and submit results for organized tournaments and club games.

Account registration and login

  1. Open /admin/register to create an account with username, email, and password (minimum 8 characters). The form is protected by Google reCAPTCHA v3.
  2. New accounts are automatically assigned the member role.
  3. Sign in at /admin/login. To report results, request a link to your player record under Report Results and wait for approval.

Profile management

The User menu contains Admin Menu (when permitted), Report Results, Profile, and Logout. Open it with a mouse, keyboard, or touch; press Esc to close it.

From /admin/profile, authenticated users can: - Update their notification and recovery email address. - Select their preferred UI language (Español, English, Português). - Toggle between Light and Dark application themes. - Choose their IANA timezone from stable options, even when they share the current UTC offset (such as UTC and Europe/London in winter). The displayed offset changes with daylight saving time; a valid saved zone outside the suggested list remains available when editing the profile. - Change password by providing their current password and confirming the new one. - Under API access tokens, create and revoke personal tokens for the authenticated API after confirming their current password. A token is shown only once and lasts up to 90 days (30 by default). Administrators choose its scopes; every other account receives the scopes its current roles allow, shown on the form. A token never grants more than the account's current role permissions, and API operations work only after an operator enables them (see the API guide).

Member profile

User profile settings for language, theme, timezone, and password management.

Password recovery

  1. If you forget your password, click Forgot password? on /admin/login or navigate to /admin/forgot-password.
  2. Enter your registered email address. If found, the system dispatches a single-use cryptographically hashed reset link.
  3. Reset links expire according to PASSWORD_RESET_TTL_SECONDS (default: 3600 seconds / 1 hour).
  4. Open /admin/reset-password/<token> to choose a new password. For security, responses never reveal whether an email address exists.

Reporting results

Members can submit match results at /admin/report-results:

  1. Player link: if your member account has no linked player, select your profile from players without a linked account and use Request link on this page. Only one request may be pending per account. A Country/Regional Manager for that player's country or an Administrator approves or rejects it in Result moderation (/admin/result-submissions), with an optional review note. Requests do not link your account or enable result reporting until approved. After approval, sign in again. Your request history and review notes remain visible here; after rejection you can submit a new request. Availability is rechecked at approval, so another account cannot claim an already linked player. Administrators can still assign links directly.
  2. Submission form:
    • Opponent: select the rival player from active players.
    • Color: select whether you played as White or Black.
    • Result: indicate White wins (1-0), Black wins (0-1), or Draw (1/2-1/2).
    • Date: match date (YYYY-MM-DD).
    • Event & Location: tournament or club event name and venue.
    • Round: round number if applicable.
    • Handicap stones: handicap stones (0 to 9) given to Black.
    • SGF file (optional): upload the .sgf game record.
  3. Queue & moderation: submitted matches enter the Pending moderation queue (/admin/result-submissions). They do not affect rankings, ratings, or reports until reviewed and approved by tournament staff.

Member result submission

The member result screen shows the linked-player requirement and pending-submission area.

Administrator panel

Sign in at /admin/login with an administrative account. Available navigation adapts to the assigned account role: - member: profile settings and match reporting for linked player. - country_organizer / regional_organizer (Organizers): player and tournament management, including player creation through tournaments, player editing/deletion, matches, SGF linking, tournament imports, participants, pairings, rounds, results, and exports. - country_manager / regional_manager (Managers): Organizer tools plus scoped player imports, news, and result moderation. - administrator: full system control including players, rating/category configurations, database backups, user accounts, audit review, and settings.

The three access levels are Global, Regional, and Country. Administrators have global access. Country roles require a country, which can come from the linked player when no explicit scope is selected; regional roles require an explicit supported region (currently Latin America, identified as latam). A country role cannot use a region scope, nor a regional role a country scope. Without a valid matching scope, geographic routes deny access. Staff can manage players in scope, matches involving at least one in-scope player, and tournaments assigned to an in-scope country.

Tools Organizers Managers Administrators
Players, tournaments, matches, and SGF records Assigned country/region Assigned country/region Global
Player imports and result moderation No Assigned country/region Global
News No Yes (shared site-wide news) Yes
Backups, dataset-wide imports, rating recalculation, categories No No Global only
Users, audit, settings No No Global only

The menu groups tasks under Players and competition (players, matches, tournaments, and result moderation), Imports and ratings (player imports, general imports, ratings, and categories), Content and game records (news and the SGF library), and Site administration (users, settings, backups, audit, and analytics). Each whole card is a keyboard-accessible link, without a separate Open link. Only permitted tools and nonempty sections appear; the organization does not change permissions.

Legacy operator accounts migrate to regional_manager, and tournament_director accounts to regional_organizer; both receive the Latin America scope, replacing any previous country scope. Migration invalidates their existing sessions and tokens once.

Tournament management

1. Creating and configuring tournaments (/admin/tournaments)

2. Managing participants

3. Pairings, rounds, and entering results

Tournament round and pairings

Tournament round control panel: board pairings, result selector, handicap stones, and standings.

4. Round processing and rating updates

Data management

1. Import assistant with preview (/admin/import)

Import historical workbooks, match spreadsheets, or OpenGotha files: - Accepted formats: - Excel workbook (.xlsx): replaces the active dataset with full players and matches. - OpenGotha XML (.xml): imports tournament metadata, participants, pairings, and handicap stones. - Match CSV (.csv): columns date, white, black, result, and optional handicap (0-9). - Create a backup before importing a workbook that replaces the active data. - Imports are limited to 10 MiB per upload, 100 MiB of decompressed XLSX content, and 10,000 rows per worksheet, CSV, or combined OpenGotha participant/game set. Player imports at /admin/players retain tighter limits of 5 MiB and 1,000 players. - OpenGotha uploads from either /admin/import or /admin/tournaments use the same staged review and approval flow. Review or edit the tournament settings, operation summary, warnings, and participant decisions; the preview does not change the database. Use Approve and import only after reviewing the updated summary. If players or tournaments change while the preview is open, upload the file again. - Explicit player reconciliation: - Previews classify rows as Exact match, Fuzzy suggestion, New player, or Duplicate. - Authorized staff choose to link to existing players, create new players, or reject rows. - Metadata can be reviewed and edited before committing. - CSV is validated before writing: dates, results (1-0, 0-1, or 1/2-1/2), handicap, existing players, and row/field errors. Any error blocks the entire import; database writes are transactional. - XLSX previews identify the worksheet and row for invalid data and do not replace data when errors are present. Replacement still requires explicit confirmation and a verified pre-import backup. - OpenGotha previews warn about games whose players are missing from the XML. The final receipt reports counts, warnings, and rating state. The imported tournament remains a draft and has no immediate rating impact; when completed, eligible games can mark the affected date for recalculation. - If DEFER_RATING_REPLAY_ON_IMPORT is enabled, imports still complete but show a notice that ratings may remain stale until the deferred replay is run.

Import preview and reconciliation

Example import preview and reconciliation. OpenGotha tournament imports use a dedicated review-and-approval screen.

2. Player administration (/admin/players)

Selecting an initial category displays the rating with one decimal place; saving preserves the precise conversion to avoid lowering the category. Manually entered ratings retain their precision.

3. Match administration (/admin/matches)

4. Rating and category configuration (/admin/ratings and /admin/categories)

5. Result moderation queue (/admin/result-submissions)

Operational and security tasks

1. Backups and restore (/admin/backups)

Backup management

Backup list with create, restore, and delete actions.

2. User account management (/admin/users)

3. News publishing (/admin/news)

4. Audit review (/admin/audit)

5. Site analytics (/admin/analytics)

6. Application security settings (/admin/settings)

Troubleshooting guide

  1. Access Forbidden (403): verify your Organizer, Manager, or Administrator role and its matching geographic scope. Player imports, news, and moderation require a Manager or Administrator; database-wide operations require an Administrator.
  2. Cannot submit results as member: confirm in /admin/users that your user account is linked to an active player record.
  3. Import failures: - Ensure CSV files use UTF-8 encoding and contain required headers date, white, black, result. - Verify date format is YYYY-MM-DD and results are 1-0, 0-1, or 1/2-1/2. - Ensure handicap stones are within the valid 0-9 range.
  4. Missing SGF records: the reference is retained without showing a broken link. If the operator returns the file to uploads/sgf under its original stored filename, the link works again; a new upload gets a different name and must be linked explicitly.
  5. Database restoration: after restoring a backup, allow schema migrations and FTS5 indexing to complete before serving requests.
  6. Production security: store secrets (APP_SECRET_KEY, ADMIN_PASSWORD, SMTP credentials, reCAPTCHA keys) in server environment variables, never in source control.
^