A comprehensive cloud-native microservices platform for managing exhibition stalls, reservations, and vendor operations. Built with modern technologies including Spring Boot, React, Kafka, and PostgreSQL.

ExhibitFlow follows a microservices architecture with event-driven communication, service discovery, centralized configuration, and API gateway patterns. The platform consists of backend services, frontend portals, and shared libraries working together to provide a complete exhibition management solution.

┌─────────────────────────────────────────────────────────────────────┐
│                         Client Applications                         │
│  ┌──────────────────────┐              ┌──────────────────────┐     │
│  │  Employee Portal     │              │   Vendor Portal      │     │
│  │  (React/TypeScript)  │              │  (React/TypeScript)  │     │
│  └──────────────────────┘              └──────────────────────┘     │
└─────────────────────────────────────────────────────────────────────┘
                              ↓                        ↓
┌─────────────────────────────────────────────────────────────────────┐
│                          API Gateway                                │
│  • Rate Limiting (Redis)  • Circuit Breaker  • Load Balancing       │
│  • CORS Configuration     • JWT Validation   • Request Routing      │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│                      Infrastructure Services                        │
│  ┌──────────────────┐              ┌──────────────────────┐         │
│  │ Service Registry │              │   Config Server      │         │
│  │    (Eureka)      │              │  (Spring Cloud)      │         │
│  └──────────────────┘              └──────────────────────┘         │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│                       Business Services                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐           │
│  │  Identity    │  │    Stall     │  │   Reservation    │           │
│  │  Service     │  │   Service    │  │    Service       │           │
│  │  (OAuth2)    │  │              │  │  (QR Codes)      │           │
│  └──────────────┘  └──────────────┘  └──────────────────┘           │
│                                                                     │
│  ┌──────────────────────────────────────────────────────┐           │
│  │           Notification Service                       │           │
│  │           (Email, Kafka Consumer)                    │           │
│  └──────────────────────────────────────────────────────┘           │
└─────────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────────┐
│                       Data & Messaging Layer                        │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐           │
│  │  PostgreSQL  │  │    Kafka     │  │      Redis       │           │
│  │  Databases   │  │   (Events)   │  │  (Rate Limit)    │           │
│  └──────────────┘  └──────────────┘  └──────────────────┘           │
└─────────────────────────────────────────────────────────────────────┘

The entry point for all client requests, providing unified access to backend services.

Key Features:

• Dynamic Routing: Routes requests to appropriate microservices based on path patterns
• Circuit Breaker: Resilience4j implementation with configurable failure thresholds (50% failure rate, 10s wait)
• Rate Limiting: Redis-backed distributed rate limiting (100 req/min default, configurable)
• Retry Mechanism: Exponential backoff for transient failures (3 attempts, 100ms-1000ms backoff)
• Security: JWT validation, OAuth2 resource server integration
• CORS Management: Configurable cross-origin policies for frontend applications
• Fallback Responses: Graceful degradation when services are unavailable
• Request Logging: Comprehensive logging with correlation IDs and duration tracking

Technology Stack:

• Spring Cloud Gateway
• Spring Security OAuth2
• Redis (rate limiting)
• Resilience4j (circuit breaker)
• Eureka Client (service discovery)

Port: 9090

Centralized authentication and authorization service managing users, roles, and permissions.

Key Features:

• JWT Authentication: HS512 symmetric encryption with configurable expiration
• OAuth2 Authorization Server: Standard OAuth2 flows implementation
• User Management: Full CRUD operations for users with role-based access control
• Role & Permission System: Hierarchical permission model (ADMIN, MANAGER, VIEWER roles)
• Password Security: BCrypt encryption with configurable strength
• Token Refresh: Long-lived refresh tokens (7 days) with rotation support
• Database Migration: Flyway-managed schema versioning
• Audit Logging: Track authentication attempts and user activities

API Endpoints:

