@pukujan/create-modular-monolith 2.0.0

package/template/backend/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "modular-monolith-starter-backend",
+  "private": true,
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "node --watch src/core/server.js",
+    "start": "node src/core/server.js",
+    "lint:boundaries": "node scripts/check-module-boundaries.mjs",
+    "lint:layers": "node scripts/check-module-layers.mjs",
+    "lint:architecture": "npm run lint:boundaries && npm run lint:layers",
+    "test": "node --test 'src/modules/**/tests/**/*.test.js'",
+    "test:evals": "node ../scripts/run-module-evals.mjs"
+  },
+  "dependencies": {
+    "cors": "^2.8.5",
+    "dotenv": "^16.4.5",
+    "express": "^4.19.2"
+  }
+}

package/template/backend/scripts/check-module-boundaries.mjs

@@ -0,0 +1,69 @@
+import { readdirSync, readFileSync, existsSync } from "fs";
+import { join, relative } from "path";
+
+const apps = [
+  { name: "backend", root: new URL("../", import.meta.url).pathname, modulesSubpath: "src/modules" },
+  {
+    name: "frontend",
+    root: new URL("../../frontend/", import.meta.url).pathname,
+    modulesSubpath: "src/modules"
+  }
+];
+
+const forbidden = [];
+
+for (const app of apps) {
+  const modulesDir = join(app.root, app.modulesSubpath);
+  if (!existsSync(modulesDir)) continue;
+
+  const moduleNames = readdirSync(modulesDir, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .filter((d) => !d.name.startsWith("."))
+    .map((d) => d.name);
+
+  for (const moduleName of moduleNames) {
+    const moduleRoot = join(modulesDir, moduleName);
+    const files = walk(moduleRoot).filter((f) =>
+      [".js", ".mjs", ".jsx"].some((ext) => f.endsWith(ext))
+    );
+
+    for (const file of files) {
+      const source = readFileSync(file, "utf8");
+
+      for (const other of moduleNames) {
+        if (other === moduleName) continue;
+        const needle = `/modules/${other}/`;
+        if (source.includes(needle)) {
+          forbidden.push({
+            app: app.name,
+            file: relative(app.root, file),
+            moduleName,
+            other,
+            needle
+          });
+        }
+      }
+    }
+  }
+}
+
+if (forbidden.length) {
+  console.error("Module boundary violations found:\n");
+  for (const hit of forbidden) {
+    console.error(`- [${hit.app}] ${hit.file} references cross-module path (${hit.needle})`);
+  }
+  process.exit(1);
+}
+
+console.log("Module boundaries OK.");
+
+function walk(dir) {
+  const entries = readdirSync(dir, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) files.push(...walk(full));
+    else files.push(full);
+  }
+  return files;
+}

package/template/backend/scripts/check-module-layers.mjs

