# haramrit09k/spaceterra architecture

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

- Interactive diagram: https://gitdiagram.com/haramrit09k/spaceterra
- Repository: https://github.com/haramrit09k/spaceterra

## Overview

##### Project type and purpose
- This is a full-stack, real-time single-player browser game (“SpaceTerra”) built with Node.js/Express on the backend, Phaser.js on the frontend, Socket.io for WebSocket communication, and MongoDB for persistent leaderboard storage.
- The README confirms the game engine (Phaser), backend stack (Express + Node), real-time comms (Socket.io) and database (MongoDB), all deployed to Heroku.

##### File structure
- Top-level files:
- server.js – application entry point where Express and Socket.io are initialized
- package.json / package-lock.json – dependency and script info
- Procfile – Heroku deployment instruction
- Directories:
- public/ – static assets served to the client (JavaScript game code, media, CSS, video demos)
- routes/ – Express route modules (index, users, chat, request)
- views/ – HTML pages (index, register, chatroom, error, sponsors)
- screenshots/ – documentation/screenshots
- No separate sub-services; everything runs as one Node/Express process.

##### README for additional insights
- Real-time leaderboard via WebSockets (Socket.io).
- Phaser.js game runs in browser, communicates back to server when score updates occur.
- Database operations: write new scores, read top scores for leaderboard.
- Hosted on Heroku with MongoDB (likely Atlas) as an external service.

##### Main components and their interactions
a. Client (Browser)
- Loads HTML from views via HTTP GET
- Loads Phaser.js game code and assets (audio, video, CSS, images) from public/
- Renders game, captures user input
- Opens a WebSocket connection to the server via Socket.io
- Emits events (e.g., “scoreSubmit”), listens for events (e.g., “leaderboardUpdate”)

b. Web Server (Node.js + Express)
- Serves static assets and HTML pages
- Defines REST/HTTP routes in routes/*.js for any non-WebSocket requests (registration, user info, etc.)
- Integrates Socket.io on the same HTTP server (server.js connects both)

c. Socket.io (Real-Time Layer)
- Handles bi-directional real-time messages
- On “scoreSubmit” from client, invokes server-side handler
- Queries or updates MongoDB, then broadcasts leaderboard changes back to all connected clients

d. Database (MongoDB)
- Stores user profiles (routes/users.js) and score records
- Read/write by the Express/Socket.io server using native driver or Mongoose

e. External Services
- Heroku platform hosting the Node process
- MongoDB Atlas (or self-hosted) as a managed database
- Optional third-party (e.g., CDN for static assets if used later)

##### Architectural patterns and design principles
- Monolithic backend combining HTTP routes and WebSocket handlers in one process
- MVC-style separation at the route level (routes folder holds controller logic)
- Static-asset separation (public/) vs. template views (views/)
- Event-driven real-time communication (Socket.io)
- Asynchronous, non-blocking I/O (Node.js)

##### Elements to include for clarity
- Clear labels on all components
- Optionally, group related files under each component (e.g., list public/* under “Static Assets”)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client (Browser)"
        direction TB
        Game["Phaser.js Game"]:::client
        subgraph "Static Assets" 
            direction TB
            Demo["demo1.mp4"]:::client
            Explosion["explosion.ogg"]:::client
            Music["music.mp3"]:::client
            Style["style.css"]:::client
        end
    end

    %% Server Layer
    subgraph "Server (Express + Socket.io)"
        direction TB
        Server["Express Server<br/>(server.js)"]:::server
        subgraph "Routes (controllers)"
            direction TB
            Index["index.js"]:::server
            Users["users.js"]:::server
            Chat["chat.js"]:::server
            Request["request.js"]:::server
        end
        subgraph "Views (templates)"
            direction TB
            VIndex["index.html"]:::server
            Register["register.html"]:::server
            Chatroom["chatroom.html"]:::server
            ErrorView["error.html"]:::server
            Sponsors["sponsors/"]:::server
        end
    end

    %% Database Layer
    DB["MongoDB"]:::db

    %% External Services
    Heroku["Heroku"]:::external
    Atlas["MongoDB Atlas"]:::external
    Screenshots["screenshots/"]:::external
    Deployment["Deployment Config"]:::external

    %% Connections
    Game -->|HTTP GET| Server
    Demo -->|HTTP GET| Server
    Explosion -->|HTTP GET| Server
    Music -->|HTTP GET| Server
    Style -->|HTTP GET| Server

    Game -->|WS:connect| Server
    Game -->|WS:scoreSubmit| Server
    Server -->|Read/Write Scores| DB
    DB -->|Query Top Scores| Server
    Server -->|WS:leaderboardUpdate| Game

    Server --> Heroku
    DB --> Atlas
    Screenshots -.-> Deployment

    %% Click Events
    click Game "https://github.com/haramrit09k/spaceterra/blob/master/public/javascripts/game1.js"
    click Demo "https://github.com/haramrit09k/spaceterra/blob/master/public/assets/video/demo1.mp4"
    click Explosion "https://github.com/haramrit09k/spaceterra/blob/master/public/media/explosion.ogg"
    click Music "https://github.com/haramrit09k/spaceterra/blob/master/public/media/music.mp3"
    click Style "https://github.com/haramrit09k/spaceterra/blob/master/public/stylesheets/style.css"
    click Server "https://github.com/haramrit09k/spaceterra/blob/master/server.js"
    click Index "https://github.com/haramrit09k/spaceterra/blob/master/routes/index.js"
    click Users "https://github.com/haramrit09k/spaceterra/blob/master/routes/users.js"
    click Chat "https://github.com/haramrit09k/spaceterra/blob/master/routes/chat.js"
    click Request "https://github.com/haramrit09k/spaceterra/blob/master/routes/request.js"
    click VIndex "https://github.com/haramrit09k/spaceterra/blob/master/views/index.html"
    click Register "https://github.com/haramrit09k/spaceterra/blob/master/views/register.html"
    click Chatroom "https://github.com/haramrit09k/spaceterra/blob/master/views/chatroom.html"
    click ErrorView "https://github.com/haramrit09k/spaceterra/blob/master/views/error.html"
    click Sponsors "https://github.com/haramrit09k/spaceterra/tree/master/views/sponsors"
    click Deployment "https://github.com/haramrit09k/spaceterra/tree/master/Procfile"
    click Deployment "https://github.com/haramrit09k/spaceterra/blob/master/package.json"
    click Deployment "https://github.com/haramrit09k/spaceterra/blob/master/README.md"
    click Screenshots "https://github.com/haramrit09k/spaceterra/tree/master/screenshots/"

    %% Styles
    classDef client fill:#D0E6FF,stroke:#0366d6,color:#0366d6;
    classDef server fill:#FFE0B2,stroke:#E65100,color:#E65100;
    classDef db fill:#C8E6C9,stroke:#388E3C,color:#388E3C;
    classDef external fill:#E0E0E0,stroke:#616161,color:#424242;
```
