انتقل إلى المحتوى الرئيسي

SIM Integration Plugin

The SIM (Sim Studio) integration plugin brings AI-native workflow orchestration to Ever Gauzy, enabling tenants to design, trigger, and monitor AI agent workflows directly from the platform.

Overview​

PropertyValue
Package@gauzy/plugin-integration-sim
Sourcepackages/plugins/integration-sim
SDKsimstudio-ts-sdk
LicenseAGPL-3.0
Version0.1.0

1. Introduction​

This document describes the architecture and workflow design for integrating SIM (Sim Studio) — an open-source visual workflow builder for AI agent workflows — into the Ever Gauzy multi-tenant SaaS platform. It covers concepts, design decisions, data flows, and schema diagrams to provide a clear mental model of how the integration works.

2. What Is SIM and Why Integrate It?​

2.1 What SIM Provides​

SIM (Sim Studio) is an open-source platform that allows users to design, build, and deploy AI agent workflows through a visual drag-and-drop canvas. It connects AI models (OpenAI, Anthropic, Google Gemini, and others), databases, APIs, and business tools into orchestrated pipelines. Workflows can be triggered through chat interfaces, REST APIs, webhooks, scheduled cron jobs, or external events.

SIM offers over 80 native integrations, real-time collaboration, and can be deployed either as a managed cloud service or self-hosted via Docker and Kubernetes.

2.2 Why Gauzy Needs SIM​

Gauzy already integrates with automation platforms — Zapier, Make, and Activepieces — which are designed for general-purpose workflow automation. SIM fills a different niche: AI-native orchestration. Where Zapier connects apps through triggers and actions, SIM connects AI agents through intelligent pipelines that can reason, branch, loop, and process unstructured data.

By integrating SIM, Gauzy tenants gain the ability to:

  • Build AI-powered automation workflows that interact with their Gauzy data
  • Execute complex multi-step AI pipelines programmatically from within Gauzy
  • Trigger AI workflows from internal Gauzy events such as timer starts, task completions, or employee onboarding
  • Monitor workflow execution history and results directly from the Gauzy dashboard

2.3 How SIM Differs from Existing Integrations​

AspectZapier / Make / ActivepiecesSIM
Primary purposeApp-to-app automationAI agent orchestration
Workflow buildingTrigger-action chainsVisual block canvas with AI agents, logic, and tools
AI capabilitiesLimited (single AI step)Native (multi-agent, reasoning, branching)
AuthenticationOAuth2 flowAPI key
Execution modelEvent-driven webhooksSDK-driven programmatic execution
Self-hostingVariesFully supported (Docker / Kubernetes)

3. Integration Approach​

3.1 Plugin-Based Architecture​

The SIM integration is implemented as a Gauzy plugin, following the same architectural pattern used by the Zapier, Make, and Activepieces integrations. This means it lives as a self-contained package within the plugins directory and registers itself with the Gauzy core through the standard plugin lifecycle.

This approach was chosen for the following reasons:

  • Consistency: Every automation integration in Gauzy is a plugin. SIM is no exception.
  • Modularity: The plugin can be enabled or disabled per deployment without affecting the core platform.
  • Reuse: The plugin leverages all existing core integration infrastructure — tenant management, settings storage, permission guards, event buses — rather than reinventing them.
  • Isolation: Plugin code is decoupled from Gauzy core, making it independently testable and maintainable.

3.2 Why Not a Microservice or MCP Extension?​

A microservice approach was considered but rejected because SIM integration is fundamentally a client-side operation — Gauzy calls SIM's API. There is no need for a separate runtime process. The SDK handles all communication.

An MCP-only extension was also considered. While SIM workflows will be selectively exposed via MCP (see Section 9), the MCP server is designed for AI assistants to call Gauzy tools, not for Gauzy to orchestrate external platforms. The plugin approach is the correct layer for this integration.

3.3 Architecture Diagram​

4. How the Plugin Fits into Gauzy​

4.1 Plugin Lifecycle​

