Lineage II High Five Fun Server

Overview

This project is a comprehensive Lineage II High Five Fun Server implementation that I’m passionate about developing and learning to deploy on Kubernetes clusters. As a fan of the classic Lineage II game, this project represents both my love for the game and my journey in mastering modern cloud-native technologies.

Project Motivation

Lineage II holds a special place in my heart as one of the most iconic MMORPGs ever created. The High Five chronicle represents the golden era of the game, and I wanted to recreate that experience while learning modern DevOps and Kubernetes deployment strategies. This project combines nostalgia with cutting-edge technology.

Architecture Overview

The system is built using a microservices architecture deployed on Kubernetes (K3s), featuring:

  • Game Server: Java-based Lineage II server implementation
  • Login Server: Authentication and character management
  • Web Server: Go-based REST API and WebSocket server
  • Web Application: Next.js React frontend
  • Resources Provider: Game assets and patch management
  • OAuth API: Centralized authentication and authorization service
  • Mailer App: Dedicated email service for notifications
  • Monitoring Stack: Prometheus, Grafana, Loki for observability
  • Databases: MySQL for game data, MongoDB for application data

Infrastructure

  • Container Orchestration: Kubernetes (K3s)
  • Ingress: Traefik with Let’s Encrypt SSL
  • Monitoring: Prometheus + Grafana + Loki stack
  • CI/CD: GitHub Actions with GHCR

External Microservices

The Lineage II Fun Server integrates with two critical external microservices that provide essential functionality:

OAuth API Service

A robust OAuth 2.0 authorization server that provides centralized authentication and authorization for the entire ecosystem:

  • JWT Token Management: Generates and validates secure access tokens with configurable expiration
  • Role-Based Access Control (RBAC): Supports user and service account types with fine-grained permissions
  • Scope-Based Permissions: Custom scopes for different service access levels
  • Multi-Application Support: Manages access across multiple target applications
  • MongoDB Integration: Persistent storage for authorization data with optimized indexes
  • Security Features: RSA private key signing, comprehensive token validation

Integration with Lineage Server:

  • WebServer uses OAuth API for service-to-service authentication
  • Validates JWT tokens for secure API access
  • Manages authorization for admin operations and user permissions
  • Caches authorization tokens for performance optimization

Mailer App Service

A dedicated email service that handles all email notifications for the gaming platform:

  • Mailer API Integration: Mailer service for email delivery
  • OAuth-Secured API: Protected endpoints requiring valid JWT tokens with sent email permission scope
  • Email Templates: Support for HTML email templates and rich formatting
  • Notification Types: Account activation, password reset, donation confirmations, server status alerts
  • Delivery Reliability: Built-in retry mechanisms and error handling

Integration with Lineage Server:

  • WebServer calls Mailer API for user registration emails
  • Server status notifications sent to administrators
  • Payment confirmation and refund notifications
  • Account activation and password reset emails
  • Uses OAuth API for authentication when sending emails

Service Communication Flow:

Loading diagram...
View PlantUML Source
@startuml Service Communication Flow

!theme aws-orange
skinparam backgroundColor #ffffff
skinparam defaultFontColor #2c3e50
skinparam sequenceMessageAlign center

title External Services Communication Flow

participant "WebServer" as WebServer #blue
participant "OAuth API" as OAuthAPI #purple
participant "Mailer App" as MailerApp #lightblue
actor "User Email" as UserEmail #lightgreen

WebServer -> OAuthAPI : Request JWT token\n(service authentication)
OAuthAPI -> WebServer : Return JWT token

WebServer -> MailerApp : Send email request\n(with JWT token)
MailerApp -> OAuthAPI : Validate JWT token\n& check scope permissions
OAuthAPI -> MailerApp : Token valid ✅

MailerApp -> MailerApp : Process email\n(templates, formatting)
MailerApp -> UserEmail : Email delivered 📧
MailerApp -> WebServer : Delivery confirmation

@enduml

