ExhibitFlow - Microservices Deployment

A comprehensive microservices-based platform for managing exhibition and bookfair operations. ExhibitFlow provides end-to-end functionality for stall management, reservations, user authentication, notifications, and both vendor and employee portals.

Table of Contents

• Overview
• Architecture
• Services
• Technology Stack
• Prerequisites
• Quick Start
• Configuration
• Service Details
• Development

Overview

ExhibitFlow is a distributed microservices platform designed for managing exhibition events, particularly bookfairs. The system handles:

• User Authentication & Authorization - OAuth2/JWT-based security with role-based access control
• Stall Management - CRUD operations with status workflows (AVAILABLE → HELD → RESERVED)
• Reservations - Orchestrated booking system with QR code generation
• Notifications - Event-driven email notifications via Kafka
• API Gateway - Centralized routing, rate limiting, and security
• Frontend Portals - React-based applications for vendors and employees

Architecture

                                    ┌─────────────────────┐
                                    │   Load Balancer     │
                                    └──────────┬──────────┘
                                               │
                                    ┌──────────▼──────────┐
                                    │    API Gateway      │
                                    │    (Port: 9090)     │
                                    └──────────┬──────────┘
                                               │
           ┌───────────────────────────────────┼───────────────────────────────────┐
           │                                   │                                   │
┌──────────▼──────────┐             ┌──────────▼──────────┐             ┌──────────▼──────────┐
│  Identity Service   │             │   Stall Service     │             │ Reservation Service │
│    (Port: 8080)     │             │   (Port: 8081)      │             │    (Port: 8084)     │
└──────────┬──────────┘             └──────────┬──────────┘             └──────────┬──────────┘
           │                                   │                                   │
           │                        ┌──────────▼──────────┐                        │
           │                        │Notification Service │                        │
           │                        │   (Port: 8087)      │                        │
           │                        └──────────┬──────────┘                        │
           │                                   │                                   │
           └───────────────────────────────────┼───────────────────────────────────┘
                                               │
                              ┌────────────────┼────────────────┐
                              │                │                │
                   ┌──────────▼─────┐  ┌───────▼──────┐  ┌──────▼───────┐
                   │  Eureka Server │  │    Kafka     │  │  PostgreSQL  │
                   │  (Port: 8761)  │  │ (Port: 9092) │  │  (Multiple)  │
                   └────────────────┘  └──────────────┘  └──────────────┘

Service Communication

• Synchronous: REST APIs via API Gateway
• Asynchronous: Apache Kafka for event streaming
• Service Discovery: Netflix Eureka
• Configuration: Environment-based configuration

Services

Service	Port	Description
API Gateway	9090	Entry point - routing, rate limiting, JWT validation
Identity Service	8080	Authentication, authorization, user management
Stall Service	8081	Stall CRUD, status management, inventory
Reservation Service	8084	Booking orchestration, QR code generation
Notification Service	8087	Email notifications via Kafka events
Eureka Server	8761	Service registry and discovery
Vendor Portal	5173	React frontend for vendors
Employee Portal	3000	React frontend for employees

Infrastructure Services

Service	Port	Description
PostgreSQL (Stall)	5432	Stall service database
PostgreSQL (Reservation)	5433	Reservation service database
PostgreSQL (Notification)	5434	Notification service database
Redis	6379	API Gateway rate limiting cache
Kafka	9092	Event streaming broker
Zookeeper	2181	Kafka coordination

Technology Stack

Backend

• Java 17/21 - Primary runtime
• Spring Boot 3.5.7 - Microservices framework
• Spring Security - OAuth2/JWT authentication
• Spring Data JPA - Database access
• Spring Cloud Gateway - API Gateway
• Spring Kafka - Event streaming
• Netflix Eureka - Service discovery
• Flyway - Database migrations
• PostgreSQL 16 - Primary database

Frontend

• React 18 - UI framework
• TypeScript - Type-safe JavaScript
• Vite - Build tool
• TailwindCSS - Styling

Infrastructure

• Docker & Docker Compose - Containerization
• Apache Kafka - Message broker
• Redis - Caching
• Nginx - Frontend web server

Prerequisites

• Docker 20.10+ and Docker Compose 2.0+
• Java 17+ (for local development)
• Node.js 18+ (for frontend development)
• Maven 3.6+ (for building Java services)
• Minimum 8GB RAM recommended for running all services

Quick Start

1. Clone the Repository

git clone https://github.com/ExhibitFlow/exhibitflow-deployment.git
cd exhibitflow-deployment

2. Configure Environment

# Copy the example environment file
cp .env.example .env

# Edit with your configuration
nano .env

3. Start All Services

# Build and start all services
docker-compose up -d --build

# Check service status
docker-compose ps

# View logs
docker-compose logs -f

4. Verify Services