When Gauzy starts, the SIM plugin goes through the standard plugin lifecycle:

  1. Registration: The plugin declares its module, entities, and configuration callback
  2. Bootstrap: The plugin validates that essential configuration is present (environment variables for default SIM URL) and logs its readiness
  3. Runtime: The module's controllers, services, and event handlers become active and respond to requests
  4. Destroy: On shutdown, the plugin cleans up any resources (cached clients, etc.)
@Plugin({
  imports: [SimModule],
  entities: [SimWorkflowExecution],
  configuration: (config: ApplicationPluginConfig) => {
    return config;
  },
})
export class IntegrationSimPlugin
  implements IOnPluginBootstrap, IOnPluginDestroy
{
  onPluginBootstrap(): void {
    console.log("IntegrationSimPlugin is being bootstrapped...");
  }

  onPluginDestroy(): void {
    console.log("IntegrationSimPlugin is being destroyed...");
  }
}

4.2 Core Module Dependencies​

The SIM plugin does not operate in isolation. It imports and depends on several core Gauzy modules:

  • Integration Tenant Module: Manages the per-tenant integration record that links a tenant to their SIM configuration
  • Integration Setting Module: Stores and retrieves per-tenant settings like API keys, base URLs, and event-to-workflow mappings
  • Integration Module: Manages the base "SIM" integration entry in the integration catalog
  • Role Permission Module: Provides guards for permission-based access control
  • CQRS Module: Enables the command bus (for creating/updating integration records) and event bus (for listening to internal Gauzy events)
  • HTTP Module: Provides HTTP client capabilities (used internally by the SIM SDK)
  • Config Module: Access to environment-level configuration

4.3 Contracts Extension​

The shared contracts package includes an entry in the integration enumeration to identify SIM as a recognized integration provider. This is a single-line addition to the existing enum that already contains entries for Zapier, Make, Activepieces, GitHub, Jira, and others.

4.4 Component Responsibility Map​

ComponentResponsibility
IntegrationSimPluginEntry point; registers the module and entity with the Gauzy plugin system
SimModuleNestJS module wiring controllers, services, and repositories
SimControllerHandles incoming REST requests (setup, execution, history, status)
SimServiceCore business logic: credential management, workflow execution, event triggers, execution history
SimClientFactoryPer-tenant SDK client instantiation with caching and concurrency control
SimRepositoryServiceData access layer for the SimWorkflowExecution entity
SimWorkflowExecutionDatabase entity storing execution logs per tenant

5. Authentication and Credential Management​

5.1 How SIM Authentication Works​

Unlike Zapier and Make which use OAuth2 with authorization codes, redirect URIs, and token refresh cycles, SIM uses a straightforward API key authentication model. Each SIM user or organization generates an API key from their SIM dashboard, and this key is included with every API request.

This simplifies the integration significantly — there is no OAuth flow to implement, no authorization controller needed, no token refresh logic, and no state parameter management. The tenant simply provides their API key, and the plugin stores it.

5.2 Credential Storage​

Credentials are stored using Gauzy's existing IntegrationSetting mechanism, which is a key-value store scoped by tenant and organization. Each tenant's SIM configuration consists of three settings:

SettingPurpose
API KeyThe SIM API key used to authenticate SDK calls
Base URLThe SIM instance URL (defaults to the cloud service, can point to a self-hosted instance)
Enabled FlagWhether the integration is active for this tenant

These settings are stored in the same way Zapier stores its client ID, client secret, and access tokens — as named entries in the integration settings table, linked to the tenant's integration record.

6. Multi-Tenant Isolation​

6.1 How Tenant Isolation Is Achieved​

Multi-tenancy is a first-class concern in this integration. The isolation model works at four levels:

Level 1 — Request Authentication: Every API request to Gauzy includes a JWT token that identifies the tenant. The TenantPermissionGuard extracts and validates this before any controller logic executes.

