Docs / Server / Architecture

💻 Server Architecture

Understanding the server-authoritative backend structure, data flow, and how to extend it.

System Overview

High-level architecture diagram

Client
StowayClientv1_2 →
InventoryAction (RemoteEvent) InventoryUpdate (RemoteEvent)
Server
InventoryService (init.luau)

Core

  • InventoryState
  • SlotManager
  • LimitChecker

Operations

  • AddOperation
  • RemoveOperation
  • SwapOperation
  • EquipOperation
  • DropOperation

Replication

  • Replicator
  • Actions

Utils

  • UUID
  • MetadataParser
  • StackChecker

Directory Structure

File organization

src/server/StowayServerV1_2/ Tree 
src/server/StowayServerV1_2/
- init.luau                    # Entry point & InventoryService API
-
- -- Core Data & Logic
- Core/
-   InventoryState.luau       # Per-player inventory state container
-   SlotManager.luau          # Hotbar/Storage slot management
-   LimitChecker.luau         # Weight limit validation
-
- -- Inventory Operations (Modular)
- Operations/
-   AddOperation.luau         # Add items (Limit → Stack → Hotbar → Storage)
-   RemoveOperation.luau      # Remove items (Validate → Reduce/Destroy)
-   SwapOperation.luau        # Swap any two slots
-   EquipOperation.luau       # Equip/Unequip items
-   DropOperation.luau        # Drop items to world
-
- -- Client Communication
- Replication/
-   Replicator.luau           # Delta updates to clients
-   Actions.luau              # Payload builders
-
- -- Utilities
- Utils/
-   UUID.luau                # Unique ID generation
-   MetadataParser.luau       # Parse metadata from tools
-   StackChecker.luau         # Stacking validation
-
- -- Debug (Remove in production!)
- Debug/
-   ChatCommands.luau         # /add, /swap, /equip, etc.

Data Flow

How requests are processed

1

Client Request

Client fires InventoryAction RemoteEvent with operation type and arguments.

↓
2

Anti-Exploit Lock

Server checks PlayerOperationLock[player]. If locked, rejects request.

↓
3

Route to Handler

Operation type maps to handler in OperationHandlers table.

↓
4

Execute Operation

Handler calls operation module's Execute() function. Validates and modifies state.

↓
5

Replicate

If successful, Replicator sends delta update via InventoryUpdate RemoteEvent.

↓
6

Client Sync

Client's NetworkHandler processes update and syncs Fusion state.

Key Components

What each module does

InventoryState

Pure data container. No logic, just storage.

  • state.Items - UUID → Item map
  • state.Hotbar - Slot → UUID
  • state.Storage - Array of UUIDs
  • state.Settings - Per-player config

SlotManager

Slot location management. Handles static vs dynamic containers.

  • FindEmptyHotbarSlot()
  • SetHotbarSlot()
  • AppendStorage()
  • FindSlotByUUID()

LimitChecker

Weight tracking and validation.

  • IsEnabled()
  • GetRemainingCapacity()
  • AddWeight()
  • RemoveWeight()

Operations

Modular operation handlers. Each handles one action.

  • Add → Remove → Swap
  • Equip → Unequip
  • Drop to world
  • Stack two stacks

Anti-Exploit Features

Server-authoritative protections

🔒

Per-Player Operation Lock

Only one operation per player at a time. Prevents spam exploits.

🔔

Single Remote Entry Point

All requests go through InventoryAction. No direct state access.

🛡

Bounds Checking

All slot indices validated before access. Prevents out-of-bounds exploits.

💪

Pcall Wrapping

All operations wrapped in pcall. Server never crashes from bad input.

Related Documentation

See also

💻

API Reference

Complete API documentation
+

Add Features

How to extend the server
⚙

Settings

Global and per-player settings
🎨

Client Architecture

Frontend structure