isolated-vm requires a native build. Ensure node-gyp and a C++ toolchain are present (apt install build-essential on Debian/Ubuntu; Xcode Command Line Tools on macOS). Run npm rebuild isolated-vm after install if pre-built binaries are unavailable.

Project setup

1. Copy the source/ directory into your project, e.g. src/enfyra/.
2. Add a tsconfig.json path alias so imports resolve cleanly:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@enfyra/*": ["src/enfyra/*"]
    },
    "module": "CommonJS",
    "target": "ES2020",
    "esModuleInterop": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true
  }
}

3. Create a .env file at the project root (values consumed by env.ts):

PORT=3000
DB_CLIENT=mysql2
DB_HOST=localhost
DB_PORT=3306
DB_NAME=enfyra
DB_USER=root
DB_PASSWORD=secret
JWT_SECRET=changeme
REDIS_URL=redis://localhost:6379

4. Place your schema file at data/snapshot.json relative to the working directory (see README schema format).

5. Add a start script in package.json:

{
  "scripts": {
    "dev": "ts-node src/enfyra/main.ts",
    "build": "tsc -p tsconfig.json",
    "start": "node dist/enfyra/main.js"
  }
}

6. Run the DB initialisation script before first boot:

npx ts-node scripts/init-db.ts

Public API

buildContainer

import { buildContainer } from './container';

function buildContainer(): AwilixContainer<CradleMap>

Constructs the Awilix IoC container with all service registrations. Call once at startup and pass the result to init and buildExpressApp. Do not call more than once per process; registrations are not idempotent.

init / shutdown

import { init, shutdown } from './init';

async function init(container: AwilixContainer): Promise<void>
async function shutdown(container: AwilixContainer): Promise<void>

init runs the full startup sequence: database connection, schema bootstrap, provision, and queue initialisation. shutdown gracefully tears down connections. Both must be awaited. Call shutdown inside SIGTERM/SIGINT handlers to prevent data loss.

buildExpressApp

import { buildExpressApp } from './express-app';
import { Express } from 'express';

function buildExpressApp(container: AwilixContainer): Express

Returns a configured Express application with CORS, body parsing, REST routes, and GraphQL mounted. Pass the result to http.createServer to attach Socket.IO alongside it. You can call app.use(...) on the returned instance to add custom middleware before the server starts listening.

Logger

import { Logger } from './shared/logger';

class Logger {
  constructor(context: string)
  log(message: string): void
  error(message: string, error?: unknown): void
  warn(message: string): void
}

Structured logger used throughout the server. Instantiate with a context string (e.g. 'MyService') to prefix all output. Use it instead of console.log so output is consistent with Enfyra's own log stream.

Working examples

Scenario - Minimal server startup

Drop-in replacement for main.ts when you only need the HTTP server without the Socket.IO gateway:

import * as http from 'http';
import { buildContainer } from './src/enfyra/container';
import { init, shutdown } from './src/enfyra/init';
import { buildExpressApp } from './src/enfyra/express-app';
import { env } from './src/enfyra/env';
import { Logger } from './src/enfyra/shared/logger';

const logger = new Logger('Bootstrap');

async function start() {
  const container = buildContainer();
  await init(container);

  const app = buildExpressApp(container);
  const server = http.createServer(app);

  server.listen(env.PORT, '0.0.0.0', () => {
    logger.log(`Listening on port ${env.PORT}`);
  });

  const stop = async () => {
    logger.warn('Shutting down...');
    await shutdown(container);
    server.close(() => process.exit(0));
  };

  process.once('SIGTERM', stop);
  process.once('SIGINT', stop);
}

start().catch((err) => {
  console.error(err);
  process.exit(1);
});

Scenario - Adding custom Express middleware

Mount your own routes after buildExpressApp returns but before the server starts listening:

import * as http from 'http';
import express from 'express';
import { buildContainer } from './src/enfyra/container';
import { init } from './src/enfyra/init';
import { buildExpressApp } from './src/enfyra/express-app';
import { env } from './src/enfyra/env';

async function start() {
  const container = buildContainer();
  await init(container);

  const app = buildExpressApp(container);

  // Custom health-check route layered on top
  app.get('/healthz', (_req, res) => {
    res.json({ status: 'ok', uptime: process.uptime() });
  });

  // Custom middleware example
  app.use('/api/v2', (req, _res, next) => {
    console.log(`[v2] ${req.method} ${req.path}`);
    next();
  });

  http.createServer(app).listen(env.PORT);
}

start();

Scenario - Wiring Socket.IO with the dynamic gateway

Replicates the full WebSocket path from main.ts so you can extend gateway behaviour:

import * as http from 'http';
import { Server } from 'socket.io';
import { createAdapter } from '@socket.io/redis-adapter';
import { buildContainer } from './src/enfyra/container';
import { init } from './src/enfyra/init';
import { buildExpressApp } from './src/enfyra/express-app';
import { env } from './src/enfyra/env';
import { Logger } from './src/enfyra/shared/logger';

const logger = new Logger('WS');

async function start() {
  const container = buildContainer();
  await init(container);

  const app = buildExpressApp(container);
  const server = http.createServer(app);

  const gateway = container.cradle.dynamicWebSocketGateway;
  if (gateway) {
    const io = new Server(server, {
      cors: { origin: true, credentials: true },
    });
    gateway.server = io;
    await gateway.afterInit(io);
    logger.log('WebSocket gateway initialised');
  }

  server.listen(env.PORT, '0.0.0.0', () => {
    logger.log(`Server ready on :${env.PORT}`);
  });
}

start();

File walkthrough

• main.ts - Orchestrates the full cold-start sequence: container, init, Express, HTTP, Socket.IO, queue.
• container.ts - Registers every service into an Awilix scoped container; the single source of truth for DI.
• env.ts - Reads process.env and exports a typed env object; throws on missing required vars.
• express-app.ts - Creates and configures the Express instance with all built-in middleware and routers.
• init.ts - Runs ordered async startup tasks (DB, bootstrap, provision); exports shutdown for cleanup.
• domain/ - Root of all business logic; re-exports via domain/index.ts.
• domain/auth/ - JWT signing/verification, bcrypt hashing, OAuth flows, session cleanup, token revocation.
• domain/bootstrap/ - Snapshot processors that translate JSON config into DB schema and API registrations.
• domain/exceptions/ - Global exception filter for Express/GraphQL, custom error classes, structured logging.
• domain/policy/ - Evaluates access policies; includes schema migration safety auditor.
• domain/shared/ - Abstract interfaces (CacheInterface, ExecutorEngineInterface) for engine implementations.
• engines/ - Concrete engine implementations (query, flow execution, etc.).
• http/ - Additional HTTP handlers (file upload, storage, custom route handling).
• modules/ - Self-contained feature modules loaded by the container.
• shared/ - Logger and other utilities shared across all layers.
• types/ - Global ambient TypeScript declarations used project-wide.

Common pitfalls and fixes

• isolated-vm fails to build on CI - Install build-essential (Linux) or ensure Xcode CLT are present; add npm rebuild isolated-vm as a CI step after npm ci.
• EADDRINUSE on restart - The server swallows the first EADDRINUSE from the persistent server.on('error') listener but re-throws it during server.once('error') in the listen promise; always run shutdown() on process exit to release the port cleanly.
• Missing JWT_SECRET causes silent 500s - env.ts may not hard-fail on missing optional vars; set all JWT/auth env vars in .env before running or auth routes return unhandled rejections.
• Awilix cradle properties are undefined at startup - Services registered with asClass using SINGLETON scope are lazy by default; access them after init() completes, not inside buildContainer().
• snapshot.json not found - The bootstrap processors resolve paths relative to process.cwd(); run the server from the project root, not from src/.
• BullMQ + ioredis connection errors block startup - flowExecutionQueueService?.init?.() is called after the server is already listening; Redis being unavailable will log errors but not crash the process unless the queue is required for your flows. Set REDIS_URL correctly or disable queue-dependent modules.

Vibe-coding prompt template

I have dropped the Enfyra backend server source into `src/enfyra/` in my
Node.js TypeScript project. The upstream package is `user@example.com`.
The integration guide is in `USAGE.md` at the project root.

Please help me integrate it step by step:

1. Read `USAGE.md` and `src/enfyra/main.ts` to understand the startup sequence.
2. Create a `src/index.ts` that calls `buildContainer`, `init`, `buildExpressApp`,
   and starts an HTTP server on the port from `env.PORT`.
3. Add any missing dependencies to `package.json` based on the list in `USAGE.md`.
4. Wire the `tsconfig.json` paths alias so `@enfyra/*` resolves to `src/enfyra/*`.
5. Generate a `.env.example` covering every variable `src/enfyra/env.ts` reads.
6. Add a custom `/healthz` route on the Express app after `buildExpressApp`.
7. Ensure graceful shutdown on SIGTERM using `shutdown` from `src/enfyra/init.ts`.

Do not invent APIs. Only use exports visible in `src/enfyra/main.ts`,
`src/enfyra/container.ts`, `src/enfyra/init.ts`, `src/enfyra/express-app.ts`,
`src/enfyra/env.ts`, and `src/enfyra/shared/logger.ts`.

License and credit

See source/LICENSE if present for the full license text. This block is derived from user@example.com by the Enfyra contributors. Community support is available at the Enfyra Discord and GitHub Discussions.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.