• POST /api/v1/auth/register - User registration
• POST /api/v1/auth/login - User authentication
• POST /api/v1/auth/refresh - Token refresh
• POST /api/v1/auth/logout - Session termination
• GET /api/v1/users - User listing (ADMIN)
• POST /api/v1/admin/roles - Role management (ADMIN)
• GET /api/v1/oauth/authorize - OAuth2 authorization
• POST /api/v1/oauth/token - OAuth2 token endpoint

Technology Stack:

• Spring Boot 3.x
• Spring Security OAuth2
• PostgreSQL
• Flyway (database migrations)
• JWT (io.jsonwebtoken)

Port: 8095

Manages exhibition stall inventory, availability, and status transitions.

Key Features:

• Stall Management: CRUD operations for stalls with filtering and pagination
• Status Workflow: AVAILABLE → HELD → RESERVED lifecycle management
• Idempotent Operations: Safe hold/release/reserve operations
• Location Management: Store and query stall locations within exhibition spaces
• Size Classification: Support for SMALL, MEDIUM, LARGE stall sizes
• Event Publishing: Kafka events for stall state changes (reserved, released, created, updated)
• Role-Based Access: ADMIN creates, MANAGER updates, VIEWER reads
• Search & Filter: Filter by status, size, location with pagination

API Endpoints:

• GET /api/stalls - List all stalls (filtered, paginated)
• GET /api/stalls/{id} - Get stall details
• GET /api/stalls/code/{code} - Get stall by unique code
• POST /api/stalls - Create new stall (ADMIN)
• PUT /api/stalls/{id} - Update stall (MANAGER)
• POST /api/stalls/{id}/hold - Hold stall temporarily (MANAGER)
• POST /api/stalls/{id}/release - Release held stall (MANAGER)
• POST /api/stalls/{id}/reserve - Reserve stall (MANAGER)

Event Publishing:

• stall.reserved - When stall is reserved
• stall.released - When stall becomes available
• stall.created - When new stall is added
• stall.updated - When stall details change

Technology Stack:

• Spring Boot 3.x
• Spring Data JPA
• PostgreSQL (PostGIS support)
• Kafka Producer
• Flyway migrations
• Custom JWT validation

Port: 8081

Handles stall reservations, payment workflows, and QR code generation.

Key Features:

• Reservation Lifecycle: Create → Pending → Confirmed/Expired flow
• Payment Lock: 5-minute payment window after reservation
• QR Code Generation: Automatic QR code creation upon payment confirmation
• User Limits: Maximum 3 concurrent reservations per user
• Automatic Cleanup: Scheduled job to expire unpaid reservations (every 60s)
• Event-Driven: Publishes reservation events to Kafka
• Feign Integration: Calls User Service and Stall Service via REST
• Cache Management: Redis caching with event-based invalidation
• Venue Map API: Provides stall locations and status for visualization
• Idempotency: Prevent duplicate reservations using database constraints

API Endpoints:

• POST /api/v1/reservations - Create new reservation
• POST /api/v1/reservations/{id}/complete-payment - Confirm payment
• GET /api/v1/reservations/my - Get user's reservations
• GET /api/v1/reservations/{id} - Get reservation details
• GET /api/v1/reservations - List all reservations (paginated, ADMIN/MANAGER)
• DELETE /api/v1/reservations/{id} - Cancel reservation
• GET /api/v1/reservations/my/count - Get active reservation count
• POST /api/v1/reservations/stalls/{stallId}/hold - Temporarily hold stall
• GET /api/v1/venue-map - Get venue layout with stall status

Event Publishing:

• reservation.created - New reservation created
• reservation.payment.completed - Payment confirmed
• reservation.payment.expired - Payment window expired
• reservation.cancelled - Reservation cancelled

Event Consumption:

• stall.created - Clear stall cache
• stall.updated - Evict specific stall from cache

Technology Stack:

• Spring Boot 3.x
• Spring Data JPA (PostGIS)
• OpenFeign (service communication)
• Kafka (producer & consumer)
• ZXing (QR code generation)
• Spring Cache
• PostgreSQL

