# tsaglam/carcassonne architecture

> Architecture diagram of the GitHub repository tsaglam/carcassonne, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tsaglam/carcassonne
- Repository: https://github.com/tsaglam/carcassonne

## Overview

##### Main Components
- Entry Point & Application Bootstrap: Represent the main class (Carcassonne.java), which starts the game.
- Controller/State Management: Create a component for game control that includes classes such as ControllerFacade, MainController, and the state-related classes (StateGameOver, StateIdle, StateManning, StatePlacing, StateMachine, AbstractGameState). This area employs the State pattern to manage different game phases.
- Model: Group together all business logic and game entities found under “model” (Player, Meeple, Round, grid, tile, terrain, and settings). Include the Artificial Intelligence components (AbstractCarcassonneMove, ArtificialIntelligence, RuleBasedAI, etc.) that are responsible for move selection and game strategy.
- View: Split the user interface into its subcomponents (main, secondary, tertiary, menubar, util). Clearly represent how these packages support user interaction, from the main game view (MainView, TileLayer, MeepleLayer, etc.) to specialized dialogs and controls (GridSizeDialog, PlayerSettingsView, etc.). Note that there’s a separation into multiple views (e.g., primary game board view, secondary panels for in-game actions, and tertiary views for statistics and settings).
- Utilities & Helpers: In the “util” package, include image scaling, caching, error reporting, and threading utilities that support the main functionalities. Also include configuration and settings from the “settings” package.

##### Relationships and Interactions
- Entry Flow: Start with the Carcassonne.java class which initializes the game, pulling together various submodules.
- Controller and State Machine: Show that user input (possibly coming from the View components, e.g., via mouse events and key bindings) is handled by the controller. The controller, through its façade and adapter classes, communicates with the game’s state machine, which transitions between states (Idle, Manning, Placing, Game Over) based on user actions.
- Model-View Interaction: Highlight how the model (game engine and objects) works in tandem with the view. For instance, when a tile is placed or a move is made, the model is updated and the View components (MainView, SecondaryView, etc.) get notified to render the changes.
- Artificial Intelligence: Include a separate block for AI components (AI classes and rule-based systems), interacting with the controller and model to simulate computer opponents.

##### Architectural Patterns and Design Principles
- MVC Pattern: Distinguish between the Model (game logic and data), View (graphical user interface), and Controller (logic for processing user inputs and managing game states).
- State Pattern: Clearly show the state machine and its various states that control the game flow.
- Facade/Adapter Patterns: Mark components such as ControllerFacade and ControllerAdapter that simplify interactions between various subsystems.
- Utility Modules: Represent helper and utility modules (for image scaling and error handling) that are used by multiple parts of the system.

##### Relevant Technologies and Tools
- Java SE 17+ is required, and Maven is used as the build tool.
- CI/CD is configured using GitHub workflows (CI.yml and sonar.yml), indicating automated build and code quality checks.

