Feel Pro Club Docs

Appearance

0006. Match Organization and Convocation ​

Status: Approved Author: Codex Created: 2026-03-09

Overview ​

This PRD defines the team-admin flow for creating a match, launching the convocation, and managing the summoned roster afterward. It also captures the ongoing list states for confirmed, pending, declined, known-substitute, and free-player invitees.

Problem Statement ​

The core promise of Feel Pro Club is that amateur games stop falling apart at the last minute. To support that promise, organizers and managers need a quick way to set up a match, publish the player requirement, notify the right players, and actively manage who confirmed, declined, or still needs a replacement.

Goals ​

  • Let organizers and managers create a playable match in a short wizard.
  • Turn the created match into a live convocation that can be managed from the team context.
  • Make it easy to replace dropped players with substitutes or players summoned from the market.

Success Metrics ​

  • High completion rate from match-start screen to active convocatoria.
  • Fast time from starting the wizard to having an active match visible in the team workspace.
  • Reduced number of unresolved pending spots close to kickoff.

Scope ​

In Scope ​

  • Match creation intro and four-step wizard.
  • Match cancellation during or after creation.
  • Match activation and persistence to the current team.
  • Summoned-player management after the convocatoria is live.
  • Push notifications to invited players.

Out of Scope ​

  • Opponent management, score entry, or post-match stats.
  • Venue booking, payment collection, or referee coordination.

Personas and Roles ​

  • Organizer: Creates the match, launches the convocatoria, manages replacements, and owns the highest level of match administration.
  • Manager: Has the same permissions as the organizer within match creation and convocation management.
  • Team member: Confirms or declines attendance from other surfaces such as Home or Team Profile.
  • Substitute or free player: Appears as an additional source of replacements once the organizer needs more players.

User Journey ​

  1. The organizer or manager enters match creation from the team workspace.
  2. The team admin selects a date, time, location, and football format.
  3. Launching the final step activates the match, generates the initial convocation, and returns the team admin to the team workspace.
  4. Invited players receive a push notification for the match invitation.
  5. The team admin opens the summoned players view to inspect confirmations, pending players, declines, known substitutes, and free players invited from the market.
  6. The team admin manages confirmations, rejections, reversions, and replacement invitations as the list evolves.

Functional Requirements ​

Match Creation Wizard ​

  1. Match creation shall begin from an explanatory start screen with a clear primary CTA and a cancel path back to the team workspace.
  2. The date step shall use a calendar that prevents selection of past dates.
  3. The time step shall support hour and quarter-hour minute selection.
  4. The location step shall integrate with an external address service such as Google Maps or an equivalent provider so the user enters a valid address.
  5. The football-format step shall support at least formats from 5-a-side through 11-a-side.
  6. The user shall be able to navigate back one step at a time without losing already entered values.
  7. Cancelling from any step shall require confirmation before discarding the setup flow.

Match Activation ​

  1. Completing the football-format step shall activate the match immediately.
  2. The selected football format shall determine the required player count for the convocatoria.
  3. The active match shall persist as the current team's next/live match so it survives team switching.
  4. Once active, the match shall become visible from the team workspace and other match-aware surfaces.
  5. Each team shall support only one active or upcoming match at a time in MVP.
  6. Creating a match shall send a push and in-app notification by default to all active players of the team.

Convocation Management ​

  1. The summoned players screen shall present sections in this order: confirmed players, players still waiting for confirmation, declined invitations, a strong visual divider, known substitutes, and free players.
  2. The screen shall show live progress toward the required number of confirmed players.
  3. When a known substitute is invited into the match, a duplicated row for that person shall appear in the pending-confirmation section while the original person remains listed in the known-substitutes section.
  4. When a free player is invited into the match, a duplicated row for that person shall appear in the pending-confirmation section while the original person remains listed in the free-players section.
  5. Any invited player shall be able to change their response between confirm and decline as many times as they want while confirmation capacity is still available and no time-window conflict exists.
  6. When a player attempts to confirm attendance, the system shall validate that none of the other matches they are already confirmed for has an overlapping time window. If a conflict exists, the confirmation shall be blocked with a clear explanation.
  7. Organizers and managers shall be able to reject any player from the confirmed list.
  8. Rejecting a confirmed player shall be reversible.
  9. Organizers and managers shall be able to manually move declined or pending players back into the confirmed list when product rules allow it.
  10. Organizers and managers shall be able to summon or cancel summons for known substitutes from inside the convocation view.
  11. Organizers and managers shall be able to summon or cancel summons for free players from inside the convocation view.
  12. Organizers and managers shall be able to remove market-summoned players from the convocation view.
  13. Inviting a known substitute or free player into the match shall send a push and in-app notification to that invited user.
  14. When a player confirms attendance, organizers and managers shall receive a push and in-app notification.
  15. When a player declines attendance, organizers and managers shall receive a push and in-app notification.
  16. When a player changes their response from confirmed to declined, organizers and managers shall receive a push and in-app notification.
  17. When an organizer or manager rejects a player from the confirmed list, the rejected player shall receive a push and in-app notification.
  18. When the number of confirmed players reaches the required count, organizers and managers shall receive a push and in-app notification.
  19. When a confirmed player declines or is rejected and the count drops below the required number, organizers and managers shall receive a push and in-app notification.
  20. A reminder notification (push and in-app) shall be sent to all players who have not yet responded as the match time approaches.
  21. When an organizer or manager cancels a summon for a known substitute or free player, the cancelled player shall receive a push and in-app notification.
  22. When the match format is changed after creation, a push and in-app notification shall be sent to all invited players for that match.