These external services follow the same deployment patterns as the main application, running in separate Kubernetes namespaces (oauth and resource) with their own MongoDB instances, SSL certificates, and monitoring configurations.

Key Features

Game Features

  • Classic Lineage II High Five Experience: Authentic gameplay mechanics
  • Multiple Server Support: Sieghardt, Lionna with different rates
  • Real-time Server Status: Live monitoring of game server availability
  • Character Management: Account creation, character viewing

Modern Web Features

  • Donation System: Integrated payment processing with PIX and credit card powered by Mercado Pago
  • Real-time Updates: WebSocket-based live data streaming
  • Responsive Design: Mobile-friendly interface
  • Multi-language Support: Portuguese and English
  • Admin Dashboard: Server management and monitoring

DevOps Features

  • Cloud-Native Deployment: Full Kubernetes manifests
  • Observability: Comprehensive monitoring and logging
  • Security: SSL/TLS, webhook validation, rate limiting
  • Scalability: Horizontal pod autoscaling ready
  • High Availability: Health checks and automatic restarts

Communication Flow

The system uses a sophisticated communication pattern:

  1. Client ↔ WebApp: HTTPS/WSS
  2. WebApp ↔ WebServer: WebSocket for real-time communication
  3. WebServer ↔ Game Server: TCP socket for game operations
  4. WebServer ↔ Databases: Connection pooling for data persistence
  5. Payment Webhooks: Secure webhook validation for payment updates
  6. Monitoring: OpenTelemetry traces and metrics collection

Development Environment

The project supports both local development and production deployment:

  • Local: Docker Compose for rapid development
  • Production: Full Kubernetes deployment with monitoring
  • CI/CD: Automated builds and deployments

System Architecture Diagrams

The following PlantUML diagrams provide detailed views of the system architecture and communication patterns. Each diagram focuses on a single, specific flow:

1. Overall System Architecture

Loading diagram...
View PlantUML Source
@startuml
!theme aws-orange
skinparam backgroundColor #ffffff
skinparam defaultFontColor #2c3e50
skinparam defaultFontSize 11
skinparam componentStyle uml2

title Lineage II High Five Fun Server - Communication Architecture

' External actors
actor "Game Client\n(Lineage II)" as GameClient #lightblue
actor "Web User\n(Browser)" as WebUser #lightgreen
cloud "Internet" as Internet #gray

' External services
cloud "Mercado Pago\nAPI" as MercadoPago #orange
cloud "GitHub Container\nRegistry" as GHCR #gray
cloud "Let's Encrypt\nCA" as LetsEncrypt #green


cloud "Cloud" as CloudDATA {
  database "MySQL Database" as MySQL #brown
  database "MongoDB" as MongoDB #brown
}

' External Microservices (separate deployments)
package "External Services" as ExternalServices {
    component "OAuth API" as OAuthAPI #purple
    component "Mailer App" as MailerApp #lightblue
}

' Kubernetes Cluster boundary
rectangle "K3s Kubernetes Cluster" as K8sCluster {

    ' Ingress Layer
    component "Traefik Ingress" as Traefik #red

    ' Application Namespace
    package "Game server" as AppNamespace {
        ' Frontend
        component "WebApp\n(Next.js)" as WebApp #lightgreen
        ' Backend API
        component "WebServer\n(Go + WebSocket)" as WebServer #blue
        ' Game Services
        component "Login Server\n(Java)" as LoginServer #yellow
        component "Sieghardt\nGame Server\n(Java L2J)" as GameServer #yellow
        component "Lionna(1000x)\nGame Server\n(Java L2J)" as LionaGameServer #yellow
        ' Support Services
        component "Resources Provider" as ResourcesProvider #cyan
        ' Databases
    }

    ' Monitoring Namespace
    package "Monitoring" as MonitoringNamespace {
        component "Prometheus" as Prometheus #orange
        component "Grafana" as Grafana #orange
        component "Loki" as Loki #orange
        component "OpenTelemetry\nCollector" as OTelCollector #orange
    }
}

