Tenant, Workspace & Domain

Tenant

A tenant is the root isolation boundary in FlowOS. Every single database collection (table) is namespaced under a tenant ID. No data can ever cross tenant boundaries — queries, indexes, and API tokens are all scoped at the tenant level first.

In a SaaS deployment each customer organisation is one tenant. In a self-hosted enterprise deployment you typically have one tenant for the whole company, with multiple workspaces inside it.

Workspace

A workspace is a configuration and data silo within a tenant. Workspaces have their own users, roles, workflows, apps, ITSM records, and settings. Most enterprise customers create one workspace per business unit or environment tier (e.g. prod, staging).

Like tenantId, the workspaceId field is stamped on every record in every table, is required and readonly, and all queries are automatically filtered by it based on the API token context.

Domain

A domain is a logical grouping that controls which module owns a table and which workspaces it is seeded into. Domains do not add an extra column to records — they are a metadata classification used during installation.

The domains table itself describes a tree of named environments (e.g. global → it → prod) used in domain-separation and scoped-app deployments.

Domain Catalogue

Every system table belongs to exactly one domain:

Collection Naming

All MongoDB collections start with root_ — enforced at application boot bycollection-guard.ts, which intercepts every Mongoose write and throws if the collection name does not start with root_. Within that constraint, three naming patterns are used:

For example, the incidents table for tenant t_acme workspace ws_prod isroot_t_acme_ws_prod_incidents, and the counter table for the same workspace isroot_t_acme_ws_prod_sys_counters. Every table — including sys_* tables — follows the same pattern.

The 1,151 Tables

FlowOS ships 1,151 pre-defined table schemas across all domains. The bulk (935) belong to the ITSM domain and follow a repeating entity-family pattern. The rest are standalone platform, observability, auth, and integration tables.

Universal Base Schema

Every one of the 935 ITSM sub-tables shares an identical set of ~70 base fields. Only the status choices and a single entity-specific parent reference differ between them. This design means you can query, filter, sort, and relate any ITSM sub-table using the same field names.

Identity fields

Descriptive fields

Classification fields

Content / payload fields

Versioning & flag fields

Date / lifecycle fields

Metric & financial fields

Workspace context (on every record)

Status Variants

The status field choices are the only thing that meaningfully differs between most sub-tables. There are three patterns:

Cross-Table Relationships

Every ITSM sub-table carries a full set of foreign key reference fields that allow any sub-table record to be linked to any other platform entity. These references are optional — set only the ones relevant to the specific sub-table type. The full set present on every sub-table:

Self and sibling references

Core ITSM process references

Service & infrastructure references

Vendor & financial references

User references

Organisational references

ITSM Entity Families

The 935 ITSM tables are organised into seven entity families. The five core ITSM process families (incident, problem, change, request, catalog) each have two prefix variants: the itsm_<entity>_prefix (extended, ~107 sub-tables with all 70 base fields) and the shorter <entity>_ prefix (lighter standalone subset). The release_ and service_ families are standalone-only.

Incident family (152 tables)

Tracks every service disruption from detection through resolution. The root table is incidents. All itsm_incident_* sub-tables carry incidentParentId linking back to a parent record within the same sub-table, and incidentId linking to the root incidents table.

Problem family (150 tables)

Root cause investigations and known error tracking. Root table: problems. Sub-tables carry problemParentId and problemId. Incident → Problem relationship is recorded via incidentId on problem sub-tables andproblemId on incident sub-tables — bidirectional cross-references.

Change family (160 tables)

ITIL-aligned change requests with CAB workflow, approval chains, and implementation windows. Root table: the main change record referenced via changeRequestId. Change sub-tables reference incidents via incidentId (the changes that fix incidents) and problems via problemId (permanent fixes for known errors).

Request family (148 tables)

Service request fulfilment. Root table: requests / request_items.requestId and requestItemId are the foreign keys used on sub-tables. Requests reference catalogItemId for the service definition and workflowIdfor the fulfillment automation.

Catalog family (145 tables)

Service catalog definitions — what employees can request. Root entity: catalog items. Referenced by catalogItemId throughout the request family. Catalog sub-tables link to serviceId (service offering) and workflowId (fulfillment workflow).

Release family (45 tables)

Release management — planning, packaging, and deploying changes to production. Root entity: releases. Release sub-tables reference releaseId → releases and cross-link to changeRequestId(changes bundled into a release) and ciId (infrastructure items being released onto).

Service family (38 tables)

Service management — the service portfolio, offerings, blueprints, and operational health. These tables define what services exist and how they are operated, distinct from the catalog (which defines what can be requested). Referenced by serviceId and serviceSpecIdthroughout the ITSM entity families.

Sub-Table Type Catalogue

Each of the 107 sub-table suffixes represents a specific process concern. The same suffix exists across all five entity families (incident, problem, change, request, catalog) with identical base schema and purpose — only the entity parent reference differs.

Cross-Entity ITSM Tables

Beyond the five entity families, the ITSM domain includes standalone tables that operate across all entity types:

Platform Domain Tables (140)

These tables back every module and are always present regardless of which ITSM modules are installed.

Identity & access

Authentication

Workflows

Apps & UI

Audit & security

SLA / OLA

CMDB

Asset management

Availability & capacity

Vendor management

Financial & budgeting

Risk & compliance

Observability & alerting

On-call & escalation

Knowledge

Projects & programs

Deployment & release

Miscellaneous platform tables

Model Factory Pattern

Every Mongoose model in FlowOS is created at query time through one of two factory functions. There are no hardcoded collection names anywhere in the application — the factories build the correct root_-prefixed name and cache the model.

getWorkspaceModel — standard tables

import { getWorkspaceModel } from '../modules/feature-registry/model-factory.js'

// Collection produced: root_<tenantId>_<workspaceId>_incidents
const Incident = getWorkspaceModel<IIncident>(tenantId, workspaceId, 'incidents', incidentSchema)
const doc = await Incident.findOne({ _id: id, tenantId, workspaceId })

Use getWorkspaceModel for all new tables and custom tables. It:

• •Builds collection name root_<tenantId>_<workspaceId>_<tableName>.
• •Calls enforceTenantWorkspaceEnvelope — auto-adds tenantId and workspaceId fields + compound index if not in the schema.
• •Caches the Mongoose model by collection name — safe to call on every request.

getCoreModel — tenant-scoped legacy tables

import { getCoreModel } from '../modules/feature-registry/model-factory.js'

// Non-strict mode: root_<tenantId>_users
// Strict mode:     root_<tenantId>_<workspaceId>_users
const User = getCoreModel<IUser>(tenantId, 'users', userSchema, { workspaceId })

Use getCoreModel only for a handful of early tables (users, roles, tenants) that pre-date workspace isolation. All new tables use getWorkspaceModel.

The collection guard

src/config/collection-guard.ts is installed at boot and wraps every Mongoose write method. It throws immediately if a collection name does not start withroot_. This prevents any accidental write to a bare collection name.

// This would throw at runtime — never do this
const BareModel = mongoose.model('Incident', schema, 'incidents')
await BareModel.create({ ... }) // ← Blocked: "Blocked non-compliant MongoDB collection 'incidents'"

// Correct
const Incident = getWorkspaceModel(tenantId, workspaceId, 'incidents', schema)
await Incident.create({ tenantId, workspaceId, ... }) // ← OK: 'root_t_acme_ws_prod_incidents'