Tournaments & Competitions

End-to-end competition management for golf clubs: create competitions, manage entries, score rounds, calculate handicaps, and publish results.

Module overview

• Package: @digiwedge/tee-time-services → TournamentsModule
• Persistence: @prisma/teetime (shared with core tee-time data)
• Env: TEETIME_DATABASE_URL (if unset, tournaments features are disabled gracefully)

Feature summary

Formats ↗

10 competition formats: Stableford, Stroke, Matchplay, team events, and more.

Scoring ↗

Stableford points, stroke play, countback tie resolution.

Handicaps ↗

WHS integration, PCC, CSS, and handicap posting.

Entries & Eligibility ↗

Player entries, divisions, eligibility rules, team events.

Draws & Pairings ↗

Random, handicap order, seeded, and tee-time draws.

Side Competitions ↗

Nearest pin, longest drive, 2's club.

Matchplay ↗

Brackets, seeding, hole-by-hole match scoring.

Results & Exports ↗

Leaderboards, finalization, CSV exports, domain events.

API Reference ↗

Complete endpoint documentation for competitions.

---

Key services

Service	Purpose
CompetitionsService	Create/update competitions, manage rounds, divisions, local rules
EntriesService	Player entries, team members, withdrawals
ScorecardsService	Hole-by-hole scoring, attestation, locking
ResultsService	Leaderboards, position assignment, finalization
DrawsService	Generate pairings (random, handicap order, seeded)
HandicapSnapshotService	Capture handicap index at entry time
HandicapPostingService	Post scores to GolfRSA/DotGolf
SeriesService	Order of Merit standings across events
SideCompetitionsService	Nearest pin, longest drive
MatchplayService	Bracket generation, seeding, match scoring
PrizeService	Prize allocation and descriptions
AppealsService	Open/update/resolve result appeals
ResultsExportService	CSV leaderboard exports
CompetitionTeeSheetSyncService	Sync tee-sheet bookings to entries

---

Competition lifecycle

┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   CREATE    │───▶│   ENTRIES   │───▶│    DRAW     │───▶│   SCORING   │
│ Competition │    │    Open     │    │  Generated  │    │  In Progress│
└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
                                                                │
                   ┌─────────────┐    ┌─────────────┐           │
                   │  COMPLETED  │◀───│  FINALIZE   │◀──────────┘
                   │   Results   │    │  Results    │
                   └─────────────┘    └─────────────┘

1. Create - Set up competition with format, rounds, divisions
2. Entries - Players enter, handicap snapshots captured
3. Draw - Generate pairings and tee times
4. Scoring - Hole-by-hole score entry, attestation
5. Finalize - Lock results, assign positions, post handicaps
6. Complete - Results published, events emitted

---

Data model

Entity	Purpose
Competition	Main competition record
CompetitionRound	Individual rounds with course/date
CompetitionDivision	Handicap/age/gender divisions
CompetitionEntry	Player entries
CompetitionTeamMember	Team member assignments
Scorecard	Round scorecards
HoleScore	Individual hole scores
HandicapSnapshot	Captured handicap at entry
CompetitionResult	Final positions
SideCompetitionResult	NTP/LD results
MatchplayBracket	Matchplay brackets
MatchplayMatch	Individual matches
DailyCourseConditions	PCC storage
Season	Season grouping

---

Quick start

Import the module

import { TournamentsModule } from '@digiwedge/tee-time-services';

@Module({
  imports: [TournamentsModule],
})
export class AppModule {}

Create a competition

const competition = await competitionsService.create({
  clubId: 'club-123',
  name: 'Monthly Medal',
  format: 'STABLEFORD',
  isHandicapQualifying: true,
  handicapAllowance: 100,
  rounds: [{
    roundNumber: 1,
    date: new Date('2025-12-15'),
    courseId: 'course-123',
    startType: 'TEE_TIMES',
  }],
  divisions: [
    { name: 'A Division', maxHandicap: 12 },
    { name: 'B Division', minHandicap: 13, maxHandicap: 24 },
  ],
});

---

Environment

Variable	Required	Description
TEETIME_DATABASE_URL	Yes	Prisma datasource for tournaments data
GolfRSA credentials	Optional	For handicap posting to GolfRSA
DotGolf credentials	Optional	For handicap posting to DotGolf

---

Testing

# Unit tests
pnpm nx test tee-time-services --testPathPattern=tournaments

# All tee-time-services tests
pnpm nx test tee-time-services --runInBand

Test coverage includes:

• Stableford calculations
• Countback tie resolution
• Handicap helpers (course handicap, PCC, CSS)
• Eligibility and division gates
• Appeals workflow
• Results and 2's club

---

Backend deep dive

For service‑level responsibilities, domain events, and operational guidance, see ./backend.md.