# truongtuan1312/blockblast-group2 architecture

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

- Interactive diagram: https://gitdiagram.com/truongtuan1312/blockblast-group2
- Repository: https://github.com/truongtuan1312/blockblast-group2

## Overview

1. **Project type and runtime**
   - This is a **desktop Java game** that clones **Block Blast**.
   - The architecture is centered on a Swing-style UI with an in-process game loop and no external backend or services.

2. **Application entry and shell**
   - `Main.java` is the startup point.
   - `BlockBlastFrame.java` is the top-level window/container.
   - `GamePanel.java` is the main rendering and update surface where gameplay is likely run.

3. **User input boundary**
   - `InputHandler.java` isolates keyboard/mouse interaction from game logic.
   - Input likely feeds the panel/game state rather than manipulating board data directly, which keeps UI and rules separated.

4. **Core game model**
   - `Board.java` represents the playfield and placement rules.
   - `Piece.java` represents the draggable/placable block shapes.
   - `InvalidPlacementException.java` is used to signal illegal moves, so placement validation is explicit in the domain layer.

5. **Piece creation and variation**
   - `PieceFactory.java` is responsible for generating pieces.
   - This is a clear creation boundary: the rest of the game consumes pieces without needing to know how they are assembled or randomized.

6. **State management and undo**
   - `GameState.java` appears to capture the full mutable game snapshot.
   - `GameStateMemento.java` supports snapshotting/restoring that state.
   - `UndoManager.java` manages the history stack or rollback flow, making undo a first-class subsystem rather than ad hoc logic.

7. **Scoring system**
   - `ScoreStrategy.java` defines scoring behavior as a pluggable policy.
   - `ClassicScoreStrategy.java` provides the concrete scoring rules used by the game.
   - This indicates the score calculation is intentionally separated from board mechanics.

8. **Rendering abstractions**
   - `Drawable.java` suggests a shared render contract for on-screen objects.
   - `ScoreText.java` is likely a UI overlay element for score feedback.
   - `LevelTheme.java` implies visual theming is data-driven or at least abstracted from gameplay logic.

9. **Visual effects subsystem**
   - `Particle.java` is the base effect type.
   - `AtmosphereParticle.java` and `DebrisParticle.java` are specialized particle effects for ambient motion and placement feedback.
   - These are presentation-only objects that enhance the game feel without affecting rules.

10. **Object reuse / performance**
   - `GameObjectPool.java` indicates pooling for transient objects, probably particles or other short-lived render entities.
   - This is a performance-oriented boundary to reduce allocation churn during gameplay.

11. **Audio feedback**
   - `SoundManager.java` is a separate subsystem for sound effects.
   - It likely reacts to game events such as placement, clears, invalid actions, or undo, instead of being called from rendering code.

12. **Overall data flow**
   - The typical flow is: **input → game panel/controller logic → board/piece validation → scoring/state update → visual/audio feedback**.
   - Undo works by restoring a prior `GameState` snapshot.
   - Rendering consumes current model state plus transient effects like particles, score text, and theme data.

13. **Main architectural boundary**
   - The code cleanly separates:
     - **game rules** (`Board`, `Piece`, scoring, exceptions),
     - **state/history** (`GameState`, memento, undo),
     - **presentation/effects** (`GamePanel`, drawable objects, particles, score text, theme),
     - **support services** (`SoundManager`, object pool, factories).
   - That separation is the key to drawing an accurate architecture diagram for this repository.

