# vck3000/proavalon architecture

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

- Interactive diagram: https://gitdiagram.com/vck3000/proavalon
- Repository: https://github.com/vck3000/proavalon

## Overview

##### Project Type and Purpose
**ProAvalon** is a **full-stack Node.js Express application** designed as an **online platform for playing "The Resistance!"** game. It facilitates real-time multiplayer interactions, user authentication, and integrates various external services to enhance functionality and user experience.

##### File Structure Analysis
- **Top-Level Directories:**
- `assets`: Contains frontend assets like avatars, game data, libraries (Bootstrap, jQuery UI, Summernote), images, scripts, stylesheets, and sounds.
- `src`: Holds the backend source code, organized into subdirectories such as `clients`, `databaseAdapters`, `gameplay`, `metrics`, `models`, `modsadmins`, `myFunctions`, `rewards`, `routes`, `sockets`, `util`, and `views`.
- `.github`: Contains GitHub Actions workflows for CI/CD.

- **Key Patterns and Architectural Choices:**
- **MVC Pattern:** Separation of concerns with `models` for data, `views` for frontend templates, and `routes`/`controllers` handling business logic.
- **Microservices Elements:** Presence of `clients` (e.g., Discord, Patreon, S3, VictoriaMetrics) suggesting modular interactions with external services.
- **Real-Time Communication:** `sockets` directory indicates extensive use of Socket.io for real-time features.
- **Configuration and Deployment:** Docker-related files (`Dockerfile`, `docker-compose.yml`) and Webpack configurations for building the frontend.

##### README Insights
- **Technologies Used:**
- **Backend:** Node.js, Express, Passport.js for authentication, Socket.io for real-time communication.
- **Database:** MongoDB managed via Docker.
- **Object Storage:** MinIO for handling file storage.
- **Metrics and Monitoring:** VictoriaMetrics and Grafana for monitoring and metrics visualization.
- **CI/CD:** GitHub Actions for automated builds and deployments.

- **Deployment Workflow:**
- Development and staging are managed via the master branch.
- Docker containers are built and pushed to DockerHub through GitHub Actions.
- Production deployment is handled on Digital Ocean.

- **Additional Features:**
- Server-wide caching for performance optimization.
- Middleware for authentication and other global functionalities.
- Comprehensive testing setup using Jest.

**a. Main Components:**
- **Frontend:**
- **Assets:** Static files including JavaScript, CSS, images, and sounds.
- **Views:** EJS templates rendering the user interface.

- **Backend:**
- **Express Server (`app.ts`):** Handles HTTP requests, serves APIs, and manages middleware.
- **Authentication Module:** Managed by Passport.js integrated with Socket.io via `passport.socketio`.
- **Real-Time Communication:** Socket.io server (`sockets/sockets.ts`) managing real-time events and interactions.

- **Database:**
- **MongoDB:** Managed through Mongoose (`databaseAdapters/mongoose`), handling data persistence.

- **External Services:**
- **MinIO:** Object storage for handling file uploads and storage.
- **VictoriaMetrics:** Metrics collection and monitoring.
- **Discord & Patreon Clients:** Integrations for community engagement and funding.

- **CI/CD Pipeline:**
- **GitHub Actions:** Automated workflows for building, testing, and deploying Docker containers.

- **Deployment:**
- **Docker Containers:** Encapsulate the application and its dependencies for consistent deployment across environments.
- **Digital Ocean:** Hosting platform for the production environment.

**b. Relationships and Interactions:**
- **User Interaction Flow:**
1. **User Interface (Frontend)** interacts with the **Express Server (Backend)** through HTTP requests for standard operations.
2. **Real-Time Features** are enabled via **Socket.io**, allowing bidirectional communication between the client and server.

- **Backend to Services:**
- **Express Server** communicates with **MongoDB** for data operations.
- **MinIO** handles file storage requests from the backend.
- **External Clients** (Discord, Patreon) interact with their respective APIs for integration features.

- **Monitoring and Metrics:**
- **VictoriaMetrics** collects data from the application, which is visualized using **Grafana**.

- **CI/CD Workflow:**
- **GitHub Actions** automates the building and testing of Docker containers, which are then deployed to **Digital Ocean** upon approval.

**c. Architectural Patterns and Design Principles:**
- **Modularity:** Clear separation of concerns with distinct modules for clients, database adapters, gameplay logic, and utilities.
- **Scalability:** Use of Docker for containerization allows the application to scale horizontally.
- **Maintainability:** Organized directory structure and adherence to MVC principles facilitate easier maintenance and feature additions.
- **Security:** User authentication managed by Passport.js, with middleware enforcing access controls.

