Univent

<sub>ucode connect uevent "Univent" is the project of ucode connect the Track FullStack programming bootcamp
lasting 5 weeks (March 31, 2025 - May 2, 2025),
where the NestJS with TypeScript and React with Next.js were used to develop the event ticketing service.

The purpose: create an event ticketing service to unite people with the same interests
using the whole cycle of Challenge Based Learning framework with a team.</sub>

📑 Table of Contents

• 🗓️ About "Univent" Platform
• 🧑‍💻 Team
• 🗓 About "Univent" Backend
• 🎯 Features and Functionality
  • 🔐 Authentication & Authorization
  • 👥 User Management
  • 🏢 Company Management
  • 🎪 Event Management
  • 🎫 Ticketing System
  • 💳 Payment Processing
  • 🛒 Order Management
  • 🎟️ Promo Codes & Discounts
  • 📧 Email System
  • 🔔 Notification System
  • 📰 News Management
  • 📬 Subscription System
  • 📊 Event Analytics & Attendees
  • 🔍 Search & Filtering
  • 📱 File Management
  • 🏗️ Background Jobs & Scheduling
  • 🛡️ Security Features
  • 🔧 API Documentation
  • 🧪 Testing Infrastructure
• 👤 Use case diagram
• 🧲 Activity diagram
• 🚚 Deployment Diagram
• 📦 Database Diagram
• ⚙️ Requirements and Dependencies
• 🚀 How to Run the Solution
• 🐋 Docker
• 📫 Email Service
  • Gmail API Configuration
  • Development Testing with Ethereal
  • Email Templates
• 🔁 REST API documentation
  • API Features
• 📬 Postman
  • Structure of the Collection
    • 📁 Auth
    • 👥 Users
    • 🏢 Companies
    • 🎪 Events
    • 🎫 Tickets
    • 📰 News
    • 🔔 Notifications
    • 🛒 Orders
    • 💳 Payments
    • 🎟️ Promo Codes
  • Importing the Collection into Postman
• 📦 Migrations
  • Migration Commands
  • Seeding
• 🪲 Testing
• 👤 Fake Data
• 🏞 Unsplash

🗓️ About "Univent" Platform

Univent is a platform for creating, attending and managing events!

Organise events with interactive maps, buy tickets, use promo codes and receive notifications.

A user-friendly profile for everyone - from organisers to guests.

Here is a link to the presentation file.

🧑‍💻 Team

Inessa Repeshko

Andrew Laskevych

Denis Kolesnichenko

Maksym Hrytsenko

🗓 About "Univent" Backend

Univent is a dynamic ticketing platform designed to simplify event management and ticketing.

The Univent backend built on Node.js, NestJS, Express, and Prisma with MySQL, provides secure event, ticket, and payment management via Stripe, integration with Google API and Unsplash, authentication with JWT, Bcrypt, and Passport, as well as automation with PDFKit, QRCode, scheduling with @nestjs/schedule, documentation with Swagger, containerisation with Docker, and testing with Jest, Faker.js, ESLint, and Prettier.

🎯 Features and Functionality

Univent is a comprehensive event management platform that provides the following features:

🔐 Authentication & Authorization

• User Registration & Login with email verification
• Google OAuth 2.0 integration for social authentication
• JWT-based authentication with access and refresh tokens
• Password reset functionality with secure token validation
• Role-based access control for different user types
• Account email confirmation system

👥 User Management

• User profile management with avatar upload support
• Account settings and password management
• User dashboard with personalized content
• Account ownership guards for secure access control

🏢 Company Management

• Company registration and profile setup
• Company logo upload and management
• Company profile pages with detailed information
• Company ownership verification and access control
• Company-specific news publishing
• Company deletion with safety checks

🎪 Event Management

• Event creation and publishing with detailed metadata
• Event poster upload and management
• Multiple event formats support (conference, workshop, etc.)
• Event themes and categorization system
• Event status management (draft, published, ongoing, finished, cancelled)
• Event venue and location management
• Event scheduling with start and end times
• Ticket sales scheduling with availability windows
• Event attendee management and visibility controls
• Event updates and notifications to subscribers

🎫 Ticketing System

• Multiple ticket types per event with different pricing
• Ticket status management (available, reserved, sold, unavailable)
• Unique ticket number generation for each ticket
• PDF ticket generation with QR codes for verification
• Ticket file management and secure download
• Ticket verification system using QR codes