- An “Entry Point & Bootstrap” block (Carcassonne.java).
- A “Game Controller” block showing the façade and adapter classes, linked with a “State Machine” block that enumerates its states.
- A “Game Model” block containing entities (Player, Meeple, Round, Tile, Grid, etc.) along with an embedded “AI Module” block.
- A “View” block subdivided into main, secondary, tertiary, and menubar components.
- A “Utilities & Settings” block for helper classes, configuration, and image handling.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Game Application"
        E1("Carcassonne.java"):::entry
        %% Controller & State Management Block
        subgraph "Controller & State Management"
            C1("Controller Facade & Adapter"):::controller
            S1("State Machine"):::state
            S2("States:Idle/Manning/Placing/GameOver"):::state
            C1 -->|"updates"| S1
            S1 -->|"controls"| S2
        end
        %% Game Model Block
        subgraph "Game Model"
            M1("Core Model (Player, Meeple, Round)"):::model
            M2("AI Module"):::model
            M3a("Grid Management"):::model
            M3b("Tile & Terrain Management"):::model
            M2 -->|"influences"| M1
            M3a -->|"integrates"| M1
            M3b -->|"integrates"| M1
        end
        %% View Block
        subgraph "View"
            V1("Main View (Game Board)"):::view
            V2("Secondary View"):::view
            V3("Tertiary Panels/Dialog"):::view
            V4("Menubar & Menu Components"):::view
            V5("View Utilities"):::view
        end
        %% Utilities & Settings Block
        subgraph "Utilities & Settings"
            U1("General Utilities"):::util
            U2("Settings & Configurations"):::util
        end
        %% Resources Block
        subgraph "Resources"
            R1("Game Assets"):::resources
        end
    end

    %% Flow of Processes
    E1 -->|"bootstraps"| C1
    V1 -->|"userInput"| C1
    V2 -->|"userInput"| C1
    V3 -->|"userInput"| C1
    V4 -->|"userInput"| C1

    C1 -->|"triggersState"| S1
    S1 -->|"updatesModel"| M1
    M1 -->|"rendersUpdate"| V1
    M1 -->|"rendersUpdate"| V2
    M1 -->|"rendersUpdate"| V3
    M1 -->|"rendersUpdate"| V4
    M2 -->|"suggestsMove"| C1

    %% Utilities interaction (dotted connections)
    U1 -.-> M1
    U1 -.-> V1
    U2 -.-> M1
    U2 -.-> V1

    %% Resources providing assets to views
    R1 -->|"suppliesAssets"| V1
    R1 -->|"suppliesAssets"| V4

    %% Click Events
    click E1 "https://github.com/tsaglam/carcassonne/blob/master/src/main/java/carcassonne/Carcassonne.java"
    click C1 "https://github.com/tsaglam/carcassonne/tree/master/src/main/java/carcassonne/control"
    click S1 "https://github.com/tsaglam/carcassonne/tree/master/src/main/java/carcassonne/control/state"
    click M1 "https://github.com/tsaglam/carcassonne/tree/master/src/main/java/carcassonne/model"
    click M2 "https://github.com/tsaglam/carcassonne/tree/master/src/main/java/carcassonne/model/ai"
    click M3a "https://github.com/tsaglam/carcassonne/tree/master/src/main/java/carcassonne/model/grid"
    click M3b "https://github.com/tsaglam/carcassonne/tree/master/src/main/java/carcassonne/model/tile"
    click V1 "https://github.com/tsaglam/carcassonne/tree/master/src/main/java/carcassonne/view/main"
    click V2 "https://github.com/tsaglam/carcassonne/tree/master/src/main/java/carcassonne/view/secondary"
    click V3 "https://github.com/tsaglam/carcassonne/tree/master/src/main/java/carcassonne/view/tertiary"
    click V4 "https://github.com/tsaglam/carcassonne/tree/master/src/main/java/carcassonne/view/menubar"
    click V5 "https://github.com/tsaglam/carcassonne/tree/master/src/main/java/carcassonne/view/util"
    click U1 "https://github.com/tsaglam/carcassonne/tree/master/src/main/java/carcassonne/util"
    click U2 "https://github.com/tsaglam/carcassonne/tree/master/src/main/java/carcassonne/settings"
    click R1 "https://github.com/tsaglam/carcassonne/tree/master/src/main/resources"

    %% Styles
    classDef entry fill:#FFD700,stroke:#DAA520,stroke-width:2px
    classDef controller fill:#ADD8E6,stroke:#0000FF,stroke-width:2px
    classDef state fill:#87CEFA,stroke:#1E90FF,stroke-width:2px
    classDef model fill:#90EE90,stroke:#008000,stroke-width:2px
    classDef view fill:#FFA07A,stroke:#FF4500,stroke-width:2px
    classDef util fill:#D3D3D3,stroke:#696969,stroke-width:2px
    classDef resources fill:#FFFFE0,stroke:#EEE8AA,stroke-width:2px
```
