# kenj-1/oop2javaproject architecture

> Architecture diagram of the GitHub repository kenj-1/oop2javaproject, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kenj-1/oop2javaproject
- Repository: https://github.com/kenj-1/oop2javaproject

## Overview

##### Project type & purpose (what you’re diagramming)
This is a **desktop Java game** (single-process) implemented with **Java Swing/IntelliJ GUI Designer** (`*.form` + `*.java`). The game is titled **“Encantadia: Echoes of the Gem”** and is structured as:
- **UI layer**: multiple Swing Frames/Dialogs representing screens and flows (welcome → main menu → mode selection → character selection → battle → result/story dialogs).
- **Domain layer**: characters with stats/behaviors (`characters/Character` + concrete hero classes).
- **Battle engine**: turn-based combat with skills, cooldowns, and status effects (`battle/TurnManager`, `Skill`, `CooldownManager`, `StatusEffect`, `TurnResult`).
- No explicit server/database; state is in-memory.

##### File structure (what components exist)
From the tree:

##### Entry point / bootstrap
- `src/encantadia/Main.java`
Likely bootstraps the app, initializes UI, starts at welcome or main menu.

##### Battle engine (core game logic)
- `src/encantadia/battle/TurnManager.java`
- `src/encantadia/battle/TurnResult.java`
- `src/encantadia/battle/Skill.java`
- `src/encantadia/battle/CooldownManager.java`
- `src/encantadia/battle/StatusEffect.java`

This is the “combat subsystem” and should be shown as a cohesive component with clear responsibilities:
- Turn sequencing, applying skills, checking cooldowns, applying status effects, producing results for UI.

##### Domain model (characters)
- `src/encantadia/characters/Character.java` (base abstraction)
- Concrete classes: `Adamus, Dea, Dirk, Flamara, MakelanShere, Mary, Tera, Tyrone` etc.

This is the “entity/model subsystem”.

##### UI / UX screens (Swing)
- `src/encantadia/ui/ux/*.java` + matching `*.form`
- `WelcomeScreenPage`
- `MainMenuFrame`
- `StorylineDialogBox`
- `CharacterSelectionFrame`
- `BattleFrame`
- `ResultDialogFrame`
- `src/encantadia/ui/ux/gamemodeselection/*`:
- `ArcadeMode`, `PVEMode`, `PVPMode` (+ forms)

These are distinct “presentation components” and also define the navigation graph.

##### README insights to incorporate
The README suggests additional conceptual modules (even if not present in your actual tree):
- `docs/mechanics.md` (implies rules that map to `battle/*`)
- Mentions `utils/` (`Dice`, `InputValidator`, `Constants`) — not in the provided tree, but if they exist in your local repo, include them as a shared utility component.

##### Encantadia Desktop App (JVM process) (one big container)
- **UI Layer (Swing/IntelliJ Forms)**
- WelcomeScreenPage
- MainMenuFrame
- StorylineDialogBox
- GameModeSelection (ArcadeMode / PVEMode / PVPMode)
- CharacterSelectionFrame
- BattleFrame
- ResultDialogFrame
- **Game Domain Layer**
- Character (base)
- Concrete Characters (Mary, Dirk, etc.)
- (Optional) “Roster/Party” concept if present in code
- **Battle Engine**
- TurnManager
- Skill
- StatusEffect
- CooldownManager
- TurnResult
- **Shared Utilities** (only if actually present)
- Dice / RNG
- Input validation
- Constants/config

##### External dependencies
- Java Swing (javax.swing)
- IntelliJ UI Designer runtime (implied by `.form` usage)

No database, no network, no microservices—so avoid “server” blocks unless you actually add them.

##### Architectural patterns present
Even if not explicitly labeled, the project strongly suggests:
- **Layering**: Presentation (Swing) vs Domain vs Engine.
- **Stateful in-memory model**: characters and battle state live in objects, no persistence.
- **Strategy-like mode branching**: Arcade/PVE/PVP as variants of a “game mode” behavior.
- **Result object pattern**: `TurnResult` as a structured output from engine → UI (good separation).

##### Relevant technologies
Explicit labels:
- “Java 8+ (JVM)”
- “Swing UI (IntelliJ GUI Designer .form)”
- If there is any AI logic inside PVE/Arcade (not shown here), label that as “AI Decision Logic”.

- One container: **Desktop App (JVM)**
- Inside it: UI / Battle / Domain / Utilities
- UI → Battle
- UI → Domain (selection/setup)
- Battle → Domain (mutates state)
- Battle → Utilities (RNG/constants) if present

Pick the core loop: **Battle Turn Execution**:
##### If end → `ResultDialogFrame`

Also produce a smaller **UI navigation flow** (state machine style) for screens.

