# youkaba/cards-game architecture

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

- Interactive diagram: https://gitdiagram.com/youkaba/cards-game
- Repository: https://github.com/youkaba/cards-game

## Overview

##### Project Type and Purpose
- This project is a Java-based REST API application built with Spring Boot and Maven. Its purpose is to simulate a basic deck of playing cards game, where multiple players interact with a “game deck” formed by one or more standard 52-card decks.
- The README explicitly lists operations such as game creation/deletion, deck manipulation, card dealing, and querying players’ hands and remaining cards per suit. It also requires an in-memory datastore with custom concurrency handling and event logging for changes.

##### File Structure
- The overall structure follows a layered, hexagonal (or ports and adapters) architecture, splitting the application into clearly defined components:
- The adapter layer is split into two directories:
- "adapters/primary" holds the entry points (REST controllers) and configuration classes. For example, CardsGameApplication.java is the main Spring Boot application, and the controllers (e.g., DeckController, GameController, PlayerController) expose the REST API.
- "adapters/secondary" holds the gateway implementations (e.g., InMemoryDeckRepository, InMemoryGameRepository) that fulfill repository interfaces.
- The "businesslogic" folder encapsulates:
- Domain models (e.g., Card, Deck, Game, Player, Suit).
- Use case implementations (e.g., CreateGame, AddPlayer, DealCard, etc.) which detail the core behaviors.
- Exception handling for domain-specific errors.
- Configuration files (RepositoriesConfiguration.java, UseCaseConfiguration.java) indicate dependency injection and wiring of these components.
- Other elements such as application.properties and test suites in the "src/test" folder further confirm the structured, testable design.

a. Main components:
- Presentation Layer (Primary Adapter):
- REST Controllers that expose endpoints for game operations (DeckController, GameController, PlayerController).
- The main application entry point (CardsGameApplication.java) and configuration classes.
- Business Logic Layer:
- Use Cases representing operations (CreateGame, DealCard, AddPlayer, etc.)
- Domain models representing Card, Deck, Game, and Player.
- Exception modules handling error cases.
- Persistence/Infrastructure Layer (Secondary Adapter):
- Repository interfaces defined in the businesslogic layer (DeckRepository, GameRepository).
- Implementations of these interfaces (InMemoryDeckRepository, InMemoryGameRepository) that provide in-memory datastore support with built-in concurrency handling.
- Event Handling Component:
- Although not isolated in its own module, the design includes triggering events when actions occur to record history changes; indicate this as a separate “Event Logging” component that interacts with each layer as required.

b. Relationships and Interactions:
- Client requests entering the system via the REST controllers.
- That use cases depend on repository interfaces (ports) and that the implementations (adapters/secondary) fulfill those contracts.
- Optionally, show configuration classes wiring these dependencies.

c. Architectural Patterns and Design Principles:
- Hexagonal/ports-and-adapters architecture: The “primary” adapters expose the API, while “secondary” adapters abstract underlying storage.
- Separation of concerns between presentation (controllers), business rules (use cases, domain models), and infrastructure (in-memory repositories).
- That dependency injection (via Spring Boot configuration classes) is used to manage component wiring.
- Patterns such as Repository Pattern (using interfaces and in-memory implementations) and use of RESTful API principles.

