System Architecture of Nexus Core

Understand how Nexus Core sits between your Spigot game servers and MongoDB, routing all data through Redis Streams with circuit breaker protection and fault-tolerant retry.

Nexus Core is a standalone Java application that acts as the data brain for a distributed Minecraft server network. Multiple Spigot game servers (Lobby, PvP, Survival, and so on) publish request packets to a shared Redis Stream. Nexus Core reads from that stream using consumer groups, validates each packet through a multi-stage security chain, and routes it to the correct DataAddon. The addon reads from or writes to MongoDB, updates the Redis cache, and publishes the response back to the originating server. As of v1.6.4, MongoDB and Redis calls are protected by Resilience4j Circuit Breakers and Exponential Backoff Retry to prevent cascading failures.

Architecture Diagram

┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│   ┌──────────────┐    ┌──────────────┐    ┌──────────────┐     │
│   │  Spigot #1   │    │  Spigot #2   │    │  Spigot #3   │     │
│   │  (Lobby)     │    │  (PvP)       │    │  (Survival)  │     │
│   └──────┬───────┘    └──────┬───────┘    └──────┬───────┘     │
│          │                   │                   │             │
│          └───────────────────┼───────────────────┘             │
│                              │ Redis Streams (signed packets)  │
│                    ┌─────────▼──────────┐                      │
│                    │    Redis Broker     │                      │
│                    │  (Streams + Cache)  │                      │
│                    └─────────┬──────────┘                      │
│                              │                                  │
│                    ┌─────────▼──────────┐                      │
│                    │   ⬡ NEXUS CORE ⬡   │                      │
│                    │                    │                      │
│                    │  ┌──────────────┐  │                      │
│                    │  │   Security   │  │  HMAC / Nonce /      │
│                    │  │ Verification │  │  Timestamp checks    │
│                    │  └──────┬───────┘  │                      │
│                    │  ┌──────▼───────┐  │                      │
│                    │  │ AddonRegistry│  │                      │
│                    │  │  Addon #100  │  │                      │
│                    │  │  Addon #200  │  │                      │
│                    │  │  Addon #500  │  │                      │
│                    │  └──────┬───────┘  │                      │
│                    └─────────┼──────────┘                      │
│                              │ CRUD Operations                  │
│                    ┌─────────▼──────────┐                      │
│                    │      MongoDB        │                      │
│                    │  (nexus_core_db)    │                      │
│                    └────────────────────┘                      │
└─────────────────────────────────────────────────────────────────┘

Three Layers

Transport Layer (Redis Streams)

As of v1.6.4, Redis Streams replace the legacy Pub/Sub channel. Spigot servers write packets with XADD; Nexus Core reads them via a consumer group using XREADGROUP and acknowledges each message with XACK after processing. This guarantees at-least-once delivery: unacknowledged messages are retained across reconnects, and consumer groups allow multiple worker instances to share the load.

Redis also serves as the shared L2 cache and publishes keyspace notifications that Nexus Core uses to keep L1 in-memory caches synchronized.

Nexus Core

The security chain runs first on every inbound packet: HMAC-SHA256 signature verification, a 5-minute timestamp window, and nonce replay detection. After validation, the AddonRegistry dispatches the request to the matching DataAddon by protocol ID. The addon consults the cache hierarchy and performs the required MongoDB operation. All MongoDB and Redis calls are wrapped in Resilience4j Circuit Breakers that trip to OPEN on high error rates, and Exponential Backoff Retry with jitter automatically retries transient failures.

Persistence Layer (Multi-Database)

As of v1.7.0, the persistence layer is abstracted behind a generic database provider interface. MongoDB remains the default adapter; PostgreSQL and MySQL are also supported out of the box. Nexus Core maintains the only connection pool to each configured data source, eliminating per-server connection overhead regardless of how many Spigot instances are running.

DataAddons declare their target database and collection (or table). The framework resolves the correct adapter at request time based on the addon’s configuration and routes all serialization transparently. Multiple data sources can run simultaneously — different addons within the same Nexus Core instance can target different databases.

Why This Design?

Problem	Without Nexus Core	With Nexus Core
DB Connections	Every server has its own connection pool	One optimized, shared pool per data source
Cache Consistency	Per-server caches diverge and go stale	Centralized Redis cache, always consistent
Data Logic	Duplicated across every server codebase	Defined once in a DataAddon, shared everywhere
Database Flexibility	Locked to a single engine	MongoDB, PostgreSQL, MySQL — or multiple at once

Related Topics

• Request Types — the nine packet types Nexus Core accepts and routes
• Cache Strategy — how L1 in-memory, L2 Redis, and MongoDB interact
• Security — the three-stage packet validation chain