Logo
Architecture

Recommended XyPriss Project Architecture

A production-ready structure for both single-server and multi-server deployments, designed for scalability, security, and maintainability.

Multi-Server Architecture

XyPriss Multi-Server (XMS) allows you to run multiple isolated server instances within a single Node.js process. Each instance has its own port, security policy, plugin set, and route scope. This is the recommended architecture for production workloads that require separation between public access, authentication, and administrative surfaces.

Example Scope
The diagrams below show a two-server setup for clarity: main for the public API and login for authentication. The same pattern can be extended to additional servers (admin, webhooks, internal) as your surface area grows.

main.server

  • Port: dynamic (assigned via config or manifest)
  • Prefix: /api
  • Strategy: strict-match
  • Routes: public API endpoints

login.server

  • Port: manifest.servers.login.port
  • Prefix: /auth
  • Plugins: superdev, Swagger (7289), Xyphra
  • Routes: rate-limited GET /, POST /login
How They Work Together
Both servers share the same underlying XHSC native engine but are fully isolated at the HTTP layer. The main server handles public API traffic, while the login server concentrates all authentication, session, and security-critical logic. Requests are routed by prefix: /api/* goes to main.server, /auth/* goes to login.server.

Recommended Project Structure

supperdev
package.json
tsconfig.json
xypriss.config.jsonc
src
server.ts
configs
servers
routers
controllers
plugins
database
schema

Initialization Flow

Configure Multi-Server

typescript
// src/configs/xypriss.config.ts
export default {
    multiServer: {
        enabled: true,
        servers: [
            { id: "main", port: 3000, routePrefix: "/api", routePrefixStrategy: "strict" },
            { id: "login", port: 3001, routePrefix: "/auth", routePrefixStrategy: "strict" }
        ]
    }
};

Create Server

typescript
import { createServer } from "xypriss";
import serverConfigs from "./configs/xypriss.config";

const app = createServer(serverConfigs);

Mount Root Router

typescript
import router from "./routers";

app.use("/", router);

Start

typescript
app.start(); // Boots both main & login instances
Why This Architecture?
Security: The auth server can have stricter plugins (rate limiting, Swagger, Xyphra) without affecting the public API surface. Scalability: Each server can be scaled or deployed independently. Maintainability: Clear separation of concerns makes the codebase easier to navigate and test.
Multi-Server Setup

Configure per-instance response control and route isolation with XMS.