Level 2 — Data Scoping: All database queries for integration records, settings, and execution logs include the tenant ID as a filter. A tenant can never read or write another tenant's SIM configuration or execution history.

Level 3 — Client Isolation: The SimClientFactory creates a separate SIM SDK client instance for each tenant, initialized with that tenant's unique API key and base URL. Clients are cached by integration ID, so two tenants with different API keys will always have different client instances.

Level 4 — Execution Isolation: Each workflow execution is logged with the tenant ID and organization ID. Execution results, inputs, and outputs are stored per-tenant and only accessible by that tenant.

6.2 Tenant Isolation Flow​

7. How Workflow Execution Works​

7.1 Execution Modes​

The SIM SDK supports two execution modes, both of which the plugin exposes:

  • Synchronous Execution: The caller sends a request and waits for the workflow to complete. The response includes the full output, duration, and execution metadata. Best for short-running workflows (under 30 seconds).
  • Asynchronous Execution: The caller sends a request and immediately receives a task ID. The workflow runs in the background on the SIM side. The caller can poll for status using the task ID. Best for long-running workflows or when the caller does not need to wait.

7.2 Synchronous Execution Flow​

7.3 Asynchronous Execution Flow​

7.4 What Happens Inside SIM​

When the SIM SDK sends an execution request, SIM processes it through its internal engine:

  1. The workflow definition is loaded (blocks, connections, configuration)
  2. The input data is injected into the entry block
  3. Each block executes in sequence or parallel depending on the graph structure
  4. AI agent blocks call their configured AI models (OpenAI, Anthropic, etc.)
  5. Logic blocks evaluate conditions and route data accordingly
  6. Output blocks collect the final results
  7. The result is returned to the caller (or stored for async polling)

Gauzy does not need to know the internal details of SIM's execution engine. The plugin treats SIM as a black box: send input, receive output.

8. Event-Driven Workflow Triggers​

8.1 Concept​

Beyond manual and API-driven execution, the SIM plugin can automatically trigger workflows in response to internal Gauzy events. This is the same pattern used by the Zapier integration, where Zapier webhooks are notified when a timer starts or stops.

The difference is that instead of posting to a webhook URL, the SIM plugin directly executes a SIM workflow using the SDK.

8.2 Event-to-Workflow Mapping​

Tenants can configure mappings between Gauzy events and SIM workflow IDs. These mappings are stored as integration settings:

Event NameMapped Workflow IDDescription
timer.startedwf-abc-123Triggered when an employee starts their timer
timer.stoppedwf-def-456Triggered when an employee stops their timer
task.completedwf-ghi-789Triggered when a task is marked complete

When a Gauzy domain event fires, the plugin's event handler checks if the tenant has SIM enabled and if there is a workflow mapped to that event. If so, it executes the workflow asynchronously with the event data as input.

8.3 Event-Driven Flow​

8.4 Important Design Decisions​

  • Event-driven execution is always asynchronous — it must not block the original Gauzy event processing
  • If the SIM integration is not configured for a tenant, the event handler silently returns without error
  • If no workflow is mapped to the event, the handler silently returns
  • Errors in SIM execution are logged but do not propagate back to the event source
  • This is an opt-in feature — tenants must explicitly configure event-to-workflow mappings

9. How SIM and the MCP Server Coexist​

9.1 Different Purposes, Complementary Roles​

Gauzy already has an MCP (Model Context Protocol) server that exposes Gauzy's data and actions as tools for AI assistants. The MCP server and SIM integration serve fundamentally different purposes:

  • MCP Server: Enables "AI-into-Gauzy" — AI assistants use Gauzy tools
  • SIM Integration: Enables "Gauzy-into-AI" — Gauzy triggers complex AI pipelines
  • Integration Point: Selected SIM workflows can be exposed as MCP tools, allowing an AI assistant to trigger a complex SIM pipeline during a chat

9.2 The Decision Matrix​

Use MCP when: A single, discrete action is needed. "Get my tasks." "Start a timer." "Create an invoice." These are direct data operations that the MCP server handles efficiently.

