Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
40 changes: 40 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
name: CI
on: [push, pull_request]

jobs:
server:
runs-on: ubuntu-latest
services:
mongo:
image: mongo:7
ports: ["27017:27017"]
defaults:
run:
working-directory: server
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
cache: npm
cache-dependency-path: server/package-lock.json
- run: npm ci
- run: npm run typecheck
- run: npm test

client:
runs-on: ubuntu-latest
defaults:
run:
working-directory: client
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
cache: npm
cache-dependency-path: client/package-lock.json
- run: npm ci
- run: npm run lint
- run: npx tsc --noEmit
- run: npm run build
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -26,3 +26,4 @@ yarn-debug.log*
.agents/
client/AGENTS.md
client/CLAUDE.md
.claude/
202 changes: 139 additions & 63 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,104 +1,180 @@
# EventHive

A full-stack event management platform where organizers create events and attendees discover & book tickets.
A full-stack event platform: organizers publish events and sell General and VIP tickets; attendees discover events, book seats, get QR-coded tickets, and review events they attended.

## Tech Stack
**Live demo:** https://event-hive-zeta.vercel.app

## Tech stack

| Layer | Technology |
|-------|------------|
| Frontend | Next.js 14, TypeScript |
| Backend | Express, TypeScript |
| Database | MongoDB |
| Auth | JWT + bcrypt |
| Architecture | Layered (Controller → Service → Repository) |
| Frontend | Next.js 16 (App Router, server components, CSS Modules), TypeScript, Phosphor icons, qrcode.react |
| Backend | Express 5, TypeScript, zod validation |
| Database | MongoDB with Mongoose (indexes enforce one ticket and one review per user per event) |
| Auth | JWT, stored in an httpOnly cookie on the Next.js origin and forwarded to the API by a same-origin proxy |
| Tests / CI | `node:test` API suite against a local MongoDB, GitHub Actions |
| Architecture | Layered (Controller → Service → Repository) with a single error middleware |

## Design system

## Project Structure
- **Palette:** the default light theme is colourful: each category owns one colour (music pink, tech blue, sports lime, art orange, food yellow, business violet, other teal) used on its cards, chips, rows and tickets, with ink buttons. The optional dark theme keeps a single stage-light magenta accent. Every text colour pair is at least 4.5:1; ratios are noted in `client/src/app/globals.css`.
- **Type:** Archivo (condensed via its width axis) for display, Geist for body and UI, Geist Mono for ticket codes.
- **Signature:** the admission ticket. Event cards, the booking panel, My Tickets and the organizer band use real notch cut-outs (CSS masks) and a perforated tear line.
- **Motion:** the landing page is deliberately loud: letters that pop in and jump under the cursor, a rotating colour-changing headline word, a cursor-following glow, parallax shapes, floating tickets with 3D tilt, magnetic buttons, crossing marquee bands, count-up stats, a pinned horizontal-scroll "Coming up" gallery, categories that slide in from alternating sides, a holographic organizer ticket whose stub tears on hover, and a rainbow scroll-progress bar, a live countdown sticker for the next event, a "Surprise Me" slot-machine pick with confetti, a statement whose words paint in as you scroll while event photos trail the cursor, and a sticky-stack "How it works" with live mini previews (chips, a stamped ticket, a scanning QR). Elsewhere: the theme switch grows out of its button as a circle (View Transitions API), confetti on a successful booking, event cards tilt toward the cursor, a navbar that turns into a glass pill on scroll, a card-to-page image morph (React `<ViewTransition>`), and a stamp when a booking succeeds. All pure CSS plus one delegated pointer listener; everything settles under `prefers-reduced-motion`.
- **Photography:** seed events and categories use subject-matched Unsplash photos (Unsplash License).

## How a request flows

```
Browser ──► Next.js server ──► Express API ──► MongoDB
│ server components fetch data with the user's token
│ /api/* proxy forwards browser mutations and sets the auth cookie
└─ proxy.ts guards /dashboard and /bookings
```
├── client/ # Next.js frontend