💳 Payment Processing

• Stripe payment integration for secure transactions
• Payment intent creation and management
• Multiple payment status tracking (pending, paid, failed, refunded)
• Automatic invoice generation and delivery
• Payment status synchronization with Stripe
• Refund handling and status updates

🛒 Order Management

• Shopping cart functionality for multiple tickets
• Order creation with item management
• Order status tracking throughout the purchase process
• Order history and detailed views
• PDF ticket access through secure order links
• Order confirmation emails with ticket attachments

🎟️ Promo Codes & Discounts

• Promo code creation with percentage-based discounts
• Event-specific promo codes with validation
• Promo code activation/deactivation controls
• Secure hash-based promo code storage
• Discount calculation and application to orders

📧 Email System

• Automated email notifications for various events
• Welcome emails for new users and companies
• Email confirmation for account verification
• Password reset emails with secure links
• Ticket confirmation emails with PDF attachments
• Multiple email themes support
• Gmail API integration for production email delivery
• Ethereal email for development testing

🔔 Notification System

• Real-time notifications for event updates
• Event status change notifications to subscribers
• Event date/venue change notifications
• New event announcements for company followers
• News publication notifications
• New attendee notifications for events
• Notification read/hide status management

📰 News Management

• Company news creation and publishing
• Event-specific news and announcements
• News editing and deletion by authorized users
• News visibility on company and event pages
• Automatic notifications for news publication

📬 Subscription System

• Event subscription for updates and notifications
• Company subscription for following organizations
• Automatic subscription when joining events
• Subscription management and unsubscribe options

📊 Event Analytics & Attendees

• Event attendee tracking and management
• Attendee visibility controls (public, attendees-only, private)
• Event aggregation and statistics
• Attendee list management for event organizers

🔍 Search & Filtering

• Event search and filtering by various criteria
• Company search and discovery
• Pagination support for large datasets
• Advanced filtering options for events and companies

📱 File Management

• Secure file upload for avatars, logos, and posters
• File type validation and size restrictions
• Organized file storage with proper directory structure
• Default placeholder images for entities

🏗️ Background Jobs & Scheduling

• JWT token cleanup scheduler
• User notification processing scheduler
• Automated background tasks for system maintenance

🛡️ Security Features

• CSRF protection with custom filters
• Request validation with comprehensive validators
• Input sanitization and type checking
• Secure password hashing using bcrypt
• Rate limiting and security headers
• Environment-based configuration management

🔧 API Documentation

• Comprehensive Swagger documentation for all endpoints
• Interactive API explorer at /api endpoint
• Detailed request/response schemas
• API versioning and security documentation

🧪 Testing Infrastructure

• Unit testing for all services and controllers
• End-to-end testing for complete user workflows
• Fake data generation for testing purposes
• Test database setup and teardown

👤 Use case diagram

🧲 Activity diagram

🚚 Deployment Diagram

📦 Database Diagram

⚙️ Requirements and Dependencies

Before starting, ensure the required technologies are installed.

• Node.JS >= v22.10
• NPM >= v10
• MySQL >= 8.0

🚀 How to Run the Solution

In the examples of all commands in the text <env> is the name of the environment to perform the migration, e.g. dev, test or prod.

1. Clone this repository and move to the project directory:

   git clone <repository-url> univent-backend
   cd univent-backend

2. Install all dependencies:

   npm install

3. For development purposes use dev environment. Configure the database connection by copying the .env.development.example to a new file .env.development. After that put your MySQL credentials of root user:

   # Database Root Configuration
   DB_ROOT_HOST=localhost
   DB_ROOT_PORT=3306
   DB_ROOT_USER=root
   DB_ROOT_PASSWORD=root
   

   Also, new DB user uevent_sql will be created after executing the next command. Credentials of uevent_sql user can be changed:

   # Database App Configuration
   DB_APP_HOST=localhost
   DB_APP_PORT=3306
   DB_APP_USER=univent_sql
   DB_APP_PASSWORD=securepass
   DB_APP_DATABASE=univent
   

   For test purposes use test environment: create .env.test file by copying the .env.test.example file.
4. Run script for create databases and user:

   npm run setup:db

5. Run command to apply necessary migrations.

   npm run migrate

6. Run command to create prisma client:

   npm run migrate:generate