Port: 8084

Asynchronous email notification service with event-driven architecture.

Key Features:

• Email Integration: SMTP-based email sending (Gmail configuration)
• Event-Driven: Kafka consumer for stall reservation events
• Idempotency: Prevents duplicate email notifications using tracking
• Template Engine: HTML email templates for professional notifications
• Bulk Email: Support for mass notification campaigns
• User Service Integration: Fetches user details via Feign client
• Error Handling: Dead letter queue support for failed messages
• Retry Logic: Automatic retry for transient failures
• Notification History: Stores all sent notifications in database

API Endpoints:

• POST /notifications/send-bulk - Send bulk email notifications
• GET /notifications/history - View notification history (future)

Event Consumption:

• stall.reserved - Triggers reservation confirmation email

Email Templates:

• Stall reservation confirmation
• Payment reminders
• Cancellation notifications

Technology Stack:

• Spring Boot 3.x
• Spring Mail
• Kafka Consumer
• Flyway
• PostgreSQL
• OpenFeign
• Thymeleaf (email templates)

Port: 8086

Centralized configuration management for all microservices.

Key Features:

• Centralized Configuration: Single source of truth for all service configurations
• Environment Profiles: Support for dev, staging, production environments
• Git Backend: Configuration stored in version-controlled repository
• Dynamic Refresh: Trigger configuration updates via Spring Cloud Bus
• Encryption: Supports encrypted configuration properties
• Service Discovery: Registered with Eureka for discovery

Technology Stack:

• Spring Cloud Config Server
• Spring Cloud Bus (for refresh)
• Eureka Client

Port: 8888

Service discovery and registration hub for microservices.

Key Features:

• Service Registration: Auto-registration of microservices
• Health Monitoring: Heartbeat-based service health checks
• Load Balancing: Client-side load balancing via Ribbon
• Failover Support: Automatic service instance discovery
• Dashboard: Web UI for monitoring registered services

Technology Stack:

• Spring Cloud Netflix Eureka Server

Port: 8761

Internal administrative dashboard for exhibition management staff.

Key Features:

• Stall Management: View, create, update, and manage stalls
• Reservation Monitoring: View all reservations with filtering and pagination
• User Management: Administer user accounts, roles, and permissions
• Notification System: Send bulk email notifications to users
• Role-Based UI: Different views for ADMIN, MANAGER, VIEWER roles
• Real-time Updates: Integration with backend event system
• Authentication: JWT-based secure login
• Responsive Design: Modern UI with CSS modules

Pages:

• Dashboard - Overview metrics and quick actions
• Stalls - Stall inventory management with grid view
• Reservations - Reservation listing with filters and status tracking
• Users - User management and role assignment
• Notifications - Bulk notification interface

Technology Stack:

• React 18
• TypeScript
• Vite (build tool)
• Zustand (state management)
• React Router (navigation)
• Axios (HTTP client)
• CSS Modules (styling)

Port: 5173 (development)

Customer-facing portal for vendors to book exhibition stalls.

Key Features:

• Stall Browsing: View available stalls with filtering by size and location
• Reservation System: Create and manage reservations
• Payment Integration: PayHere payment gateway integration (configured)
• QR Code Display: View reservation QR codes for entry
• Reservation History: Track past and current bookings
• Genre/Category Support: Browse stalls by genre
• Theme Support: Light/dark mode toggle
• Mock Service Worker: Development-time API mocking

Pages:

• Dashboard - Vendor overview and stats
• Stalls - Browse and filter available stalls
• Reservations - View and manage bookings
• Payment - Payment processing interface
• Genres - Category-based navigation

Technology Stack:

• React 18
• TypeScript
• Vite
• Zustand (state management)
• React Router
• MSW (Mock Service Worker)
• PayHere SDK
• Context API (theming)

Port: 5174 (development)

Shared Kafka event definitions for cross-service communication.

Purpose:

• Ensures event schema consistency across services
• Provides type-safe event classes
• Centralized event versioning

Event Definitions:

• BaseEvent - Base class with common fields (eventId, eventType, timestamp, sourceService)
• StallReservedEvent - Stall reservation notification event

Topics:

• stall-events - Main stall event stream
• dead-letter-events - Failed event processing

Technology Stack:

• Java 17
• Jackson (JSON serialization)
• Lombok
• Maven (published to repository)

• Framework: Spring Boot 3.x
• Language: Java 17
• Build Tool: Maven
• API Documentation: SpringDoc OpenAPI (Swagger)
• Security: Spring Security, OAuth2, JWT
• Service Discovery: Netflix Eureka
• API Gateway: Spring Cloud Gateway
• Resilience: Resilience4j (Circuit Breaker, Rate Limiter)
• Database: PostgreSQL (with PostGIS extension)
• Database Migration: Flyway
• Messaging: Apache Kafka
• Caching: Spring Cache with Redis
• Service Communication: OpenFeign
• Monitoring: Spring Actuator, Prometheus

• Framework: React 18
• Language: TypeScript
• Build Tool: Vite
• State Management: Zustand
• Routing: React Router v6
• HTTP Client: Axios
• Styling: CSS Modules
• Mock API: MSW (Mock Service Worker)
• Payment: PayHere SDK

• Containerization: Docker, Docker Compose
• Message Broker: Apache Kafka
• Cache Store: Redis
• Database: PostgreSQL 15+
• Service Registry: Eureka Server
• Config Management: Spring Cloud Config

• Independent deployment and scaling
• Service isolation with circuit breakers
• Event-driven communication via Kafka
• Service discovery with Eureka

• OAuth2 authorization server
• JWT token-based authentication (HS512)
• Role-based access control (RBAC)
• API Gateway security layer
• Rate limiting (100 req/min default)

• Circuit breaker pattern (50% failure threshold)
• Retry mechanism with exponential backoff
• Graceful degradation with fallback responses
• Redis-backed distributed rate limiting

• Kafka for asynchronous communication
• Event sourcing for stall state changes
• Idempotent event processing
• Dead letter queue for failed events

• PostgreSQL with PostGIS for spatial data
• Flyway for database version control
• Redis caching for performance
• JPA/Hibernate ORM

• Comprehensive API documentation (Swagger)
• Docker Compose for local development
• Mock Service Worker for frontend development
• Centralized configuration management
• Actuator endpoints for monitoring

• Stall inventory management with lifecycle
• Reservation system with payment locking (5 min)
• QR code generation for reservations
• User limit enforcement (3 reservations max)
• Automated email notifications
• Venue map visualization
• Bulk notification system

exhibitflow/
├── api-gateway-service/       # API Gateway with routing and security
├── identity-service/          # Authentication and authorization
├── stall-service/             # Stall inventory management
├── reservation-service/       # Reservation and payment handling
├── notification-service/      # Email notification system
├── config-server/             # Centralized configuration
├── service-registry/          # Eureka service discovery
├── common-events/             # Shared Kafka event library
├── employee-portal/           # React admin dashboard
├── vender-portal/             # React vendor booking portal
└── exhibitflow-deployment/    # Docker Compose orchestration

• Reservation → User Service: Fetch user details for reservations
• Reservation → Stall Service: Check stall availability and status
• Notification → User Service: Retrieve user email for notifications
• API Gateway → All Services: Request routing and load balancing

• Stall Service → Reservation Service:
  • stall.created, stall.updated events for cache invalidation
• Stall Service → Notification Service:
  • stall.reserved event triggers email notification
• Reservation Service → Notification Service:
  • reservation.created, reservation.payment.completed events

• users - User accounts and credentials
• roles - Role definitions (ADMIN, MANAGER, VIEWER)
• permissions - Granular permission entries
• user_roles - User-role associations
• role_permissions - Role-permission mappings
• refresh_tokens - Active refresh tokens

• stalls - Stall inventory with location (PostGIS geometry), size, status