- The browser never calls Express directly, so there is no CORS layer and the token never touches JavaScript.
- `POST /api/auth/login` and `/register` return the user; the Next.js proxy keeps the token in an httpOnly cookie (`SameSite=Lax`, 7 days).
- Public pages (home, events, event detail) are server-rendered with real metadata (title, description, Open Graph image).
- Every write is validated with zod on the server; unknown fields are stripped, so clients cannot set `organizerId` or `bookedCount`.

## Project structure

```
├── client/ # Next.js frontend
│ └── src/
│ ├── app/ # Pages (Home, Events, Auth, Dashboard, Bookings)
│ ├── components/ # Navbar, Footer, EventCard
│ ├── lib/ # API client
│ └── types/ # TypeScript interfaces
├── server/ # Express backend
│ ├── app/ # Routes (server components) + client islands
│ │ ├── api/[...path]/ # Same-origin proxy to the Express API (sets/clears the auth cookie)
│ │ ├── events/ # Listing with filters + pagination, event detail (booking, reviews)
│ │ ├── bookings/ # My tickets with QR codes and cancellation
│ │ ├── dashboard/ # Organizer: stats, create/edit events, attendees
│ │ └── auth/ # Login / register
│ ├── components/ # Navbar, Footer, EventCard, EventForm, ConfirmButton, …
│ ├── lib/ # server.ts (SSR fetch + session), api.ts (browser mutations), session.ts, categories.ts
│ ├── proxy.ts # Route protection (Next 16 "proxy", formerly middleware)
│ └── types/
├── server/ # Express backend
│ └── src/
│ ├── config/ # Database singleton
│ ├── controllers/
│ ├── interfaces/ # IPaymentGateway abstraction
│ ├── middleware/ # Auth + RBAC
│ ├── models/ # Mongoose schemas (User, Event, Booking, Review)
│ ├── repositories/
│ ├── routes/
│ └── services/
├── idea.md # Project concept document
└── *Diagram.* # UML diagrams (Class, ER, Sequence, Use Case)
│ ├── index.ts # App (exported for Vercel and tests); server.ts listens locally
│ ├── schemas.ts # zod request schemas
│ ├── config/ # Database singleton
│ ├── controllers/ # Thin: parse input, call a service, send JSON
│ ├── services/ # Business rules (ownership, booking and review rules)
│ ├── repositories/ # Mongoose queries
│ ├── models/ # User, Event, Booking, Review (+ indexes), Ticket factory
│ ├── middleware/ # auth (JWT), rbac, errorHandler
│ ├── interfaces/ # IPaymentGateway + mock gateways
│ ├── seed.ts # Demo data
│ └── tests/ # API tests (node:test)
├── .github/workflows/ci.yml
├── idea.md # Project concept document
└── *Diagram.* # UML diagrams (Class, ER, Sequence, Use Case)
```

## OOP & Design Patterns
## Features

- **Discover:** search, category and date filters (all in the URL), pagination, past events, "More like this" on every event, and a ⌘K / Ctrl+K quick search across events, categories and pages.
- **Save:** heart any event; saved events live on `/saved`.
- **Book:** General or VIP tickets, confetti on success, QR-coded tickets under My Tickets, cancellation with refund.
- **Plan:** add an event to Google Calendar or download an `.ics` file (Apple Calendar, Outlook); share via the native share sheet or copy the link.
- **Host:** create and edit events, see revenue and sales, list attendees, and run a **check-in desk** at the door (type the code or scan the QR with the camera where the browser supports `BarcodeDetector`); each ticket can only be admitted once.
- **Review:** attendees rate events after they end.

## Business rules