7. Run command to build the project:

   npm run build

8. Seeds help you fill your database with initial data for a presentation or project launch. To start creating test data, run the command:

   npm run migrate:seed

   or run following command to rewrite data:

   npm run migrate:refresh

9. Start the server:

   npm run start:dev

10. Application will be launched on http://localhost:8080/api.

🐋 Docker

Environment variables are taken from .env.development file. You can start containers with the command:

docker-compose --env-file .env.development up -d

To view a list of containers:

docker ps -a

To stop running containers:

docker-compose stop

To stop and delete containers, networks, and associated resources (with volumes):

docker-compose down -v

📫 Mailing Service

The application uses Gmail API for production email delivery with OAuth2 authentication, providing reliable and secure email sending capabilities.

Gmail API Configuration

The application is configured to use Gmail API for sending emails in production. To set up Gmail integration:

1. Google Cloud Console Setup:
   • Create a project in Google Cloud Console
   • Enable Gmail API for your project
   • Create OAuth 2.0 credentials (Client ID and Client Secret)
   • Add your redirect URI for OAuth flow
2. Environment Configuration: Configure the following variables in your .env.development file:

   GOOGLE_GMAIL_USER=your-gmail@gmail.com
   GOOGLE_GMAIL_API_REFRESH_TOKEN=your_refresh_token
   GOOGLE_OAUTH_CLIENT_ID=your_client_id
   GOOGLE_OAUTH_CLIENT_SECRET=your_client_secret
   GOOGLE_OAUTH_REDIRECT_URI=your_redirect_uri

3. OAuth2 Flow:
   • Use Google OAuth2 flow to obtain refresh token
   • The application automatically refreshes access tokens as needed

Development Testing with Ethereal

For development and testing purposes, you can use Ethereal Email - a fake SMTP service where messages are captured but never delivered.

Default test credentials:

• login: ricky43@ethereal.email
• password: 4e1zbM2nxsMu2d823E

Email Templates

Email types supported:

• Account email confirmation
• Password reset notifications
• Welcome emails for new companies
• Ticket confirmation with PDF attachments

🔁 REST API documentation

The comprehensive API documentation is available at https://univent-platform.onrender.com/api or http://localhost:8080/api and provides:

• Interactive API Explorer: Built with Swagger UI, allowing you to test endpoints directly in the browser
• Complete Endpoint Coverage: Documentation for all available REST endpoints including authentication, users, companies, events, tickets, orders, promo codes, notifications, and payments
• Security Documentation: Clear indication of which endpoints require JWT authentication and CSRF tokens
• Request/Response Schemas: Detailed schema definitions with examples for all data structures
• Error Response Documentation: Comprehensive error codes and response formats
• Automated Security Annotations: The system automatically applies appropriate security requirements (JWT Bearer auth, CSRF tokens) based on route guards and decorators

API Features:

• JWT Authentication: Bearer token authentication for protected endpoints
• CSRF Protection: Cross-Site Request Forgery protection for state-changing operations
• Role-based Access Control: Different access levels for users, companies, and system operations
• Pagination Support: Cursor and offset-based pagination for large datasets
• File Upload Support: Endpoints for avatar, logo, and poster uploads
• Real-time Validation: Request validation with detailed error messages

The documentation is generated automatically from code annotations using @nestjs/swagger and includes operation sorting, filtering, and persistent authorization for easier testing.

📬 Postman

The univent.postman_collection.json file is a preconfigured Postman collection designed to simplify testing and interaction with the Univent API. This collection includes a comprehensive set of API requests organized into logical folders, covering authentication, user management, event handling, subscriptions, payments, notifications, promo codes, orders, and more. By importing this collection into Postman you can quickly set up and execute API calls to explore the Univent API's functionality.

Structure of the Collection

The univent.postman_collection.json file contains comprehensive API endpoint definitions organized into the following main categories:

📁 Auth

• Get CSRF token
• Register (user registration)
• Confirm email (email verification)
• Login / Login With Test User
• Refresh access token
• Logout
• Request password recovery
• Confirm password recovery

👥 Users

• Subscriptions: Get event/company subscriptions
• Notifications: Get user notifications (all, filtered, paginated)
• Get all users / Get user by ID / Get current user
• Get user companies and orders
• Update user profile and password
• Upload avatar

🏢 Companies

