System

The System module is the operational backbone of the platform. It provides tenant resolution, file management, background job execution, multi-tenant database provisioning, settings management, record history, PDF generation, and the shared event bus used by other modules.

What it covers

Authentication

All System endpoints require a valid session. Database provisioning and job management endpoints require system:admin permission.

Core services

Tenant Resolution

Resolves the active tenant account from the incoming request. Used internally by every authenticated request; also exposed for external tooling.

GET /api/system/tenant-resolution/resolve
# Headers: X-Account-Key: acme-corp (or resolved from subdomain)

# Response:
{ "accountKey": "acme-corp", "databaseName": "origin_acme_corp" }

Settings

Per-account key/value configuration. Used by AI (LLM API keys), Communications (SMTP config), and others:

GET  /api/system/settings                          # list all settings for account
GET  /api/system/settings?filter[key]=openai.key   # get specific setting
POST /api/system/settings
{
  "key": "openai.key",
  "value": "sk-...",
  "isSecret": true
}
PUT  /api/system/settings/{id}

Secret settings have their value masked in list responses.

Job Management

Background jobs are registered via JobManagementService and executed asynchronously:

GET  /api/system/jobs                              # list job definitions
POST /api/system/jobs                              # register a new job type
GET  /api/system/job-histories                     # list execution records
GET  /api/system/job-histories?filter[status]=failed  # filter by status

# Job types
GET  /api/system/job-types

Multi-Tenant Database

Provision a new tenant database or run migrations:

POST /api/system/multi-tenant-database/provision
{
  "accountKey": "new-client",
  "plan": "enterprise"
}

POST /api/system/multi-tenant-database/migrate
{
  "accountKey": "new-client"
}

Record History

Immutable audit trail — every create, update, and delete on any model is logged:

GET /api/system/record-history
  ?filter[modelKey]=opportunities
  &filter[recordId]=<opp_id>
  &sort=-timestamp

Each history entry includes operation, before, after, changedBy, and timestamp.

PDF Preview

Generate a PDF rendering of a record or document template. Routes are registered in setup() directly on the Express app:

POST /api/system/pdf/preview
{
  "templateId": "<template_id>",
  "recordId": "<record_id>",
  "modelKey": "financeInvoices"
}
# Returns: PDF binary (Content-Type: application/pdf)

Data models

The event bus

eventsService is a singleton exported from this module and consumed by the Workflow, Notifications, and Scheduled Events services:

import { eventsService } from '@thefuturebegins/enterprise-module-system';

// Publish an event
eventsService.publish('contact.created', { contactId: '...' });

// Subscribe to events
eventsService.on('contact.created', async (payload) => {
  await notificationsService.send({ ... });
});

This is an in-process pub/sub bus — not a message queue. For durable event processing across restarts, use Scheduled Events (Workflow module).

Common patterns

Auditing changes to a record

GET /api/system/record-history
  ?filter[recordId]=<contact_id>
  &filter[modelKey]=contacts
  &sort=-timestamp
  &limit=20

Reading a secret setting

GET /api/system/settings?filter[key]=stripe.secret_key
# value is masked unless you have system:admin permission

API sections

These sections are available in the System API Reference:

• Imports Activity
• Job Histories
• Job Types
• Jobs
• Multi Tenant Database
• Role Workspace Selections
• Settings
• Tenant Resolution
• User Role Selections