- **Check-in:** only the event's organizer (or an admin) can admit tickets; codes are case-insensitive; the update is atomic so a ticket scanned twice is admitted once; cancelled tickets are refused.
- **Booking:** only published, upcoming events; one confirmed ticket per user per event (database unique index, race-safe); seats are decremented atomically and returned if anything fails after the decrement; VIP costs double; the mock payment's transaction id is stored and refunded on cancellation; no cancellation once the event has started.
- **Reviews:** only attendees with a confirmed ticket, only after the event has ended, one review per user; the endpoint returns the average and count.
- **Events:** organizers manage only their own events (admins can manage any); the attendee list (names, emails) is visible only to the event's organizer.
- **Registration** can only create `attendee` or `organizer` accounts.

## OOP and design patterns

- **Inheritance**: `User` ← `Attendee` / `Organizer` / `Admin`; `Event` ← `OnlineEvent` / `VenueEvent`
- **Abstraction**: `IPaymentGateway` interface with `MockPaymentGateway` implementation
- **Abstraction**: `IPaymentGateway` interface with mock Stripe/PayPal implementations
- **Factory**: `TicketFactory` creates VIP / General tickets
- **Singleton**: `Database` connection
- **Singleton**: `Database` connection (cached across serverless invocations)
- **Encapsulation**: `BaseController` response helpers; services hide rules from controllers

## Setup (Local Development)
## Local development

### Prerequisites
- Node.js ≥ 18
- MongoDB running locally (or a MongoDB Atlas URI)

- Node.js 20 or newer
- MongoDB running locally (`brew services start mongodb-community` on macOS) or a MongoDB Atlas URI

### Backend

```bash
cd server
npm install
cp .env.example .env # Then edit .env with your values
npm run dev # Starts on http://localhost:5001
cp .env.example .env # set MONGODB_URI and a random JWT_SECRET
npm run seed # demo users, 11 events, bookings and reviews
npm run dev # http://localhost:5001/api
```

Demo logins created by the seed (password `password123`): `organizer@eventhive.dev`, `organizer2@eventhive.dev`, `attendee@eventhive.dev`, `attendee2@eventhive.dev`.

### Frontend

```bash
cd client
npm install
npm run dev # Starts on http://localhost:3000
cp .env.example .env.local # API_URL=http://localhost:5001/api
npm run dev # http://localhost:3000
```

### Checks

```bash
cd server && npm run typecheck && npm test # tests use mongodb://localhost:27017/eventhive_test
cd client && npm run lint && npx tsc --noEmit && npm run build
```

## Deployment
CI runs the same checks on every push (`.github/workflows/ci.yml`) with a MongoDB service container.

## Deployment (Vercel, two projects)

**Backend** — root directory `server`, deployed as a serverless function (`vercel.json`):

