Skip to content

Str 110 update bingo cell structure to have full question and short version #87

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lnqminh3003 merged 6 commits into from
Mar 24, 2026
Merged

Str 110 update bingo cell structure to have full question and short version #87

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
41d03c0
Added new format for bing_grid response to include a short version of…
rodolfo-gp Mar 19, 2026
1e3c01a
fixed some type bugs
rodolfo-gp Mar 20, 2026
09d894d
added bingo route documentation
rodolfo-gp Mar 20, 2026
e89c83a
Fix bingo model schema, validation, and error handling for BingoTile …
rxmox Mar 22, 2026
b3d627b
Update bingo docs to reflect BingoTile grid format
rxmox Mar 22, 2026
74ea597
fix get bingo game by eventId
lnqminh3003 Mar 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
174 changes: 126 additions & 48 deletions shatter-backend/docs/API_REFERENCE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,42 +7,55 @@

## Table of Contents

- [General Information](#general-information)
- [Endpoint Summary](#endpoint-summary)
- [Authentication (`/api/auth`)](#authentication-apiauth)
- [POST /api/auth/signup](#post-apiauthsignup)
- [POST /api/auth/login](#post-apiauthlogin)
- [GET /api/auth/linkedin](#get-apiauthlinkedin)
- [GET /api/auth/linkedin/callback](#get-apiauthlinkedincallback)
- [POST /api/auth/exchange](#post-apiauthexchange)
- [Users (`/api/users`)](#users-apiusers)
- [GET /api/users](#get-apiusers)
- [POST /api/users](#post-apiusers)
- [GET /api/users/me](#get-apiusersme)
- [GET /api/users/:userId](#get-apiusersuserid)
- [GET /api/users/:userId/events](#get-apiusersuseриdevents)
- [PUT /api/users/:userId](#put-apiusersuserid)
- [Events (`/api/events`)](#events-apievents)
- [POST /api/events/createEvent](#post-apieventscreateevent)
- [GET /api/events/event/:joinCode](#get-apieventseventjoincode)
- [GET /api/events/:eventId](#get-apieventseventid)
- [PUT /api/events/:eventId/status](#put-apieventseventidstatus)
- [POST /api/events/:eventId/join/user](#post-apieventseventиdjoinuser)
- [POST /api/events/:eventId/join/guest](#post-apieventseventиdjoinguest)
- [GET /api/events/createdEvents/user/:userId](#get-apieventscreatedeventsuseriduserid)
- [Bingo (`/api/bingo`)](#bingo-apibingo)
- [POST /api/bingo/createBingo](#post-apibingocreatebingo)
- [GET /api/bingo/getBingo/:eventId](#get-apibingogetbingoeventid)
- [PUT /api/bingo/updateBingo](#put-apibingoupdatebingo)
- [Participant Connections (`/api/participantConnections`)](#participant-connections-apiparticipantconnections)
- [POST /api/participantConnections/](#post-apiparticipantconnections)
- [POST /api/participantConnections/by-emails](#post-apiparticipantconnectionsby-emails)
- [DELETE /api/participantConnections/delete](#delete-apiparticipantconnectionsdelete)
- [GET /api/participantConnections/getByParticipantAndEvent](#get-apiparticipantconnectionsgetbyparticipantandevent)
- [GET /api/participantConnections/getByUserEmailAndEvent](#get-apiparticipantconnectionsgetbyuseremailandevent)
- [GET /api/participantConnections/connected-users](#get-apiparticipantconnectionsconnected-users)
- [Planned Endpoints](#planned-endpoints-)
- [Quick Start Examples](#quick-start-examples)
- [Shatter Backend — API Reference](#shatter-backend--api-reference)
- [Table of Contents](#table-of-contents)
- [Endpoint Summary](#endpoint-summary)
- [General Information](#general-information)
- [Authentication](#authentication)
- [Response Format](#response-format)
- [Common Status Codes](#common-status-codes)
- [Authentication (`/api/auth`)](#authentication-apiauth)
- [POST `/api/auth/signup`](#post-apiauthsignup)
- [POST `/api/auth/login`](#post-apiauthlogin)
- [GET `/api/auth/linkedin`](#get-apiauthlinkedin)
- [GET `/api/auth/linkedin/callback`](#get-apiauthlinkedincallback)
- [POST `/api/auth/exchange`](#post-apiauthexchange)
- [Users (`/api/users`)](#users-apiusers)
- [GET `/api/users`](#get-apiusers)
- [POST `/api/users`](#post-apiusers)
- [GET `/api/users/me`](#get-apiusersme)
- [GET `/api/users/:userId`](#get-apiusersuserid)
- [GET `/api/users/:userId/events`](#get-apiusersuseridevents)
- [PUT `/api/users/:userId`](#put-apiusersuserid)
- [Events (`/api/events`)](#events-apievents)
- [POST `/api/events/createEvent`](#post-apieventscreateevent)
- [GET `/api/events/event/:joinCode`](#get-apieventseventjoincode)
- [GET `/api/events/:eventId`](#get-apieventseventid)
- [PUT `/api/events/:eventId/status`](#put-apieventseventidstatus)
- [POST `/api/events/:eventId/join/user`](#post-apieventseventidjoinuser)
- [POST `/api/events/:eventId/join/guest`](#post-apieventseventidjoinguest)
- [GET `/api/events/createdEvents/user/:userId`](#get-apieventscreatedeventsuseruserid)
- [Bingo (`/api/bingo`)](#bingo-apibingo)
- [POST `/api/bingo/createBingo`](#post-apibingocreatebingo)
- [GET `/api/bingo/getBingo/:eventId`](#get-apibingogetbingoeventid)
- [PUT `/api/bingo/updateBingo`](#put-apibingoupdatebingo)
- [POST `/api/bingo/generate`](#post-apibingogenerate)
- [Participant Connections (`/api/participantConnections`)](#participant-connections-apiparticipantconnections)
- [POST `/api/participantConnections/`](#post-apiparticipantconnections)
- [POST `/api/participantConnections/by-emails`](#post-apiparticipantconnectionsby-emails)
- [DELETE `/api/participantConnections/delete`](#delete-apiparticipantconnectionsdelete)
- [GET `/api/participantConnections/getByParticipantAndEvent`](#get-apiparticipantconnectionsgetbyparticipantandevent)
- [GET `/api/participantConnections/getByUserEmailAndEvent`](#get-apiparticipantconnectionsgetbyuseremailandevent)
- [GET `/api/participantConnections/connected-users`](#get-apiparticipantconnectionsconnected-users)
- [Planned Endpoints ⏳](#planned-endpoints-)
- [Quick Start Examples](#quick-start-examples)
- [1. Sign up](#1-sign-up)
- [2. Log in](#2-log-in)
- [3. Create an event](#3-create-an-event)
- [4. Join the event (as authenticated user)](#4-join-the-event-as-authenticated-user)
- [5. Join the event (as guest)](#5-join-the-event-as-guest)
- [6. Create a bingo game for the event](#6-create-a-bingo-game-for-the-event)
- [7. Get the bingo game](#7-get-the-bingo-game)

---

Expand Down Expand Up @@ -848,9 +861,9 @@ Create a bingo game for an event.

| Field | Type | Required | Notes |
|---------------|------------|----------|-------|
| `_eventId` | ObjectId | Yes | Must reference an existing event |
| `description` | string | No | |
| `grid` | string[][] | No | 2D array of strings |
| `_eventId` | ObjectId | Yes | Must reference an existing event |
| `description` | string | No | |
| `grid` | BingoTile\[\]\[\] | No | 2D array of `{ question: string, shortQuestion: string }` |

**Success Response (201):**

Expand All @@ -863,9 +876,16 @@ Create a bingo game for an event.
"_eventId": "665a...",
"description": "Networking Bingo",
"grid": [
["Has a pet", "Speaks 3 languages", "Loves hiking"],
["Works remotely", "Free space", "Plays guitar"],
["From another country", "Has a blog", "Codes in Rust"]
[
{ "question": "Has a pet", "shortQuestion": "Has pet" },
{ "question": "Speaks 3 languages", "shortQuestion": "Speaks languages" },
{ "question": "Loves hiking outdoors", "shortQuestion": "Loves hiking" }
],
[
{ "question": "Works remotely full-time", "shortQuestion": "Works remotely" },
{ "question": "Free space", "shortQuestion": "Free space" },
{ "question": "Plays guitar regularly", "shortQuestion": "Plays guitar" }
]
]
}
}
Expand All @@ -877,7 +897,7 @@ Create a bingo game for an event.
|--------|-------|
| 400 | `"_eventId is required"` |
| 400 | `"_eventId must be a valid ObjectId"` |
| 400 | `"grid must be a 2D array of strings"` |
| 400 | `"grid must be a 2D array of { question: string, shortQuestion: string }"` |
| 404 | `"Event not found"` |

---
Expand All @@ -903,7 +923,12 @@ Get bingo by event ID (or bingo ID).
"_id": "bingo_a1b2c3d4",
"_eventId": "665a...",
"description": "Networking Bingo",
"grid": [["Has a pet", "Speaks 3 languages", ...], ...]
"grid": [
[
{ "question": "Has a pet", "shortQuestion": "Has pet" },
{ "question": "Speaks 3 languages", "shortQuestion": "Speaks languages" }
]
]
}
}
```
Expand All @@ -926,9 +951,9 @@ Update a bingo game.

| Field | Type | Required | Notes |
|---------------|------------|----------|-------|
| `id` | string | Yes | Bingo `_id` or event `_eventId` |
| `description` | string | No | |
| `grid` | string[][] | No | 2D array of strings |
| `id` | string | Yes | Bingo `_id` or event `_eventId` |
| `description` | string | No | |
| `grid` | BingoTile\[\]\[\] | No | 2D array of `{ question: string, shortQuestion: string }` |

**Success Response (200):**

Expand All @@ -945,14 +970,67 @@ Update a bingo game.
|--------|-------|
| 400 | `"id is required"` |
| 400 | `"description must be a string"` |
| 400 | `"grid must be a 2D array of strings"` |
| 400 | `"grid must be a 2D array of { question: string, shortQuestion: string }"` |
| 400 | `"Nothing to update: provide description and/or grid"` |
| 404 | `"Bingo not found"` |

**Special Behavior:** Tries to find by `_id` first, then falls back to `_eventId`.

---

### POST `/api/bingo/generate`

Generate an AI-powered bingo grid based on a given context.

- **Auth:** Protected

**Request Body:**

| Field | Type | Required | Notes |
|-----------|--------|----------|-------|
| `context` | string | Yes | Context used to generate bingo content |
| `n_rows` | number | Yes | Number of rows (1–5) |
| `n_cols` | number | Yes | Number of columns (1–5) |

**Example Request:**

```json
{
"context": "Software engineer networking event where developers meet, discuss tech stacks, exchange ideas, talk about startups, open source, AI, and career opportunities",
"n_rows": 2,
"n_cols": 2
}
```

**Example Response:**
```
{
"status": true,
"bingo_grid": [
[
{
"question": "Sketches architecture on a napkin",
"shortQuestion": "Napkin architecture"
},
{
"question": "Shows a product demo on phone",
"shortQuestion": "Phone product demo"
}
],
[
{
"question": "Explains their open-source contribution",
"shortQuestion": "Open-source contribution"
},
{
"question": "Asks 'What's your current stack?'",
"shortQuestion": "Current stack question"
}
]
]
}
```

## Participant Connections (`/api/participantConnections`)

### POST `/api/participantConnections/`
Expand Down
2 changes: 1 addition & 1 deletion shatter-backend/docs/DATABASE_SCHEMA.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -177,7 +177,7 @@
| `_id` | String | Auto | Auto | Custom: `bingo_<8 random chars>` |
| `_eventId` | ObjectId | Yes | — | Refs `Event` |
| `description` | String | No | — | |
| `grid` | [[String]] | No | — | 2D array of strings |
| `grid` | [[{ question: String, shortQuestion: String }]] | No | — | 2D array of BingoTile objects |

### Pre-Save Hooks

Expand Down
2 changes: 2 additions & 0 deletions shatter-backend/src/ai/prompts/bingo_short_questions.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
You will generate the bingo grid with shortened version of the questions while maintaining the same structure.
Each entry should be turned into a max 3 word version of the question that describes what the question is about.
Loading
Loading