**d. Technologies, Frameworks, and Libraries:**
- **Backend:** Node.js, Express, Socket.io, Passport.js, Mongoose, TypeScript.
- **Frontend:** EJS templating, Bootstrap, jQuery UI, Summernote.
- **DevOps:** Docker, Docker Compose, GitHub Actions.
- **Testing:** Jest.
- **Monitoring:** VictoriaMetrics, Grafana.
- **Other Libraries:** Various utility libraries for handling specific functionalities (e.g., captcha, VPN detection).

##### Elements

- **Clear Labels:** Each component (e.g., Frontend, Express Server, MongoDB, MinIO, Socket.io) should be distinctly labeled.
- Users interacting with the Frontend.
- Frontend making API calls to the Express Server.
- Express Server communicating with MongoDB and MinIO.
- Real-time events flowing through Socket.io between Frontend and Backend.
- External Services interacting with the Backend.
- CI/CD pipeline deploying to the Hosting Platform.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global entities
    Users(("Users")):::external

    %% Subgraphs and modules
    subgraph "Frontend" 
        Assets["Assets"]:::frontend
        Avatars["Avatars"]:::frontend
        Libraries["Libraries"]:::frontend
        Bootstrap["Bootstrap"]:::frontend
        jQueryUI["jQuery UI"]:::frontend
        Summernote["Summernote"]:::frontend
        Scripts["Scripts"]:::frontend
        LobbyScripts["Lobby Scripts"]:::frontend
        ForumScripts["Forum Scripts"]:::frontend
        Stylesheets["Stylesheets"]:::frontend
        Views["Views (EJS Templates)"]:::frontend
    end

    subgraph "Backend" 
        ExpressServer["Express Server"]:::backend
        Authentication["Authentication Module"]:::backend
        Middleware["Middleware"]:::backend
        SendEmail["sendEmail"]:::backend
        SendEmailVerification["sendEmailVerification"]:::backend
        SocketIO["Socket.io"]:::backend
        DatabaseAdapters["MongoDB Adapters"]:::backend
        Mongoose["Mongoose"]:::backend
        Models["Models (Data Schemas)"]:::backend
        Routes["Routes (API Endpoints)"]:::backend
        ModAdmin["Mod/Admin Functionality"]:::backend
        CommandsMod["Commands Mod"]:::backend
        Rewards["Rewards System"]:::backend
        Utilities["Utilities"]:::backend
        Captcha["CAPTCHA Utilities"]:::backend
        VPNDetection["VPN Detection Utilities"]:::backend
    end

    subgraph "Database" 
        MongoDB["MongoDB"]:::database
    end

    subgraph "External Services" 
        MinIO["MinIO (S3 Client)"]:::external
        VictoriaMetrics["VictoriaMetrics"]:::external
        Discord["Discord Client"]:::external
        Patreon["Patreon Client"]:::external
        Grafana["Grafana"]:::external
    end

    subgraph "CI/CD Pipeline" 
        GitHubActions["GitHub Actions"]:::ci_cd
        Workflows["Workflows"]:::ci_cd
    end

    subgraph "Deployment" 
        Docker["Docker Containers"]:::deployment
        DigitalOcean["Digital Ocean"]:::deployment
    end

    %% Connections
    Users -->|Interacts with| Assets
    Assets -->|Uses| Avatars
    Assets -->|Uses| Libraries
    Libraries -->|Includes| Bootstrap
    Libraries -->|Includes| jQueryUI
    Libraries -->|Includes| Summernote
    Assets -->|Includes| Scripts
    Scripts -->|Includes| LobbyScripts
    Scripts -->|Includes| ForumScripts
    Assets -->|Includes| Stylesheets
    Assets -->|Serves| Views
    Views -->|Rendered by| ExpressServer
    ExpressServer -->|Handles Requests| Routes
    ExpressServer -->|Manages Authentication| Authentication
    Authentication -->|Uses| Middleware
    Middleware -->|Includes| SendEmail
    Middleware -->|Includes| SendEmailVerification
    ExpressServer -->|Communicates with| SocketIO
    SocketIO -->|Handles Real-Time Events| Users
    ExpressServer -->|Connects to| DatabaseAdapters
    DatabaseAdapters -->|Uses| Mongoose
    Mongoose -->|Interacts with| MongoDB
    ExpressServer -->|Uses| Models
    ExpressServer -->|Defines| Routes
    ExpressServer -->|Manages| ModAdmin
    ModAdmin -->|Includes| CommandsMod
    ExpressServer -->|Manages| Rewards
    ExpressServer -->|Uses| Utilities
    Utilities -->|Includes| Captcha
    Utilities -->|Includes| VPNDetection
    ExpressServer -->|Uses| MinIO
    ExpressServer -->|Uses| VictoriaMetrics
    VictoriaMetrics -->|Monitored by| Grafana
    ExpressServer -->|Integrates with| Discord
    ExpressServer -->|Integrates with| Patreon
    GitHubActions -->|Runs| Workflows
    Workflows -->|Builds| Docker
    Docker -->|Deploys to| DigitalOcean

    %% Click Events
    click Assets "https://github.com/vck3000/proavalon/tree/master/assets/"
    click Avatars "https://github.com/vck3000/proavalon/tree/master/assets/avatars/"
    click Bootstrap "https://github.com/vck3000/proavalon/tree/master/assets/libraries/bootstrap-3.3.7-dist/"
    click jQueryUI "https://github.com/vck3000/proavalon/tree/master/assets/libraries/jquery-ui-1.12.1/"
    click Summernote "https://github.com/vck3000/proavalon/tree/master/assets/libraries/summernote-0.8.9-dist/"
    click Scripts "https://github.com/vck3000/proavalon/tree/master/assets/scripts/"
    click LobbyScripts "https://github.com/vck3000/proavalon/tree/master/assets/scripts/lobby/"
    click ForumScripts "https://github.com/vck3000/proavalon/tree/master/assets/scripts/forum/"
    click Stylesheets "https://github.com/vck3000/proavalon/tree/master/assets/stylesheets/"
    click Views "https://github.com/vck3000/proavalon/tree/master/src/views/"
    click ExpressServer "https://github.com/vck3000/proavalon/blob/master/src/app.ts"
    click Middleware "https://github.com/vck3000/proavalon/blob/master/src/routes/middleware.ts"
    click SendEmail "https://github.com/vck3000/proavalon/blob/master/src/myFunctions/sendEmail.ts"
    click SendEmailVerification "https://github.com/vck3000/proavalon/blob/master/src/myFunctions/sendEmailVerification.ts"
    click SocketIO "https://github.com/vck3000/proavalon/tree/master/src/sockets/"
    click DatabaseAdapters "https://github.com/vck3000/proavalon/tree/master/src/databaseAdapters/mongoose/"
    click Mongoose "https://github.com/vck3000/proavalon/tree/master/src/databaseAdapters/mongoose/"
    click MinIO "https://github.com/vck3000/proavalon/tree/master/src/clients/s3/"
    click VictoriaMetrics "https://github.com/vck3000/proavalon/tree/master/src/clients/victoriaMetrics/"
    click Discord "https://github.com/vck3000/proavalon/tree/master/src/clients/discord/"
    click Patreon "https://github.com/vck3000/proavalon/tree/master/src/clients/patreon/"
    click ModAdmin "https://github.com/vck3000/proavalon/tree/master/src/modsadmins/"
    click CommandsMod "https://github.com/vck3000/proavalon/tree/master/src/sockets/commands/mod/"
    click Rewards "https://github.com/vck3000/proavalon/tree/master/src/rewards/"
    click GitHubActions "https://github.com/vck3000/proavalon/tree/master/.github/workflows/"
    click Docker "https://github.com/vck3000/proavalon/tree/master/Dockerfile"
    click DigitalOcean "https://github.com/vck3000/proavalon/blob/master/docker-compose.yml"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef backend fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef database fill:#FFFFE0,stroke:#000,stroke-width:1px;
    classDef external fill:#FFA500,stroke:#000,stroke-width:1px;
    classDef ci_cd fill:#DDA0DD,stroke:#000,stroke-width:1px;
    classDef deployment fill:#FFC0CB,stroke:#000,stroke-width:1px;
    class Users,ExpressServer,Frontend,Backend,Database,ExternalServices,CI_CD_Pipeline,Deployment external;

    class Assets,Avatars,Libraries,Bootstrap,jQueryUI,Summernote,Scripts,LobbyScripts,ForumScripts,Stylesheets,Views frontend;
    class ExpressServer,Authentication,Middleware,SendEmail,SendEmailVerification,SocketIO,DatabaseAdapters,Mongoose,Models,Routes,ModAdmin,CommandsMod,Rewards,Utilities,Captcha,VPNDetection backend;
    class MongoDB database;
    class MinIO,VictoriaMetrics,Discord,Patreon,Grafana external;
    class GitHubActions,Workflows ci_cd;
    class Docker,DigitalOcean deployment;
```