Use SIM when: A complex, multi-step pipeline is needed. "Analyze all employee timesheets for the quarter, generate a summary report, identify anomalies, and email the results to the HR manager." This requires chaining multiple AI agents with business logic — exactly what SIM excels at.

9.3 Optional MCP Bridge​

As an advanced feature, selected SIM workflows can be exposed as MCP tools. This allows AI assistants to trigger complex SIM workflows through the MCP protocol. The MCP server would include a tool that calls the SIM plugin's execution endpoint, bridging the two systems.

This is optional and should be implemented only after the core plugin is stable.

10. Execution Logging and Audit Trail​

10.1 What Gets Logged​

Every workflow execution — whether manual, API-driven, or event-triggered — is recorded in a dedicated execution log. Each log entry captures:

  • Workflow ID: Which SIM workflow was executed
  • Execution ID: SIM's internal execution identifier (for cross-referencing with SIM's own logs)
  • Status: The execution outcome — queued, processing, completed, failed, or cancelled
  • Input: The data sent to the workflow (sanitized to remove any sensitive information)
  • Output: The result returned by the workflow
  • Error: If the execution failed, the error details
  • Duration: How long the execution took in milliseconds
  • Triggered By: What initiated the execution — manual (user action), event (Gauzy domain event), api (programmatic call), or schedule (cron-based)
  • Tenant and Organization: Standard multi-tenancy scoping

10.2 Execution Log Data Model​

10.3 Retention and Querying​

Execution logs are indexed by tenant, workflow ID, and status for efficient querying. The API exposes paginated access to execution history with optional filters. For long-running deployments, a retention policy should be implemented to archive or delete logs older than a configurable period (e.g., 90 days).

11. Security Considerations​

11.1 API Key Protection​

SIM API keys are the most sensitive piece of data in this integration. They must be:

  • Encrypted at rest in the database using Gauzy's existing encryption mechanism for integration settings
  • Never returned in any API response — the settings endpoint returns a boolean indicating whether an API key exists, not the key itself
  • Accessible only server-side — the key is loaded by the client factory when creating SDK instances, and never sent to the browser

11.2 Permission Model​

Access to the SIM integration is controlled through Gauzy's existing role-based permission system:

ActionPermission Required
Set up or modify SIM integrationINTEGRATION_ADD
Execute workflowsINTEGRATION_EDIT
View settings and execution historyINTEGRATION_VIEW
Remove integrationINTEGRATION_DELETE

These permissions are checked at the controller level using Gauzy's standard guard chain: first the TenantPermissionGuard validates tenant access, then the PermissionGuard validates the user has the required permission.

11.3 Input Sanitization​

Workflow input data passes through validation DTOs before being sent to SIM. This prevents injection of malformed payloads. Timeout values are bounded (minimum 1 second, maximum 5 minutes) to prevent resource exhaustion.

11.4 Tenant Data Boundaries​

The complete isolation described in Section 6 ensures that one tenant cannot:

  • Read another tenant's API key
  • Execute workflows using another tenant's SIM credentials
  • View another tenant's execution history
  • Modify another tenant's event-to-workflow mappings

12. Resilience and Error Handling​

12.1 SDK-Level Retry​

The SIM SDK provides a built-in retry mechanism with exponential backoff. When a request fails due to a transient error (network timeout, rate limiting, server overload), the SDK automatically retries with increasing delays:

  • First retry after ~1 second
  • Second retry after ~2 seconds
  • Third retry after ~4 seconds
  • Each delay has ±25% jitter to prevent thundering herd
  • If the SIM server returns a Retry-After header, the SDK respects it

12.2 Error Classification​

The SDK provides typed errors that the plugin translates into appropriate HTTP responses:

