Project Layout

DieselEngine uses a virtual filesystem backed by PostgreSQL. Scripts, assets, and folders all live in this tree. While you can organize files however you like, the following convention keeps projects maintainable as they grow.

Recommended Structure

/classes/         Utility classes (Java interop wrappers, pagination, etc.)
/services/        Business logic — one class per domain, static methods
/tools/           Higher-level orchestration (API controllers, AI clients)
/types/           JSDoc typedef files (no runtime logic)
/ingresses/       HTTP handler scripts, organized by route domain
  /api/           Public API endpoints
  /backend/       Admin endpoints (nested by entity)
  /website_api/   Customer-facing endpoints
  /ws/            WebSocket handler scripts
/cronjobs/        Scheduled task scripts
/startup/         Initialization scripts (connect MinIO, start services)

Convention Details

/services/

One file per domain entity. Each file exports a class with static methods that encapsulate all database access and business logic:

// /services/ItemService.js
export class ItemService {
  static getItemById(id) { /* ... */ }
  static createItem(data) { /* ... */ }
  static updateItem(id, data) { /* ... */ }
  static deleteItem(id) { /* ... */ }
  static findItems(searchTerm, page, pageSize) { /* ... */ }
}

/ingresses/

HTTP handler scripts. Each file exports a handleRequest function and typically delegates to a service class. Keep handlers thin — validation, parameter extraction, and response formatting only:

// /ingresses/api/get-item.js
import { ItemService } from '../../services/ItemService.js';

export function handleRequest(context) {
  const id = context.getParameter("id");
  const item = ItemService.getItemById(parseInt(id));

  if (!item) {
    return Results.notFound().renderRaw(JSON.stringify({ error: "Not found" }));
  }

  return Results.json().renderRaw(JSON.stringify(item));
}

/classes/

Reusable utility classes like pagination helpers, formatters, or Java interop wrappers:

// /classes/Paginator.js
export class Paginator {
  static paginate(query, page, pageSize) {
    const offset = (page - 1) * pageSize;
    return { limit: pageSize, offset };
  }
}

/types/

JSDoc typedef files for documentation and editor support. These contain no runtime logic — only @typedef declarations:

// /types/Item.js
/**
 * @typedef {Object} Item
 * @property {number} id
 * @property {string} name
 * @property {number} price
 * @property {string} created_at
 */

/startup/

Short scripts that run once when DieselEngine starts. Typically used for connecting to external services:

// /startup/connect_minio.js
const minio = diesel.getMinIOService();
minio.connect("http://minio:9000", "minioadmin", "minioadmin");

/cronjobs/

Scripts executed on a schedule. They run their top-level code directly (no handleRequest):

// /cronjobs/cleanup.js
import { CleanupService } from '../services/CleanupService.js';

const deleted = CleanupService.purgeOldRecords(30);
console.log(`Purged ${deleted} records older than 30 days`);

File Types

Type	Extension	Purpose
JAVASCRIPT	.js	Executable scripts (ES modules)
PLAIN_TEXT	any	Configuration, templates, data files

TIP

All JavaScript files are treated as ES modules. You can use import/export syntax throughout.