# mylaana/aresexpedition architecture

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

- Interactive diagram: https://gitdiagram.com/mylaana/aresexpedition
- Repository: https://github.com/mylaana/aresexpedition

## Overview

##### Project Type and Purpose
- This is a full-stack, real-time, browser-based board-game application (“Ares Expedition”).
- Frontend: Angular SPA (v19) serving UI and handling game state via RxJS.
- Backend: Java Spring Boot (Java 23) exposing both REST endpoints and a STOMP-over-WebSocket API for two-way, low-latency game messaging.
- Auxiliary: A Python CSV parser to generate card and game data JSON files.

##### High-Level Components
A. Client/Browser (Angular SPA)
- UI Components (many card, game-event and layout components)
- Services:
– api.service (REST calls)
– rx-stomp.service (WebSocket connections)
– game-state.service (front-end model)
– event-pile (RxJS event bus)
- Models & DTO interfaces for mapping payloads
- Static assets: card data, images, styles
B. Backend (Spring Boot)
- Config: ApiConfig (REST), WebSocketConfig (STOMP endpoints)
- Controllers:
– ApiController (REST: create game, list cards)
– GameController (HTTP game-management calls)
– WsControllerInput / Output & InputRouter (STOMP message handling)
- Services & Factories: NewGameService, QueryMessageFactory, MessageOutputFactory
- Repository layer: JsonGameDataHandler reading/writing JSON “database”
- Domain Model: Game, PlayerState subclasses, DTOs and enums
C. Parser Script
- parser/parser.py reads CSV, emits JSON used by both front and back
D. Data Storage
- JSON files under back/data (database.json, save.json)

##### Interactions and Data Flows
- On page load the Angular app fetches initial config via REST GET.
- User actions (e.g., “Play card”, “Ready”) generate events in the front-end event pile → transformed into STOMP message payloads → sent to back via WebSocket.
- Backend receives STOMP messages → controllers route to services → update domain model → repository persists JSON → back emits STOMP broadcast messages to all subscribed clients.
- Some operations (e.g., create new game, load card metadata) use REST POST/GET from Angular to Spring Boot.

##### Architectural Patterns & Principles
- MVC on both sides:
- Frontend: Components (View/Controller), game-state service (Model)
- Backend: Controllers, Services (business logic), Repository (persistence)
- Event-Driven Architecture: RxJS event pile drives UI updates; STOMP for server-client events.
- Layered separation: UI → API layer (REST/WS) → Business layer → Data layer.
- DTOs isolate transport schemas from domain models.

