# safwan-hossain/java-poker architecture

> Architecture diagram of the GitHub repository safwan-hossain/java-poker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/safwan-hossain/java-poker
- Repository: https://github.com/safwan-hossain/java-poker

## Overview

##### Project Type and Purpose
- This is a Java-based backend application built with Maven that implements the logic for a multiplayer poker game.
- The project is structured in a layered way; it incorporates domain logic (poker game rules and state), orchestration of game rounds, state machine-driven game flow, and WebSocket-based communication to interact with clients.
- The presence of a Dockerfile indicates that the application is designed to be containerized and potentially deployed as part of a microservices infrastructure.

##### Analyzing the File Structure
- Top-Level Structure:
- Key files include the Maven build files (pom.xml, mvnw) and a Dockerfile.
- The “src/main/java” folder is organized into several packages: application (orchestrator for game logic), domain (game and relational logic like player and deck management), enumeration (constants/enumerators for game states), infrastructure (communication, config, and websocket management), server (game lobby, settings, sessions), services (game update, table registry, timeout management), and statemachine (actions, configuration, events, guards).
- There’s also a “src/test” folder with tests focused on domain utilities (like hand evaluation).

a. Main Components:
- Application Entry Point: Represented by PokerGameApplication.
- Application / Orchestration Layer: Include GameLogicHandler and RoundFlowManager. This layer coordinates the primary game logic and round flow.
- Domain Layer: Shows core domain objects and managers (Game, ServerGame, Player, Card, Deck, HandEvaluation, BettingManager, DeckManager, PlayerManager, etc.). These encapsulate the game’s state and rules.
- Infrastructure / Communication Layer:
- WebSocket Components: GameWebSocketHandler, WebSocketManager, and related configuration (WebSocketConfig) that enable real-time communication.
- Communication Services: GameBroadcaster, GameMessenger, and the update package with various update implementations which handle message transmission.
- Service Layer: Includes services like GameTableRegistry, GameUpdateService, and TimeoutService that manage session/state and update logic.
- State Machine: Components grouped under “statemachine” (actions, events, guards, configuration). This layer handles transitions such as round start, round end, player actions, and game over via defined actions and guard conditions.

b. Relationships and Data Flow:
- Client connections (via WebSocket) interact with the Communication Layer which channels inputs to the Application Layer.
- From the entry point, GameLogicHandler and RoundFlowManager consume actions and then use domain managers to update the game state.
- The Domain Layer interacts tightly with the State Machine which defines business rules using actions (e.g., AdvanceRoundAction, ApplyPlayerMoveAction) and guards (e.g., IsRoundFinishedGuard, IsPlayerActionValidGuard).
- Service Layer components interface with both the domain and communication layers to broadcast game updates to client applications through predefined messaging protocols.
- Configuration classes (like JacksonConfig) help set up serialization, while the Dockerfile and Maven scripts define the build and deployment pipeline.

