Stage 6A — Tournament Schemas, Admin Wizard & Registration

[KineticTactic]

What this is: The entry point for the knockout tournament system. No match engine logic — purely the data layer and the admin creation UI.

Starts after: Stage 4 complete.

Owner: Full-stack developer comfortable with multi-step forms and Mongoose.

Tasks

1. Verify tournament schemas against real usage (schemas were created in Stage 1; this stage validates them with actual documents)

   • Create test Contest documents with format: 'bracket', roomFormat: 'blitz' and roomFormat: 'arena'.
   • Verify ContestRound and ContestStanding work correctly for bracket structure.
   • Verify ContestRoom tournament context fields (nullable roundId, bracket position) do not affect standalone room queries. Run Stage 3 + 4 tests to confirm.

2. Tournament Creation Wizard (/internal/contests/admin/new-contest)

   • Multi-step form:
     • Step 1: name, description. Format is fixed: bracket. Room format: blitz or arena. Team size: 1 (1v1) or 3 (3v3).
     • Step 2: registration settings (open/closed, deadline, max participants).
     • Step 3: match preset selection.
     • Step 4: bracket settings (third-place playoff toggle, seeding method: CF rating or manual).
     • Step 5: preview & confirm.
   • Server-side validation on every step.
   • On submission: create Contest document with format: 'bracket', status: 'draft', roomFormat, teamSize.

3. Registration flow

   • POST /api/contests/:id/register — player or team registers.
   • Validates deadline, max participants.
   • Triggers solved:<cfHandle> prefetch BullMQ job for all registering members.
   • Appends to Contest.registrations.

4. Preset management (/internal/contests/admin/presets)

   • CRUD for ContestPreset. Archive (not delete). Archived presets are not shown in the creation wizard but are preserved in DB for historical reference.

5. Contest status transitions

   • draft → registration (admin publishes).
   • registration → active (admin starts or scheduled auto-start).
   • active → completed (all bracket rounds done).

Testing Gate

• Admin creates a knockout tournament (blitz rooms) via the wizard. Contest document in MongoDB has the correct shape: format: 'bracket', roomFormat: 'blitz', registrations: [], status: 'draft'.
• Admin creates a knockout tournament with arena rooms. Same shape, roomFormat: 'arena'.
• 4 players register. Contest.registrations updated. solved:* keys populated for all 4 CF handles.
• Registering after deadline → rejected.
• Preset archived → no longer appears in the wizard. A historical room referencing it still resolves correctly.

Handoff Contract

• All testing gate items pass.
• Contest documents for knockout format exist in the dev DB as test fixtures.
• Stage 3 + 4 regression still passes — tournament context fields are inert on standalone rooms.

---

[Ayan-Bain]

Stage 6A Implementation

This document details the modifications and new files introduced in the Stage 6A commit for the CCW Contest Platform (Knockout Tournament Data Layer & Admin Creation UI).

---

1. Schema & Model Enhancements

• CustomContest.ts:
  • Configured format to support 'bracket' knockout structures.
  • Restricted the status enum exclusively to ["draft", "registration", "active", "completed"].
  • Relaxed timing constraints by making startTime, endTime, and durationSeconds optional.
  • Added new fields: description, teamSize (1 or 3), registrations subdocument array, registrationSettings (deadline, type, max participants), and bracketSettings (third-place playoff toggle, seeding method).
  • Configured indexes for { format: 1, status: 1 }.
• ContestPreset.ts:
  • Added archived: Boolean field (defaulting to false) to filter active templates in the creator interface.
• ContestRoom.ts:
  • Added bracketPosition: String (nullable) to record tree positions (e.g. '3PO' for third-place playoff) without impacting standalone match query filters.
• ContestRound.ts:
  • Added bracketLevel: String (e.g., 'semifinal') to tag match round segments.
• ContestStanding.ts:
  • Added aggregate tournament performance variables: wins, losses, draws, and eliminated (defaulting to 0/false).

---

2. API Endpoints

• src/app/api/contests/presets/route.ts:
  • GET: Returns active presets. Supports ?includeArchived=true query.
  • POST (Admin only): Inserts new presets. Enforces unique names.
• src/app/api/contests/presets/[id]/route.ts:
  • GET: Retrieves preset by ID.
  • PUT (Admin only): Modifies configuration values.
  • PATCH (Admin only): Archives or restores presets.
• src/app/api/contests/[id]/register/route.ts:
  • POST: Enrolls user/team for tournament registration.
  • Handles solo (1v1) and team (3v3) registration flows.
  • Verifies registration deadlines, player verified CF handle requirements, and enqueues solved_prefetch BullMQ worker tasks.
• src/app/api/contests/[id]/status/route.ts:
  • PATCH (Admin only): Updates status values sequentially through the chain: draft -> registration -> active -> completed.
  • Emits updates via Server-Sent Events (SSE).

---

3. UI Component Additions

• Administration Landing (/admin):
  • Added navigation cards directing admins directly to Contest Presets and Create Tournament.
• Contest Presets Dashboard (/admin/contests/presets):
  • Premium table listing active and archived presets.
  • Modals supporting creation, editing, and toggle archiving operations.
• Tournament Creation Wizard (/admin/contests/new):
  • Step-by-step progress tracking circles connected by solid, center-aligned lines.
  • Form validation on steps (Basic Info, Registration, Preset Selection, Bracket/Seeding Settings, Preview).
  • Connects to backend server actions to validate and commit tournament documents.

---

4. Background Workers & Verification

• cfSyncWorker.ts:
  • Added a handler block for solved_prefetch jobs, calling the Codeforces integration API to cache user solve histories in Redis (solved:<cfHandle>) upon registration.
• scripts/test-stage6a.ts:
  • Created an automated test suite matching the specifications of the Stage 6A test plan.