# miguel-motta-u/the-matrix-back architecture

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

- Interactive diagram: https://gitdiagram.com/miguel-motta-u/the-matrix-back
- Repository: https://github.com/miguel-motta-u/the-matrix-back

## Overview

##### Recognize the Project Type and Purpose
- The project is a Node.js backend application with a game-focused domain. It has multiple responsibilities such as handling game logic (entities like characters, enemies, boards, matches), lobby/matchmaking functionality, REST and WebSocket controllers, and worker processes.
- Although the README explains a basic scaffold for Fastify-based projects, the file tree shows a much richer domain (game, lobbies, workers) indicating that it serves as a backend for a game application, possibly supporting real-time interactions via WebSockets along with RESTful endpoints.
- There is a docker-compose file that spins up a Redis instance, which likely acts as a data store or pub/sub mechanism for realtime communication.

##### File Structure
- Top-Level Folders:
- src/ holds the entire source code.
- Controllers (both REST and WebSocket) in src/controllers, each handling different interfaces.
- The app/ directory within src/ contains domain-specific logic for the game, such as:
- game/characters: defines various character types (base Character, Enemy and its specific types like Troll; Player).
- game/match: defines match management and board components (Board, BoardDifficulty1, CellBoard, Fruit).
- game/services: encapsulates the business logic for handling game mechanics.
- lobbies/: handles lobby management and matchmaking using services.
- Plugins located in src/plugins include initialization for environment variables, error handling, Redis, static files, and WebSocket configurations.
- The workers directory suggests asynchronous processing (e.g., handling enemy-specific tasks).
- There’s also a test/ directory for unit and integration tests.

- Additional Files:
- Docker-compose.yml indicates use of a Redis container for caching, pub/sub or session storage.
- Environment templates (.env.example), configuration files (tsconfig.json, nodemon.json), and workflow files in .github show this project’s deployment and CI/CD setup.
- Public folder with static HTML suggests some static assets are served (perhaps for testing or a minimal UI).

##### Key Components
a. Client / Frontend Interaction:
- Even if its role is minimal, indicate a “Client” or “Browser/Front-End” sending REST and WebSocket requests (e.g., for game control or lobby matchmaking).
b. REST API Layer:
- REST Controllers (e.g., UserController) found under src/controllers/rest.
- Routes (src/routes/rest) that map endpoints to these controllers.
c. WebSocket API Layer:
- WebSocket Controllers (GameController, MatchMakingController) handling real-time interactions.
- Endpoints with the WebSocket plugin (in src/plugins/websocket.ts) which sets up necessary real-time communication infrastructure.
d. Application Logic / Domain Layer:
- Within src/app/ show two key domains: “Game” and “Lobbies.”
- Under “Game”: include concepts like Characters (Players, Enemies, Troll), Match management (Match, Board variants, Cells, Fruit) and the GameService.
- Under “Lobbies”: include the matchmaking service to manage player lobbies.
e. Service Layer:
- Controllers call the business logic from services (GameService, MatchMakingService) to carry out complex domain logic.
f. Plugin and Infrastructure Components:
- Plugins for initializing the environment, error handling, static resources, Redis integration, and WebSocket configuration.
g. Workers:
h. External Dependencies:
- Dockerized Redis instance (launched via docker-compose) as an external service component.

##### Architectural Relationships and Patterns
- Use an MVC-like layering where:
- The Controllers (REST and WebSocket) serve as entry points.
- They interact with the underlying Services that encapsulate business logic.
- The Services interact with Domain Objects (Game components such as Characters, Matches, and Boards).
- Background workers form a side process feeding data or handling asynchronous tasks parallel to the main event loop.
- The use of Redis for caching and messaging shows that a distributed in-memory datastore is an integral part of the infrastructure.
- Plugins denote a modular approach using Fastify’s plugin system to decouple repetitive configuration tasks.
- The structure shows separation of concerns with a clean distinction between API layer, business logic, and supporting infrastructure.

