# lambdaclass/mirra_backend architecture

> Architecture diagram of the GitHub repository lambdaclass/mirra_backend, 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/lambdaclass/mirra_backend
- Repository: https://github.com/lambdaclass/mirra_backend

## Overview

##### Project Overview & Purpose
- Mirra Backend is an umbrella Elixir project built by splitting concerns into multiple decoupled apps (modules). Each module has its own responsibility, from game logic and physics (Arena) to client rendering (Game Client), request routing (Gateway), game-specific logic (ChampionsOfMirra), persistence and shared game data (GameBackend), and configurations (Configurator). Several supporting/testing modules (e.g., arena_load_test and bot_manager) also exist.
- The main purpose is to create a modular ecosystem where each game or service is independent yet can interact through well-defined integration points.

##### Main Components
- Arena:
- Handles core game logic, including player interactions and real-time game updates.
- Contains a 2D physics engine (with native components in Rust for collision detection).
- Game Client:
- Communicates primarily with the Arena.
- Gateway:
- Acts as the entry point for websocket connections.
- Routes incoming messages to the appropriate game or service modules.
- ChampionsOfMirra:
- Contains game-specific logic (battle simulation, campaigns, items, units, users).
- Integrates with general/shared logic provided by GameBackend.
- GameBackend:
- Central persistence and shared logic layer.
- Manages data related to users, units, items, and configurations that other apps consume.
- Configurator:
- Provides a system for managing game configurations and feature flags.
- Supports immutable configurations to enable rollbacks and A/B testing.
- (Optional/Future) Additional apps like Bots, Matchmaking, Marketplace, Chat, Inventory, and Leaderboard that expand functionality.

##### Relationships and Interactions
- Game Client sends user actions to Arena.
- Arena receives actions, interacts with its native physics engine, and then broadcasts game updates.
- Gateway connects external clients (via websockets) to the appropriate back-end (Arena, ChampionsOfMirra, GameBackend, etc.).
- Game-specific modules (ChampionsOfMirra) rely on data and rules provided by GameBackend.
- Configurator influences the behavior of all apps by managing game configurations and feature flags.
- That many of these apps operate within the umbrella architecture, meaning interactions are typically done through function calls or internal messaging rather than REST/pipes. Still, drawing clear boundaries is valuable.

##### Architectural Patterns
- Modularity – each app is self-contained and communicates via defined interfaces.
- Layering:
- Presentation/client layer (Game Client)
- Gateway/routing layer (Gateway)
- Core game logic/physics layer (Arena)
- Business and domain logic (ChampionsOfMirra, GameBackend)
- Configuration management layer (Configurator)
- Native modules such as the physics engine (in Arena/native and bot_manager/native) which are integrated for performance critical paths (collision detection, path finding).

##### Relevant Technologies and Frameworks
- Elixir/OTP for building the concurrent, fault-tolerant applications.
- Protobuf for websocket message serialization (noting separate JS Protobuf in Game Client for front-end).
- Nix and devenv – indicate these are used for reproducible environments and dependency management.
- Docker (docker-compose) for containerized deployment.
- Additionally, mention testing and CI/CD pipelines defined under the .github/workflows directory.
- That native sub-components (written in Rust and managed via Cargo) illustrate how performance-critical modules are implemented.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Presentation Layer"
        GC["Game Client\n(render arena)"]
    end

    subgraph "Routing Layer"
        GW["Gateway\n(websocket entry point)"]
    end

    subgraph "Core Game Logic Layer"
        A["Arena\n(core game logic & physics)"]
        NP["Native Physics Engine\n(collision detection)"]
        A -->|"use"| NP
    end

    subgraph "Business & Domain Layer"
        COM["ChampionsOfMirra\n(game-specific logic)"]
        GB["GameBackend\n(shared persistence)"]
        COM -->|"shared_logic"| GB
    end

    subgraph "Configuration Layer"
        CF["Configurator\n(configuration management)"]
    end

    subgraph "Testing/Support Layer"
        BM["Bot Manager\n(support/testing module)"]
    end

    %% Interactions between layers
    GC -->|"player_actions"| A
    GW -->|"routes_messages"| A
    GW -->|"routes_messages"| COM
    GW -->|"routes_messages"| GB
    CF -->|"config_updates"| A
    CF -->|"config_updates"| GC
    CF -->|"config_updates"| GW
    CF -->|"config_updates"| COM
    CF -->|"config_updates"| GB
    BM -->|"integration_test"| A

    %% Click Events
    click A "https://github.com/lambdaclass/mirra_backend/tree/main/apps/arena"
    click GC "https://github.com/lambdaclass/mirra_backend/tree/main/apps/game_client"
    click GW "https://github.com/lambdaclass/mirra_backend/tree/main/apps/gateway"
    click COM "https://github.com/lambdaclass/mirra_backend/tree/main/apps/champions"
    click GB "https://github.com/lambdaclass/mirra_backend/tree/main/apps/game_backend"
    click CF "https://github.com/lambdaclass/mirra_backend/tree/main/apps/configurator"
    click NP "https://github.com/lambdaclass/mirra_backend/tree/main/apps/arena/native/physics"
    click BM "https://github.com/lambdaclass/mirra_backend/tree/main/apps/bot_manager"

    %% Styles
    classDef frontend fill:#bae1ff,stroke:#0055AA,stroke-width:2px;
    classDef communication fill:#C0EFC0,stroke:#2E7D32,stroke-width:2px;
    classDef logic fill:#FFE0B2,stroke:#F57C00,stroke-width:2px;
    classDef business fill:#D1C4E9,stroke:#5E35B1,stroke-width:2px;
    classDef config fill:#C5CAE9,stroke:#283593,stroke-width:2px;
    classDef native fill:#F8BBD0,stroke:#880E4F,stroke-width:2px;
    classDef test fill:#FFECB3,stroke:#F9A825,stroke-width:2px;

    class GC frontend;
    class GW communication;
    class A logic;
    class COM business;
    class GB business;
    class CF config;
    class NP native;
    class BM test;
```
