Home Overview Architecture Core Systems Gameplay Social Economy Content UI/UX Roadmap

§2 — Architecture

Three-component stack: API server, Game Server, Electron/web Client. All three are production-ready.

100%
Complete

System Topology

  [Client — Electron / Browser]
       │  REST (login, server browser)   │  Socket.IO (realtime gameplay)
       ▼                                  ▼
  [API Server :3001]              [Game Server :3002]
  Express + JWT + MongoDB          Socket.IO + MongoDB
  ── auth/register/login           ── ~115 socket handlers
  ── server browser CRUD           ── 21 game systems
  ── JWT token issue               ── resource tick (60s)
                                   ── market tick  (15min)
       ▲                                  ▲
       └──────── MongoDB Atlas ───────────┘
                 Shared DB (separate collections)

API Server (port 3001)

Purpose

Handles player account management and the server browser. Does not run any game logic.

Endpoints

  • POST /api/auth/register — create account, bcrypt hash
  • POST /api/auth/login — issue JWT
  • GET /api/auth/verify — validate token
  • POST /api/auth/logout
  • GET /api/servers — list game servers
  • POST /api/servers/create — register a game server
  • POST /api/servers/:id/join
  • POST /api/servers/:id/leave
  • GET /api/servers/user/current

Security

  • Helmet.js headers
  • Rate limiting (1000 req/min; bypassed for localhost)
  • JWT secret via .env file
  • CORS whitelist + no-origin allowed (Electron)

Dependencies

  • express, cors, helmet, compression
  • bcryptjs, jsonwebtoken
  • mongoose, winston, joi
  • rate-limiter-flexible
API Server100%
All auth + server browser endpoints implemented

Game Server (port 3002)

Purpose

Real-time multiplayer engine. Owns all gameplay state. Communicates exclusively via Socket.IO.

Key Numbers

~115
socket.on handlers
23
Game systems
3650+
Lines of code

Background Ticks

  • 60 s — Resource production tick (metal, gas, crystal, energyCells, darkMatter)
  • 15 min — Market listing expiry check
  • Continuous — Fleet mission ETA, ship build queue

Rate Limiting

Max 20 socket events/sec per connection. Violators are temporarily dropped. (GDD §18.4)

Loaded Systems

  • ContentLoader, ResourceSystem, IdleSystem
  • QuestSystem, SkillSystem, DungeonSystem
  • CraftingSystem, ItemSystem, ShipSystem
  • FleetSystem, GalaxySystem, BaseSystem
  • MissionSystem, ReputationSystem, AllianceSystem
  • MarketSystem, SocialSystem, ResearchSystem
  • GalaxyEventSystem, SeasonSystem, GameSystem
  • RaidSystem, AllianceWarSystem
Game Server100%
v3.5: ~115 socket handlers; RaidSystem + AllianceWarSystem added; /health; ErrorReporter; gem_purchase; alliance chat

Client (Electron + Browser)

Entry Point

Client/index.html — single-page app (~9,750 lines) containing all 20 tab UIs, inline script modules: GSO_Crafting, GSO_Fleet, GSO_GemStore, GSO_AllianceChat, GSO_AllianceResearch, GSO_Market, GSO_i18n, GSO_A11y, GSO_Settings, GSO_Raids, GSO_PvpRankings, GSO_AllianceWars, GSO_PushNotifications.

Key Files

  • GameInitializer.js — Socket.IO setup, 50+ event listeners
  • UIManager.js — Tab routing, nav sync
  • electron-main.js — Electron window + IPC
  • LiveMainMenu.js — Login / server browser UI
  • locales/ — 8 JSON files (136 keys each)

Responsive Breakpoints

  • < 640px — Phone (bottom nav bar + drawer)
  • ≥ 640px — Tablet
  • ≥ 1024px — Desktop
  • ≥ 1280px — Wide

Mobile Features

  • Bottom navigation bar (5 primary tabs)
  • Slide-up drawer (11 secondary tabs)
  • iOS safe-area insets
  • 42px minimum tap targets
Client Architecture99%
v3.5: 20 tabs; GSO_i18n + GSO_A11y + GSO_Raids + GSO_PvpRankings + GSO_AllianceWars + GSO_PushNotifications

Database Schema

PlayerData (GameServer)

PlayerData {
  userId, username,
  stats:    { level, experience, credits, gems, skillPoints, totalKills, ... },
  inventory:{ items[], maxSize:50 },
  ship:     { id, health, attack, modules:{}, rarity },
  base:     { buildings:{} },
  quests:   { active[], completed[] },
  skills:   {},   crafting:  {},   idleSystem: {},
  starbase: { wallpaper, ownedWallpapers[], unlockedRooms[] },
  reputation:   { federation, pirate_syndicate, merchant_guild, rogue_ai, void_cult },
  fleetMissions:[],  shipQueue:[],
  allianceId, allianceTag, allianceName, allianceRank,
  resources:{ metal, gas, crystal, energyCells, darkMatter, lastTick },
  buildings:{},  exploredSectors:[],  homeSector,  research:{},
  combatLog:[],  friends:[],  friendRequests:[],  market:{},
  pvp:   { rating, wins, losses, winStreak, bestStreak, seasonRating, tier, lastRankedAt },
  raids: { completed[], weeklyDone, monthlyBossDone, totalRaids }
}

GameServer Model (API)

GameServer { serverId, name, type, region, maxPlayers, currentPlayers, gameServerUrl, owner }
Database Schema95%
All fields implemented; migration logic present