Game Night Organiser — Technical Specification

Version: 1.0
Date: March 2026
Status: Draft

---

1. Recommended Tech Stack

Layer	Technology	Reasoning
Frontend	React	Component-based UI suits the multiple interactive views (scheduling, voting, leaderboard). Large community and easy to find help.
Styling	Tailwind CSS	Utility-first CSS framework that makes mobile-friendly design fast to build
Backend	Node.js + Express	Lightweight and beginner-friendly. Well suited to a simple REST API.
Database	PostgreSQL	Reliable relational database — good fit for structured data like sessions, players, and votes
Hosting	Render or Railway	Free tiers available, simple deployment, good for MVPs
Unique links	UUID generation	Each group gets a unique ID baked into their URL (e.g. /group/abc123)

---

2. System Architecture Overview

┌─────────────────────────────────────────┐
│              User's Browser             │
│           (React Frontend)              │
└───────────────────┬─────────────────────┘
                    │ HTTP Requests (REST API)
                    ▼
┌─────────────────────────────────────────┐
│         Node.js / Express Backend       │
│              (REST API)                 │
└───────────────────┬─────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────┐
│            PostgreSQL Database          │
└─────────────────────────────────────────┘

How it works:

• The React frontend runs in the user’s browser and makes requests to the backend API
• The Express backend handles all business logic (e.g. calculating best date, tallying votes)
• PostgreSQL stores all persistent data — groups, players, sessions, votes, and scores
• No authentication server is needed — group identity is handled via the unique URL

---

3. Data Models

These are the key entities (tables) in the database and the information stored against each one.

3.1 Group

Represents a single game night group, identified by a unique link.

Field	Type	Description
id	UUID	Unique identifier, used in the group URL
name	String	Display name of the group
created_at	Timestamp	When the group was created

---

3.2 Player

Represents a named participant within a group.

Field	Type	Description
id	UUID	Unique identifier
group_id	UUID	The group this player belongs to
name	String	Display name entered on first visit
created_at	Timestamp	When the player first joined

---

3.3 SchedulingRound

Represents one scheduling exercise — a set of proposed dates that members vote on.

Field	Type	Description
id	UUID	Unique identifier
group_id	UUID	The group this round belongs to
status	Enum	open, closed, confirmed
confirmed_date	Date	The final agreed date (once confirmed)
created_at	Timestamp	When the round was opened

---

3.4 DateOption

A single candidate date within a scheduling round.

Field	Type	Description
id	UUID	Unique identifier
round_id	UUID	The scheduling round this belongs to
date	Date	The proposed date

---

3.5 Availability

Records whether a player is available for a given date option.

Field	Type	Description
id	UUID	Unique identifier
date_option_id	UUID	The date being responded to
player_id	UUID	The player submitting availability
available	Boolean	Whether they can attend

---

3.6 GameNight

Represents a confirmed and completed game night session.

Field	Type	Description
id	UUID	Unique identifier
group_id	UUID	The group this session belongs to
date	Date	When the session took place
game_name	String	Name of the game played
duration_minutes	Integer	How long the session lasted
mvp_player_id	UUID	Player awarded MVP
created_at	Timestamp	When the record was created

---

3.7 GameResult

Stores the individual result for each player in a game night.

Field	Type	Description
id	UUID	Unique identifier
game_night_id	UUID	The session this result belongs to
player_id	UUID	The player
score	Integer	Points scored (if applicable)
won	Boolean	Whether this player won

---

3.8 GameSuggestion & Vote

A game suggested for an upcoming night, and votes cast against it.

GameSuggestion

Field	Type	Description
id	UUID	Unique identifier
group_id	UUID	The group this belongs to
game_name	String	Name of the suggested game
suggested_by	UUID	Player who suggested it
status	Enum	open, confirmed

GameVote

Field	Type	Description
id	UUID	Unique identifier
suggestion_id	UUID	The suggestion being voted on
player_id	UUID	The player casting the vote

---

4. API Endpoints

These are the key routes the backend will expose to the frontend.

Groups

Method	Endpoint	Description
POST	/api/groups	Create a new group, returns unique group ID
GET	/api/groups/:groupId	Get group details and members

Players

Method	Endpoint	Description
POST	/api/groups/:groupId/players	Register a new player name in the group

Scheduling

Method	Endpoint	Description
POST	/api/groups/:groupId/scheduling	Open a new scheduling round with date options
GET	/api/groups/:groupId/scheduling/current	Get the current open scheduling round
POST	/api/scheduling/:roundId/availability	Submit availability for a player
POST	/api/scheduling/:roundId/confirm	Confirm the best date and close the round

Game Voting

Method	Endpoint	Description
GET	/api/groups/:groupId/suggestions	Get all current game suggestions and vote counts
POST	/api/groups/:groupId/suggestions	Add a new game suggestion
POST	/api/suggestions/:suggestionId/vote	Cast a vote for a suggestion
POST	/api/suggestions/:suggestionId/confirm	Confirm a suggestion as the chosen game

Game Nights & Results

Method	Endpoint	Description
POST	/api/groups/:groupId/gamenights	Create a new completed game night record
GET	/api/groups/:groupId/gamenights	Get all past game nights for a group
POST	/api/gamenights/:nightId/results	Submit player results for a game night

Leaderboard

Method	Endpoint	Description
GET	/api/groups/:groupId/leaderboard	Get all-time stats per player

---

5. MVP Scope & Suggested Build Order

Rather than building everything at once, here is the recommended order to get to a working product as quickly as possible. Each stage produces something usable.

Stage 1 — Foundation (Build first)

• Set up the project structure (React frontend + Express backend)
• Create the database and run migrations for all data models
• Build group creation and the shared link system
• Allow players to enter their name on first visit

✅ Milestone: A shareable group page where members can identify themselves

---

Stage 2 — Scheduling

• Build the scheduling round creation flow
• Allow members to submit their availability against proposed dates
• Display availability responses and highlight the best date
• Allow the host to confirm a date

✅ Milestone: The group can agree on a date for their next game night

---

Stage 3 — Game Voting

• Allow any member to suggest a game
• Display suggestions with live vote counts
• Allow members to vote
• Allow the host to confirm the chosen game

✅ Milestone: The group can decide what to play before the night

---

Stage 4 — Score Tracking

• Build the results entry form (game, date, duration, scores, MVP)
• Save results to the database
• Display a history log of past game nights

✅ Milestone: The group has a permanent record of their sessions

---

Stage 5 — Leaderboard (Nice-to-have)

• Aggregate results data per player (wins, points, MVP count)
• Build and display the leaderboard page

✅ Milestone: Full product complete — all features live

---

End of Technical Specification v1.0