| Variable | Value |
|----------|-------|
| `MONGODB_URI` | MongoDB Atlas connection string (allow Vercel's IPs in Atlas Network Access) |
| `JWT_SECRET` | a long random string |
| `JWT_EXPIRES_IN` | `7d` |

**Frontend** — root directory `client`:

| Variable | Value |
|----------|-------|
| `API_URL` | `https://<your-backend>.vercel.app/api` |

### Backend (Vercel)
1. Push code to GitHub
2. Create a new Project on [Vercel](https://vercel.com)
3. Set root directory to `server`
4. Add environment variables in settings:
- `MONGODB_URI` = your MongoDB Atlas connection string
- `JWT_SECRET` = a strong random string
- `JWT_EXPIRES_IN` = `7d`
- `CORS_ORIGIN` = your Vercel frontend URL
5. Deploy (Vercel will use `vercel.json` to deploy it as a Serverless API)
`API_URL` is server-only; the browser talks to the frontend's own `/api/*` proxy.

### Frontend (Vercel)
1. Import the GitHub repo on [Vercel](https://vercel.com)
2. Set root directory to `client`
3. Add environment variable:
- `NEXT_PUBLIC_API_URL` = `https://your-backend-url.onrender.com/api`
4. Deploy
## API

## API Endpoints
All routes are under `/api`. Responses are `{ success, data }` or `{ success: false, error }`; list endpoints add `pagination`.

| Method | Endpoint | Auth | Description |
|--------|----------|------|-------------|
| POST | `/api/auth/register` | No | Register user |
| POST | `/api/auth/login` | No | Login |
| GET | `/api/events` | No | List events |
| GET | `/api/events/search` | No | Search events |
| POST | `/api/auth/register` | No | Register (`attendee` or `organizer`) |
| POST | `/api/auth/login` | No | Login, returns user + token |
| GET | `/api/events` | No | List published upcoming events: `q`, `category`, `eventType`, `from`, `to`, `page`, `limit` |
| GET | `/api/events/:id` | No | Event detail |
| POST | `/api/events` | Organizer/Admin | Create event |
| GET | `/api/events/my/events` | Organizer/Admin | My managed events |
| PUT | `/api/events/:id` | Organizer/Admin | Update event |
| DELETE | `/api/events/:id` | Organizer/Admin | Delete event |
| POST | `/api/bookings` | User | Book ticket |
| GET | `/api/events/my/events` | Organizer/Admin | My events with revenue |
| PUT | `/api/events/:id` | Owner/Admin | Update event |
| DELETE | `/api/events/:id` | Owner/Admin | Delete event (cancels its bookings) |
| POST | `/api/bookings` | User | Book a ticket (`eventId`, `ticketType`) |
| GET | `/api/bookings/my` | User | My bookings |
| PATCH | `/api/bookings/:id/cancel` | User | Cancel booking |
| GET | `/api/bookings/event/:eventId` | Organizer/Admin | Event attendees/bookings |
| POST | `/api/reviews` | User | Leave review |
| GET | `/api/reviews/event/:eventId` | No | List reviews for event |
| PATCH | `/api/bookings/:id/cancel` | User | Cancel a booking (refund, seat released) |
| GET | `/api/bookings/event/:eventId` | Owner/Admin | Attendees of an event |
| POST | `/api/bookings/check-in` | Owner/Admin | Admit a ticket at the door (`eventId`, `code`); once only |
| GET | `/api/me/saved` | User | My saved events |
| GET | `/api/me/saved/ids` | User | Ids of my saved events |
| PUT | `/api/me/saved/:eventId` | User | Save an event (idempotent) |
| DELETE | `/api/me/saved/:eventId` | User | Remove a saved event |
| POST | `/api/reviews` | Attendee of the event | Leave a review after the event ends |
| GET | `/api/reviews/event/:eventId` | No | Reviews with `averageRating` and `reviewCount` |
| GET | `/api/health` | No | Health check |

Errors use proper status codes: 400 validation, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict (duplicate ticket, sold out, duplicate review).
8 changes: 4 additions & 4 deletions client/.env.example
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Client Environment Variables
# Copy this file to .env.local and fill in your actual values
# Next.js requires browser-available variables to start with NEXT_PUBLIC_
# Copy this file to .env.local and fill in your values

# The URL of your backend API
NEXT_PUBLIC_API_URL=http://localhost:5001/api
# Server-only: the Next.js server (pages + /api proxy) calls the Express API here.
# The browser never talks to Express directly.
API_URL=http://localhost:5001/api
7 changes: 6 additions & 1 deletion client/next.config.ts
Original file line number Diff line number Diff line change
@@ -1,7 +1,12 @@
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
/* config options here */
// Lighthouse and crawlers that do not run JavaScript get metadata in <head> instead of streamed into the body
htmlLimitedBots: /Chrome-Lighthouse|Bingbot|DuckDuckBot|Slurp|Baiduspider|YandexBot|facebookexternalhit|Twitterbot|LinkedInBot|Applebot/i,
images: {
// Organizers paste any https image URL for their event
remotePatterns: [{ protocol: "https", hostname: "**" }],
},
};

export default nextConfig;
24 changes: 24 additions & 0 deletions client/package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 2 additions & 0 deletions client/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,9 @@
"lint": "eslint"
},
"dependencies": {
"@phosphor-icons/react": "^2.1.10",
"next": "16.2.1",
"qrcode.react": "^4.2.0",
"react": "19.2.4",
"react-dom": "19.2.4"
},
Expand Down
Loading
Loading