' External connections
Internet --> Traefik
WebUser --> Internet
GameClient --> Internet

' Ingress routing
Traefik --> WebApp
Traefik --> WebServer

' Game client connections (external LoadBalancer)
GameClient --> LoginServer
GameClient --> GameServer
GameClient --> LionaGameServer


' Internal service communication
WebApp --> WebServer
WebServer --> LoginServer
WebServer --> GameServer
WebServer --> LionaGameServer
LoginServer --> GameServer
LoginServer --> LionaGameServer

' Database connections
WebServer --> MySQL
WebServer --> MongoDB
WebServer --> ResourcesProvider
LoginServer --> MySQL
GameServer --> MySQL
LionaGameServer --> MySQL
LionaGameServer --> WebServer
GameServer --> WebServer

' External API calls
WebServer --> MercadoPago
MercadoPago --> WebServer

' External microservices integration
WebServer --> OAuthAPI
WebServer --> MailerApp
OAuthAPI --> MongoDB
MailerApp --> OAuthAPI

' Resource management
WebApp --> ResourcesProvider

' Monitoring and observability
WebServer --> OTelCollector
WebApp --> Prometheus
WebServer --> Prometheus
GameServer --> Prometheus
LoginServer --> Prometheus
OTelCollector --> Prometheus
Prometheus --> Grafana
Loki --> Grafana

' SSL/TLS
LetsEncrypt --> Traefik

' Container registry
GHCR --> K8sCluster


note right of WebServer
  **WebSocket Processors:**
  • donation_payment_flow
  • donation_history_flow
  • server_status_flow
  • account_flow
  • character_flow

  **Real-time Features:**
  • Live server status
  • Payment processing
  • Character updates
  • Donation history

  **External Integrations:**
  • OAuth API for authentication
  • Mailer App for notifications
  • Mercado Pago for payments
end note
@enduml

Shows the complete system overview including all services, databases, external integrations, and communication flows within the Kubernetes cluster.

2. Payment Flow

Loading diagram...
View PlantUML Source
@startuml Lineage II Fun Server - Payment Flow

!theme aws-orange
skinparam backgroundColor #ffffff
skinparam defaultFontColor #2c3e50
skinparam sequenceMessageAlign center

title Donation Payment Flow

actor "Player" as Player #lightgreen
participant "WebApp" as WebApp #lightgreen
participant "WebServer" as WebServer #blue
participant "Database" as DB #brown
participant "Mercado Pago" as MercadoPago #orange
participant "Game Server" as GameServer #yellow

== Payment Process ==

Player -> WebApp : Select donation package
WebApp -> WebApp : Show payment options\n(PIX, Credit/Debit Card)
Player -> WebApp : Choose payment method & confirm

WebApp -> WebServer : Create payment request
WebServer -> DB : Store payment record
WebServer -> MercadoPago : Create payment\n(PIX or Card)

MercadoPago -> WebServer : Payment created\n(QR code or card form)
WebServer -> WebApp : Return payment details
WebApp -> Player : Display payment interface

Player -> MercadoPago : Complete payment\n(PIX scan or card details)
MercadoPago -> WebServer : Payment webhook\n(approved/rejected)

@enduml

2.1 Payment Flow Status Updated

Loading diagram...
View PlantUML Source
@startuml Lineage II Fun Server - Payment Flow Status Updated

!theme aws-orange
skinparam backgroundColor #ffffff
skinparam defaultFontColor #2c3e50
skinparam sequenceMessageAlign center

title Donation Payment Flow

actor "Player" as Player #lightgreen
participant "WebApp" as WebApp #lightgreen
participant "WebServer" as WebServer #blue
participant "Database" as DB #brown
participant "Mercado Pago" as MercadoPago #orange
participant "Game Server" as GameServer #yellow

alt Payment Approved
    WebServer -> DB : Update payment status
    WebServer -> GameServer : Add coins to account
    GameServer -> WebServer : Coins added successfully
    WebServer -> WebApp : Payment success notification
    WebApp -> Player : Show success message