c. Architectural Patterns & Technologies:
- Layered Architecture: Separates concerns into presentation (websocket), application/orchestration, domain logic, and infrastructure.
- State Machine Pattern: Utilized to handle game state transitions via defined actions, events, and guard conditions.
- Event-Driven / Messaging Design: Indicated by the presence of a “GameStateEventPublisher” and various update impl classes – likely to handle asynchronous game updates.
- Websocket Communication: For real-time interaction and updates between clients and the server.
- Docker Containerization: For deployment management.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    client["Client (WebSocket)"]:::client

    %% Communication Layer
    subgraph "Communication Layer"
        gameWSHandler["GameWebSocketHandler"]:::infra
        wsManager["WebSocketManager"]:::infra
        wsConfig["WebSocketConfig"]:::infra
        jackson["JacksonConfig"]:::config
        broadcaster["GameBroadcaster"]:::infra
        messenger["GameMessenger"]:::infra
    end

    %% Application / Orchestration Layer
    subgraph "Application Layer"
        entry["PokerGameApplication"]:::app
        logicHandler["GameLogicHandler"]:::app
        roundManager["RoundFlowManager"]:::app
    end

    %% Domain Layer
    subgraph "Domain Layer"
        game["Game"]:::domain
        serverGame["ServerGame"]:::domain
        betting["BettingManager"]:::domain
        deckMgr["DeckManager"]:::domain
        playerMgr["PlayerManager"]:::domain
        card["Card"]:::domain
        cardFactory["CardFactory"]:::domain
        deck["Deck"]:::domain
        handEval["HandEvaluation"]:::domain
        player["Player"]:::domain
    end

    %% State Machine Layer
    subgraph "State Machine"
        baseAction["BaseAction"]:::state
        stateConfig["PokerStateMachineConfig"]:::state
        eventPub["GameStateEventPublisher"]:::state
        baseGuard["BaseGuard"]:::state
    end

    %% Service Layer
    subgraph "Service Layer"
        updateService["GameUpdateService"]:::service
        tableRegistry["GameTableRegistry"]:::service
        timeout["TimeoutService"]:::service
    end

    %% Deployment
    deploy["Dockerfile"]:::deploy

    %% Connections

    %% Client to Communication
    client -->|"connects"| gameWSHandler

    %% Communication internal connections
    wsConfig --> wsManager
    wsManager --> gameWSHandler

    %% Application Layer initialization
    entry --> logicHandler
    entry --> roundManager

    %% Communication to Application Layer
    gameWSHandler -->|"forwards input"| logicHandler

    %% Application Layer to Domain Layer
    logicHandler -->|"updates"| game
    logicHandler -->|"manages"| betting
    logicHandler -->|"manages"| deckMgr
    logicHandler -->|"manages"| playerMgr
    roundManager -->|"controls round"| serverGame

    %% Domain Layer Interactions
    game -->|"state changes"| baseAction
    serverGame -->|"triggers"| baseGuard

    %% Domain additional interactions
    card -->|"used by"| cardFactory
    cardFactory -->|"creates"| card
    deck -->|"evaluated by"| handEval
    player -->|"participates in"| game

    %% State Machine to Service Layer
    baseAction --> updateService
    baseGuard --> updateService
    stateConfig --> updateService
    eventPub --> updateService

    %% Service Layer to Communication (broadcast updates)
    updateService --> broadcaster
    updateService --> messenger
    broadcaster -->|"pushes updates"| gameWSHandler
    messenger -->|"pushes notifications"| gameWSHandler

    %% Configuration link to Application layer (for serialization)
    jackson --> logicHandler

    %% Deployment connection (overall containerization)
    deploy --- entry

    %% Click Events for Application Layer
    click entry "https://github.com/safwan-hossain/java-poker/blob/main/src/main/java/com/poker/PokerGameApplication.java"
    click logicHandler "https://github.com/safwan-hossain/java-poker/blob/main/src/main/java/com/poker/application/orchestrator/GameLogicHandler.java"
    click roundManager "https://github.com/safwan-hossain/java-poker/blob/main/src/main/java/com/poker/application/orchestrator/RoundFlowManager.java"

    %% Click Events for Domain Layer
    click game "https://github.com/safwan-hossain/java-poker/blob/main/src/main/java/com/poker/domain/game/Game.java"
    click serverGame "https://github.com/safwan-hossain/java-poker/blob/main/src/main/java/com/poker/domain/game/ServerGame.java"
    click betting "https://github.com/safwan-hossain/java-poker/blob/main/src/main/java/com/poker/domain/game/manager/BettingManager.java"
    click deckMgr "https://github.com/safwan-hossain/java-poker/blob/main/src/main/java/com/poker/domain/game/manager/DeckManager.java"
    click playerMgr "https://github.com/safwan-hossain/java-poker/blob/main/src/main/java/com/poker/domain/game/manager/PlayerManager.java"
    click card "https://github.com/safwan-hossain/java-poker/blob/main/src/main/java/com/poker/domain/player/Card.java"
    click cardFactory "https://github.com/safwan-hossain/java-poker/blob/main/src/main/java/com/poker/domain/player/CardFactory.java"
    click deck "https://github.com/safwan-hossain/java-poker/blob/main/src/main/java/com/poker/domain/player/Deck.java"
    click handEval "https://github.com/safwan-hossain/java-poker/blob/main/src/main/java/com/poker/domain/player/HandEvaluation.java"
    click player "https://github.com/safwan-hossain/java-poker/blob/main/src/main/java/com/poker/domain/player/Player.java"

    %% Click Events for Communication Layer
    click gameWSHandler "https://github.com/safwan-hossain/java-poker/blob/main/src/main/java/com/poker/infrastructure/websocket/GameWebSocketHandler.java"
    click wsManager "https://github.com/safwan-hossain/java-poker/blob/main/src/main/java/com/poker/infrastructure/websocket/WebSocketManager.java"
    click wsConfig "https://github.com/safwan-hossain/java-poker/blob/main/src/main/java/com/poker/infrastructure/config/WebSocketConfig.java"
    click broadcaster "https://github.com/safwan-hossain/java-poker/blob/main/src/main/java/com/poker/infrastructure/communication/GameBroadcaster.java"
    click messenger "https://github.com/safwan-hossain/java-poker/blob/main/src/main/java/com/poker/infrastructure/communication/GameMessenger.java"
    click jackson "https://github.com/safwan-hossain/java-poker/blob/main/src/main/java/com/poker/infrastructure/config/JacksonConfig.java"

    %% Click Events for Service Layer
    click updateService "https://github.com/safwan-hossain/java-poker/blob/main/src/main/java/com/poker/services/GameUpdateService.java"
    click tableRegistry "https://github.com/safwan-hossain/java-poker/blob/main/src/main/java/com/poker/services/GameTableRegistry.java"
    click timeout "https://github.com/safwan-hossain/java-poker/blob/main/src/main/java/com/poker/services/TimeoutService.java"

    %% Click Events for State Machine Layer
    click baseAction "https://github.com/safwan-hossain/java-poker/blob/main/src/main/java/com/poker/statemachine/actions/BaseAction.java"
    click stateConfig "https://github.com/safwan-hossain/java-poker/blob/main/src/main/java/com/poker/statemachine/config/PokerStateMachineConfig.java"
    click eventPub "https://github.com/safwan-hossain/java-poker/blob/main/src/main/java/com/poker/statemachine/events/GameStateEventPublisher.java"
    click baseGuard "https://github.com/safwan-hossain/java-poker/blob/main/src/main/java/com/poker/statemachine/guards/BaseGuard.java"

    %% Click Event for Deployment
    click deploy "https://github.com/safwan-hossain/java-poker/tree/main/Dockerfile"

    %% Styles
    classDef client fill:#D4A5A5,stroke:#000,stroke-width:1px;
    classDef app fill:#AED6F1,stroke:#000,stroke-width:1px;
    classDef domain fill:#A9DFBF,stroke:#000,stroke-width:1px;
    classDef infra fill:#F9E79F,stroke:#000,stroke-width:1px;
    classDef service fill:#F5B7B1,stroke:#000,stroke-width:1px;
    classDef state fill:#F8C471,stroke:#000,stroke-width:1px;
    classDef config fill:#CCD1D1,stroke:#000,stroke-width:1px;
    classDef deploy fill:#E8DAEF,stroke:#000,stroke-width:1px;
```
