Designing a KrakenJS Micro‑Service: Dependency Injection, Lazy Loading, and Trust Boundaries

Problem Statement

When building a micro‑service in Node.js, developers often struggle to keep startup fast, avoid global state, and enforce clear trust boundaries between components. KrakenJS’s module system promises isolated containers, dependency injection, and lazy loading, but the design space can still be confusing. This article provides a concrete architecture note that shows how to satisfy these requirements with the minimal viable design, outlines operational checks, and highlights failure modes that may require a redesign.

Requirements

• Fast startup – non‑critical services should not block the main thread.
• Clear isolation – modules must expose only a public API and cannot leak state to the global scope.
• Stateless request handling – controllers should be instantiated per request to avoid cross‑request contamination.
• Config‑driven behaviour – environment‑specific overrides should be mergeable without code changes.
• Observability – lifecycle hooks and built‑in metrics are required for health checks.
• Extensibility – cross‑cutting concerns (logging, auth) should be added via plugins, not by editing core modules.

Smallest Suitable Design

The core of the service is a single KrakenJS application that declares three modules:

1. db – a singleton module that provides a connection pool.
2. auth – a lazy module that depends on db and implements login logic.
3. router – the entry point that maps URLs to controller actions.

By keeping the module graph shallow, we reduce the risk of circular dependencies and keep the startup footprint minimal.

Module Definition Example

The following is a minimal auth module definition. It is declared as lazy: true so that it is only loaded when a request hits the /login route.

// modules/auth/module.js
module.exports = {
  name: 'auth',
  lazy: true,
  requires: ['db'],
  onStart: async ({ db }) => {
    // Verify the connection pool is healthy before handling requests
    await db.pool.query('SELECT 1');
  },
  api: {
    login: async ({ db }, { username, password }) => {
      const user = await db.pool.query('SELECT * FROM users WHERE username=$1', [username]);
      if (!user) throw new Error('User not found');
      // Password verification omitted for brevity
      return { token: 'fake-jwt' };
    }
  }
};

Notice the constructor‑style injection of db via the requires array. The onStart hook guarantees that the database connection is ready before any controller action runs.

Routing Configuration

The router module maps the /login endpoint to the auth.login controller. Because auth is lazy, this route is the trigger that loads the module.

// modules/router/module.js
module.exports = {
  name: 'router',
  requires: ['auth'],
  routes: {
    '/login': {
      method: 'POST',
      controller: 'auth.login'
    }
  }
};

Controllers are instantiated per request, ensuring statelessness. If a controller needs request‑specific data, it receives it as a second argument.

Trust and Data Boundaries

• Module Isolation – each module runs in its own sandbox. The only shared surface is the public API defined in the api object.
• Configuration Scope – modules load config.js from their own directory. Overrides in config.env.js are merged at runtime, preventing accidental leakage of secrets.
• Service Registry – KrakenJS automatically wires declared services into modules. Because services are injected by constructor, no global service locator is exposed.

Operational Checks

To validate that the architecture works as intended, run the following checks:

• Dependency Graph Validation – krakenjs list-modules prints a dependency graph. Verify no cycles exist.
• Lazy Load Verification – start the app with KRAKEN_ENV=dev node app.js and monitor console logs. Non‑lazy modules should log at startup; lazy modules should log only after the first request.
• Metrics Endpoint – enable the built‑in metrics plugin. Query /metrics to see counters for module_start and module_stop.
• Unit Tests – run krakenjs test to assert that auth does not load until a /login request is made.

Failure Modes & Redesign Triggers

1. Circular Dependencies – if auth accidentally requires a module that in turn requires auth, startup will fail. Use krakenjs list-modules to detect cycles early.
2. Heavy I/O on First Request – a lazy module that performs a large database migration on onStart will delay the first request. Consider pre‑warming by invoking krakenjs warm at deployment.
3. Unawaited Async Init – forgetting await in onStart can leave the module in an incomplete state. Add unit tests that assert readiness before handling a request.
4. Plugin Conflicts – multiple authentication plugins that modify the same middleware chain may produce unpredictable order. Document plugin registration order and use the krakenjs plugins CLI to inspect the chain.
5. Memory Leaks – services that retain request context can grow memory usage. Ensure services are stateless or use request‑scoped instances.
6. Config Mismatches – inconsistent schema between dev and prod can cause routing failures. Validate config files against a JSON schema during build.

When to Redesign

• If traffic grows to the point where the latency of first‑time lazy loads is unacceptable, pre‑warm critical modules during deployment or convert them to eager modules.
• When services need to maintain state (e.g., a caching layer), move them out of the module system or introduce a dedicated stateful service registry.
• When cross‑cutting concerns become too complex for plugins, consider refactoring them into separate modules that can be swapped per environment.

Conclusion

By keeping the module graph minimal, enforcing constructor‑based injection, and leveraging lazy loading judiciously, a KrakenJS micro‑service can achieve fast startup, clear trust boundaries, and robust observability. Operational checks such as dependency graph validation and metrics monitoring guard against common failure modes. When the system’s needs evolve—higher traffic, more stateful services, or complex cross‑cutting concerns—review the module boundaries and consider pre‑warming or architectural refactors to maintain performance and maintainability.