else Payment Failed
    WebServer -> DB : Update payment status
    WebServer -> WebApp : Payment failed notification
    WebApp -> Player : Show error & retry options
end

@enduml

Payment Flow Features:

  • 💳 Multiple Payment Methods: PIX (instant), Credit Card, Debit Card support
  • 🔐 Secure Processing: PCI-compliant card tokenization and encryption
  • ⚡ Real-time Updates: WebSocket notifications for instant feedback
  • 🛡️ Security Validation: HMAC SHA256 webhook signature verification
  • 🔄 Background Monitoring: Automatic status checking every 5 minutes
  • 💰 Instant Rewards: Coins added to game inventory immediately
  • 📱 PIX Integration: Brazil’s instant payment system with QR codes
  • 💳 Card Processing: Support for all major credit/debit card brands

Details the end-to-end donation payment process using both PIX and Credit/Debit card methods with Mercado Pago integration.

3. Account Registration Flow

Loading diagram...
View PlantUML Source
@startuml Lineage II Fun Server - Account Registration

!theme aws-orange
skinparam backgroundColor #ffffff
skinparam defaultFontColor #2c3e50
skinparam sequenceMessageAlign center

title Account Registration Process

actor "User" as User #lightgreen
participant "WebApp" as WebApp #lightgreen
participant "WebServer" as WebServer #blue
participant "Database" as DB #brown
participant "Mailer App" as MailerApp #lightblue
participant "Game Server" as GameServer #yellow

User -> WebApp : Fill registration form\n(username, email, password)
WebApp -> WebApp : Validate form data
WebApp -> WebServer : Submit registration request

WebServer -> WebServer : Validate user data\n& check duplicates
WebServer -> DB : Store user account
DB -> WebServer : Account created successfully

WebServer -> MailerApp : Send welcome email
MailerApp -> User : Welcome email sent

WebServer -> GameServer : Create game account
GameServer -> GameServer : Initialize player data\n(starting items, stats)
GameServer -> WebServer : Game account ready

WebServer -> WebApp : Registration successful
WebApp -> User : Show success message\n& check email for activation

@enduml

4. Account Activation Flow

Loading diagram...
View PlantUML Source
@startuml Lineage II Fun Server - Account Activation

!theme aws-orange
skinparam backgroundColor #ffffff
skinparam defaultFontColor #2c3e50
skinparam sequenceMessageAlign center

title Account Activation Process

actor "User" as User #lightgreen
participant "WebApp" as WebApp #lightgreen
participant "WebServer" as WebServer #blue
participant "Database" as DB #brown

User -> User : Check email & click activation link
User -> WebApp : Access activation URL
WebApp -> WebServer : Activate account request

WebServer -> WebServer : Validate activation token
WebServer -> DB : Update account status\n(active = true)
DB -> WebServer : Account activated

WebServer -> WebApp : Account activated successfully
WebApp -> User : Account ready!\nYou can now login

@enduml

5. WebSocket Connection Flow

Loading diagram...
View PlantUML Source
@startuml Lineage II Fun Server - WebSocket Connection

!theme aws-orange
skinparam backgroundColor #ffffff
skinparam defaultFontColor #2c3e50
skinparam sequenceMessageAlign center

title WebSocket Connection & Real-time Updates

actor "User" as User #lightgreen
participant "WebApp" as WebApp #lightgreen
participant "WebServer" as WebServer #blue
participant "Game Server" as GameServer #yellow

User -> WebApp : Open application
WebApp -> WebServer : WebSocket connection request
WebServer -> WebServer : Authenticate & register client
WebServer -> WebApp : Connection established

loop Every 30 seconds
    WebServer -> GameServer : Check server status
    GameServer -> WebServer : Server data (players, status)
    WebServer -> WebApp : Broadcast server status
    WebApp -> User : Update live server info
end

@enduml

6. Account Data Flow

Loading diagram...
View PlantUML Source
@startuml Lineage II Fun Server - Account Data

