# aayushmau5/battleship architecture

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

- Interactive diagram: https://gitdiagram.com/aayushmau5/battleship
- Repository: https://github.com/aayushmau5/battleship

## Overview

##### Main Components
- Client/Browser – Represents the user’s interface. Note that the assets folder (with CSS, JavaScript, Tailwind configuration) along with HEEx templates in the web layer indicates the use of Phoenix LiveView. This component handles the presentation and interacts via WebSockets (or standard HTTP) to receive live game updates.
- Phoenix Web Server – The core of the web layer is found in the battleship_web module. Within this, you have:
- Endpoint (handles incoming HTTP/WebSocket requests)
- Router (routes requests to the appropriate live view or controller)
- Live Views and Components (live game pages, board, components for editing, home, multiplayer/play options, etc.)
- Views and Templates (for rendering HTML responses)
- Battleship Game Engine – Found in the battleship module that encapsulates the game logic:
- Modules like gameboard, computer, player, ship, matrix, room, and task_runner. They define game state, rules (matrix-based game state with markers for ship, hit, and miss), and processes for managing game flow.
- Other modules such as mailer can be used for notifications or game state updates.
- Auxiliary Components – Configuration files, release scripts, and test files that support building, deployment, and quality assurance.

##### Relationships and Interactions
- The Browser communicates with the Phoenix Endpoint using HTTP and websockets, triggering Live Views.
- Live Views use a combination of the Battleship web modules and the underlying game engine (Battleship module) to process game actions. For example, when a move is made:
- A Live Component picks up the user event.
- The game logic module (gameboard, ship, etc.) processes the move, updates the state matrix, and signals a hit or miss.
- The result is sent back to the LiveView, which updates the UI.
- There is an implicit separation of concerns: The web layer handles user interaction/presentation while the battleship module manages game state and rules.
- In multiplayer scenarios, Phoenix PubSub and Presence (as hinted in the commented section of the README) mediate real-time communication between user processes, ensuring that state changes are propagated to all connected clients.

##### Architectural Patterns and Design Decisions
- MVC / MVVM-like separation: Although a typical Phoenix project, this app cleanly separates core game logic (model) from user interface (live view and templates – view/controller).
- Real-time communication: Phoenix LiveView along with PubSub and Presence for real-time, low-latency interactions.
- Modular Design: Splitting into dedicated modules (game engine vs. web interface) makes integration points clear.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client / Browser
    subgraph "Client/Browser"
        direction TB
        A1["Assets (CSS, JS, Tailwind)"]:::client
        A2["LiveViews"]:::client
        A3["HEEx Templates"]:::client
    end

    %% Phoenix Web Server
    subgraph "Phoenix Web Server"
        direction TB
        B1["Endpoint"]:::server
        B2["Router"]:::server
        B3["LiveViews & Components"]:::server
        B4["Views & Templates"]:::server
    end

    %% Battleship Game Engine
    subgraph "Battleship Game Engine"
        direction TB
        C1["Gameboard Module"]:::engine
        C2["Computer Module"]:::engine
        C3["Player Module"]:::engine
        C4["Ship Module"]:::engine
        C5["Matrix Module"]:::engine
        C6["Room Module"]:::engine
        C7["Task Runner Module"]:::engine
        C8["Mailer Module"]:::engine
    end

    %% Deployment/Infrastructure
    subgraph "Deployment/Infrastructure"
        direction TB
        D0["Deployment Manager"]:::deployment
        D1["Dockerfile"]:::deployment
        D2["fly.toml"]:::deployment
        D3["Cluster Config"]:::deployment
        D4["Config Files"]:::deployment
    end

    %% Relationships between Client and Phoenix Web Server
    A1 -->|"HTTP/WebSocket"| B1
    A2 -->|"HTTP/WebSocket"| B1
    A3 -->|"HTTP/WebSocket"| B1

    %% Internal Phoenix Web Server Flow
    B1 -->|"Routes"| B2
    B1 -->|"Triggers"| B3
    B4 -->|"Renders"| A3

    %% Real-time communication via PubSub/Presence (dotted connection)
    A2 -.->|"PubSub/Presence"| B3
    A3 -.->|"PubSub/Presence"| B3

    %% Phoenix Web Server to Game Engine interactions (calls game logic)
    B3 -->|"Calls GameLogic"| C1
    B3 -->|"Calls GameLogic"| C2
    B3 -->|"Calls GameLogic"| C3
    B3 -->|"Calls GameLogic"| C4
    B3 -->|"Calls GameLogic"| C5
    B3 -->|"Calls GameLogic"| C6
    B3 -->|"Calls GameLogic"| C7
    B3 -->|"Calls GameLogic"| C8

    %% Deployment influences both Web Server and Game Engine
    D0 --- B1
    D0 --- C1

    %% Click Events for Client/Browser Components
    click A1 "https://github.com/aayushmau5/battleship/tree/main/assets/"
    click A2 "https://github.com/aayushmau5/battleship/tree/main/lib/battleship_web/live"
    click A3 "https://github.com/aayushmau5/battleship/tree/main/lib/battleship_web/templates"

    %% Click Events for Phoenix Web Server Components
    click B1 "https://github.com/aayushmau5/battleship/blob/main/lib/battleship_web/endpoint.ex"
    click B2 "https://github.com/aayushmau5/battleship/blob/main/lib/battleship_web/router.ex"
    click B3 "https://github.com/aayushmau5/battleship/tree/main/lib/battleship_web/live"
    click B4 "https://github.com/aayushmau5/battleship/tree/main/lib/battleship_web/templates/layout"

    %% Click Events for Battleship Game Engine Modules
    click C1 "https://github.com/aayushmau5/battleship/blob/main/lib/battleship/gameboard.ex"
    click C2 "https://github.com/aayushmau5/battleship/blob/main/lib/battleship/computer.ex"
    click C3 "https://github.com/aayushmau5/battleship/blob/main/lib/battleship/player.ex"
    click C4 "https://github.com/aayushmau5/battleship/blob/main/lib/battleship/ship.ex"
    click C5 "https://github.com/aayushmau5/battleship/blob/main/lib/battleship/matrix.ex"
    click C6 "https://github.com/aayushmau5/battleship/blob/main/lib/battleship/room.ex"
    click C7 "https://github.com/aayushmau5/battleship/blob/main/lib/battleship/task_runner.ex"
    click C8 "https://github.com/aayushmau5/battleship/blob/main/lib/battleship/mailer.ex"

    %% Click Events for Deployment/Infrastructure Components
    click D1 "https://github.com/aayushmau5/battleship/tree/main/Dockerfile"
    click D2 "https://github.com/aayushmau5/battleship/blob/main/fly.toml"
    click D3 "https://github.com/aayushmau5/battleship/tree/main/elixir_cluster_with_remote_flyio"
    click D4 "https://github.com/aayushmau5/battleship/tree/main/config/"

    %% Styles
    classDef client fill:#D1E8FF,stroke:#064273,stroke-width:2px;
    classDef server fill:#F7D6BF,stroke:#9C4A2D,stroke-width:2px;
    classDef engine fill:#DFF6DD,stroke:#2D6A4F,stroke-width:2px;
    classDef deployment fill:#FFE3E3,stroke:#A4161A,stroke-width:2px;
```
