cat resource.md
Claude Generated Technical Specification
A technical specification generated by Claude as part of a workshop with work experience students.
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