!theme aws-orange
skinparam backgroundColor #ffffff
skinparam defaultFontColor #2c3e50
skinparam sequenceMessageAlign center

title Account Information Request

actor "User" as User #lightgreen
participant "WebApp" as WebApp #lightgreen
participant "WebServer" as WebServer #blue
participant "Database" as DB #brown

User -> WebApp : Request account info
WebApp -> WebServer : Get account data (WebSocket)
WebServer -> DB : Query user account
DB -> WebServer : Account & character data
WebServer -> WebApp : Send account info
WebApp -> User : Display account details

@enduml

7. Payment Notification Flow

Loading diagram...
View PlantUML Source
@startuml Lineage II Fun Server - Payment Notification

!theme aws-orange
skinparam backgroundColor #ffffff
skinparam defaultFontColor #2c3e50
skinparam sequenceMessageAlign center

title Payment Success Notification

participant "WebServer" as WebServer #blue
participant "WebApp" as WebApp #lightgreen
participant "Game Server" as GameServer #yellow
actor "User" as User #lightgreen

note over WebServer : Payment webhook received\nfrom Mercado Pago

WebServer -> GameServer : Add coins to account
GameServer -> WebServer : Coins added successfully
WebServer -> WebApp : Payment success notification\n(WebSocket broadcast)
WebApp -> User : Show success message\n"Coins added! 🎉"

@enduml

8. WebSocket Reconnection Flow

Loading diagram...
View PlantUML Source
@startuml Lineage II Fun Server - WebSocket Reconnection

!theme aws-orange
skinparam backgroundColor #ffffff
skinparam defaultFontColor #2c3e50
skinparam sequenceMessageAlign center

title WebSocket Auto-reconnection

actor "User" as User #lightgreen
participant "WebApp" as WebApp #lightgreen
participant "WebServer" as WebServer #blue

WebServer -> WebApp : Connection lost ❌
WebApp -> WebApp : Detect disconnection
WebApp -> WebApp : Wait (exponential backoff)
WebApp -> WebServer : Attempt reconnection
WebServer -> WebApp : Reconnection successful ✅
WebApp -> WebApp : Restore application state
WebApp -> User : Connection restored

@enduml

WebSocket Features:

  • 🔄 Real-time Updates: Live server status, payment notifications, character updates
  • 🔗 Binding Pattern: Clean separation between UI and WebSocket logic
  • 🛡️ Auto-reconnection: Exponential backoff strategy for connection recovery
  • 📊 Message Processors: Dedicated handlers for each message type
  • 🎯 Targeted Broadcasting: Efficient message routing to specific clients
  • ⚡ Low Latency: Direct WebSocket communication for instant updates

Illustrates the real-time communication patterns between the React frontend and Go backend using WebSocket connections.

9. External Services Integration

Loading diagram...
View PlantUML Source
@startuml Lineage II Fun Server - External Services

!theme aws-orange
skinparam backgroundColor #ffffff
skinparam defaultFontColor #2c3e50
skinparam sequenceMessageAlign center

title External Services Integration

participant "WebServer" as WebServer #blue
participant "OAuth API" as OAuthAPI #purple
participant "Mailer App" as MailerApp #lightblue
participant "Database" as DB #brown
actor "User Email" as UserEmail #lightgreen

== Authentication & Email Flow ==

WebServer -> OAuthAPI : Request authentication token
OAuthAPI -> DB : Validate credentials
DB -> OAuthAPI : User authorized
OAuthAPI -> WebServer : JWT token

WebServer -> WebServer : User registration/donation event
WebServer -> MailerApp : Send email request\n(with JWT token)
MailerApp -> OAuthAPI : Validate token & scope
OAuthAPI -> MailerApp : Token valid

MailerApp -> MailerApp : Send email
MailerApp -> UserEmail : Email delivered
MailerApp -> WebServer : Email sent successfully


@enduml

Details the integration with external microservices (OAuth API and Mailer App), showing authentication flows, email notifications, and service-to-service communication patterns.