SIM ErrorMeaningPlugin Response
UNAUTHORIZEDInvalid API key401 Unauthorized — prompts tenant to reconfigure
TIMEOUTWorkflow took too long408 Request Timeout — suggest increasing timeout or using async
RATE_LIMIT_EXCEEDEDToo many requests429 Too Many Requests — with retry guidance
USAGE_LIMIT_EXCEEDEDAccount quota exhausted402 Payment Required — tenant needs to upgrade SIM plan
EXECUTION_ERRORWorkflow logic failed500 Internal Server Error — with SIM's error details

12.3 Circuit Breaker​

To prevent cascading failures when a SIM instance is completely down, the plugin implements a circuit breaker per tenant:

This prevents the plugin from overwhelming a struggling SIM instance and provides fast failure responses to users when SIM is known to be unavailable.

13. Deployment Strategy​

13.1 Two Deployment Models​

The plugin supports two deployment models for SIM, configurable per tenant:

Cloud SIM (Default): Tenants use SIM's managed service at sim.ai. This is the simplest option — the tenant creates a SIM account, generates an API key, and configures it in Gauzy. No infrastructure management required.

Self-Hosted SIM: For enterprises that require data sovereignty, private AI models (via Ollama), or network isolation, SIM can be deployed alongside Gauzy using Docker Compose or Kubernetes. Each tenant can point to a different SIM instance by configuring their base URL.

13.2 Infrastructure Relationship​

13.3 Key Infrastructure Notes​

  • SIM uses its own PostgreSQL database — it does not share Gauzy's database
  • When self-hosted with Docker, SIM and Gauzy communicate via the Docker internal network
  • When self-hosted with Kubernetes, they should share the same namespace for network proximity
  • The plugin only needs one environment variable for default configuration: the default SIM base URL

14. Scalability and Monitoring​

14.1 Performance Considerations​

The client factory caches SIM SDK client instances per tenant. This avoids the overhead of loading credentials and instantiating a new client on every request. When credentials change, the cache is invalidated for that specific tenant.

For high-volume deployments, an optional job queue (BullMQ) can be added to handle workflow executions asynchronously within Gauzy itself, providing benefits such as concurrency control, delayed execution, priority queues, and dead letter queues for persistently failing executions.

14.2 Monitoring Points​

MetricHow to TrackPurpose
Execution success rateCount completed vs. failed in execution logDetect workflow reliability issues
Average execution durationAggregate duration from execution logIdentify performance degradation
Error rate by typeGroup execution errors by error codeUnderstand failure patterns
Rate limit proximityCheck remaining quota via SDKPrevent hitting limits
Executions per tenantCount executions grouped by tenantIdentify heavy users
Circuit breaker stateTrack open/closed per tenantDetect SIM availability issues

14.3 Health Check​

The plugin should expose a health check that verifies connectivity to the SIM instance. This can be called by Gauzy's monitoring system to detect SIM downtime early, before users encounter errors.

15. API Surface Design​

15.1 Endpoint Overview​

All endpoints are mounted under the base path /api/integration/sim/ and require authentication plus appropriate permissions.

MethodEndpointPermissionDescription
POST/setupINTEGRATION_ADDConfigure SIM integration (API key)
GET/settingsINTEGRATION_VIEWGet sanitized integration settings
POST/workflows/:workflowId/executeINTEGRATION_EDITExecute a workflow (sync or async)
GET/workflows/:workflowId/validateINTEGRATION_VIEWValidate a workflow is deployed
GET/jobs/:jobId/statusINTEGRATION_VIEWGet async job status
GET/executionsINTEGRATION_VIEWGet execution history (paginated)
GET/status/:integrationTenantIdINTEGRATION_VIEWCheck if integration is enabled
GET/integration-tenant/:integrationTenantIdINTEGRATION_VIEWGet integration tenant info (redacted)

15.2 Request/Response Design Principles​

  • No secrets in responses: API keys are never returned. Only boolean flags indicating their presence.
  • Consistent error format: All errors follow Gauzy's standard error response structure.
  • Pagination: List endpoints support limit/offset pagination.
  • Filtering: Execution history can be filtered by workflow ID and status.
  • Validation: All inputs pass through DTOs with class-validator rules. Timeout values are bounded. Required fields are enforced.