• News: Create/get company news
• Events: Get company events
• Subscriptions: Company subscription management
• Register company
• Get all companies (with query params, pagination)
• Get company by ID
• Update company / Upload logo
• Delete company

🎪 Events

• Formats: Get all formats / Get format by ID / Sync formats
• Themes: Get all themes / Get theme by ID / Sync themes
• Attendees: Update attendee visibility
• News: Create/get event news
• Promo codes: Create/validate event promo codes
• Tickets: Create/get event tickets
• Create event / Get events
• Update event / Upload poster
• Get event attendees / Get event subscriptions

🎫 Tickets

• Get all tickets
• Get ticket by ID
• Update ticket

📰 News

• Get news by ID
• Update news
• Delete news

🔔 Notifications

• Update notification status (mark as read/hidden)

🛒 Orders

• Create order
• Get order by ID

💳 Payments

• Create Stripe payment intent
• Handle Stripe webhooks

🎟️ Promo Codes

• Get promo code by ID
• Update promo code
• Validate promo code

Importing the Collection into Postman

Follow these steps to import and set up the Univent Postman collection:

1. Open Postman:
   • Launch the Postman application on your computer.
2. Import the Collection:
   • Click the Import button in the top-left corner of Postman.
   • In the import dialog, select Choose Files and navigate to the univent.postman_collection.json file in your project directory.
   • Alternatively, drag and drop the univent.postman_collection.json file into the import dialog.
   • Click Import to load the collection into Postman.