##### Final Steps
- Iteratively add the detailed connections (data flows and dependencies) between these layers.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        Client["Client (Browser)"]:::client
    end

    %% API Layer
    subgraph "API Layer"
        subgraph "REST API"
            REST_Routes["REST Routes"]:::controller
            REST_Controller["REST Controller (UserController)"]:::controller
        end
        subgraph "WebSocket API"
            WS_Game["WebSocket Controller (GameController)"]:::controller
            WS_Match["WebSocket Controller (MatchMakingController)"]:::controller
            WS_Plugin["WebSocket Plugin"]:::plugin
            WS_Service["WebSocket Service Impl"]:::service
        end
    end

    %% Domain Layer
    subgraph "Domain Layer"
        subgraph "Game Domain"
            subgraph "Characters"
                Character["Character"]:::domain
                Enemy["Enemy"]:::domain
                Troll["Troll"]:::domain
                Player["Player"]:::domain
            end
            subgraph "Match Management"
                Match["Match"]:::domain
                Board["Board"]:::domain
                BoardDiff1["BoardDifficulty1"]:::domain
                CellBoard["CellBoard"]:::domain
                Fruit["Fruit"]:::domain
            end
            GameService["GameService"]:::service
            GameServiceImpl["GameService Impl"]:::service
        end
        subgraph "Lobbies Domain"
            MatchMakingService["MatchMakingService"]:::service
            MatchMakingImpl["MatchMaking Impl"]:::service
        end
    end

    %% Plugins & Infrastructure
    subgraph "Plugins & Infrastructure"
        Env_Plugin["Env Initialization"]:::plugin
        Error_Plugin["Error Handling"]:::plugin
        Redis_Plugin["Redis Integration"]:::plugin
        Static_Plugin["Static Files"]:::plugin
        Plugin_Index["Plugin Index"]:::plugin
    end

    %% Worker Processes
    subgraph "Worker Processes"
        Enemies_Worker["Enemies Worker"]:::worker
        General_Worker["General Worker"]:::worker
        Worker_Error["Worker Error Handling"]:::worker
    end

    %% External Services
    subgraph "External Services"
        Docker_Redis["Dockerized Redis Instance"]:::external
    end

    %% Connections between Client and API
    Client -->|"sends REST request"| REST_Routes
    Client -->|"initiates WebSocket"| WS_Plugin

    %% REST API Flow
    REST_Routes -->|"routes to"| REST_Controller

    %% WebSocket API Flow
    WS_Game -->|"processes WS event"| WS_Service
    WS_Match -->|"processes WS event"| WS_Service
    WS_Plugin -->|"forwards WS connection"| WS_Service

    %% Controllers invoking Services
    REST_Controller -->|"calls"| GameService
    REST_Controller -->|"calls"| MatchMakingService
    WS_Service -->|"triggers"| GameService
    WS_Service -->|"triggers"| MatchMakingService

    %% Game Service internal flow
    GameService -->|"delegates to"| GameServiceImpl
    GameServiceImpl -->|"handles"| Character
    GameServiceImpl -->|"handles"| Enemy
    GameServiceImpl -->|"handles"| Troll
    GameServiceImpl -->|"handles"| Player
    GameServiceImpl -->|"manages"| Match
    GameServiceImpl -->|"manages"| Board
    GameServiceImpl -->|"manages"| BoardDiff1
    GameServiceImpl -->|"manages"| CellBoard
    GameServiceImpl -->|"manages"| Fruit

    %% Lobby Service internal flow
    MatchMakingService -->|"implements"| MatchMakingImpl

    %% Services interacting with Infrastructure
    GameServiceImpl -->|"uses"| Redis_Plugin
    MatchMakingImpl -->|"uses"| Redis_Plugin
    Redis_Plugin -->|"connects to"| Docker_Redis

    %% Error Handling paths
    REST_Controller -->|"reports"| Error_Plugin
    WS_Service -->|"reports"| Error_Plugin

    %% Worker Processes interactions
    GameServiceImpl -->|"triggers async"| Enemies_Worker
    Enemies_Worker -->|"handles errors"| Worker_Error
    General_Worker -->|"handles errors"| Worker_Error

    %% Click Events
    click Client "https://github.com/miguel-motta-u/the-matrix-back/blob/main/public/queue.html"
    click REST_Routes "https://github.com/miguel-motta-u/the-matrix-back/blob/main/src/routes/rest.ts"
    click REST_Controller "https://github.com/miguel-motta-u/the-matrix-back/blob/main/src/controllers/rest/UserController.ts"
    click WS_Game "https://github.com/miguel-motta-u/the-matrix-back/blob/main/src/controllers/websockets/GameController.ts"
    click WS_Match "https://github.com/miguel-motta-u/the-matrix-back/blob/main/src/controllers/websockets/MatchMakingController.ts"
    click WS_Plugin "https://github.com/miguel-motta-u/the-matrix-back/blob/main/src/plugins/websocket.ts"
    click WS_Service "https://github.com/miguel-motta-u/the-matrix-back/blob/main/src/app/WebSocketServiceImpl.ts"

    click Character "https://github.com/miguel-motta-u/the-matrix-back/blob/main/src/app/game/characters/Character.ts"
    click Enemy "https://github.com/miguel-motta-u/the-matrix-back/blob/main/src/app/game/characters/enemies/Enemy.ts"
    click Troll "https://github.com/miguel-motta-u/the-matrix-back/blob/main/src/app/game/characters/enemies/Troll.ts"
    click Player "https://github.com/miguel-motta-u/the-matrix-back/blob/main/src/app/game/characters/players/Player.ts"

    click Match "https://github.com/miguel-motta-u/the-matrix-back/blob/main/src/app/game/match/Match.ts"
    click Board "https://github.com/miguel-motta-u/the-matrix-back/blob/main/src/app/game/match/boards/Board.ts"
    click BoardDiff1 "https://github.com/miguel-motta-u/the-matrix-back/blob/main/src/app/game/match/boards/BoardDifficulty1.ts"
    click CellBoard "https://github.com/miguel-motta-u/the-matrix-back/blob/main/src/app/game/match/boards/CellBoard.ts"
    click Fruit "https://github.com/miguel-motta-u/the-matrix-back/blob/main/src/app/game/match/boards/Fruit.ts"

    click GameService "https://github.com/miguel-motta-u/the-matrix-back/blob/main/src/app/game/services/GameService.ts"
    click GameServiceImpl "https://github.com/miguel-motta-u/the-matrix-back/blob/main/src/app/game/services/GameServiceImpl.ts"

    click MatchMakingService "https://github.com/miguel-motta-u/the-matrix-back/blob/main/src/app/lobbies/services/MatchMakingService.ts"
    click MatchMakingImpl "https://github.com/miguel-motta-u/the-matrix-back/blob/main/src/app/lobbies/services/MatchmakingImpl.ts"

    click Env_Plugin "https://github.com/miguel-motta-u/the-matrix-back/blob/main/src/plugins/env.ts"
    click Error_Plugin "https://github.com/miguel-motta-u/the-matrix-back/blob/main/src/plugins/errorsHandler.ts"
    click Redis_Plugin "https://github.com/miguel-motta-u/the-matrix-back/blob/main/src/plugins/redis.ts"
    click Static_Plugin "https://github.com/miguel-motta-u/the-matrix-back/blob/main/src/plugins/static.ts"
    click Plugin_Index "https://github.com/miguel-motta-u/the-matrix-back/blob/main/src/plugins/index.ts"

    click Enemies_Worker "https://github.com/miguel-motta-u/the-matrix-back/blob/main/src/workers/Enemies.worker.ts"
    click General_Worker "https://github.com/miguel-motta-u/the-matrix-back/blob/main/src/workers/worker.ts"
    click Worker_Error "https://github.com/miguel-motta-u/the-matrix-back/blob/main/src/workers/WorkerError.ts"

    click Docker_Redis "https://github.com/miguel-motta-u/the-matrix-back/blob/main/docker-compose.yml"

    %% Styles
    class Client client
    class REST_Routes,REST_Controller,WS_Game,WS_Match,WS_Plugin controller
    class WS_Service,GameService,GameServiceImpl,MatchMakingService,MatchMakingImpl service
    class Character,Enemy,Troll,Player,Match,Board,BoardDiff1,CellBoard,Fruit domain
    class Env_Plugin,Error_Plugin,Redis_Plugin,Static_Plugin,Plugin_Index plugin
    class Enemies_Worker,General_Worker,Worker_Error worker
    class Docker_Redis external
```