Service	Health Check URL
Eureka Dashboard	http://localhost:8761
API Gateway	http://localhost:9090/actuator/health
Identity Service	http://localhost:8080/api/v1/actuator/health
Stall Service	http://localhost:8081/actuator/health
Reservation Service	http://localhost:8084/actuator/health
Notification Service	http://localhost:8087/actuator/health

5. Test Authentication

# Login as admin
curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "admin123"}'

Configuration

Environment Variables

Create a .env file in the root directory:

# Database Configuration
STALL_DB_NAME=stalldb
STALL_DB_USER=stalluser
STALL_DB_PASSWORD=stallpass

RESERVATION_DB_NAME=reservation_db
RESERVATION_DB_USER=postgres
RESERVATION_DB_PASSWORD=your_password

# JWT Configuration
JWT_SECRET=your-256-bit-secret-key
JWT_EXPIRATION=86400000
JWT_REFRESH_EXPIRATION=604800000

# OAuth2 Configuration
OAUTH2_ISSUER_URI=http://identity-service:8080
OAUTH2_CLIENT_ID=exhibitflow-client
OAUTH2_CLIENT_SECRET=exhibitflow-secret
OAUTH2_REDIRECT_URIS=http://localhost:3000/callback
OAUTH2_SCOPES=read,write

Default Credentials

User	Password	Roles	Description
admin	admin123	ADMIN	Full administrative access

New users can register via /api/v1/auth/register and automatically receive the VIEWER role.

Service Details

Identity Service

Handles authentication and authorization using JWT and OAuth2.

Key Features:

• JWT token generation and validation
• OAuth2 Authorization Server
• User registration and management
• Role-Based Access Control (RBAC)
• Permission management

API Endpoints:

• POST /api/v1/auth/register - Register new user
• POST /api/v1/auth/login - Login and get tokens
• POST /api/v1/auth/refresh - Refresh access token
• GET /api/v1/users/me - Get current user profile

Swagger UI: http://localhost:8080/api/v1/swagger-ui.html

Stall Service

Manages exhibition stalls with status workflows.

Key Features:

• Stall CRUD operations
• Status workflow: AVAILABLE → HELD → RESERVED
• Advanced filtering and pagination
• Kafka event publishing for state changes

Status Transitions: with 5 minuted hold

AVAILABLE ──hold──> HELD ──reserve──> RESERVED
    ▲                 │                  │
    │                 └──────release─────┘
    └───────────────release──────────────┘

API Endpoints:

• GET /api/stalls - List all stalls (with filters)
• POST /api/stalls - Create new stall (Admin)
• POST /api/stalls/{id}/hold - Hold a stall
• POST /api/stalls/{id}/reserve - Reserve a stall
• POST /api/stalls/{id}/release - Release a stall

Swagger UI: http://localhost:8081/swagger-ui.html

Reservation Service

Orchestrates the reservation process across multiple services.

Key Features:

• Maximum 3 stalls per business
• Automatic QR code generation
• Service-to-service coordination
• Compensating transactions for consistency

Kafka Topics:

• reservation.created
• payment.completed
• reservation.cancelled
• payment.expired

API Endpoints:

• POST /api/reservations - Create reservation
• GET /api/reservations/my - Get user's reservations
• DELETE /api/reservations/{id} - Cancel reservation

Notification Service

Event-driven notification system using Kafka.

Key Features:

• Kafka consumer for stall events
• Email notifications via SMTP
• Template-based notifications

Consumed Topics:

• stall.reserved

API Gateway

Central entry point with security and rate limiting.

Key Features:

• JWT token validation
• CORS configuration
• Rate limiting with Redis
• Circuit breaker pattern
• Request/response logging

API Documentation

Each service exposes OpenAPI/Swagger documentation:

Service	Swagger UI URL
Identity Service	http://localhost:8080/api/v1/swagger-ui.html
Stall Service	http://localhost:8081/swagger-ui.html
Reservation Service	http://localhost:8084/swagger-ui.html

Development

Building Services Individually

# Build a specific service
cd identity-service
mvn clean package -DskipTests

# Build Docker image
docker build -t identity-service:latest .

Running in Development Mode

# Start infrastructure only
docker-compose up -d postgres-stall postgres-reservation postgres-notification redis kafka zookeeper eureka-server

# Run service locally
cd stall-service
mvn spring-boot:run

Frontend Development

# Vendor Portal
cd vendor-portal
npm install
npm run dev  # http://localhost:5173

# Employee Portal
cd employee-portal
npm install
npm run dev  # http://localhost:3000

Viewing Logs

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f identity-service

# Filter by time
docker-compose logs --since 10m stall-service

Database Access

# Stall database
docker exec -it stall-postgres psql -U stalluser -d stalldb

# Reservation database
docker exec -it reservation-postgres psql -U postgres -d reservation_db

Kafka Management

# List topics
docker exec exhibitflow-kafka kafka-topics --bootstrap-server localhost:9092 --list

# Consume events
docker exec exhibitflow-kafka kafka-console-consumer \
  --bootstrap-server localhost:9092 \
  --topic stall.reserved \
  --from-beginning