Main entry points: [`GamePanel.java`](https://github.com/truongtuan1312/blockblast-group2/blob/main/GamePanel.java) (Game Panel), [`InputHandler.java`](https://github.com/truongtuan1312/blockblast-group2/blob/main/InputHandler.java) (Input), [`Drawable.java`](https://github.com/truongtuan1312/blockblast-group2/blob/main/Drawable.java) (Drawable), [`Particle.java`](https://github.com/truongtuan1312/blockblast-group2/blob/main/Particle.java) (Particle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App Shell"]
  node_main(("Main<br/>entrypoint<br/>[Main.java]"))
  node_frame["Game Frame<br/>window"]
  node_panel["Game Panel<br/>loop-view<br/>[GamePanel.java]"]
  node_input["Input<br/>[InputHandler.java]"]
end

subgraph group_core["Game Core"]
  node_board["Board<br/>rules-model<br/>[Board.java]"]
  node_piece{{"Piece<br/>model<br/>[Piece.java]"}}
  node_invalid(("Invalid Move<br/>domain-exception"))
  node_state[("Game State<br/>snapshot<br/>[GameState.java]")]
  node_memento["Memento<br/>snapshot-adapter"]
  node_undo["Undo<br/>history-manager<br/>[UndoManager.java]"]
  node_score["Score Strategy<br/>policy<br/>[ScoreStrategy.java]"]
  node_classic["Classic Score<br/>policy-impl"]
end

subgraph group_ui["Presentation"]
  node_drawable["Drawable<br/>render-contract<br/>[Drawable.java]"]
  node_theme["Theme<br/>visual-config<br/>[LevelTheme.java]"]
  node_scoretext["Score Text<br/>overlay<br/>[ScoreText.java]"]
  node_particle(("Particle<br/>effect-base<br/>[Particle.java]"))
  node_atmo(("Atmosphere<br/>effect"))
  node_debris(("Debris<br/>effect"))
end

subgraph group_support["Support"]
  node_factory["Piece Factory<br/>generator<br/>[PieceFactory.java]"]
  node_pool["Object Pool<br/>reuse-service"]
  node_sound["Sound<br/>audio-service<br/>[SoundManager.java]"]
end

node_main -->|"creates"| node_frame
node_frame -->|"hosts"| node_panel
node_panel -->|"receives"| node_input
node_input -->|"moves"| node_board
node_input -->|"selects"| node_piece
node_board -->|"throws"| node_invalid
node_panel -->|"updates"| node_state
node_state -->|"captures"| node_memento
node_undo -->|"stores"| node_memento
node_undo -->|"restores"| node_state
node_factory -->|"creates"| node_piece
node_score -->|"implemented by"| node_classic
node_panel -->|"uses"| node_score
node_panel -->|"renders"| node_drawable
node_drawable -->|"includes"| node_scoretext
node_drawable -->|"includes"| node_particle
node_particle -->|"specializes"| node_atmo
node_particle -->|"specializes"| node_debris
node_panel -->|"styles"| node_theme
node_panel -->|"reuses"| node_pool
node_panel -->|"plays"| node_sound

click node_main "https://github.com/truongtuan1312/blockblast-group2/blob/main/Main.java"
click node_frame "https://github.com/truongtuan1312/blockblast-group2/blob/main/BlockBlastFrame.java"
click node_panel "https://github.com/truongtuan1312/blockblast-group2/blob/main/GamePanel.java"
click node_input "https://github.com/truongtuan1312/blockblast-group2/blob/main/InputHandler.java"
click node_board "https://github.com/truongtuan1312/blockblast-group2/blob/main/Board.java"
click node_piece "https://github.com/truongtuan1312/blockblast-group2/blob/main/Piece.java"
click node_invalid "https://github.com/truongtuan1312/blockblast-group2/blob/main/InvalidPlacementException.java"
click node_factory "https://github.com/truongtuan1312/blockblast-group2/blob/main/PieceFactory.java"
click node_state "https://github.com/truongtuan1312/blockblast-group2/blob/main/GameState.java"
click node_memento "https://github.com/truongtuan1312/blockblast-group2/blob/main/GameStateMemento.java"
click node_undo "https://github.com/truongtuan1312/blockblast-group2/blob/main/UndoManager.java"
click node_score "https://github.com/truongtuan1312/blockblast-group2/blob/main/ScoreStrategy.java"
click node_classic "https://github.com/truongtuan1312/blockblast-group2/blob/main/ClassicScoreStrategy.java"
click node_drawable "https://github.com/truongtuan1312/blockblast-group2/blob/main/Drawable.java"
click node_theme "https://github.com/truongtuan1312/blockblast-group2/blob/main/LevelTheme.java"
click node_scoretext "https://github.com/truongtuan1312/blockblast-group2/blob/main/ScoreText.java"
click node_particle "https://github.com/truongtuan1312/blockblast-group2/blob/main/Particle.java"
click node_atmo "https://github.com/truongtuan1312/blockblast-group2/blob/main/AtmosphereParticle.java"
click node_debris "https://github.com/truongtuan1312/blockblast-group2/blob/main/DebrisParticle.java"
click node_pool "https://github.com/truongtuan1312/blockblast-group2/blob/main/GameObjectPool.java"
click node_sound "https://github.com/truongtuan1312/blockblast-group2/blob/main/SoundManager.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_frame,node_panel,node_input toneBlue
class node_board,node_piece,node_invalid,node_state,node_memento,node_undo,node_score,node_classic toneAmber
class node_drawable,node_theme,node_scoretext,node_particle,node_atmo,node_debris toneMint
class node_factory,node_pool,node_sound toneRose
```

## Components

### App Shell

Startup and top-level windowing

- [Main](https://github.com/truongtuan1312/blockblast-group2/blob/main/Main.java): entrypoint · Application bootstrap · `Main.java`
- [Game Frame](https://github.com/truongtuan1312/blockblast-group2/blob/main/BlockBlastFrame.java): window · Top-level desktop container · `BlockBlastFrame.java`
- [Game Panel](https://github.com/truongtuan1312/blockblast-group2/blob/main/GamePanel.java): loop-view · Main update and render surface · `GamePanel.java`
- [Input](https://github.com/truongtuan1312/blockblast-group2/blob/main/InputHandler.java): input-boundary · Keyboard and mouse handling · `InputHandler.java`

### Game Core

Rules, state, scoring, and undo

- [Board](https://github.com/truongtuan1312/blockblast-group2/blob/main/Board.java): rules-model · Playfield and placement rules · `Board.java`
- [Piece](https://github.com/truongtuan1312/blockblast-group2/blob/main/Piece.java): model · Block shape model · `Piece.java`
- [Invalid Move](https://github.com/truongtuan1312/blockblast-group2/blob/main/InvalidPlacementException.java): domain-exception · Illegal placement signal · `InvalidPlacementException.java`
- [Game State](https://github.com/truongtuan1312/blockblast-group2/blob/main/GameState.java): snapshot · Mutable game snapshot · `GameState.java`
- [Memento](https://github.com/truongtuan1312/blockblast-group2/blob/main/GameStateMemento.java): snapshot-adapter · State capture and restore · `GameStateMemento.java`
- [Undo](https://github.com/truongtuan1312/blockblast-group2/blob/main/UndoManager.java): history-manager · Undo stack and rollback flow · `UndoManager.java`
- [Score Strategy](https://github.com/truongtuan1312/blockblast-group2/blob/main/ScoreStrategy.java): policy · Scoring rule contract · `ScoreStrategy.java`
- [Classic Score](https://github.com/truongtuan1312/blockblast-group2/blob/main/ClassicScoreStrategy.java): policy-impl · Default scoring rules · `ClassicScoreStrategy.java`

### Presentation

Rendering, effects, and feedback

- [Drawable](https://github.com/truongtuan1312/blockblast-group2/blob/main/Drawable.java): render-contract · Shared render interface · `Drawable.java`
- [Theme](https://github.com/truongtuan1312/blockblast-group2/blob/main/LevelTheme.java): visual-config · Level look and feel · `LevelTheme.java`
- [Score Text](https://github.com/truongtuan1312/blockblast-group2/blob/main/ScoreText.java): overlay · Score feedback text · `ScoreText.java`
- [Particle](https://github.com/truongtuan1312/blockblast-group2/blob/main/Particle.java): effect-base · Base visual effect · `Particle.java`
- [Atmosphere](https://github.com/truongtuan1312/blockblast-group2/blob/main/AtmosphereParticle.java): effect · Ambient motion effect · `AtmosphereParticle.java`
- [Debris](https://github.com/truongtuan1312/blockblast-group2/blob/main/DebrisParticle.java): effect · Placement feedback effect · `DebrisParticle.java`

### Support

Factories, pooling, and services

- [Piece Factory](https://github.com/truongtuan1312/blockblast-group2/blob/main/PieceFactory.java): generator · Creates and randomizes pieces · `PieceFactory.java`
- [Object Pool](https://github.com/truongtuan1312/blockblast-group2/blob/main/GameObjectPool.java): reuse-service · Reuses transient objects · `GameObjectPool.java`
- [Sound](https://github.com/truongtuan1312/blockblast-group2/blob/main/SoundManager.java): audio-service · Sound effect playback · `SoundManager.java`

## Connections

- Main → Game Frame: creates · Bootstraps the application shell
- Game Frame → Game Panel: hosts · Window contains the main game surface
- Game Panel → Input: receives · Panel delegates user events to input handling
- Input → Board: moves · Input drives placement attempts against the board
- Input → Piece: selects · Input interacts with the active piece
- Board → Invalid Move: throws · Illegal placements are signaled as domain errors
- Game Panel → Game State: updates · Game loop advances the mutable state
- Game State → Memento: captures · State can be snapshotted for rollback
- Undo → Memento: stores · Undo manager retains snapshots
- Undo → Game State: restores · Undo restores a prior game state
- Piece Factory → Piece: creates · Factory produces playable pieces
- Score Strategy → Classic Score: implemented by · Classic scoring is the concrete policy
- Game Panel → Score Strategy: uses · Gameplay consults scoring rules
- Game Panel → Drawable: renders · Visual objects follow a shared draw contract
- Drawable → Score Text: includes · Score text is one drawable overlay
- Drawable → Particle: includes · Particles participate in rendering
- Particle → Atmosphere: specializes · Ambient particle subtype
- Particle → Debris: specializes · Debris particle subtype
- Game Panel → Theme: styles · Theme config informs presentation
- Game Panel → Object Pool: reuses · Transient effects may be pooled
- Game Panel → Sound: plays · Gameplay events trigger audio feedback