Match Cancellation ​

  1. Organizers and managers shall be able to cancel an already active match from the team workspace.
  2. Cancelling an active match shall require an explicit destructive confirmation.
  3. Cancelling an active match shall clear the current active match state from the team workspace.
  4. Cancelling an active match shall send a push and in-app notification to every player who was invited to that match, regardless of whether they had confirmed, declined, or not yet responded.
  5. Cancelling an active match shall also send a push and in-app notification to known substitutes and free players who had been explicitly invited into that match.
  6. Cancelling an active match shall not notify known substitutes or free players who were never called into that match.

Match Ending ​

  1. Organizers and managers shall be able to end an active match from the team workspace.
  2. Ending a match shall move it to a completed/archived state and free the team to create a new match.
  3. A new match cannot be created for a team while an active match exists.

Business Rules and Permissions ​

  • Organizers and managers have the same level of permissions for match creation, convocation management, and match cancellation.
  • Match creation is incomplete until date, time, location, and format are all present.
  • The required player count is derived from the selected format rather than manually entered.
  • Only one active or upcoming match may exist per team at a time in MVP.
  • Match creation notifies all active players of the team by default.
  • Known substitutes and free players are notified only when they are explicitly invited into the match.
  • Confirmed spots are assigned on a first-confirmed, first-kept basis until the required-player limit is reached.
  • Once the required-player limit is reached, no additional invited player may newly confirm unless a confirmed spot becomes available again.
  • An invited player may continue changing between confirm and decline, but a new confirmation can succeed only when capacity is available at that moment and no time-window conflict exists.
  • A match occupies a 2-hour time window: from 30 minutes before the scheduled start time through 90 minutes after it (30 min warm-up + 60 min match duration + 30 min cooldown). A player may not be confirmed for two matches whose time windows overlap.
  • When a team member leaves or is removed from a team, their confirmed attendance and pending invitations for all future matches of that team are automatically revoked. They are removed from all affected convocations without requiring organizer action.
  • A match with zero or insufficient confirmations at kickoff time remains active. Matches are never auto-cancelled; they must be ended or cancelled manually by an organizer or manager.
  • If the match format is changed after creation, the list of confirmed players is not affected. The confirmed player count may surpass the new format's required count.
  • When a player's account is deleted (GDPR hard-delete), they shall be automatically removed from all convocations they appear in.

UX Considerations ​

  • The wizard should keep one scheduling decision per screen to reduce organizer fatigue.
  • The convocation screen should feel operational and list-centric, with strong visibility into who is in, out, or still pending.
  • The confirmed, pending, and declined sections should be visually prioritized above the replacement pools for known substitutes and free players.
  • Destructive changes to a live convocatoria should always require confirmation when they remove someone already counted in the roster.
  • Address entry should feel trustworthy and precise, with map-backed validation rather than loose free-text guessing.

Error States ​

  • Match activation shall preserve all entered wizard data until the match is created. If the activation call fails, the organizer stays in the wizard with retry and no active-match success state is shown.
  • While activation is in flight, the flow shall block duplicate submits and back-navigation that would create ambiguity. If the user leaves the screen, re-entry shall show the request as still pending or return them to the intact draft.
  • If the maps or place-lookup dependency is unavailable, the location step shall show a service-unavailable state, preserve any prior selection, and offer retry rather than trapping the organizer in a broken step.
  • Convocation mutations that change attendance or summon state may update optimistically only with full rollback on failure, including player counts and section placement.
  • Capacity checks and 2-hour overlap checks shall be revalidated at confirmation time. If a player loses the last available spot or becomes conflicting because of concurrent actions, the UI shall explain why the confirmation failed and leave the player in a recoverable state.
  • A match cannot be activated with zero invited players. If the convocation is empty, the flow shall block activation and explain the missing prerequisite.
  • If notification fan-out fails after a match is created, changed, or cancelled, the match state still remains authoritative in Home and the team workspace, and the system shall retry delivery outside the current user flow.