> ## Documentation Index
> Fetch the complete documentation index at: https://nexus-core.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```text theme={null}
┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│   ┌──────────────┐    ┌──────────────┐    ┌──────────────┐     │
│   │  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](/concepts/request-types) — the nine packet types Nexus Core accepts and routes
* [Cache Strategy](/concepts/cache-strategy) — how L1 in-memory, L2 Redis, and MongoDB interact
* [Security](/concepts/security) — the three-stage packet validation chain


## Related topics

- [Nexus Core: Centralized Cache Orchestration for Minecraft](/index.md)
- [Installing Nexus Core](/installation.md)
- [Nexus Core Changelog](/reference/changelog.md)
- [Protocol and Packet Structure Reference](/reference/packet-structure.md)
- [Packet Security and Replay Protection in Nexus Core](/concepts/security.md)