@@ -0,0 +1,152 @@
+import { readdirSync, readFileSync, existsSync } from "fs";
+import { join, relative } from "path";
+
+const root = new URL("../", import.meta.url).pathname;
+const modulesDir = join(root, "src/modules");
+
+const LAYERS = [
+  "routes",
+  "services",
+  "repositories",
+  "adapters",
+  "domain",
+  "events",
+  "prompts",
+  "evals",
+  "schemas",
+  "utils",
+  "config"
+];
+
+const FORBIDDEN_IMPORTS = {
+  domain: ["services", "routes", "repositories", "adapters", "events", "prompts", "evals"],
+  routes: ["repositories", "adapters", "domain", "events", "prompts", "evals"],
+  repositories: ["services", "routes", "events", "evals", "prompts"],
+  prompts: ["services", "routes", "repositories", "adapters", "events", "evals"],
+  utils: ["services", "routes", "repositories", "adapters", "domain", "events", "prompts", "evals"],
+  schemas: ["services", "routes", "repositories", "adapters", "domain", "events", "evals", "prompts"],
+  adapters: ["services", "routes", "events", "evals", "prompts"],
+  events: ["routes", "repositories", "adapters", "prompts", "evals"],
+  evals: ["routes", "events", "repositories", "adapters"],
+  config: ["routes", "services", "repositories", "adapters", "domain", "events", "prompts", "evals"]
+};
+
+if (!existsSync(modulesDir)) {
+  console.log("No modules directory found. Skipping.");
+  process.exit(0);
+}
+
+const moduleNames = readdirSync(modulesDir, { withFileTypes: true })
+  .filter((d) => d.isDirectory())
+  .filter((d) => !d.name.startsWith("_"))
+  .map((d) => d.name);
+
+const violations = [];
+
+for (const moduleName of moduleNames) {
+  const moduleRoot = join(modulesDir, moduleName);
+  const files = walk(moduleRoot).filter((f) => {
+    if (f.includes("/tests/") || f.includes("\\tests\\")) return false;
+    if (f.endsWith(".test.js") || f.endsWith(".test.mjs")) return false;
+    return f.endsWith(".js") || f.endsWith(".mjs");
+  });
+
+  for (const file of files) {
+    const fromLayer = layerForFile(file, moduleRoot);
+    if (!fromLayer || fromLayer === "index") continue;
+
+    const forbidden = FORBIDDEN_IMPORTS[fromLayer];
+    if (!forbidden) continue;
+
+    const source = readFileSync(file, "utf8");
+    const imports = extractRelativeImports(source);
+
+    for (const imp of imports) {
+      const toLayer = layerForImportPath(imp, file, moduleRoot);
+      if (!toLayer) continue;
+      if (forbidden.includes(toLayer)) {
+        violations.push({
+          file: relative(root, file),
+          fromLayer,
+          toLayer,
+          importPath: imp
+        });
+      }
+    }
+  }
+}
+
+if (violations.length) {
+  console.error("Module layer violations found:\n");
+  for (const hit of violations) {
+    console.error(
+      `- ${hit.file} (${hit.fromLayer}) must not import ${hit.toLayer} via "${hit.importPath}"`
+    );
+  }
+  console.error("\nSee docs/architecture/MODULE_INTERNAL_CONTRACT.md");
+  process.exit(1);
+}
+
+console.log("Module layers OK.");
+
+function layerForFile(filePath, moduleRoot) {
+  const rel = relative(moduleRoot, filePath);
+  if (rel === "index.js") return "index";
+  const segment = rel.split(/[/\\]/)[0];
+  return LAYERS.includes(segment) ? segment : null;
+}
+
+function layerForImportPath(importPath, fromFile, moduleRoot) {
+  const fromDir = join(fromFile, "..");
+  let resolved = importPath.startsWith(".")
+    ? join(fromDir, importPath)
+    : null;
+
+  if (!resolved) {
+    for (const layer of LAYERS) {
+      if (
+        importPath.includes(`/${layer}/`) ||
+        importPath.startsWith(`${layer}/`) ||
+        importPath.includes(`../${layer}/`)
+      ) {
+        return layer;
+      }
+    }
+    return null;
+  }
+
+  if (!resolved.endsWith(".js") && !resolved.endsWith(".mjs")) {
+    resolved += ".js";
+  }
+
+  const rel = relative(moduleRoot, resolved);
+  const segment = rel.split(/[/\\]/)[0];
+  return LAYERS.includes(segment) ? segment : null;
+}
+
+function extractRelativeImports(source) {
+  const imports = [];
+  const patterns = [
+    /from\s+["'](\.[^"']+)["']/g,
+    /import\s*\(\s*["'](\.[^"']+)["']\s*\)/g,
+    /require\s*\(\s*["'](\.[^"']+)["']\s*\)/g
+  ];
+  for (const pattern of patterns) {
+    let match;
+    while ((match = pattern.exec(source)) !== null) {
+      imports.push(match[1]);
+    }
+  }
+  return imports;
+}
+
+function walk(dir) {
+  const entries = readdirSync(dir, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) files.push(...walk(full));
+    else files.push(full);
+  }
+  return files;
+}

package/template/backend/src/core/module-loader.js

