# manusajith/ex_mmog architecture

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

- Interactive diagram: https://gitdiagram.com/manusajith/ex_mmog
- Repository: https://github.com/manusajith/ex_mmog

## Overview

##### Project type and purpose
- This is a full-stack, browser-based multiplayer online game built with Elixir and the Phoenix framework.
- Purpose: render a 2D grid in the browser, allow players to move, attack, die, respawn, and see each other in real time.

##### File structure
- Top-level:
- assets/ – JavaScript/CSS, Webpack config, static files (frontend build pipeline).
- lib/ex_mmog/ – core game logic and OTP application entry point.
- lib/ex_mmog_web/ – Phoenix web layer: endpoint, router, controllers, LiveView, channels, templates, views.
- config/ – environment settings and release configuration.
- priv/ – gettext translations.
- test/ – unit tests for game logic and web layer.
- Patterns:
- MVC + real-time channels / LiveView.
- OTP supervision: Application.ex boots the endpoint, PubSub, GameSupervisor, etc.
- Game logic isolated in lib/ex_mmog/game/* following a state-machine pattern (actions, state, players).

##### README for additional insights
- Confirms real-time browser game at /game.
- Game mechanics: move, attack within radius, respawn.
- No external database: state is held in memory via GenServers.
- Deployed as an Elixir Release to Gigalixir.

a. Client Side
- Browser UI (HTML/CSS/JS built by Webpack, rendered via templates and LiveView)
- WebSocket connection (Phoenix Channels / LiveView socket)
b. Server Side
- Phoenix Endpoint (HTTP & WebSocket listener)
- Router → directs /game to GameController or GameLive
- GameController (initial page load)
- GameLive (LiveView process handling UI updates and events)
- UserSocket → Channel(s) for presence and real-time messaging
- GameSupervisor → supervises dynamic game GenServers
- GameServer (per-game or single shared GenServer)
- Game modules: Board, State, Players, Actions (attack, move, join, cleanup)
- PubSub (Phoenix.PubSub) for broadcasting state changes
c. Optional
- I18n via Gettext (priv/gettext)
- Deployment (Release, Gigalixir)

##### Relationships and interactions
- Browser sends HTTP GET /game → Phoenix Endpoint → Router → GameController → renders template + mounts GameLive.
- GameLive opens WebSocket to UserSocket → joins “game:lobby” channel or mounts LiveView.
- Player actions (clicks, keypresses) → pushed as events over socket → GameLive.handle_event or Channel.handle_in.
- Those handlers invoke GameServer via GenServer.call/cast.
- GameServer updates its state (Board, Players, State modules).
- After state change, GameServer publishes update via PubSub.
- GameLive or Channels subscribe and broadcast to connected clients → UI rerenders.

##### Architectural patterns & principles
- MVC for initial requests; real-time MVU (Model-View-Update) with LiveView/Channels.
- OTP: supervision tree, fault tolerance, stateful GenServers.
- Single or small set of GameServer processes rather than database persistence—low latency in-memory state.
- Clear separation: web concerns (controllers/views/templates) vs. game logic modules.

##### Technologies / frameworks to label
- Elixir & OTP (Supervisor, GenServer)
- Phoenix (Endpoint, Router, Controllers, Views, Templates)
- Phoenix LiveView / Channels (real-time updates)
- Webpack / Babel / npm (frontend asset pipeline)
- Gigalixir + Elixir Releases (deployment)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        Assets["Assets (JS/CSS/Static)"]:::frontend
        Webpack["webpack.config.js"]:::frontend
        Entry["js/app.js"]:::frontend
        SocketJS["js/socket.js"]:::frontend
        CSS["css/app.css & phoenix.css"]:::frontend
        BrowserUI["Browser UI (LiveView Templates)"]:::frontend
        Assets --> Webpack
        Assets --> Entry
        Assets --> SocketJS
        Assets --> CSS
        Entry --> BrowserUI
    end

    %% Client-to-Server Connections
    BrowserUI -->|"HTTP GET /game"| Endpoint
    BrowserUI -->|"WebSocket connect"| UserSocket

    %% Backend Layer
    subgraph "Backend Layer"
        direction TB
        Endpoint["Endpoint (HTTP & WebSocket)"]:::phoenix
        Router["Router (/game route)"]:::phoenix
        GameController["GameController"]:::phoenix
        GameLive["GameLive"]:::phoenix
        UserSocket["UserSocket & Channels"]:::phoenix
        Presence["Presence Channel"]:::phoenix
        DB[(PubSub)]:::phoenix
        GameSupervisor["GameSupervisor"]:::otp
        GameServer["GameServer (GenServer)"]:::otp
        CoreAPI["Game API Wrapper"]:::otp
        Board["Board Module"]:::otp
        State["Game State Module"]:::otp
        Players["Players Module"]:::otp
        Actions["Actions Aggregator"]:::otp
        Move["Action: Move"]:::otp
        Attack["Action: Attack"]:::otp
        Join["Action: Join"]:::otp
        Cleanup["Action: Cleanup"]:::otp

        Endpoint --> Router
        Router --> GameController
        GameController --> GameLive
        UserSocket --> Presence
        GameLive --> GameServer
        GameServer --> CoreAPI
        CoreAPI --> Board
        CoreAPI --> State
        CoreAPI --> Players
        CoreAPI --> Actions
        Actions --> Move
        Actions --> Attack
        Actions --> Join
        Actions --> Cleanup
        GameServer --> DB
        DB --> GameLive
        GameLive --> BrowserUI
        GameSupervisor --> GameServer
    end

    %% Supervision Tree
    subgraph "Supervision Tree"
        direction TB
        Application["Application"]:::otp
        Supervisor["Supervisor"]:::otp
        PS["PubSub"]:::phoenix
        EndpointSupervisor["Endpoint"]:::phoenix
        GS["GameSupervisor"]:::otp

        Application --> Supervisor
        Supervisor --> EndpointSupervisor
        Supervisor --> PS
        Supervisor --> GS
        GS --> GameServer
    end

    %% Click Events
    click Assets "https://github.com/manusajith/ex_mmog/tree/master/assets/"
    click Webpack "https://github.com/manusajith/ex_mmog/blob/master/assets/webpack.config.js"
    click Entry "https://github.com/manusajith/ex_mmog/blob/master/assets/js/app.js"
    click SocketJS "https://github.com/manusajith/ex_mmog/blob/master/assets/js/socket.js"
    click CSS "https://github.com/manusajith/ex_mmog/blob/master/assets/css/app.css"
    click CSS "https://github.com/manusajith/ex_mmog/blob/master/assets/css/phoenix.css"
    click Endpoint "https://github.com/manusajith/ex_mmog/blob/master/lib/ex_mmog_web/endpoint.ex"
    click Router "https://github.com/manusajith/ex_mmog/blob/master/lib/ex_mmog_web/router.ex"
    click GameController "https://github.com/manusajith/ex_mmog/blob/master/lib/ex_mmog_web/controllers/game_controller.ex"
    click BrowserUI "https://github.com/manusajith/ex_mmog/blob/master/lib/ex_mmog_web/templates/game/index.html.leex"
    click EndpointSupervisor "https://github.com/manusajith/ex_mmog/blob/master/lib/ex_mmog_web/templates/layout/app.html.eex"
    click GameLive "https://github.com/manusajith/ex_mmog/blob/master/lib/ex_mmog_web/live/game_live.ex"
    click UserSocket "https://github.com/manusajith/ex_mmog/blob/master/lib/ex_mmog_web/channels/user_socket.ex"
    click Presence "https://github.com/manusajith/ex_mmog/blob/master/lib/ex_mmog_web/channels/presence.ex"
    click Application "https://github.com/manusajith/ex_mmog/blob/master/lib/ex_mmog/application.ex"
    click GameServer "https://github.com/manusajith/ex_mmog/blob/master/lib/ex_mmog/server.ex"
    click CoreAPI "https://github.com/manusajith/ex_mmog/blob/master/lib/ex_mmog/game.ex"
    click Board "https://github.com/manusajith/ex_mmog/blob/master/lib/ex_mmog/board.ex"
    click State "https://github.com/manusajith/ex_mmog/blob/master/lib/ex_mmog/game/state.ex"
    click Players "https://github.com/manusajith/ex_mmog/blob/master/lib/ex_mmog/game/players.ex"
    click Actions "https://github.com/manusajith/ex_mmog/blob/master/lib/ex_mmog/game/actions.ex"
    click Move "https://github.com/manusajith/ex_mmog/blob/master/lib/ex_mmog/game/actions/move.ex"
    click Attack "https://github.com/manusajith/ex_mmog/blob/master/lib/ex_mmog/game/actions/attack.ex"
    click Join "https://github.com/manusajith/ex_mmog/blob/master/lib/ex_mmog/game/actions/join.ex"
    click Cleanup "https://github.com/manusajith/ex_mmog/blob/master/lib/ex_mmog/game/actions/cleanup.ex"
    click PS "https://github.com/manusajith/ex_mmog/blob/master/lib/ex_mmog_web/endpoint.ex"
    click Application "https://github.com/manusajith/ex_mmog/blob/master/config/releases.exs"

    %% Styles
    classDef frontend fill:#ffcc99,stroke:#333,stroke-width:1px
    classDef phoenix fill:#99ccff,stroke:#333,stroke-width:1px
    classDef otp fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef infra fill:#f2f2f2,stroke:#333,stroke-width:1px
```