• reservations - Reservation records with stall_id, user_id, status, QR code, payment timestamp

• notifications - Notification history with event_id (idempotency key), user_id, status

ADMIN (All Permissions)
  ├─ User Management: Create, Update, Delete Users
  ├─ Role Management: Assign/Revoke Roles
  ├─ Stall Management: Create, Update, Delete Stalls
  ├─ Full System Access
  │
MANAGER
  ├─ Stall Management: Update Stalls, Hold/Release/Reserve
  ├─ View All Reservations
  ├─ No User/Role Management
  │
VIEWER (Read-Only)
  ├─ View Stalls
  ├─ View Own Reservations
  ├─ Create Own Reservations

1. User logs in via /api/v1/auth/login with credentials
2. Identity Service validates and returns JWT access token + refresh token
3. Client includes Authorization: Bearer <token> in subsequent requests
4. API Gateway validates JWT signature and extracts claims
5. Request routed to target service with user context
6. Service validates role/permission requirements

• Java 17+
• Node.js 18+
• Docker & Docker Compose
• PostgreSQL 15+
• Apache Kafka
• Redis
• Maven 3.8+

SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/identity_db
DB_USERNAME=postgres
DB_PASSWORD=yourpassword
JWT_SECRET=your-256-bit-secret-key
OAUTH2_ISSUER_URI=http://localhost:8095/api/v1

SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/stalldb
SPRING_KAFKA_BOOTSTRAP_SERVERS=localhost:9092
JWT_SECRET=your-256-bit-secret-key

spring.datasource.url=jdbc:postgresql://localhost:5532/reservation_db
spring.kafka.bootstrap-servers=localhost:9092
services.user-service.url=http://localhost:8095
services.stall-service.url=http://localhost:8081
jwt.secret=your-256-bit-secret-key

spring.mail.host=smtp.gmail.com
[email protected]
spring.mail.password=your-app-password
services.user-service.url=http://localhost:8095
services.user-service.bearer-token=admin-token

REDIS_HOST=localhost
REDIS_PORT=6379
JWT_ISSUER_URI=http://localhost:8095/api/v1
CORS_ALLOWED_ORIGINS=http://localhost:5173,http://localhost:5174

VITE_API_URL=http://localhost:9090
VITE_API_TIMEOUT=30000

VITE_API_URL=http://localhost:9090
VITE_PAYHERE_MERCHANT_ID=your-merchant-id

# Navigate to deployment directory
cd exhibitflow-deployment

# Start all services
docker compose up -d

# View logs
docker compose logs -f

# Stop all services
docker compose down

• API Gateway: http://localhost:9090
• Eureka Dashboard: http://localhost:8761
• Identity Service: http://localhost:8095
• Stall Service: http://localhost:8081
• Reservation Service: http://localhost:8084
• Notification Service: http://localhost:8086
• Employee Portal: http://localhost:5173
• Vendor Portal: http://localhost:5174

All services expose Spring Actuator endpoints:

• GET /actuator/health - Service health status
• GET /actuator/info - Service information
• GET /actuator/metrics - Application metrics
• GET /actuator/prometheus - Prometheus-formatted metrics

• Centralized logging with correlation IDs
• MDC (Mapped Diagnostic Context) for request tracing
• Configurable log levels per service
• Console output with timestamp formatting

• Prometheus integration via Actuator
• Custom business metrics (reservation counts, stall status)
• JVM metrics (memory, threads, GC)
• HTTP request metrics (latency, status codes)

Each service provides interactive Swagger UI documentation:

• Identity Service: http://localhost:8095/api/v1/swagger-ui.html
• Stall Service: http://localhost:8081/swagger-ui.html
• Reservation Service: http://localhost:8084/swagger-ui.html

The API Gateway aggregates all service documentation:

• http://localhost:9090/swagger-ui.html

• Apache Kafka for event streaming
• PostgreSQL & PostGIS for spatial data
• Docker & containerization