From bf48f3baefcc40f2093964910d28a39359fb474e Mon Sep 17 00:00:00 2001
From: gbena-afk <gbena966@gmail.com>
Date: Sun, 28 Jun 2026 15:49:09 +0100
Subject: [PATCH] chore(dev): make legacy server explicit, add deprecation
 warning, and recommend decoupled path in README

---
 README.md    | 27 +++++++++++++++++++++------
 package.json |  4 +++-
 server.ts    |  6 ++++++
 3 files changed, 30 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 081f8b9..e7e1ff3 100644
--- a/README.md
+++ b/README.md
@@ -51,10 +51,10 @@ npm run dev
 
 Open [http://localhost:3000](http://localhost:3000) in your browser.
 
-For the custom server with WebSocket support and `/metrics`, run:
+For the custom server with WebSocket support and `/metrics`, run the recommended decoupled web server:
 
 ```bash
-npm run dev:ws
+npm run dev:decoupled
 ```
 
 ### Environment Variables
@@ -84,9 +84,9 @@ cp .env.microservices.example .env.local
 **Development:**
 ```bash
 npm run dev              # Standard Next.js dev server
-npm run dev:ws           # Legacy monolithic server with WebSocket
-npm run dev:decoupled    # Microservices web server (requires Redis)
+npm run dev:decoupled    # Microservices web server (recommended; requires Redis)
 npm run worker:indexer   # Microservices indexer worker (requires Redis)
+npm run dev:legacy       # Legacy monolithic server (deprecated; use only for compatibility)
 npm run test:websocket   # Test WebSocket connection
 ```
 
@@ -115,7 +115,7 @@ npm run format           # Format code with Prettier
 
 ## Telemetry
 
-The custom server exposes Prometheus metrics on `http://localhost:3000/metrics` when running `npm run dev:ws`.
+The custom server exposes Prometheus metrics on `http://localhost:3000/metrics` when running `npm run dev:decoupled`.
 
 You can configure OpenTelemetry to export spans to Jaeger by setting:
 
@@ -217,9 +217,24 @@ Stellar Network → Event Indexer → Translation Engine → WebSocket Server 
 ⚠️ **Known limitations:** Under heavy load, indexing can starve the HTTP/WebSocket server of CPU cycles. See deprecation notice in `server.ts`.
 
 ```bash
-npm run dev:ws
+npm run dev:legacy
 ```
 
+Migration note for local scripts/configs:
+
+- If you have local tooling, CI scripts, or process managers that call `server.ts` directly or run `npm run dev:ws`, update them to the new explicit legacy script:
+
+```bash
+# To keep running the legacy monolithic server (not recommended):
+npm run dev:legacy
+
+# Recommended: use the decoupled microservices server and indexer:
+npm run dev:decoupled
+npm run worker:indexer
+```
+
+This change ensures `npm run dev` and the documented development path do not silently start the deprecated server.
+
 ---
 
 For new contributors wanting to understand the system's data flow and internal architecture, see the comprehensive [**ARCHITECTURE.md**](ARCHITECTURE.md) guide which includes:
diff --git a/package.json b/package.json
index 61d91fd..3ec0a20 100644
--- a/package.json
+++ b/package.json
@@ -4,7 +4,9 @@
   "private": true,
   "scripts": {
     "dev": "next dev",
-    "dev:ws": "node --max-old-space-size=512 --expose-gc -r ts-node/register --project tsconfig.server.json server.ts",
+    "dev:ws": "node --max-old-space-size=512 --expose-gc -r ts-node/register --project tsconfig.server.json server-decoupled.ts",
+    "dev:legacy": "node --max-old-space-size=512 --expose-gc -r ts-node/register --project tsconfig.server.json server.ts",
+    "dev:decoupled": "npm run dev:ws",
     "start:ws": "node --max-old-space-size=1024 --max-semi-space-size=64 --initial-old-space-size=128 --optimize-for-size dist/server.js",
     "profile:heap": "node --expose-gc --max-old-space-size=512 -r tsx/cjs scripts/profile-heap.ts",
     "build": "next build",
diff --git a/server.ts b/server.ts
index bcc318e..9e9ab37 100644
--- a/server.ts
+++ b/server.ts
@@ -36,6 +36,12 @@
  * Run with: npx ts-node --project tsconfig.server.json server.ts
  * (or via the `dev:ws` npm script)
  */
+
+// Visible runtime deprecation warning for developers running the legacy server.
+// This should make it obvious when someone accidentally starts the deprecated
+// monolithic server. The process continues to run for compatibility, but the
+// warning recommends the decoupled microservices path.
+console.warn("\n\u001b[33mDEPRECATION: \`server.ts\` is a legacy monolithic server with a known CPU-starvation flaw.\nRecommended: use the microservices/decoupled path (npm run dev:decoupled).\nTo run the legacy server anyway, use the explicit script: npm run dev:legacy\u001b[0m\n");
 import { createServer, IncomingMessage } from "http";
 import { parse } from "url";
 import next from "next";