16. Implementation Phases​

Phase 1 — Foundation​

Establish the plugin skeleton and contracts. This includes adding the SIM entry to the integration enumeration, creating the plugin package with its project configuration files, and installing the SIM TypeScript SDK as a dependency. No business logic yet — just the scaffolding.

Phase 2 — Core Plugin​

Build the plugin entry point, NestJS module, configuration constants, and the tenant-scoped client factory. At the end of this phase, the plugin can bootstrap, register with Gauzy, and create SIM SDK client instances per tenant. No execution yet.

Phase 3 — Business Logic​

Implement the core service, REST controller, DTOs, and the execution log entity with its repositories. At the end of this phase, tenants can configure their SIM integration, execute workflows (synchronously and asynchronously), check job status, and view execution history.

Phase 4 — Event Integration​

Add CQRS event handlers that listen to Gauzy domain events and trigger SIM workflows. Implement the event-to-workflow mapping configuration. This phase makes the integration reactive — workflows can fire automatically based on platform activity.

Phase 5 — Testing​

Write unit tests for the service and client factory, integration tests with a mock SIM server, and end-to-end tests for the full execution flow. Validate multi-tenant isolation, error handling, and retry behavior.

Phase 6 — Deployment and Polish​

Add the plugin to the application's plugin list, run database migrations for the execution log entity, seed the integration catalog, test with both cloud and self-hosted SIM instances, and document environment variables.

17. Risk Assessment​

17.1 Technical Risks​

  • SIM API changes: As SIM evolves, its API may introduce breaking changes. Mitigation: pin the SDK version and implement an adapter layer that isolates the plugin from direct SDK coupling. Run integration tests against new SDK versions before upgrading.
  • SIM instance downtime: Whether cloud or self-hosted, SIM may become unavailable. Mitigation: the circuit breaker prevents cascading failures, the retry mechanism handles transient outages, and async execution decouples the caller from SIM availability.
  • Rate limiting: SIM enforces rate limits on API calls. Mitigation: the SDK's built-in retry respects rate limit headers, and the plugin can implement Gauzy-side per-tenant throttling to prevent any single tenant from exhausting shared quotas.

17.2 Security Risks​

  • API key exposure: If API keys leak, an attacker could execute workflows on the tenant's SIM account. Mitigation: encrypt keys at rest, never return them in API responses, and ensure they are only accessed server-side.
  • Cross-tenant data access: A vulnerability in tenant isolation could allow one tenant to access another's configuration or execution data. Mitigation: rely on Gauzy's battle-tested TenantPermissionGuard and always scope queries by tenant ID.
  • Malicious workflow input: A user could attempt to inject harmful data through workflow inputs. Mitigation: validate all inputs through DTOs, sanitize payloads, and rely on SIM's own input validation as a second layer.

17.3 Operational Risks​

  • Cost management: AI workflow executions on SIM consume compute resources and potentially AI model API credits. Mitigation: monitor usage per tenant via the execution log, and optionally implement per-tenant execution limits.
  • Log storage growth: High-volume tenants could generate large amounts of execution history data. Mitigation: implement a configurable retention policy and paginate all list queries.
  • Self-hosted maintenance burden: Organizations that self-host SIM take on the responsibility of updates, backups, and monitoring. Mitigation: provide clear documentation and health check endpoints to simplify operations.

Summary​

The SIM integration brings AI-native workflow orchestration to Ever Gauzy. It follows the established plugin architecture, reuses the core integration infrastructure, and maintains strict multi-tenant isolation. The design is intentionally simple — SIM uses API key authentication (no OAuth complexity), the SDK handles retries and rate limiting, and execution logging provides a complete audit trail.

The integration complements rather than replaces the existing MCP server: MCP handles single-action AI tool calls, while SIM handles complex multi-step AI pipelines. Together, they give Gauzy tenants a complete AI automation toolkit — from simple data queries to sophisticated agent workflows.