From 95d7012ef85b7f61bc700d4db0351db3d8218f91 Mon Sep 17 00:00:00 2001 From: rxmox Date: Thu, 9 Apr 2026 18:38:48 -0600 Subject: [PATCH 1/2] Rewrite backend README with project overview, env var docs, and links to guides --- shatter-backend/README.md | 94 ++++++++++++++++++++++++++++++++------- 1 file changed, 77 insertions(+), 17 deletions(-) diff --git a/shatter-backend/README.md b/shatter-backend/README.md index 1919203..47e2852 100644 --- a/shatter-backend/README.md +++ b/shatter-backend/README.md @@ -1,27 +1,87 @@ -# Introduction +# Shatter Backend -Our backend uses: NodeJs + TypeScript + Express + MongoDB +Backend API for **Shatter**, a networking and icebreaker platform that helps facilitate engaging social interactions at events. Participants join events via QR code or join code and play icebreaker games, while organizers manage events through a web dashboard. -# How to run +**Built with:** Node.js · TypeScript · Express · MongoDB · Pusher -- Step 1: Clone the repo - -- Step 2: Enter to `shatter-backend` dir by running the command in the terminal -``` -cd shatter-backend -``` -- Step 3: Install the dependencies and libraries by running -``` +## Quick Start + +### Prerequisites + +- [Node.js](https://nodejs.org/) (v18+) +- [MongoDB](https://www.mongodb.com/) instance (local or Atlas) +- npm + +### Setup + +```bash +git clone https://github.com/techstartucalgary/Networking-Icebreakers.git +cd Networking-Icebreakers/shatter-backend npm i ``` -- Step 4: Run the backend -``` + +Create a `.env` file in `shatter-backend/` with the following variables: + +| Variable | Description | +|---|---| +| `MONGO_URI` | MongoDB connection string | +| `JWT_SECRET` | Random 32-character string for signing tokens | +| `JWT_EXPIRATION` | Token expiry duration (default: `30d`) | +| `LINKEDIN_CLIENT_ID` | LinkedIn OAuth app client ID | +| `LINKEDIN_CLIENT_SECRET` | LinkedIn OAuth app client secret | +| `LINKEDIN_CALLBACK_URL` | LinkedIn OAuth callback URL | +| `CORS_ORIGINS` | Comma-separated allowed origins (optional, allows all if unset) | +| `PUSHER_APP_ID` | Pusher app ID for real-time events | +| `PUSHER_KEY` | Pusher key | +| `PUSHER_SECRET` | Pusher secret | +| `PUSHER_CLUSTER` | Pusher cluster (e.g. `us2`) | + +### Run + +```bash npm run dev ``` -- Step 5: the backend will run localy in port 4000 (http://localhost:4000) -# Note -- Because you are working on backend, you will use Postman to test your API, but in some cases, you are expected to run frontend locally to test if needed, check the guide `shatter-web/readme.MD` -- Don't push changes directly to main, create your own branch and pull request to merge +The server starts at `http://localhost:4000`. + +## Project Structure + +``` +src/ +├── server.ts # Entry point: env validation, DB connection, server start +├── app.ts # Express config, CORS, route mounting +├── controllers/ # Route handlers (auth, users, events, bingo, connections, leaderboard) +├── middleware/ # JWT auth middleware +├── models/ # Mongoose schemas (User, Event, Participant, Bingo, etc.) +├── routes/ # Express route definitions +├── utils/ # JWT, password hashing, Pusher client, LinkedIn OAuth +└── types/ # TypeScript type declarations +``` + +All routes are prefixed with `/api`. See the [API Reference](docs/API_REFERENCE.md) for full endpoint documentation. + +## Documentation + +| Guide | Description | +|---|---| +| [API Reference](docs/API_REFERENCE.md) | Full endpoint documentation with request/response examples | +| [Database Schema](docs/DATABASE_SCHEMA.md) | MongoDB collections, fields, indexes, and relationships | +| [Event Lifecycle](docs/EVENT_LIFECYCLE.md) | Event state machine and transition rules | +| [Real-Time Events](docs/REALTIME_EVENTS_GUIDE.md) | Pusher channel and event reference | +| [Route Protection](docs/ROUTE_PROTECTION_GUIDE.md) | How to add JWT auth to new routes | +| [Bingo Walkthrough](docs/bingo_walkthrough.md) | Bingo game implementation details | +| [Feature List](docs/feature_list.md) | Feature overview and status | + +## Available Scripts + +| Command | Description | +|---|---| +| `npm run dev` | Start development server with hot reload (port 4000) | +| `npm run build` | Compile TypeScript to `dist/` | +| `npm start` | Run the production build | +## Contributing +- Don't push directly to `main`. Create a feature branch and open a pull request +- Use [Postman](https://www.postman.com/) to test API endpoints locally +- If you need to test with the frontend, see [`shatter-web/readme.MD`](../shatter-web/readme.MD) From 94a9fdca4b25ea63d4d4749f9f060691d9c32388 Mon Sep 17 00:00:00 2001 From: Omar Ahmed Date: Thu, 9 Apr 2026 18:40:38 -0600 Subject: [PATCH 2/2] Update contributing guidelines in README Removed reference to testing with the frontend in the README. --- shatter-backend/README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/shatter-backend/README.md b/shatter-backend/README.md index 47e2852..c352ac2 100644 --- a/shatter-backend/README.md +++ b/shatter-backend/README.md @@ -84,4 +84,3 @@ All routes are prefixed with `/api`. See the [API Reference](docs/API_REFERENCE. - Don't push directly to `main`. Create a feature branch and open a pull request - Use [Postman](https://www.postman.com/) to test API endpoints locally -- If you need to test with the frontend, see [`shatter-web/readme.MD`](../shatter-web/readme.MD)