add README.md

Author: Zone-Infinity

README.md

@@ -0,0 +1,311 @@
+# DataCenterPlugin
+
+Centralized data persistence layer for Minecraft server backends, providing unified database access, caching, and cross-plugin data consistency.
+
+---
+
+## Why This Exists
+
+In a multi-plugin Minecraft server, each plugin typically manages its own data, leading to:
+
+- duplicated database connections
+- inconsistent data models
+- race conditions across plugins
+- difficulty maintaining consistent updates across systems
+
+DataCenterPlugin centralizes persistence into a single layer, enforcing consistent data access patterns and reducing duplication across plugins.
+
+---
+
+## Overview
+
+DataCenterPlugin acts as the core data service for a Minecraft server backend.
+
+It provides:
+
+- unified database access
+- schema management
+- caching for performance
+- consistent read/write patterns
+
+Other plugins depend on it for reliable player data storage and retrieval.
+
+---
+
+## Core Responsibilities
+
+- Manage database connections using HikariCP
+- Register schemas and create tables automatically
+- Provide unified data access via `DataKey` abstractions
+- Maintain in-memory caching with TTL
+- Ensure consistency across plugins accessing shared data
+- Perform atomic upsert operations
+
+---
+
+## Architecture / Design
+
+### Internal Components
+
+- **DataCenter**  
+  Central manager handling connections and schema registration
+
+- **DataKey**  
+  Defines a data domain (table + schema metadata)
+
+- **Column**  
+  Maps Java types to SQL types
+
+- **Data / SingleData / MultipleData**  
+  Represent stored entities and persistence logic
+
+---
+
+### Data Flow
+
+```
+Player Event
+   ↓
+Plugin Logic
+   ↓
+DataCenter.get(DataKey, UUID)
+   ↓
+Cache lookup (if enabled)
+   ↓
+Database query (on miss)
+   ↓
+Data object returned
+   ↓
+Modification → Upsert
+   ↓
+Cache update
+```
+
+---
+
+### Cross-Plugin Interaction
+
+Plugins access the system through a shared `DataCenter` instance.
+
+Each plugin:
+
+1. Registers its `DataKey`
+2. Uses typed access to read/write data
+3. Relies on DataCenter for consistency
+
+This avoids tight coupling while maintaining shared state.
+
+---
+
+## Data & State Management
+
+### Storage Architecture
+
+- **Primary storage:** MariaDB
+- **Connection pooling:** HikariCP
+- **Cache:** In-memory, per-module TTL-based
+- **Configuration:** YAML-based
+
+---
+
+### Data Models
+
+- **SingleData**  
+  One value per player (e.g., credits)
+
+- **MultipleData**  
+  Structured multi-column data (e.g., stats, rewards)
+
+---
+
+### Consistency Model
+
+- Writes use an upsert strategy (UPDATE → fallback INSERT)
+- Cache is invalidated immediately on write
+- Read-after-write consistency is guaranteed within a single server instance
+- No distributed locking; consistency relies on controlled access through DataCenter
+
+---
+
+## Key Features
+
+- Modular data registration via `DataKey`
+- Automatic table creation
+- TTL-based caching for frequently accessed data
+- Type-safe schema definitions
+- Built-in support for leaderboard queries
+
+---
+
+## Interesting Engineering Decisions
+
+### Upsert-First Persistence
+
+Instead of separating INSERT and UPDATE:
+
+- Attempt UPDATE
+- If no rows affected → INSERT
+
+This ensures:
+
+- simpler calling code
+- correct handling of new players
+- idempotent operations
+
+---
+
+### CSV-Based Storage (Rewards)
+
+Some modules store multiple values in a single column using CSV.
+
+Tradeoff:
+
+- simpler queries
+- less normalized schema
+
+Chosen due to limited relational complexity needs.
+
+---
+
+### High-Precision Currency
+
+Credits stored as:
+
+```
+NUMERIC(15,3)
+```
+
+Avoids floating-point rounding issues common in game economies.
+
+---
+
+## Design Tradeoffs
+
+- Simplicity over full normalization (e.g., CSV storage)
+- Local caching instead of distributed caching (single-server assumption)
+- Explicit SQL instead of ORM for control and predictability
+- Auto-commit transactions instead of manual transaction control
+
+---
+
+## Challenges & Solutions
+
+### 1. Cross-Plugin Data Access
+
+**Problem:**  
+Multiple plugins required shared access to player data without tight coupling.
+
+**Solution:**  
+Introduced `DataKey` registry pattern:
+
+- plugins declare schemas
+- receive typed access objects
+- remain independent but consistent
+
+---
+
+### 2. Performance Under Load
+
+**Problem:**  
+Frequent reads (e.g., credits during PvP) caused excessive DB load.
+
+**Solution:**  
+Added module-specific TTL caching:
+
+- reduced redundant queries
+- maintained acceptable staleness
+
+---
+
+### 3. Schema Evolution
+
+**Problem:**  
+Schema changes risk breaking existing deployments.
+
+**Solution:**
+
+- used `CREATE TABLE IF NOT EXISTS`
+- avoided destructive migrations
+- allowed incremental schema updates
+
+---
+
+## Example Flow: Player Earns Credits
+
+1. Plugin requests credits:
+   ```
+   Credits credits = dataCenter.get(CreditsKey.INSTANCE, playerUUID);
+   ```
+
+2. Cache is checked
+
+3. On miss → database query executed
+
+4. Plugin updates value:
+   ```
+   credits.add(100.0);
+   ```
+
+5. Upsert operation persists data
+
+6. Cache updated
+
+---
+
+## Limitations
+
+- Designed for single-server architecture (no multi-server sync)
+- No distributed cache coherence
+- No explicit transaction boundaries beyond single queries
+- Schema migrations are manual
+- No concurrency control beyond server-thread model
+
+---
+
+## Usage
+
+This is a library plugin.
+
+Example:
+
+```
+DataCenter dataCenter = SolarDataCenter.ins.getDataCenter();
+Credits credits = dataCenter.get(CreditsKey.INSTANCE, playerUuid);
+```
+
+---
+
+## Tech Stack
+
+- Java 8
+- Spigot API (1.8.8)
+- MariaDB
+- HikariCP
+- YAML configuration
+- Maven
+
+---
+
+## Notes
+
+Used in a live multiplayer server environment with frequent player-driven data updates.
+
+The system prioritizes:
+
+- consistency
+- simplicity
+- performance
+
+over feature completeness.
+
+---
+
+## TODO / Improvements
+
+- Persist schema metadata and detect missing columns on startup
+- Safely add new columns (`ALTER TABLE ADD COLUMN`) without breaking existing data
+- Replace all raw SQL with prepared statements
+- Centralize query construction to avoid unsafe dynamic SQL
+- Improve cache handling (configurable TTL, better invalidation)
+- Add basic transaction support for multi-step operations
+- Improve error handling and logging