Structuring Kraken.js Applications: Convention-Based vs. Explicit Routing

The Routing Dilemma in Kraken.js

When building with Kraken.js, the primary architectural decision is whether to rely on the framework's convention-over-configuration routing or to implement explicit route overrides. Relying on conventions speeds up initial development but can lead to unpredictable URL structures as the application grows. The goal is to balance rapid prototyping with a maintainable API surface.

Comparing Routing Strategies

Kraken.js automatically maps the controllers/ directory to URL endpoints. However, for complex applications, you may need more granular control over HTTP methods and path parameters.

Feature	Convention-Based Routing	Explicit Route Overrides
Configuration	Zero config; based on file names.	Manual definition in controllers.
Development Speed	High (instant endpoint creation).	Medium (requires manual mapping).
URL Flexibility	Low (tied to folder structure).	High (custom paths and regex).
Maintainability	Difficult for large-scale APIs.	Easier to audit and document.

Trade-offs and Constraints

Convention-based routing is ideal for internal tools or simple CRUD applications where the resource name matches the URL (e.g., controllers/users.js becomes /users). The constraint is that any change to the file system directly alters the public API, which can break client-side integrations if not managed carefully.

Explicit routing allows you to decouple the physical file structure from the URI. This is necessary when implementing RESTful patterns that require specific HTTP verbs (PUT, DELETE) or complex parameterization that the default directory scanner cannot infer.

Implementation: Implementing a Decoupled Controller

To implement a robust routing strategy, separate your business logic into Services and your request handling into Controllers. This ensures that if you change your routing strategy, your core logic remains untouched.

Step 1: Create a Service
Define the business logic in services/user-service.js. This file should not contain any Express-specific req or res objects.

// services/user-service.js
module.exports = {
  getUserById: function(id) {
    // Logic to fetch user from database
    return { id: id, name: 'Technical User' };
  }
};

Step 2: Create the Controller
In controllers/users.js, use the service. To move beyond simple convention, you can define specific actions that Kraken.js will map to endpoints.

// controllers/users.js
const userService = require('../services/user-service');

module.exports = {
  // Convention: maps to /users
  index: function (req, res) {
    res.render('users/index', { title: 'User List' });
  },
  // Convention: maps to /users/profile/:id
  profile: function (req, res) {
    const user = userService.getUserById(req.params.id);
    res.render('users/profile', { user: user });
  }
};

Validation and Verification

To verify the routing is functioning as expected, run the application using the Kraken CLI and check the endpoint reachability.

• Command: Run npm start from the project root.
• Permissions: Ensure the user has read/write access to the config/ and controllers/ directories.
• Check: Navigate to http://localhost:3000/users/profile/123.
• Expected Result: The server should render the users/profile template with the ID 123 passed to the service.

Limitations

Kraken.js is a legacy framework. Its routing mechanism is tightly coupled to the Node.js version it was designed for. If you encounter TypeError issues during route registration, verify that your Node.js version matches the requirements of the specific Kraken.js version installed. Because it relies on directory scanning, adding a temporary file or a backup file (e.g., users.js.bak) inside the controllers/ folder may inadvertently create a new, unwanted route.

Rollback Procedure

If a routing change causes 404 errors or unexpected behavior, revert the file structure or controller exports to the previous state. Since Kraken.js generates routes dynamically at startup, a simple restart of the Node process is required to apply changes or roll back to a previous directory configuration.