@@ -0,0 +1,35 @@
+import { readdirSync, existsSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { getEventBus } from "../shared/events/index.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export async function loadModules(app) {
+  const modulesDir = join(__dirname, "../modules");
+  if (!existsSync(modulesDir)) return;
+
+  const moduleContext = { eventBus: getEventBus() };
+  const names = readdirSync(modulesDir, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .filter((d) => !d.name.startsWith("_"))
+    .filter((d) => !d.name.startsWith("."))
+    .map((d) => d.name);
+
+  for (const name of names) {
+    const moduleEntry = join(modulesDir, name, "index.js");
+    if (!existsSync(moduleEntry)) continue;
+
+    try {
+      const mod = await import(`../modules/${name}/index.js`);
+      if (typeof mod.register === "function") {
+        mod.register(app, moduleContext);
+        console.log(`✓ Module loaded: ${name}`);
+      } else {
+        console.warn(`! Module ignored (missing register): ${name}`);
+      }
+    } catch (error) {
+      console.error(`✗ Module failed: ${name} —`, error.message);
+    }
+  }
+}

package/template/backend/src/core/server.js

@@ -0,0 +1,24 @@
+import express from "express";
+import cors from "cors";
+import dotenv from "dotenv";
+import { loadModules } from "./module-loader.js";
+import { errorHandler } from "../shared/http/errors.js";
+
+dotenv.config();
+
+const app = express();
+app.use(cors());
+app.use(express.json({ limit: "10mb" }));
+
+await loadModules(app);
+
+app.get("/api/health", (_, res) => {
+  res.json({ status: "ok", loadedAt: new Date().toISOString() });
+});
+
+app.use(errorHandler);
+
+const port = process.env.PORT || 3001;
+app.listen(port, () => {
+  console.log(`Backend running on port ${port}`);
+});

package/template/backend/src/modules/_reference/README.md

@@ -0,0 +1,11 @@
+# Reference (example module)
+
+**Not loaded at runtime** — folder name starts with `_`. Copy patterns from here or use `npm run new:module`.
+
+See [Module internal contract](../../../docs/architecture/MODULE_INTERNAL_CONTRACT.md).
+
+## Layout
+
+`routes` → `services` → `repositories` / `domain` / `adapters`
+
+`prompts` + `evals` for AI workflows. `tests/` for unit and integration coverage.

package/template/backend/src/modules/_reference/adapters/README.md

@@ -0,0 +1,3 @@
+# Adapters — _reference
+
+Wrappers for external systems (courts, e-file, storage, LLM providers).

package/template/backend/src/modules/_reference/config/index.js

@@ -0,0 +1,4 @@
+export const moduleConfig = {
+  name: "_reference",
+  label: "_reference"
+};

package/template/backend/src/modules/_reference/domain/README.md

@@ -0,0 +1,3 @@
+# Domain — _reference
+
+Pure entities, value objects, and domain rules. No Express, DB, or HTTP imports.

package/template/backend/src/modules/_reference/evals/README.md

@@ -0,0 +1,6 @@
+# Evals — _reference
+
+- **datasets/** — fixtures (input, expected constraints).
+- **runners/** — `*.eval.mjs` files executed via `npm run test:evals`.
+
+Run: `npm run test:evals -- _reference`

package/template/backend/src/modules/_reference/evals/datasets/example.cases.json

@@ -0,0 +1,12 @@
+{
+  "cases": [
+    {
+      "id": "health-shape",
+      "description": "Health payload includes module name",
+      "input": {},
+      "expect": {
+        "status": "ok"
+      }
+    }
+  ]
+}

package/template/backend/src/modules/_reference/evals/runners/example.eval.mjs

@@ -0,0 +1,25 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { getHealth } from "../../services/health.service.js";
+import { renderPrompt } from "../../../../shared/ai/prompt-registry.js";
+import * as examplePrompt from "../../prompts/templates/example.prompt.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+test("_reference: health service matches dataset", () => {
+  const dataset = JSON.parse(
+    readFileSync(join(__dirname, "../datasets/example.cases.json"), "utf8")
+  );
+  const expected = dataset.cases[0].expect;
+  const result = getHealth({ name: "_reference" });
+  assert.equal(result.status, expected.status);
+  assert.equal(result.module, "_reference");
+});
+
+test("_reference: example prompt renders variables", () => {
+  const rendered = renderPrompt(examplePrompt.template, { matterId: "MAT-001" });
+  assert.match(rendered, /MAT-001/);
+});

package/template/backend/src/modules/_reference/events/index.js

@@ -0,0 +1,4 @@
+export function registerModuleEvents(context) {
+  // context.eventBus.on("some:event", handler);
+  context.eventBus.emit("module:registered", { module: "_reference" });
+}

package/template/backend/src/modules/_reference/index.js

@@ -0,0 +1,9 @@
+import { createModuleRouter } from "./routes/index.js";
+import { registerModuleEvents } from "./events/index.js";
+import { moduleConfig } from "./config/index.js";
+
+export function register(app, context) {
+  const router = createModuleRouter({ config: moduleConfig, context });
+  app.use("/api/_reference", router);
+  registerModuleEvents(context);
+}

package/template/backend/src/modules/_reference/prompts/manifest.json

@@ -0,0 +1,14 @@
+{
+  "module": "_reference",
+  "prompts": [
+    {
+      "id": "example-assistant",
+      "version": "1.0.0",
+      "file": "templates/example.prompt.js",
+      "description": "Example prompt for ${title}",
+      "variables": [
+        "matterId"
+      ]
+    }
+  ]
+}

package/template/backend/src/modules/_reference/prompts/templates/example.prompt.js

@@ -0,0 +1,7 @@
+export const id = "example-assistant";
+export const version = "1.0.0";
+export const variables = ["matterId"];
+
+export const template = `You are a legal workflow assistant for module _reference.
+Matter id: {{matterId}}
+Respond with structured JSON only.`;

package/template/backend/src/modules/_reference/routes/health.routes.js

@@ -0,0 +1,10 @@
+import { Router } from "express";
+import { getHealth } from "../services/health.service.js";
+
+export function createHealthRoutes({ config }) {
+  const router = Router();
+  router.get("/health", (_req, res) => {
+    res.json(getHealth(config));
+  });
+  return router;
+}

package/template/backend/src/modules/_reference/routes/index.js

@@ -0,0 +1,8 @@
+import { Router } from "express";
+import { createHealthRoutes } from "./health.routes.js";
+
+export function createModuleRouter({ config, context }) {
+  const router = Router();
+  router.use(createHealthRoutes({ config, context }));
+  return router;
+}

package/template/backend/src/modules/_reference/schemas/health.schema.js

@@ -0,0 +1,8 @@
+export function isHealthResponse(value) {
+  return Boolean(
+    value &&
+      typeof value.module === "string" &&
+      typeof value.status === "string" &&
+      typeof value.timestamp === "string"
+  );
+}

package/template/backend/src/modules/_reference/services/health.service.js

@@ -0,0 +1,7 @@
+export function getHealth(config) {
+  return {
+    module: config.name,
+    status: "ok",
+    timestamp: new Date().toISOString()
+  };
+}

package/template/backend/src/modules/_reference/tests/integration/health.routes.test.js

@@ -0,0 +1,20 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { createTestApp } from "../../../../shared/testing/create-test-app.js";
+import { register } from "../../index.js";
+
+test("GET /api/_reference/health", async () => {
+  const app = createTestApp(register);
+  const server = app.listen(0);
+  const { port } = server.address();
+
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}/api/_reference/health`);
+    assert.equal(res.status, 200);
+    const body = await res.json();
+    assert.equal(body.module, "_reference");
+    assert.equal(body.status, "ok");
+  } finally {
+    server.close();
+  }
+});

package/template/backend/src/modules/_reference/tests/unit/health.service.test.js

@@ -0,0 +1,9 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { getHealth } from "../../services/health.service.js";
+
+test("getHealth returns module metadata", () => {
+  const result = getHealth({ name: "_reference" });
+  assert.equal(result.module, "_reference");
+  assert.equal(result.status, "ok");
+});

package/template/backend/src/modules/_reference/utils/index.js

@@ -0,0 +1,3 @@
+export function moduleSlug(value) {
+  return String(value ?? "").trim().toLowerCase();
+}

package/template/backend/src/shared/ai/prompt-registry.js

@@ -0,0 +1,42 @@
+import { readFileSync, existsSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath, pathToFileURL } from "url";
+
+/**
+ * Load a versioned prompt template from a module's prompts/ folder.
+ * @param {string} moduleDir - absolute path to backend/src/modules/<name>
+ * @param {string} promptId - id matching prompts/templates and manifest
+ */
+export async function loadPromptTemplate(moduleDir, promptId) {
+  const manifestPath = join(moduleDir, "prompts", "manifest.json");
+  if (!existsSync(manifestPath)) {
+    throw new Error(`Prompt manifest not found: ${manifestPath}`);
+  }
+
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  const entry = manifest.prompts?.find((p) => p.id === promptId);
+  if (!entry?.file) {
+    throw new Error(`Prompt id not in manifest: ${promptId}`);
+  }
+
+  const filePath = join(moduleDir, "prompts", entry.file);
+  const mod = await import(pathToFileURL(filePath).href);
+  return {
+    id: mod.id ?? promptId,
+    version: mod.version ?? entry.version ?? "0.0.0",
+    template: mod.template,
+    variables: mod.variables ?? entry.variables ?? []
+  };
+}
+
+export function renderPrompt(template, variables = {}) {
+  let output = template;
+  for (const [key, value] of Object.entries(variables)) {
+    output = output.replaceAll(`{{${key}}}`, String(value ?? ""));
+  }
+  return output;
+}
+
+export function moduleDirFromMeta(metaUrl) {
+  return dirname(fileURLToPath(metaUrl));
+}

package/template/backend/src/shared/events/index.js

@@ -0,0 +1,8 @@
+import { EventEmitter } from "events";
+
+const bus = new EventEmitter();
+bus.setMaxListeners(100);
+
+export function getEventBus() {
+  return bus;
+}

package/template/backend/src/shared/http/errors.js

@@ -0,0 +1,10 @@
+export function errorHandler(error, _req, res, _next) {
+  const status = Number.isInteger(error?.status) ? error.status : 500;
+  const message = error?.message || "Internal Server Error";
+
+  if (status >= 500) {
+    console.error("Unhandled error:", error);
+  }
+
+  res.status(status).json({ error: message });
+}

package/template/backend/src/shared/testing/create-test-app.js

@@ -0,0 +1,13 @@
+import express from "express";
+
+/**
+ * Minimal Express app for module integration tests.
+ * Pass a register function from the module under test.
+ */
+export function createTestApp(register) {
+  const app = express();
+  app.use(express.json());
+  const context = { eventBus: { emit() {}, on() {} } };
+  register(app, context);
+  return app;
+}