##### Practical “don’t overthink it” decomposition (as many components as possible)
Given this repo, the best “maximally separated but still truthful” breakdown is:

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% ========= External Dependencies =========
    subgraph "External Dependencies"
        Swing["Java Swing / AWT\n(javax.swing, java.awt)"]:::external
        IntelliJ["IntelliJ GUI Designer Runtime\n(.form binding)"]:::external
    end

    %% ========= Single Process Container =========
    subgraph "Encantadia: Echoes of the Gem (Desktop App • Single JVM Process)"
        direction TB

        Main["Main (App Bootstrap)\nencantadia.Main"]:::bootstrap

        %% ----- UI Layer -----
        subgraph "UI Layer (Swing Screens • .form + .java)"
            direction TB

            UIUX["UI/UX Package\nencantadia.ui.ux"]:::package

            Welcome["WelcomeScreenPage\n(Frame/Page)"]:::ui
            MainMenu["MainMenuFrame\n(Main navigation)"]:::ui
            Story["StorylineDialogBox\n(Dialog)"]:::ui

            subgraph "Game Mode Selection (Branching Screens)"
                direction TB
                UIModePkg["gamemodeselection Package\nencantadia.ui.ux.gamemodeselection"]:::package
                Arcade["ArcadeMode\n(Screen)"]:::ui
                PVE["PVEMode\n(Screen)"]:::ui
                PVP["PVPMode\n(Screen)"]:::ui
            end

            CharSelect["CharacterSelectionFrame\n(Choose heroes/roster)"]:::ui
            BattleUI["BattleFrame\n(Controls + renders combat)"]:::ui
            ResultUI["ResultDialogFrame\n(Win/Lose summary)"]:::ui
        end

        %% ----- Battle Engine -----
        subgraph "Battle Engine (Turn-based Combat Subsystem)\nencantadia.battle"
            direction TB
            BattlePkg["Battle Package\nencantadia.battle"]:::package

            TurnMgr["TurnManager\n(Sequencing + executeTurn)"]:::engine
            Cooldowns["CooldownManager\n(Track/decrement cooldowns)"]:::engine
            Skill["Skill\n(Abilities/actions)"]:::engine
            Status["StatusEffect\n(Buffs/debuffs over turns)"]:::engine
            TurnRes["TurnResult\n(Result DTO for UI)"]:::engine
        end

        %% ----- Domain Model -----
        subgraph "Domain Model (Characters)\nencantadia.characters"
            direction TB
            CharPkg["Characters Package\nencantadia.characters"]:::package

            Character["Character (Base/Abstract)\n(HP/MP/Stats/State)"]:::domain

            subgraph "Concrete Characters"
                direction TB
                Adamus["Adamus"]:::domain
                Dea["Dea"]:::domain
                Dirk["Dirk"]:::domain
                Flamara["Flamara"]:::domain
                Makelan["MakelanShere"]:::domain
                Mary["Mary"]:::domain
                Tera["Tera"]:::domain
                Tyrone["Tyrone"]:::domain
            end
        end

        %% ===== Dependencies (compile-time / call relationships) =====
        Main -->|"initializes_UI"| Welcome
        Main -->|"loads_UI_designer_forms"| IntelliJ
        UIUX -->|"uses"| Swing
        UIUX -->|"binds_forms"| IntelliJ

        %% UI navigation (runtime transitions) - dashed
        Welcome -.->|"next_screen"| MainMenu
        MainMenu -.->|"open_story"| Story
        Story -.->|"back_to_menu"| MainMenu
        MainMenu -.->|"select_mode"| Arcade
        MainMenu -.->|"select_mode"| PVE
        MainMenu -.->|"select_mode"| PVP
        Arcade -.->|"configure_rules_then"| CharSelect
        PVE -.->|"configure_rules_then"| CharSelect
        PVP -.->|"configure_rules_then"| CharSelect
        CharSelect -.->|"start_battle"| BattleUI
        BattleUI -.->|"end_of_battle"| ResultUI
        ResultUI -.->|"retry_or_menu"| MainMenu

        %% UI -> Domain (setup)
        CharSelect -->|"creates/selects"| Character
        CharSelect -->|"instantiates"| Adamus
        CharSelect -->|"instantiates"| Dea
        CharSelect -->|"instantiates"| Dirk
        CharSelect -->|"instantiates"| Flamara
        CharSelect -->|"instantiates"| Makelan
        CharSelect -->|"instantiates"| Mary
        CharSelect -->|"instantiates"| Tera
        CharSelect -->|"instantiates"| Tyrone

        %% UI -> Engine (battle actions)
        BattleUI -->|"execute_turn(skill_click)"| TurnMgr
        BattleUI <-->|"render_from"| TurnRes

        %% Engine internals
        TurnMgr -->|"checks/updates"| Cooldowns
        TurnMgr -->|"applies"| Skill
        TurnMgr -->|"applies/ticks"| Status
        TurnMgr -->|"produces"| TurnRes

        %% Engine -> Domain (mutates in-memory state)
        TurnMgr -->|"reads/writes_state"| Character
        Skill -->|"targets"| Character
        Status -->|"attached_to"| Character
        Cooldowns -->|"stored_on"| Character

        %% Domain inheritance/extension
        Adamus -->|"extends"| Character
        Dea -->|"extends"| Character
        Dirk -->|"extends"| Character
        Flamara -->|"extends"| Character
        Makelan -->|"extends"| Character
        Mary -->|"extends"| Character
        Tera -->|"extends"| Character
        Tyrone -->|"extends"| Character
    end

    %% ========= Legend =========
    subgraph "Legend"
        direction TB
        L1["Solid arrow = call/use dependency (code)"]:::legend
        L2["Dashed arrow = UI navigation/transition (runtime flow)"]:::legend
        L3["Color coding:\nBlue=UI  Orange=Engine  Green=Domain  Gray=External  Purple=Bootstrap"]:::legend
    end

    %% ========= Click Events (from component mapping) =========
    click Main "https://github.com/kenj-1/oop2javaproject/blob/main/src/encantadia/Main.java"

    click UIUX "https://github.com/kenj-1/oop2javaproject/tree/main/src/encantadia/ui/ux/"
    click Welcome "https://github.com/kenj-1/oop2javaproject/blob/main/src/encantadia/ui/ux/WelcomeScreenPage.java"
    click MainMenu "https://github.com/kenj-1/oop2javaproject/blob/main/src/encantadia/ui/ux/MainMenuFrame.java"
    click Story "https://github.com/kenj-1/oop2javaproject/blob/main/src/encantadia/ui/ux/StorylineDialogBox.java"
    click CharSelect "https://github.com/kenj-1/oop2javaproject/blob/main/src/encantadia/ui/ux/CharacterSelectionFrame.java"
    click BattleUI "https://github.com/kenj-1/oop2javaproject/blob/main/src/encantadia/ui/ux/BattleFrame.java"
    click ResultUI "https://github.com/kenj-1/oop2javaproject/blob/main/src/encantadia/ui/ux/ResultDialogFrame.java"

    click UIModePkg "https://github.com/kenj-1/oop2javaproject/tree/main/src/encantadia/ui/ux/gamemodeselection/"
    click Arcade "https://github.com/kenj-1/oop2javaproject/blob/main/src/encantadia/ui/ux/gamemodeselection/ArcadeMode.java"
    click PVE "https://github.com/kenj-1/oop2javaproject/blob/main/src/encantadia/ui/ux/gamemodeselection/PVEMode.java"
    click PVP "https://github.com/kenj-1/oop2javaproject/blob/main/src/encantadia/ui/ux/gamemodeselection/PVPMode.java"

    click BattlePkg "https://github.com/kenj-1/oop2javaproject/tree/main/src/encantadia/battle/"
    click TurnMgr "https://github.com/kenj-1/oop2javaproject/blob/main/src/encantadia/battle/TurnManager.java"
    click TurnRes "https://github.com/kenj-1/oop2javaproject/blob/main/src/encantadia/battle/TurnResult.java"
    click Skill "https://github.com/kenj-1/oop2javaproject/blob/main/src/encantadia/battle/Skill.java"
    click Cooldowns "https://github.com/kenj-1/oop2javaproject/blob/main/src/encantadia/battle/CooldownManager.java"
    click Status "https://github.com/kenj-1/oop2javaproject/blob/main/src/encantadia/battle/StatusEffect.java"

    click CharPkg "https://github.com/kenj-1/oop2javaproject/tree/main/src/encantadia/characters/"
    click Character "https://github.com/kenj-1/oop2javaproject/blob/main/src/encantadia/characters/Character.java"
    click Adamus "https://github.com/kenj-1/oop2javaproject/blob/main/src/encantadia/characters/Adamus.java"
    click Dea "https://github.com/kenj-1/oop2javaproject/blob/main/src/encantadia/characters/Dea.java"
    click Dirk "https://github.com/kenj-1/oop2javaproject/blob/main/src/encantadia/characters/Dirk.java"
    click Flamara "https://github.com/kenj-1/oop2javaproject/blob/main/src/encantadia/characters/Flamara.java"
    click Makelan "https://github.com/kenj-1/oop2javaproject/blob/main/src/encantadia/characters/MakelanShere.java"
    click Mary "https://github.com/kenj-1/oop2javaproject/blob/main/src/encantadia/characters/Mary.java"
    click Tera "https://github.com/kenj-1/oop2javaproject/blob/main/src/encantadia/characters/Tera.java"
    click Tyrone "https://github.com/kenj-1/oop2javaproject/blob/main/src/encantadia/characters/Tyrone.java"

    %% ========= Styles =========
    classDef ui fill:#1f77b4,stroke:#0b3d66,color:#ffffff,stroke-width:1.5px
    classDef engine fill:#ff7f0e,stroke:#8a3f00,color:#111111,stroke-width:1.5px
    classDef domain fill:#2ca02c,stroke:#0b5a0b,color:#ffffff,stroke-width:1.5px
    classDef external fill:#7f7f7f,stroke:#3a3a3a,color:#ffffff,stroke-width:1.5px
    classDef bootstrap fill:#6f42c1,stroke:#3b1d6b,color:#ffffff,stroke-width:1.5px
    classDef package fill:#e8f1ff,stroke:#7aa7d9,color:#0b2a4a,stroke-width:1.2px
    classDef legend fill:#fff7cc,stroke:#c9a400,color:#3a2f00,stroke-width:1px
```
