Skip to main content

Architecture Overview

ZyveraWeb uses a layered architecture with a platform-independent core and platform-specific adapters, following the Adapter pattern.

High-Level Diagram

┌──────────────────────────────────────────────────────────┐
│                     ZyveraWebCore                         │
│  (Lifecycle, Config, Server, Commands, ACME, Handlers)   │
└────────────────────┬─────────────────────────────────────┘
                     │ uses
              ┌──────┴──────┐
              │  Platform   │  <-- Interface
              │  interface  │
              └──────┬──────┘
                     │ implemented by
        ┌────────────┼────────────────┐
        │            │                │
  BukkitPlatform  VelocityPlatform  BungeePlatform
        │            │                │
  ┌─────┴─────┐  ┌──┴───┐       ┌────┴────┐
  │ JavaPlugin │  │Plugin│       │  Plugin │
  │ (Bukkit)   │  │(Vel.)│       │(Bungee) │
  └────────────┘  └──────┘       └─────────┘

Core Module (core/)

The core module contains all platform-independent code:

Package Responsibility
platform/ Platform interface and abstractions (logger, config, scheduler, metrics)
web/server/ HTTP and HTTPS server implementations
web/handler/ Request handlers: static files, virtual hosts, reverse proxy, Node.js
web/script/ JavaScript runtime abstraction and GraalJS implementation
web/config/ Site configuration data classes
web/ratelimit/ Per-IP token bucket rate limiter
acme/ Let's Encrypt ACME v2 client
node/ Pure-JVM npm package installer
command/ Command interfaces and implementations
endpoint/ HTTP endpoint registry
util/ Utility classes (time parsing)

Platform Module (platform-*/)

Each platform module provides:

  1. A main plugin class that initializes the platform adapter
  2. A Platform implementation that bridges core APIs to the server platform
  3. Platform-specific command handling
  4. Platform-specific scheduling
  5. Platform-specific metrics
  6. Platform-specific HTTP endpoints (e.g., /api/players)

Request Flow

HTTP Request
    │
    ▼
HttpServer / HttpsServer
    │
    ▼
EndpointRegistry.match(path)
    │
    ├── /api/*  →  Platform-specific handlers (players, placeholder)
    │
    └── /*      →  VirtualHostHandler
                        │
                        ├── domain match?  →  Site-specific handler
                        │     ├── web    →  FileHandler (static files)
                        │     ├── proxy  →  ReverseProxyHandler
                        │     └── node   →  NodeSiteHandler
                        │                     ├── public/ (static)
                        │                     └── server.js (GraalJS)
                        │
                        └── no match  →  Default/catch-all handler

Key Design Decisions

Decision Rationale
JDK built-in HTTP server Avoid dependency conflicts with Minecraft server
GraalJS for JavaScript No external Node.js process; runs in-JVM
Pure-JVM npm installer Works without Node.js or shell access
ShadowJar fat JAR Bundles all dependencies; single-file deployment
Platform abstraction Single codebase, three platform targets

No comments to display

Back to top