# solaris-games/solaris architecture

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

- Interactive diagram: https://gitdiagram.com/solaris-games/solaris
- Repository: https://github.com/solaris-games/solaris

## Overview

##### Main Components
- Client Application – Built using Vue.js and PixiJS.
- Contains game logic, UI components (views, dialogs, menus, game components), and assets.
- Uses event buses and socket channels for interactive, real-time functionalities.
- Server (Backend API) – Powered by Node.js with Express and MongoDB.
- Handles API endpoints, game logic, user authentication, state management, and routing.
- Organizes code around controllers, middleware, and services (e.g., game, player, guild, diplomacy, etc.).
- Includes job schedulers that run automated tasks (e.g., game ticks, cleanup, official game checks).
- Hosts socket handlers and emitters to manage real-time communication.
- Common Library – Shared code between client and server.
- Includes shared types, API controllers, socket utilities, and other business logic.
- Database – MongoDB with Mongoose providing persistent storage for players, games, and in-game events.
- Auxiliary Services – Deployment components (Docker compose and PM2), configuration files, and migration scripts.

##### Out Relationships and Data Flow
- The Client communicates with the Server via:
- RESTful API calls (using endpoints defined in the server’s Express application).
- Real-time communications (via websockets – client socket emitters/handlers and corresponding server counterparts).
- The Server interacts with:
- The MongoDB database for reading and writing persistent game and user data.
- Scheduled job services that trigger periodic game updates (game tick, cleanup jobs).
- The “Common” layer sits between client and server, encapsulating shared types and utilities that ensure API consistency.
- Docker and PM2 are used for deployment and continuous development cycles, so you might also show how the development and deployment pipeline interacts with the overall system.

##### Architectural Patterns and Design Principles
- Separation of Concerns – The client, server, and common libraries are clearly separated.
- Layered Architecture – Presentation (client UI), business logic (server controllers/services), and data-layer (MongoDB).
- Event-Driven Communication – Both the client and server make use of event buses and socket channels to manage real-time events (e.g., game state changes, chat, diplomacy events).
- Modular Design – Individual modules for game logic, account management, configuration, and scheduled tasks (as evidenced by directories like “views”, “api/controllers”, “services”, and “jobs”).

##### Detail Technologies and Frameworks
- Client: Vue.js for UI components and PixiJS for rendering graphics.
- Server: Node.js, Express, and Mongoose/MongoDB for database handling.
- Real-time Communication: Websockets for in-game events and notifications.
- Build/Dev Tools: Docker (docker-compose), PM2, and the automated development scripts mentioned in the README.
- Additional libraries: Utility scripts (e.g., helpers for game, diplomacy, and socket interactions).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client"
        ClientApp["Client Application"]:::client
        UIComponents["UI Components"]:::client
        GameLogic["Game Logic"]:::client
        EventBus["Event Bus"]:::client
        ClientSockets["Client Sockets"]:::client
    end

    %% Common Library
    subgraph "Common"
        CommonLib["Common Library"]:::common
    end

    %% Server Layer
    subgraph "Server"
        Controllers["Controllers"]:::server
        Middleware["Middleware"]:::server
        Services["Services"]:::server
        ScheduledJobs["Scheduled Jobs"]:::server
        ServerSockets["Socket Handlers"]:::server
    end

    %% Database
    Database["MongoDB Database"]:::database

    %% Deployment / Auxiliary Services
    subgraph "Deployment"
        DockerCompose["Docker Compose"]:::deployment
        DockerComposeReq["Docker Compose Requirements"]:::deployment
        PM2["PM2 Configuration"]:::deployment
        ServerConfig["Server Configuration"]:::deployment
    end

    %% Connections between Client and Server
    ClientApp -->|"API_calls"| Controllers
    ClientSockets -->|"WebSocket"| ServerSockets
    UIComponents --> ClientApp
    GameLogic --> ClientApp
    EventBus --> ClientApp

    %% Shared Library interactions
    ClientApp -->|"shared_types"| CommonLib
    Controllers -->|"shared_utilities"| CommonLib
    Services -->|"shared_logic"| CommonLib

    %% Server internal interactions
    Middleware -->|"Filters"| Controllers
    ScheduledJobs -->|"Triggers"| Services
    Services -->|"CRUD_operations"| Database

    %% Deployment interactions
    DockerCompose -->|"Deploys"| Controllers
    PM2 -->|"Manages"| ScheduledJobs
    ServerConfig -->|"Configures"| Middleware

    %% Click Events for Client
    click ClientApp "https://github.com/solaris-games/solaris/tree/master/client/src"
    click UIComponents "https://github.com/solaris-games/solaris/tree/master/client/src/views"
    click GameLogic "https://github.com/solaris-games/solaris/tree/master/client/src/game"
    click EventBus "https://github.com/solaris-games/solaris/blob/master/client/src/eventBus.ts"
    click ClientSockets "https://github.com/solaris-games/solaris/tree/master/client/src/sockets"

    %% Click Events for Server
    click Controllers "https://github.com/solaris-games/solaris/tree/master/server/api/controllers"
    click Middleware "https://github.com/solaris-games/solaris/tree/master/server/api/middleware"
    click Services "https://github.com/solaris-games/solaris/tree/master/server/services"
    click ScheduledJobs "https://github.com/solaris-games/solaris/tree/master/server/jobs"
    click ServerSockets "https://github.com/solaris-games/solaris/tree/master/server/sockets"

    %% Click Event for Common Library
    click CommonLib "https://github.com/solaris-games/solaris/tree/master/common/"

    %% Click Event for Database
    click Database "https://github.com/solaris-games/solaris/tree/master/server/db"

    %% Click Events for Deployment
    click DockerCompose "https://github.com/solaris-games/solaris/blob/master/docker-compose.yaml"
    click DockerComposeReq "https://github.com/solaris-games/solaris/blob/master/docker-compose.requirements.yml"
    click PM2 "https://github.com/solaris-games/solaris/blob/master/pm2.config.js"
    click ServerConfig "https://github.com/solaris-games/solaris/tree/master/server/config"

    %% Styles
    classDef client fill:#ccf,stroke:#333,stroke-width:2px;
    classDef server fill:#cfc,stroke:#333,stroke-width:2px;
    classDef common fill:#eee,stroke:#333,stroke-width:2px;
    classDef database fill:#fc9,stroke:#333,stroke-width:2px;
    classDef deployment fill:#fcc,stroke:#333,stroke-width:2px;
```
