Backend application platform
The backend application platform is the server side of Twenty. It gives browser clients, external clients, installed applications, background jobs, and maintenance commands one workspace-scoped system for data, access, metadata, usage, and events.
Server composition
The server is one Nest application made from shared engine services, product modules, API transports, and process controls. A workspace is a customer environment with its own records, members, model, applications, and access rules. The composition is defined by packages/…/app.module.ts.
Application composition
AppModule joins database access, the core engine, product modules, GraphQL APIs, REST, MCP, browser delivery, sessions, and shared request controls. A transport builds caller context first. Engine or product services then perform the business action in that context.
| Boundary | Main purpose |
|---|---|
| Core GraphQL | Workspace record operations. |
| Metadata GraphQL | Workspace model and configuration operations. |
| Admin GraphQL | Instance administration. |
| REST | HTTP resources and record routes. |
| MCP | Workspace-scoped tools for agents and external tool clients. |
| Frontend delivery | Browser documents served by the HTTP process. |
Request controls cover identity, workspace scope, API use, session safety, suspended workspaces, access, and request logging. The server admin workspace can also require a signed identity assertion from a configured issuer and audience before it accepts a request.
References: packages/…/app.module.ts• L49-145 packages/…/server-admin-identity-assertion.service.ts• L41-108
Process entrypoints
The platform uses separate runtime roles for request work, long work, and short maintenance work. Each role reuses shared engine rules but has a different lifetime and output.
| Process | Responsibility |
|---|---|
| HTTP process | Serve APIs and browser documents. |
| Worker process | Run queued jobs and recurring work. |
| Command process | Run administration, upgrade, and cleanup tasks. |
The HTTP process prepares sessions, request limits, uploads, cross-origin rules, proxy handling, and graceful shutdown before it listens. The worker starts an application context without an HTTP listener. The command process runs a task and closes after it drains work that must finish before exit.
The diagram shows the three process roles and their shared platform boundary.
flowchart TD
HTTP[HTTP process] --> APP[AppModule]
WORKER[Worker process] --> WORKER_APP[Queue worker application]
COMMAND[Command process] --> COMMAND_APP[Command application]
APP --> TRANSPORTS[GraphQL, REST, MCP, frontend]
APP --> ENGINE[Shared engine services]
WORKER_APP --> ENGINE
WORKER_APP --> JOBS[Background jobs]
COMMAND_APP --> ENGINE
COMMAND_APP --> TASKS[Maintenance tasks]
Shutdown drains requests and active jobs. It also flushes platform records that must not be lost when a process closes.
References: packages/…/main.ts• L34-143 packages/…/queue-worker.module.ts• L11-29 packages/…/queue-worker.ts• L10-36 packages/…/command.ts• L10-40
Workspace request context
Workspace request context is the identity envelope for server work. It links a caller to a user or other principal, a workspace, an acting member, permissions, an application when one exists, and usage checks.
Record APIs resolve the workspace model and effective field access before they read or change records. Workers rebuild the same scope from job data when they run later work. This keeps APIs, tools, applications, and jobs inside one data boundary.
References: packages/…/common-api-context-builder.service.ts• L40-128 packages/…/workspace-data-source.service.ts• L30-71 packages/…/principal-permissions-read.service.ts• L28-109 packages/…/application-job.service.ts• L43-141
Engine services
The engine owns rules that must stay the same across product areas and transports. It provides shared boundaries for workspace data, metadata, access, applications, tools, automation, files, outbound requests, usage, queues, billing, and lifecycle state.
Workspace data and metadata
Workspace data services provide record operations inside the current workspace. Workspace metadata is the configurable model for objects, fields, views, roles, permissions, page layouts, tools, workflows, applications, and related settings.
The API resolves metadata and field access before it builds a record operation. The workspace data boundary then combines that model with permissions, validation, billing state, record limits, events, and the right database pool. All callers therefore use one workspace model rather than a separate model per transport.
See API, metadata, and workspace runtime for API contracts, metadata resolution, guards, caches, and data sources.
References: packages/…/common-api-context-builder.service.ts• L40-128 packages/…/workspace-data-source.service.ts• L30-71 packages/…/core-engine.module.ts• L89-183
Access and permission services
Access services decide which caller can read, change, share, or manage workspace resources. They resolve roles and targets from workspace state, then apply those principals to object, field, and record checks.
Record access groups support fast record checks for workspaces that use them. The platform rebuilds group state when roles or model rules change. The same policy limits application reach and tool grants, so automation cannot pass records or fields outside its intended scope.
References: packages/…/principal-permissions-read.service.ts• L28-109 packages/…/tool-executor.service.ts• L66-127 packages/…/core-engine.module.ts• L89-183
Application lifecycle services
Application services connect an application registration to an installation in a workspace. A registration identifies an application and its versions. An installation applies one version and owns the content, model changes, files, connections, logic, front components, settings, and runtime resources declared by that version.
The manifest is the checked declaration of those resources. Install, upgrade, development sync, export, and uninstall use shared lifecycle rules. The platform validates content and permissions, applies workspace changes, updates application access, stores front-end sources and public assets, and records durable progress and results. A workspace-and-application lock prevents concurrent changes from corrupting the model.
Application OAuth supports clients that describe themselves at a client ID metadata URL. Connection providers also support discovered OAuth clients and API-key flows for installed applications. The platform keeps these flows inside the application and workspace access boundary.
References: packages/…/application-manifest.module.ts• L31-71 packages/…/application-sync.service.ts• L67-153 packages/…/connection-provider.module.ts• L39-90
Application manifest scope
An application manifest can describe workspace objects and fields as well as tools, logic, workflows, roles, permissions, agents, views, page layouts, connections, and browser components. The platform turns that declaration into one set of workspace metadata before it applies the change.
Application content presents the application-owned part of that metadata as a compact product view. It excludes deleted, system-only, and user-personal items, then adds labels and counts that connect objects to fields, views, layouts, and permissions. Workspace-visible workflows and non-private agents remain available to the application view without exposing personal workspace state.
Database event triggers use a lookup that puts the application's own entities before workspace entities. This lets an application refer to its own model while still listening to records in the wider workspace. The same resolved settings are used for logic functions and agent triggers.
References: packages/…/build-application-content-from-flat-entity-maps.util.ts• L78-132 packages/…/build-application-content-from-flat-entity-maps.util.ts• L212-413 packages/…/compute-application-manifest-all-universal-flat-entity-maps.service.ts• L69-84 packages/…/compute-application-manifest-all-universal-flat-entity-maps.service.ts• L235-271 packages/…/database-event-trigger-manifest-lookup.type.ts• L16-27
Tools and automation
Tools expose controlled actions to agents, workflows, applications, and other callers. The platform resolves caller scope before it dispatches record work, static tools, logic functions, or MCP server tools.
Workflow execution rebuilds the workspace and application context from the workflow run. It checks that the run still has a role and that a step target belongs to an application the run can reach. A tool call then resolves its target and input, runs it in the user or application context, and returns a result or a controlled error.
References: packages/…/tool-executor.service.ts• L66-127 packages/…/workflow-execution-context.service.ts• L42-168 packages/…/core-engine.module.ts• L127-130
Queue services
Queue services carry work from a request or event to a worker. Producers add jobs or recurring jobs with workspace or application scope. The worker runs the registered handler and publishes job state, progress, metrics, and errors to clients and operators.
The queue also protects shared capacity. It can remove duplicate work, retry failed work, pace a busy scope, share priority fairly between scopes, and refuse jobs when a workspace or application memory share is full. Completed or removed work releases its charge. Reconciliation releases charges left by jobs that no longer exist.
The following flow shows how a scoped request becomes later work.
sequenceDiagram
participant Client
participant API as API transport
participant Context as Workspace context
participant Domain as Engine or product service
participant Store as Workspace data
participant Events as Workspace events
participant Queue
participant Worker
Client->>API: Send request
API->>Context: Load caller and workspace scope
Context->>Domain: Call operation
Domain->>Store: Read or change data
Store-->>Events: Publish scoped change
Domain-->>API: Return response
Events->>Queue: Add later work when needed
Queue->>Worker: Deliver scoped job
Worker->>Domain: Run background operation
Worker->>Store: Persist result or publish event
Application jobs use this same boundary. Before enqueue, the platform checks that the logic function belongs to the active application, then carries workspace, application, and optional user scope into the job.
See Data persistence and event processing for persistence events, subscriptions, workflow triggers, and cleanup processing.
References: packages/…/message-queue.service.ts• L27-129 packages/…/bullmq.driver.ts• L262-531 packages/…/application-job.service.ts• L74-167 packages/…/queue-worker.module.ts• L11-29
Deferred workspace operations
Deferred workspace operations let metadata changes finish work after the main change commits. They store the workspace, application, operation name, payload, and order before dispatching a scoped job.
The worker claims pending operations in order, loads the metadata needed by their handlers, runs each operation with a bounded database connection, and records success or failure. Retries, recovery work, and an administrative retry command allow failed operations to return to pending state without repeating completed operations.
References: packages/…/deferred-workspace-operation-runner.service.ts• L55-176 packages/…/deferred-workspace-operation-runner.service.ts• L242-367 packages/…/jobs.module.ts• L123-153
Product-module boundaries
Product modules group business behavior by user-facing capability. They use engine services for workspace state, access, persistence, metadata, events, queues, usage, and billing. They do not own server startup or transport-wide rules.
Product capabilities
The top-level product boundary is packages/…/modules.module.ts. It assembles capabilities for messaging, calendars, connected accounts, email campaigns, call recordings, dashboards, onboarding suggestions, workflows, members, and related hooks and webhooks.
Each product area gives a user-facing capability its meaning. Shared engine services keep rules the same across product areas. A larger area may also own jobs, scheduled work, tools, storage, billing, usage, and metrics while still using the shared engine.
| Product area | Responsibility |
|---|---|
| Messaging | Import, send, and organize workspace messages. |
| Calendar | Import and manage events and participants. |
| Connected accounts | Track external account state and synchronization. |
| Emailing | Manage campaigns, delivery state, suppression, and results. |
| Call recording | Process recordings and connect them to workspace activity. |
| Dashboards | Provide dashboard data and chart queries. |
| Workflow | Build and run definitions, triggers, waits, and actions. |
| Workspace members | Manage member actions and cleanup. |
Workflow shows the boundary clearly. The engine supplies shared workflow state, access, tools, and run services. The product area supplies workflow building, triggers, actions, waits, and execution behavior.
References: packages/…/modules.module.ts• L27-54 packages/…/emailing.module.ts• L70-155 packages/…/core-engine.module.ts• L127-130
Background job boundary
The worker job boundary is broader than any one product module because a job runs without an HTTP request. It assembles platform and product jobs for application lifecycle, exports, billing, email, cleanup, event logs, subscriptions, AI, automation, SDK generation, workspace operations, and recurring work.
This boundary is a contract between the producer, the processor, and the worker. A job must carry enough workspace or application scope to rebuild its context later. The worker then reports its state and outcome without making the caller wait for long work.
References: packages/…/jobs.module.ts• L78-153 packages/…/queue-worker.module.ts• L11-29 packages/…/message-queue.service.ts• L38-129
Related backend guides
This page gives the platform view. Use the child pages for flows that cross several engine services:
- API, metadata, and workspace runtime explains transport contracts, metadata resolution, guards, caches, and data sources.
- Data persistence and event processing explains persistence, database events, worker queues, subscriptions, workflow triggers, and cleanup processing.
Change checklist
When these files or sections are changed, remember to consider these:
- Keep transport middleware and worker context aligned so every entrypoint resolves the same workspace and caller boundary.
- Keep application manifest fields aligned with metadata sync, front-end source and asset handling, application permissions, trigger lookup, and SDK generation.
- Keep application content filters and relationship counts aligned with manifest ownership and visibility rules when new application metadata is added.
- Keep application job ownership checks aligned with job payload scope, queue registration, and worker context rebuild.
- Keep queue names, job payload scope, fairness and memory limits, job registration, and worker drain behavior aligned.
- Invalidate or rebuild workspace metadata and permission state when model, role, or application rules change.
- Keep server admin identity assertion settings aligned as one complete trust contract. Partial configuration must not open the server admin workspace.
- Keep shutdown ordering aligned with request draining, queue draining, usage recording, and event recording.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A queued job lacks workspace or application scope. | The worker cannot rebuild the caller boundary and the job fails or risks the wrong scope. | Carry scope in the job data and rebuild context in the worker. |
| An application enqueues a logic function owned by another application. | The job can run code outside the application's declared boundary or fails at enqueue. | Resolve the active application and verify logic-function ownership before enqueue. |
| Two application lifecycle changes run for one workspace at the same time. | Model changes or application resources can become inconsistent. | Use the workspace-and-application lifecycle lock. |
| Application trigger lookup ignores the application's own entities. | A logic or agent trigger can resolve the wrong object or field. | Give application entity maps priority over workspace maps. |
| Application content includes personal, deleted, or system-only metadata. | An application view can show state outside its intended product boundary. | Filter content by ownership and visibility before building the application view. |
| Server admin identity assertion settings are incomplete. | Requests to the server admin workspace are refused instead of falling back to an open path. | Require the header, signing-key URL, issuer, and audience as one complete configuration. |
| Queue memory charges are not released after job removal or completion. | A workspace or application can be blocked from adding valid later work. | Release charges on terminal job states and reconcile stale charges. |
| The HTTP process closes modules before it drains requests and recorders. | Requests or usage and event records can be lost. | Drain the HTTP server, flush recorders, then close the application. |
| Metadata or permission state stays stale after a model or role change. | Record operations can use old fields or access rules. | Recompute the workspace maps and permission principals before the operation. |
Key files
| File | Why to read it |
|---|---|
| packages/…/app.module.ts | Shows how transports, engine services, product modules, and request controls form the HTTP application. |
| packages/…/main.ts | Shows the HTTP process lifecycle and shutdown order. |
| packages/…/queue-worker.module.ts | Shows the worker boundary and job drain contract. |
| packages/…/command.ts | Shows the short-lived command entrypoint and final queue drain. |
| packages/…/core-engine.module.ts | Shows the shared engine boundary. |
| packages/…/common-api-context-builder.service.ts | Shows how an API request becomes workspace metadata and permission context. |
| packages/…/workspace-data-source.service.ts | Shows the workspace data boundary used for record work. |
| packages/…/application-sync.service.ts | Shows the shared application manifest sync and uninstall boundary. |
| packages/…/build-application-content-from-flat-entity-maps.util.ts | Shows how application-owned metadata becomes a filtered content view with related counts and labels. |
| packages/…/application-job.service.ts | Shows application-owned background job validation and scope. |
| packages/…/server-admin-identity-assertion.service.ts | Shows the extra trust boundary for the server admin workspace. |
| packages/…/bullmq.driver.ts | Shows queue execution, fairness, memory limits, job state, and worker drain behavior. |
| packages/…/jobs.module.ts | Shows the cross-product background job boundary. |
| packages/…/modules.module.ts | Shows the product-module boundary. |