3. Verify the Collection:
   • Once imported, the "univent" collection will appear in the Collections sidebar on the left.
   • Expand the collection to view the organized folders (e.g., Auth, Users, Companies, Events, etc.).
   • The collection uses variables like {{url}}, {{csrfToken}}, {{accessToken}}, and {{refreshToken}} to dynamically configure requests.
   • Create a new Postman environment or update an existing one:
     • Click the Environments tab in Postman.
     • Create a new environment (e.g., "Univent") or select an existing one.
     • Add the following variables (initial values are provided in the collection's variable section):
     • url: Set to http://localhost:8080/api (or your API's base URL).
       • csrfToken: Initially set to a placeholder (e.g., 8gAKNsET-yxO1S-Qny8PrGewCQ_qnn5yc6qE). This will be updated automatically by the "Get CSRF Token" request.
       • accessToken: Placeholder for the JWT access token, updated by the "Login" or "Refresh Access Token" requests.
       • refreshToken: Placeholder for the JWT refresh token, updated by the "Login" request.
       • passwordResetLink and confirmEmailLink: Optional variables for password reset and email confirmation links.
       • baseUrl: Optional variable for additional URL configurations.
     • Save the environment and select it from the environment dropdown in Postman.
4. Test the Collection:
   • Start by running the Get CSRF Token request in the Auth folder. This request retrieves a CSRF token and stores it in the csrfToken variable using a Postman test script.
   • Proceed to the Register or Login requests to authenticate and obtain accessToken and refreshToken values, which are automatically stored by test scripts.
   • Use the authenticated tokens to test other endpoints (e.g., retrieving event subscriptions, creating orders, or validating promo codes).
   • Each request includes example responses in the collection, showing expected status codes (e.g., 200 OK, 201 Created, 422 Unprocessable Entity) and response bodies.

📬 Postman

The univent.postman_collection.json file is a preconfigured Postman collection designed to simplify testing and interaction with the Univent API. This collection includes a comprehensive set of API requests organized into logical folders, covering authentication, user management, event handling, subscriptions, payments, notifications, promo codes, orders, and more. By importing this collection into Postman you can quickly set up and execute API calls to explore the Univent API's functionality.

Structure of the Collection

The univent.postman_collection.json file is organized into several folders, each corresponding to a specific category of API endpoints. Below is an overview of the main folders and their test cases, as shown in the screenshots provided.

Importing the Collection into Postman

Follow these steps to import and set up the Univent Postman collection:

1. Open Postman:
   • Launch the Postman application on your computer.
2. Import the Collection:
   • Click the Import button in the top-left corner of Postman.
   • In the import dialog, select Choose Files and navigate to the /docs/postman/univent.postman_collection.json file in your project directory.
   • Alternatively, drag and drop the univent.postman_collection.json file into the import dialog.
   • Click Import to load the collection into Postman.
3. Verify the Collection:
   • Once imported, the "univent" collection will appear in the Collections sidebar on the left.
   • Expand the collection to view the organized folders (e.g., Auth, Users, Companies, Events, etc.), as shown in the screenshots (auth.png, users.png, companies.png, events.png, others.png).
4. Set Up Environment Variables:
   • The collection uses variables like {{url}}, {{csrfToken}}, {{accessToken}}, and {{refreshToken}} to dynamically configure requests.
   • Create a new Postman environment or update an existing one:
     • Click the Environments tab in Postman.
     • Create a new environment (e.g., "Univent") or select an existing one.
     • Add the following variables (initial values are provided in the collection's variable section):
     • url: Set to http://localhost:8080/api (or your API's base URL).
       • csrfToken: Initially set to a placeholder (e.g., 8gAKNsET-yxO1S-Qny8PrGewCQ_qnn5yc6qE). This will be updated automatically by the "Get CSRF Token" request.
       • accessToken: Placeholder for the JWT access token, updated by the "Login" or "Refresh Access Token" requests.
       • refreshToken: Placeholder for the JWT refresh token, updated by the "Login" request.
       • passwordResetLink and confirmEmailLink: Optional variables for password reset and email confirmation links.
       • baseUrl: Optional variable for additional URL configurations.
     • Save the environment and select it from the environment dropdown in Postman.
5. Test the Collection:
   • Start by running the Get CSRF Token request in the Auth folder. This request retrieves a CSRF token and stores it in the csrfToken variable using a Postman test script.
   • Proceed to the Register or Login requests to authenticate and obtain accessToken and refreshToken values, which are automatically stored by test scripts.
   • Use the authenticated tokens to test other endpoints (e.g., retrieving event subscriptions, creating orders, or validating promo codes).
   • Each request includes example responses in the collection, showing expected status codes (e.g., 200 OK, 201 Created, 422 Unprocessable Entity) and response bodies.

📦 Migrations

Migration Commands

1. Create new migration:

   npm run migrate:create --name <migration_name>

2. Apply migrations:

   npm run migrate

3. Generate Prisma client:

   npm run migrate:generate

4. Seed database with demo data:

   npm run migrate:seed

5. Reset and refresh database:

   npm run migrate:refresh

Seeding

The seeding system creates comprehensive demo data including:

• Users with various roles
• Companies with events and news
• Event formats and themes
• Tickets with different statuses
• Promotional codes and orders
• Subscriptions and notifications
• Event attendees with different visibility settings

🪲 Testing

For all commands in the text below, the environment is a test that uses the variables of the .env.test.example file.

1. Unit tests
   • Run all unit tests with a detailed report:

   npm run test:unit

   • Run one specific unit test file with a detailed report:

   npm run test:unit -- <file_name>

2. End-to-end (e2e) testing
   • Run all e2e tests with detailed report:

   npm run test:e2e

   • Run one specific e2e test file with a detailed report:

   npm run test:e2e -- <file_name>

3. All testing
   • Run all e2e and unit tests with detailed report:

   npm run test

👤 Fake Data

To fill the database with demo data of users, companies, events and tickets, run the following command:

npm run migarte:seed

Here is the fake data for presentations.

User data for testing:

• full name:

  Test User
  

• email:

  test.user@univent.com
  

All test users have a password:

Password123!$

🏞 Unsplash

Unsplash is the internet’s source of freely usable images.

To connect to the Unsplash, follow these steps:

1. Sign up for an account with Unsplash:
   • Go to (Unsplash Developers)[https://unsplash.com/developers] and sign in to your Unsplash account (or create a new one).
2. Create an app:
   • In the Your Applications section, click New Application.
   • Fill in the fields: name of the app (for example, Event App), description (for example, Get images for events).
   • Accept the terms and conditions.
3. Get the API key:
   • After creating the app, you will see the Access Key (and Secret Key if you need OAuth). The Access Key is your API key.
   • Copy the key and save it in a safe place.
4. After put your access key to the .env.development file:

   UNSPLASH_ACCESS_KEY=<API_key>

Note: In Development Mode, you have 50 requests per hour. To increase the limit (up to 5000 requests/hour), apply for production access via the Unsplash dashboard, providing use cases with attribution.

More information can be found in the Unsplash API Documentation.

---

© Inessa Repeshko. 2025