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
- Use Skip to content to bypass navigation. Menus work with keyboard and touch; press Esc to close them.
- Rating filters and category formulas remain usable if enhanced controls fail to load. Registration uses Google reCAPTCHA.
- Content, statistics, variable, and navigation cards share borders, corners, and responsive spacing. Player-directory and tournament-list cards are full-card links: activate the title, metadata, or inner space, or use the keyboard. Border and shadow feedback signal interaction, and keyboard focus stays visible. Admin player cards open the profile while Edit and Delete retain their separate actions. Cards containing tables, forms, or multiple destinations are not converted into a single link. Theme colors, each screen's alignment, full-card admin-menu links, and the highlighted rating remain.
Table of contents
- Accessibility and device support
- Public interface
- Member interface
- Administrator panel
- Troubleshooting guide
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.
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
- Rankings (
/rankings): filter the leaderboard by country, region, Sub-18, and female rankings. The administrator's default region is initially Latin America and also applies to the home-page leaderboard and API. Choose All regions to include players from every country; filters intersect. The country selector lists only countries currently assigned to players. The Sub-18 and female filters can be selected together. Country values use ISO 3166-1 alpha-3; legacy alpha-2 values are normalized. - Player directory (
/players): search by first or last name, filter by minimum and maximum rating range, filter by last active date, and sort by any column with configurable pagination. - Player profile (
/player/view?id=<id>): - Administrators, Managers, and Organizers see Edit only when their permissions and geographic scope authorize that player; it opens the existing admin editor.
- Summary of current rating, RD, volatility, and category.
- Career milestones: peak historical rating, longest winning streak, wins as White, and wins as Black.
- Public country with a small flag, birth year, and a female-player checkmark, plus top-five country, regional, Sub-18, and female ranking achievements when eligible. Profiles do not show a global rank badge.
- On Taiwan profiles, visitors from mainland China see Chinese Taipei without a flag; outside mainland China, the Taiwan flag is displayed. When location is unknown, the browser's preferred language is used: Simplified Chinese shows the alternative and all other languages show the flag. Detection depends on the local GeoLite database and available IP, so it may be approximate; see
GEOIP_COUNTRY_DBin the README for configuration. - Comparative activity, win, improvement, and best-rating achievements follow the administrator's region, independently of the rankings-page filters. With Latin America selected, only players from that region are compared; their games against out-of-region opponents still count. Players outside the region do not receive those comparative or country, regional, Sub-18, or female ranking achievements. All regions compares players from every country again. The organizer marker for linked accounts with staff roles is independent of region.
- Sub-18 eligibility uses calendar years:
ranking_year - 18 <= birth_year <= ranking_year(for example, 2008 through 2026 during 2026). The internal value9999identifies a Sub-18 player whose birth year is unknown; the profile displays that designation, not the value. The player remains eligible until the record is updated, so staff must review it. - Complete match history with date, color, opponent, result, event, and link to the SGF viewer if available. PairGo games appear in the same history, sorted by date, showing both teams, the PairGo badge, and a link to the game; they do not count toward statistics or head-to-head records. Unrated game/tournament badges are not displayed; rated-status controls and rules remain unchanged.
- Interactive rating evolution chart over time.
- Tournament history with initial seed rank and final standing position. Completed PairGo tournaments appear in both players' tournament histories like any other result and link only to the tournament page.
- Head-to-head opponent records table.
Public profile with current rating, category, and activity summary for the selected player.
Matches and SGF viewer
- Match list (
/matches): browse the entire match history with filters for date range and player, plus sorting by date, White player, Black player, result, or round. - SGF viewer (
/matches/<id>/recordand/sgf-library/<filename>): interactive SGF game viewer powered by BesoGo. Step through moves move-by-move, switch between Simple and Dark themes, and download the raw SGF file via direct link (/matches/<id>/sgfor/sgf/<filename>).
Public tournaments
- Tournament list (
/tournaments): displays active and completed tournaments with date, location, pairing system, round count, and status. Canceled tournaments are not listed. Draft tournaments and their games remain hidden from the public; Organizers, Managers, and Administrators can include drafts with the Show drafts option. - Tournament details (
/tournaments/<id>): view round-by-round pairings, table assignments, match results, and live standings with Dan/Kyu categories, points (Pts/MMS), SOS, SOSOS, and SODOS tiebreaks. For completed tournaments, standings appear before the pairings. Staff with edit permission and geographic scope over the tournament see Edit, which opens its administrative settings. - Canceled individual tournaments retain public direct-link detail access despite being omitted from lists; the authenticated API also permits those details with
tournaments:read. Canceled PairGo web detail pages remain staff-only. - Individual standings use the last rating calculated before the start date for the category. With no earlier rated games they use the initial rating; if the snapshot or start date is unavailable they use the entry seed rating. Pending entries use their entry rating and PairGo retains its team category. Same-day games are not treated as earlier because their time is not recorded; the category does not change the seed-rating tiebreak.
Tournament details with round selector, board pairings, results, and standings.
Period reports and export
- Reports screen (
/reports): analyze player performances over custom and standard time periods: - Predefined periods: All time, This year, This quarter, or Custom date range.
- Optional player filter to inspect records against individual opponents, clubs, and countries during the period.
- Date ranges
start_dateandend_dateare inclusive and evaluated in the server's fixed timezone (UTC-5). - The player table shows 25 results per page by default, with options for 50 or 100. Page navigation preserves active filters. Pagination only limits rendered HTML rows; report data and exports continue to use the full period and filters.
- Matches with invalid dates or results are excluded and tallied in the report summary.
- CSV export (
/reports/export.csv): downloads a CSV spreadsheet reflecting the exact calculated report table and active filters. - PDF export (
/reports/export.pdf): generates a formatted PDF document with centered headers, generation date, current language, and the selected player and period in the filename.
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
- Open
/admin/registerto create an account with username, email, and password (minimum 8 characters). The form is protected by Google reCAPTCHA v3. - New accounts are automatically assigned the
memberrole. - 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).
User profile settings for language, theme, timezone, and password management.
Password recovery
- If you forget your password, click Forgot password? on
/admin/loginor navigate to/admin/forgot-password. - Enter your registered email address. If found, the system dispatches a single-use cryptographically hashed reset link.
- Reset links expire according to
PASSWORD_RESET_TTL_SECONDS(default: 3600 seconds / 1 hour). - 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:
- 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. - 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
.sgfgame record.
- 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.
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)
- Name, venue, country, and dates: enter the official title, city/location, tournament country, and start/end dates. The explicit country determines the geographic scope of tournament operations.
- Round count: set total scheduled rounds.
- PairGo format: choose PairGo when creating the event to play in two-player teams, with no gender restrictions. All four pairing systems are available; the players' average rating determines the team's category and seed. The format cannot be changed after creation. PairGo is always unrated.
- Pairing system:
- Standard Swiss (
swiss): pairs players with identical or close scores, avoiding rematches and alternating colors. - Category Swiss (
swiss_cat): restricts pairings strictly within rating categories for a specified initial number of rounds. - Accelerated Swiss (
accelerated_swiss): divides participants into acceleration bands (Go 3-band scheme or custom category limits) during initial rounds to speed up convergence. Bonuses use whole points; custom decimal values are not valid. - McMahon (
mcmahon): assigns starting McMahon scores (MMS) based on rating using the McMahon Bar (mm_bar), Floor (mm_floor), and Zero (mm_zero). Bar and floor use category selectors from9 danto30 kyuin settings and import reviews, and category labels in overviews; zero remains numeric. Legacy values outside that range are retained as a selected option. Saving preserves stored values and pairing rules; bar must remain above floor. - BYE and absence points:
- BYE points: points awarded to an odd unassigned player (default: 1.0 point).
- Absence points: points awarded for unplayed absence games (default: 0.0 points).
- Automatic handicap: enable or disable automatic handicap stone suggestions calculated from category differences.
- Tournament rating: Rated tournament is checked by default. Uncheck it so that, once completed, the tournament and its games remain public without affecting ratings; those games are labeled unrated.
- Quick list actions: the tournament list, filters, Copy selected tournaments, and Delete selected tournaments buttons appear before the create and import forms, without per-row action buttons. Use the table-header checkbox to select or clear all tournaments on the current page.
- Copy tournaments in bulk: select up to 100 tournaments and choose Copy selected tournaments to create one draft per tournament with its settings and participants. Dates, pairings, and results are not copied. If any tournament is invalid or outside your scope, none are copied; retrying the same request does not duplicate the copies.
- Delete tournaments in bulk: select tournaments on the current page and confirm deletion. Their rounds, pairings, participants, and linked tournament matches are removed; SGF files are retained.
2. Managing participants
- PairGo teams: use Manage teams to select two distinct active players per team. A player can belong to only one team in an event. When rounds remain, a team added after a completed round joins the next one; if the current round is open, it must participate in that round. Editing or removing a paired team requires confirmation that all its round pairings and results will be deleted; re-pair the affected boards afterward. Copying an event retains teams but not rounds or results.
- Add participants in bulk: select multiple available players on the participant-management page and add them in one action.
-
Remove participants in bulk: select multiple enrolled players and confirm removal. The operation is atomic; if any selected player cannot be removed (for example, because they have already been paired), none are removed.
-
Register players: add existing active players via the selector or create a pending player in the tournament. When a similar name is detected, a dialog identifies the tournament, entered name, and candidate: use the suggested player, review the entry, or create the player anyway. For existing pending players, accept the candidate or keep them pending. Escape closes the dialog; nobody is linked without an explicit action. If JavaScript or native dialogs are unavailable, the suggestion and actions remain on the page.
- Withdraw participants: remove players before round 1 begins.
- OpenGotha XML import: direct uploads at
/admin/tournamentsopen a review of the settings, planned operations, warnings, and rating impact. No data changes until you explicitly approve. You can link participants, accept a suggestion, create players, leave them pending, or skip them; update the operation summary after changing decisions and approve again. The tournament is created as a draft, and approval expires after 15 minutes.
3. Pairings, rounds, and entering results
- Generate round: automatically pairs players using the chosen pairing system, preventing past rematches and balancing colors.
- BYE handling: when participant count is odd, assigns a BYE automatically. The engine tracks BYE history so no player receives a second BYE while other participants have not received one.
- Manual and assisted pairing:
- Pair selected: choose two unpaired participants and click Pair Selected.
- Unpair / Unpair all: dissolve a specific board pairing or reset the entire round.
- Handicap adjustment per board: each board displays the suggested handicap stones; the Organizer can adjust stones before saving results.
- 7-state result cycling: click the winner's name or result text to advance through:
1.
-: Pending result. 2.1-0: White victory. 3.1/2-1/2: Draw. 4.0-1: Black victory. 5.1-!0: White wins by Black absence / forfeit. 6.!0-1: Black wins by White absence / forfeit. 7.!0-0: Both players absent (double forfeit). Clicking the winning player again clears the result back to pending (-). - Player categories: each pairing shows a compact category (for example
5dor3k) beside each player's name.
Tournament round control panel: board pairings, result selector, handicap stones, and standings.
4. Round processing and rating updates
- Process round (
Procesar ronda): - Materializes played individual game results (
1-0,1/2-1/2,0-1) into official database matches. PairGo results remain games of their tournament pairings, appear in the public match list and in all four players' match histories; they never enter rating or individual-statistic calculations. - Absence results (
1-!0,!0-1,!0-0) count toward tournament standings and tiebreaks but are never converted into rating matches. - Applies logarithmic rating adjustments for handicap stones if present.
- For individual tournaments, triggers incremental rating recomputation ordered chronologically by date and round.
- Standings and tiebreaks: standings positions are unique and sequential. Ties in points or MMS are resolved deterministically by SOS, SOSOS, SODOS, base rating, and alphabetical name.
- Ordering and migrations: within a day, rating updates use round number and then insertion order. Round notes are stored as integers when possible; unknown rounds use round 1. Tournament tables migrate automatically at startup.
- Tournament lifecycle:
- Draft (
draft): hidden from public view during organization. - Active (
active): published and visible with live pairings and standings. - Completed (
completed): concluded tournament with final standings. If Rated tournament is unchecked, its games still appear in public lists and profiles but do not affect ratings. - Canceled (
canceled): omitted from the public list, and its matches do not affect ratings. - Player profiles list completed tournaments only. Active tournament games do not affect ratings until completion; drafts and canceled tournaments are omitted from public lists and their games do not affect ratings. Canceled individual details remain accessible by direct link.
- Result exports: OpenGotha export is available for individual tournaments, not PairGo.
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.
Example import preview and reconciliation. OpenGotha tournament imports use a dedicated review-and-approval screen.
2. Player administration (/admin/players)
- Located under Players and competition for Organizers, Managers, and Administrators. The separate CSV/XLSX import action belongs to Imports and ratings and requires a Manager or Administrator.
- Filter players by name, rating range, and active status.
- Import players: upload CSV or XLSX with
Name,Rank, andCountrycolumns. Use Go ranks from30kthrough9d(for example,5kor1d); Country may be blank. Review the row-level validation preview before confirming the import. Existing or duplicate names and invalid rows block the whole import. - Edit player (
/admin/players/edit?id=<id>): update name, display name, initial rating, country, optional birth year, a checkbox indicating a female player, and active status. Demographic values are public; birth year is used for the Sub-18 ranking. If the player is known to be Sub-18 but their birth year is unknown, leave the year blank and select Sub-18 (birth year unknown). Clear the checkbox to remove that designation or replace it with a known year; both cannot be supplied together. - Delete player: safe confirmation modal warning about cascade deletion of associated match history.
- Initial Category and Initial Rating: choose a category from the 9 dan to 30 kyu dropdown to update the initial rating, or edit the rating to update the selected category. Both fields remain editable, without a mode selector or help text. Empty ratings or ratings outside the category range leave the selection blank without changing the rating. The base conversion is
rating = m * exp((c + 29) / k), wherec = dan - 1orc = -kyu, plus the configured initial offset. Players without matches also update their current rating; players with history use the normal replay workflow. Immediate synchronization requires JavaScript; without it, category changes apply on save if the rating is unchanged; if both fields change, the rating takes precedence.
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)
- Located under Players and competition, subject to geographic scope.
- Paginated list of all matches with date and player filters.
- Add match (
/admin/matches/add): form with strict date validation (YYYY-MM-DD), distinct player validation, result validation (1-0,0-1,1/2-1/2), handicap stones (0-9), and optional SGF upload. - Edit match (
/admin/matches/edit?id=<id>): update players, dates, results, or round notes. - When tournament results become official matches,
eventkeeps the tournament name andnotes(shown asRound) stores the round as an integer. Legacy values are converted when they contain a number; text without a number is kept and treated as round 0. - SGF attachment & deletion: link existing SGF records from the library or upload new files.
4. Rating and category configuration (/admin/ratings and /admin/categories)
- Glicko-2 parameters:
- Default initial rating (e.g., 1500).
- Default initial rating deviation (RD, e.g., 350).
- Default initial volatility ($\sigma$, e.g., 0.06).
- System constant $\tau$ (e.g., 0.5).
- Category parameters:
- Scale constant $k$ and offset $m$.
- Initial rating offset (default +5 points; 0 disables it). Applies to categories of newly imported players, manually created pending players, and initial-category edits; if it would reach the next category, it is capped at the midpoint of the selected category. Directly entered ratings and imported pending ratings are unchanged. Migration and settings saves update unlinked manual pending entries whose category is known or unambiguously identifiable; other pending entries and existing players are not automatically updated. Changing settings does not regenerate existing pairings.
- Minimum category thresholds for Dan and Kyu levels.
- Rating recalculation:
- Full recompute: rebuilds entire rating history from scratch ordered by date and round.
- Incremental replay: recalculates snapshots starting from the earliest modified date (dirty date).
- Status changes that add or remove completed tournament games mark the earliest affected date; ratings update when one of these actions is run.
5. Result moderation queue (/admin/result-submissions)
- Review pending game submissions from community members.
- Inspect submitter, opponent, colors, result, date, handicap stones, and attached SGF record.
- Approve: materializes the match in the official database and triggers rating recomputation.
- Reject: rejects the submission and records a review note for audit tracking.
Operational and security tasks
1. Backups and restore (/admin/backups)
- Located under Site administration; all backup operations remain administrator-only.
- Create backup: generates a timestamped, integrity-verified SQLite backup in
backups/. SGF files stay inuploads/sgf; the backup keeps only the links from match records to them. - Restore backup:
- Before restoring, saves a verified snapshot of the current database as
*-pre-restore-*.dbinbackups/. - Prepares the restored copy, runs pending database migrations on it, and verifies it before replacing the active database. If any step fails, the active database is left unchanged.
- Rebuilds full-text search artifacts and the FTS5 search index (
players_fts). - Leaves
uploads/sgfunchanged. References to missing SGF files remain stored and are ignored until the files return under the same names. - Restricts candidate backups to managed files and designated
.bakfallbacks. - Scheduled backups: backups created by the
scripts/scheduled_backup.pyjob are listed here with the manual ones. The job keeps the newestSCHEDULED_BACKUP_KEEPscheduled backups (default 14) and never deletes manual, pre-import, or pre-restore backups. - Operational status (administrators only): shows when ratings first became dirty, the latest replay outcomes, scheduled backup and restore-check outcomes, retention, manual restores, and failed admin actions. New events are limited to 180 days and 2,000 entries; older events with unknown timezones are retained indefinitely. New times are displayed in the viewer's timezone, while older values are shown as recorded. Public pages show only whether ratings are current, stale, or unavailable; they do not expose the internal date.
- Restore drill: scheduled backups are restored and verified in a temporary database before old backups are pruned. Practice a full restore only on a disposable instance, then verify both the database and SGF files.
- Maintenance window: before replacing the active database, block new writes and let in-flight requests finish during the final swap. If application traffic cannot be paused, schedule the restore for a maintenance window; open SQLite readers can prevent the atomic replacement, especially on Windows.
- SGF protection: the application never backs up or restores
uploads/sgf; SQLite stores only filenames and links. If file protection is desired, the operator must copy and restore that directory separately outside the application. - Delete backups: purge older backups to free storage space.
- Run
python scripts/check_legacy_players_state.pyto audit the active database and managed backups.
Backup list with create, restore, and delete actions.
2. User account management (/admin/users)
- Create and edit accounts with roles
administrator,country_organizer,regional_organizer,country_manager,regional_manager, ormember. - Assign a country to Country roles or a supported region to Regional roles. A linked player's country is a fallback only for Country roles. Missing or incompatible scopes do not grant geographic access. Changes to a role or scope invalidate existing sessions and tokens.
- Link user accounts to player profiles to enable result reporting.
- Assign account-specific IANA timezones; a valid previously saved zone outside the suggested options remains visible when editing the account.
- Activate or deactivate user logins.
3. News publishing (/admin/news)
- Located under Content and game records, available to Managers and Administrators. News is shared site-wide content, not country-scoped.
- Compose news articles with title, body, and status (Draft or Published).
- Insert smart tags:
[player:12],[tournament:5],[match:104], rendered publicly as interactive links and SGF badges.
4. Audit review (/admin/audit)
- Comprehensive audit trail of all state-changing operations: imports, tournament lifecycle, match edits, rating changes, user updates, and backups.
- Filter by acting user, action category, free-text query, and date range.
- Compact JSON payload capped at 2 KiB per event. New events are displayed and filtered in the viewer's timezone and pruned after 730 days (
AUDIT_RETENTION_DAYS); older events with unknown timezones are shown as recorded and retained indefinitely. - New events are ordered by UTC instant; legacy events follow in recording order because their exact chronological order cannot be recovered.
5. Site analytics (/admin/analytics)
- Administrator-only report of successful public HTML page views and approximate daily visitors over the last 30 days.
- Authenticated requests, administration routes, and user agents that look like bots are excluded. Bot detection is approximate.
- A temporary 24-hour cookie contains only the date and avoids counting the same browser more than once a day. Clearing or blocking cookies can inflate counts; visits on different days count again, so period totals are visitor-days, not unique people.
- When GeoLite2 is available, the request IP is used only in memory to obtain a country from the local database; this feature does not save it in the analytics database. Hosting access logs are separate. Missing locations are grouped as unknown. IPs, visitor identifiers, paths, user agents, and referrers are not stored by this feature.
- Aggregates live in a separate SQLite file with the
.analytics.dbsuffix beside the primary database; application backups/restores exclude it. Daily totals and countries are retained for 400 days and pruned at startup and on the first write or administrative report of each new day, without restarting workers.
6. Application security settings (/admin/settings)
- Configure maximum failed login attempts before temporary IP block.
- Adjust rate-limiting time window (in seconds).
- Configure password reset token lifetime (TTL).
- Set the player name format:
Last name, First name(default),First name Last name, or a custom template with{first_name}and{last_name}. Names are displayed in this format; saving a change does not modify stored data. When editing a player, you can enter an optional custom name. First and last names cannot contain commas. - Set the default ranking and achievement region to Latin America (initial default) or All regions. This affects the home-page leaderboard, web and API rankings, and profile achievements, but not the player directory.
- The reset button restores application defaults, including the Latin America ranking region.
- The review of other global administrator settings is tracked in F24 of the roadmap.
Troubleshooting guide
- 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.
- Cannot submit results as member: confirm in
/admin/usersthat your user account is linked to an active player record. - Import failures:
- Ensure CSV files use UTF-8 encoding and contain required headers
date,white,black,result. - Verify date format isYYYY-MM-DDand results are1-0,0-1, or1/2-1/2. - Ensure handicap stones are within the valid 0-9 range. - Missing SGF records: the reference is retained without showing a broken link. If the operator returns the file to
uploads/sgfunder its original stored filename, the link works again; a new upload gets a different name and must be linked explicitly. - Database restoration: after restoring a backup, allow schema migrations and FTS5 indexing to complete before serving requests.
- Production security: store secrets (
APP_SECRET_KEY,ADMIN_PASSWORD, SMTP credentials, reCAPTCHA keys) in server environment variables, never in source control.







