🌌 EventFlow

EventFlow is a modern, high-performance, and scalable Event Management & Ticketing platform designed with a Microservices Architecture. Built using NestJS and TypeScript, it handles user authentication, event creation, secure ticket purchasing, real-time check-ins, and event-driven email notifications using Apache Kafka as the event broker and PostgreSQL powered by Drizzle ORM.

---

🛠️ Tech Stack & Badges

To support massive scalability and clear separations of concerns, EventFlow relies on a robust set of modern technologies:

Technology	Description
	Core framework for REST API and microservices
	Strict type safety across apps and libraries
	Event-driven architecture and asynchronous message broker
	Reliable relational data storage
	Next-generation lightweight ORM and schema migrations
	Containerized local infrastructure for development
	Fast, disk-space efficient package workspace manager
	Transactional email mock testing dashboard

---

🚀 Key Features

EventFlow is split into functional microservices that communicate using REST APIs for synchronous requests and Apache Kafka for asynchronous event flows:

🛡️ 1. API Gateway (Port 3000)

• Single Entry Point: Directs client traffic to appropriate backend services.
• Authentication Guard: Intercepts incoming requests and validates JWT signatures.
• Global Interceptors & Filters: Formats outbound API responses and serializes exceptions uniformly.

🔑 2. Authentication Service (Port 3001)

• Credential Safety: Utilizes bcrypt for secure hashing and storage of passwords.
• Token Issuance: Generates secure JSON Web Tokens (JWT) for session management.
• Event Dispatch: Dispatches a user.registered event to Kafka upon successful sign-up.

📅 3. Events Service (Port 3003)

• Lifecycle Management: Supports creating, updating, publishing, and cancelling events.
• Role Enforcement: Restricts modifying and publishing actions to authenticated organizers.
• Dynamic Search: Fetches open events publically or retrieves event history filtering by organizer.

🎫 4. Tickets Service (Port 3004)

• Purchase Pipeline: Facilitates buying tickets for active events with validation limits.
• Check-In Validation: Empowers event organizers to check in attendees using unique ticket codes.
• Cancellation & Refund: Handles ticket cancellation, updating ticket status, and emitting events.

🔔 5. Notifications Service (Port 3006)

• Event-Driven: Listens to Kafka topics asynchronously without blocking transactional logic.
• Email Delivery: Utilizes nodemailer to dispatch transactional emails:
  • Welcome Email: Sent when user.registered is received.
  • Ticket Confirmation: Sent with ticket codes and receipt info when ticket.purchased is received.
  • Cancellation Notice: Sent when ticket.cancelled is received.

📦 6. Shared Monorepo Libraries (libs/)

• @app/common: System-wide DTO validations (class-validator), filters, constants, and utilities.
• @app/database: Core connection pooling and table schemas (Users, Events, Tickets) using Drizzle.
• @app/kafka: Wrapper module providing simplified Kafka client connections and topic constants.

---

📂 Project Structure

EventFlow utilizes a NestJS monorepo layout powered by pnpm workspaces:

eventflow-app/
├── apps/                               # Microservices Applications
│   ├── api-gateway/                    # Central entrypoint routing API traffic
│   ├── auth-service/                   # Register, login, and user profile management
│   ├── events-service/                 # Managing events creation, update & publishing
│   ├── tickets-service/                # Buying tickets, cancellations & check-ins
│   └── notifications-service/          # Listens to Kafka events and fires emails
│
├── libs/                               # Shared Internal Libraries
│   ├── common/                         # Shared DTOs, Exception Filters, & Constants
│   ├── database/                       # Drizzle ORM DB Client and PostgreSQL Schema
│   └── kafka/                          # Client configs, service wrappers & Kafka topics
│
├── drizzle/                            # Auto-generated SQL migration files
├── drizzle.config.ts                   # Drizzle migrations configuration file
├── docker-compose.yaml                 # PostgreSQL, Kafka, Zookeeper, and Mailhog config
├── package.json                        # Dependencies, workspaces, and scripts
└── pnpm-workspace.yaml                 # Monorepo workspaces definition

---

⚙️ Installation & Setup

Follow these instructions to run the EventFlow ecosystem locally:

📋 Prerequisites

• Node.js (v18 or higher recommended)
• pnpm package manager (npm install -g pnpm)
• Docker & Docker Compose

Step 1: Clone and Install Dependencies

# Clone the repository
git clone <repository-url>
cd eventflow-app

# Install project workspaces dependencies
pnpm install

Step 2: Configure Environment Variables

Create a .env file in the root directory:

DATABASE_URL="postgresql://eventflowapp:eventflow_password@localhost:5432/eventflowapp?schema=public"
JWT_SECRET="your-super-secure-jwt-secret-key"

Step 3: Run Infrastructure Services

Spin up PostgreSQL, Apache Kafka, Zookeeper, and Mailhog via Docker:

docker-compose up -d

Step 4: Run Database Migrations

Create and execute database schemas via Drizzle ORM:

# Generate migrations based on schemas
pnpm db:generate

# Apply migrations to PostgreSQL
pnpm db:migrate

Step 5: Start the Microservices

To run the full monorepo in development mode, open multiple terminal tabs and run the desired services:

# Start API Gateway (Defaults to Port 3000)
pnpm start:dev api-gateway

# Start Auth Service (Port 3001)
pnpm start:dev auth-service

# Start Events Service (Port 3003)
pnpm start:dev events-service

# Start Tickets Service (Port 3004)
pnpm start:dev tickets-service

# Start Notifications Service (Port 3006)
pnpm start:dev notifications-service

---

🚦 Endpoint Routing Map

Clients send requests to the API Gateway (http://localhost:3000), which proxy routes downstream:

Client Endpoint	Downstream Route	HTTP Method	Auth Required	Description
/auth/register	auth-service/register	POST	❌	Create a new user profile
/auth/login	auth-service/login	POST	❌	Log in to obtain a JWT token
/auth/profile	auth-service/profile	GET	🔐 JWT	Retrieve current user profile
/events	events-service/	POST / GET	🔐 (POST only)	Create / list events
/events/my-events	events-service/my-events	GET	🔐 JWT	View events created by organizer
/events/:id	events-service/:id	GET / PUT	🔐 (PUT only)	Retrieve / edit event details
/events/:id/publish	events-service/:id/publish	POST	🔐 Organizer	Publish event to public listing
/events/:id/cancel	events-service/:id/cancel	POST	🔐 Organizer	Cancel event
/tickets/purchase	tickets-service/purchase	POST	🔐 JWT	Buy tickets for an active event
/tickets/my-tickets	tickets-service/my-tickets	GET	🔐 JWT	View tickets owned by current user
/tickets/check-in	tickets-service/check-in	POST	🔐 Organizer	Validate/Check-in ticket at the door

---

🐳 Monitoring & Dashboards

While running Docker infrastructure, you can access diagnostic dashboards to monitor operations:

• Kafka Management UI: Access http://localhost:8989 to view active clusters, topics, consumer groups, and stream events.
• Mailhog Dashboard: Access http://localhost:8025 to view outbound transaction emails captured by the SMTP agent.

---

📝 License

Contact: Nguyễn Đình Huy Hoàng - [ndhhoang.02052002@gmail.com]