d. Relevant Technologies and Frameworks:
- Java 17 and Spring Boot 3.x as the base technology.
- Maven (pom.xml, mvnw, mvnw.cmd) for build configuration.
- In-memory data handling with custom concurrency support.
- The event triggering and logging requirement.
- Testing frameworks used in unit tests (as observed in the “src/test” folder).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    Client["HTTP Client"]:::client

    %% Presentation Layer (Primary Adapter)
    subgraph "Presentation Layer (Primary Adapter)"
        CA["CardsGameApplication"]:::presentation
        DC["DeckController"]:::presentation
        GC["GameController"]:::presentation
        PC["PlayerController"]:::presentation
        RC["RepositoriesConfiguration"]:::config
        UC["UseCaseConfiguration"]:::config
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        %% Domain Models
        C["Card"]:::business
        D["Deck"]:::business
        G["Game"]:::business
        P["Player"]:::business
        S["Suit"]:::business

        %% Use Cases
        CG["CreateGame"]:::business
        CD["CreateDeck"]:::business
        AP["AddPlayer"]:::business
        DCa["DealCard"]:::business
        Others["Others(usecases)"]:::business

        %% Exception Handling
        ExistEx["AlreadyExistException"]:::business
        NotFoundEx["NotFoundException"]:::business
    end

    %% Persistence/Infrastructure Layer (Secondary Adapter)
    subgraph "Persistence/Infrastructure Layer"
        DR["DeckRepository"]:::repository
        GR["GameRepository"]:::repository
        IMDR["InMemoryDeckRepository"]:::repository
        IMGR["InMemoryGameRepository"]:::repository
    end

    %% Event Logging Component
    subgraph "Event Logging"
        EL["Event Logger"]:::event
    end

    %% Connections
    Client -->|"sendsRequest"| CA

    CA -->|"triggers"| DC
    CA -->|"triggers"| GC
    CA -->|"triggers"| PC

    DC -->|"calls"| CD
    DC -->|"calls"| DCa
    GC -->|"calls"| CG
    PC -->|"calls"| AP

    %% Use case to Event Logging
    CG -->|"triggersEvent"| EL
    CD -->|"triggersEvent"| EL
    AP -->|"triggersEvent"| EL
    DCa -->|"triggersEvent"| EL

    %% Use case dependencies on domain models
    CG -->|"operates_on"| G
    CD -->|"operates_on"| D
    AP -->|"operates_on"| P
    DCa -->|"operates_on"| C

    %% Use cases wired by configuration
    UC -->|"wires"| CG
    UC -->|"wires"| CD
    UC -->|"wires"| AP
    UC -->|"wires"| DCa
    UC -->|"wires"| Others

    %% Repository wiring
    CG -->|"uses"| GR
    CD -->|"uses"| DR
    AP -->|"uses"| DR
    DCa -->|"uses"| DR

    DR -->|"impl_by"| IMDR
    GR -->|"impl_by"| IMGR
    RC -->|"configures"| IMDR
    RC -->|"configures"| IMGR

    %% Click Events for Presentation Layer
    click CA "https://github.com/youkaba/cards-game/blob/master/src/main/java/com/example/cardsgame/adapters/primary/CardsGameApplication.java"
    click DC "https://github.com/youkaba/cards-game/blob/master/src/main/java/com/example/cardsgame/adapters/primary/controllers/DeckController.java"
    click GC "https://github.com/youkaba/cards-game/blob/master/src/main/java/com/example/cardsgame/adapters/primary/controllers/GameController.java"
    click PC "https://github.com/youkaba/cards-game/blob/master/src/main/java/com/example/cardsgame/adapters/primary/controllers/PlayerController.java"
    click RC "https://github.com/youkaba/cards-game/blob/master/src/main/java/com/example/cardsgame/adapters/primary/config/RepositoriesConfiguration.java"
    click UC "https://github.com/youkaba/cards-game/blob/master/src/main/java/com/example/cardsgame/adapters/primary/config/UseCaseConfiguration.java"

    %% Click Events for Business Logic Layer - Domain Models
    click C "https://github.com/youkaba/cards-game/blob/master/src/main/java/com/example/cardsgame/businesslogic/models/Card.java"
    click D "https://github.com/youkaba/cards-game/blob/master/src/main/java/com/example/cardsgame/businesslogic/models/Deck.java"
    click G "https://github.com/youkaba/cards-game/blob/master/src/main/java/com/example/cardsgame/businesslogic/models/Game.java"
    click P "https://github.com/youkaba/cards-game/blob/master/src/main/java/com/example/cardsgame/businesslogic/models/Player.java"
    click S "https://github.com/youkaba/cards-game/blob/master/src/main/java/com/example/cardsgame/businesslogic/models/Suit.java"

    %% Click Events for Business Logic Layer - Use Cases
    click CG "https://github.com/youkaba/cards-game/blob/master/src/main/java/com/example/cardsgame/businesslogic/usecases/CreateGame.java"
    click CD "https://github.com/youkaba/cards-game/blob/master/src/main/java/com/example/cardsgame/businesslogic/usecases/CreateDeck.java"
    click AP "https://github.com/youkaba/cards-game/blob/master/src/main/java/com/example/cardsgame/businesslogic/usecases/AddPlayer.java"
    click DCa "https://github.com/youkaba/cards-game/blob/master/src/main/java/com/example/cardsgame/businesslogic/usecases/DealCard.java"

    %% Click Events for Business Logic Layer - Exceptions
    click ExistEx "https://github.com/youkaba/cards-game/blob/master/src/main/java/com/example/cardsgame/businesslogic/exceptions/AlreadyExistException.java"
    click NotFoundEx "https://github.com/youkaba/cards-game/blob/master/src/main/java/com/example/cardsgame/businesslogic/exceptions/NotFoundException.java"

    %% Click Events for Persistence/Infrastructure Layer
    click DR "https://github.com/youkaba/cards-game/blob/master/src/main/java/com/example/cardsgame/businesslogic/gateways/DeckRepository.java"
    click GR "https://github.com/youkaba/cards-game/blob/master/src/main/java/com/example/cardsgame/businesslogic/gateways/GameRepository.java"
    click IMDR "https://github.com/youkaba/cards-game/blob/master/src/main/java/com/example/cardsgame/adapters/secondary/gateways/repositories/InMemoryDeckRepository.java"
    click IMGR "https://github.com/youkaba/cards-game/blob/master/src/main/java/com/example/cardsgame/adapters/secondary/gateways/repositories/InMemoryGameRepository.java"

    %% Styles
    classDef client fill:#D3D3D3,stroke:#333,stroke-width:2px;
    classDef presentation fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef business fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef repository fill:#FFFFE0,stroke:#333,stroke-width:2px;
    classDef config fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef event fill:#FFB6C1,stroke:#333,stroke-width:2px;
```