##### Final Checklist
- Clear, human-readable labels for each component and protocol.
- Enough granularity: at least group by front-end app modules, REST controller vs WebSocket controller on backend, services, and JSON data store.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Browser Layer
    subgraph "Client Browser (Angular 19)"
        direction TB
        UI["UI Components"]:::frontend
        APIService["api.service"]:::frontend
        WSService["rx-stomp.service"]:::frontend
        GameState["game-state.service"]:::frontend
        EventPile["event-pile (RxJS event bus)"]:::frontend
        Models["Models & DTOs"]:::frontend
        Assets["Static Assets"]:::frontend
        Styles["Styles"]:::frontend
    end

    %% API Gateways Layer
    subgraph "API Gateways"
        direction TB
        ApiREST["ApiController (REST)"]:::backend_api
        GameREST["GameController (HTTP)"]:::backend_api
        InputRouter["InputRouter (STOMP Router)"]:::backend_api
        WsIn["WsControllerInput"]:::backend_api
        WsOut["WsControllerOutput"]:::backend_api
    end

    %% Business Logic Layer
    subgraph "Business Logic"
        direction TB
        NewGame["NewGameService"]:::backend_business
        QueryFactory["QueryMessageFactory"]:::backend_business
        OutputFactory["MessageOutputFactory"]:::backend_business
        JsonHandler["JsonGameDataHandler"]:::backend_business
        Domain["Domain Model & DTOs"]:::backend_business
        Enums["Enums"]:::backend_business
    end

    %% Data Store Layer
    subgraph "Data Store"
        direction TB
        Database["JSON Data Store"]:::datastore
    end

    %% Parser Utility
    Parser["Parser Script (Python CSV→JSON)"]:::parser

    %% Flows
    UI -->|"REST JSON"| ApiREST
    UI -->|"REST JSON"| GameREST
    UI -->|"STOMP over WebSocket"| InputRouter
    UI -->|"STOMP over WebSocket"| WsIn

    ApiREST -->|"invoke"| NewGame
    GameREST -->|"manage game"| NewGame
    WsIn -->|"route message"| QueryFactory
    QueryFactory -->|"map to model"| Domain
    NewGame -->|"create/update"| Domain
    Domain -->|"persist"| JsonHandler
    JsonHandler -->|"read/write"| Database
    Domain -->|"prepare output"| OutputFactory
    OutputFactory -->|"emit STOMP"| WsOut
    WsOut -->|"STOMP over WebSocket"| UI

    %% Parser flows
    Parser -->|"generate JSON"| Assets
    Parser -->|"generate JSON"| Database

    %% Click Events
    click UI "https://github.com/mylaana/aresexpedition/tree/main/front/src/app/components"
    click APIService "https://github.com/mylaana/aresexpedition/blob/main/front/src/app/services/api/api.service.ts"
    click WSService "https://github.com/mylaana/aresexpedition/blob/main/front/src/app/services/websocket/rx-stomp.service.ts"
    click GameState "https://github.com/mylaana/aresexpedition/blob/main/front/src/app/services/core-game/game-state.service.ts"
    click Models "https://github.com/mylaana/aresexpedition/tree/main/front/src/app/models"
    click Models "https://github.com/mylaana/aresexpedition/tree/main/front/src/app/interfaces"
    click Assets "https://github.com/mylaana/aresexpedition/blob/main/front/src/assets/data/cards_data.json"
    click Assets "https://github.com/mylaana/aresexpedition/blob/main/front/src/assets/data/phase-cards_data.json"
    click Assets "https://github.com/mylaana/aresexpedition/blob/main/front/src/assets/data/game-item_data.json"
    click Styles "https://github.com/mylaana/aresexpedition/tree/main/front/src/styles"
    click ApiREST "https://github.com/mylaana/aresexpedition/blob/main/back/src/main/java/com/ares_expedition/config/ApiConfig.java"
    click InputRouter "https://github.com/mylaana/aresexpedition/blob/main/back/src/main/java/com/ares_expedition/controller/websocket/InputRouter.java"
    click WsIn "https://github.com/mylaana/aresexpedition/blob/main/back/src/main/java/com/ares_expedition/controller/websocket/WsControllerInput.java"
    click WsOut "https://github.com/mylaana/aresexpedition/blob/main/back/src/main/java/com/ares_expedition/controller/websocket/WsControllerOutput.java"
    click GameREST "https://github.com/mylaana/aresexpedition/blob/main/back/src/main/java/com/ares_expedition/controller/game/GameController.java"
    click NewGame "https://github.com/mylaana/aresexpedition/blob/main/back/src/main/java/com/ares_expedition/services/NewGameService.java"
    click QueryFactory "https://github.com/mylaana/aresexpedition/blob/main/back/src/main/java/com/ares_expedition/services/QueryMessageFactory.java"
    click OutputFactory "https://github.com/mylaana/aresexpedition/blob/main/back/src/main/java/com/ares_expedition/model/factory/MessageOutputFactory.java"
    click JsonHandler "https://github.com/mylaana/aresexpedition/blob/main/back/src/main/java/com/ares_expedition/repository/JsonGameDataHandler.java"
    click Parser "https://github.com/mylaana/aresexpedition/blob/main/parser/parser.py"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef backend_api fill:#98FB98,stroke:#333,stroke-width:1px
    classDef backend_business fill:#FFA500,stroke:#333,stroke-width:1px
    classDef datastore fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef parser fill:#DDA0DD,stroke:#333,stroke-width:1px
```
