Architecture

Relevant source files

• .devcontainer/Dockerfile
• .github/workflows/docs-embeddings.yml
• .github/workflows/i18n.yml
• .github/workflows/migrations.yml
• .github/workflows/publish-cli.yml
• .github/workflows/publish-ts-sdk.yml
• .github/workflows/test-build.yml
• apps/docs/content/docs/en/blocks/api.mdx
• apps/docs/package.json
• apps/docs/tsconfig.json
• apps/sim/.env.example
• apps/sim/.gitignore
• apps/sim/app/api/auth/sso/providers/route.ts
• apps/sim/app/api/auth/sso/register/route.ts
• apps/sim/app/api/resume/[workflowId]/[executionId]/[contextId]/route.ts
• apps/sim/app/global-error.tsx
• apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/editor/components/sub-block/components/combobox/combobox.tsx
• apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/editor/components/sub-block/components/dropdown/dropdown.tsx
• apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/editor/components/sub-block/components/mcp-dynamic-args/mcp-dynamic-args.tsx
• apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/editor/components/sub-block/components/messages-input/messages-input.tsx
• apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/editor/components/sub-block/hooks/use-depends-on-gate.ts
• apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/editor/components/sub-block/hooks/use-sub-block-value.ts
• apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/editor/components/sub-block/sub-block.tsx
• apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/editor/editor.tsx
• apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/workflow-block/workflow-block.tsx
• apps/sim/app/workspace/[workspaceId]/w/[workflowId]/workflow.tsx
• apps/sim/blocks/types.ts
• apps/sim/hooks/use-collaborative-workflow.ts
• apps/sim/instrumentation-client.ts
• apps/sim/instrumentation-node.ts
• apps/sim/lib/execution/constants.ts
• apps/sim/lib/mcp/tool-validation.ts
• apps/sim/lib/workflows/subblocks.ts
• apps/sim/next.config.ts
• apps/sim/package.json
• apps/sim/stores/operation-queue/store.ts
• apps/sim/stores/workflows/utils.test.ts
• apps/sim/stores/workflows/utils.ts
• apps/sim/stores/workflows/workflow/store.test.ts
• apps/sim/stores/workflows/workflow/store.ts
• apps/sim/stores/workflows/workflow/types.ts
• apps/sim/stores/workflows/workflow/utils.test.ts
• apps/sim/stores/workflows/workflow/utils.ts
• apps/sim/tools/http/request.stringified.test.ts
• apps/sim/tools/http/request.test.ts
• apps/sim/tools/http/request.ts
• apps/sim/tools/http/types.ts
• apps/sim/tools/http/utils.ts
• apps/sim/tsconfig.json
• bun.lock
• docker-compose.local.yml
• docker-compose.prod.yml
• docker/app.Dockerfile
• docker/db.Dockerfile
• docker/realtime.Dockerfile
• helm/sim/templates/_helpers.tpl
• helm/sim/templates/deployment-worker.yaml
• helm/sim/values.yaml
• package.json
• packages/db/drizzle.config.ts
• packages/db/index.ts
• packages/db/package.json
• packages/db/scripts/deregister-sso-provider.ts
• packages/db/scripts/migrate-deployment-versions.ts
• packages/db/scripts/register-sso-provider.ts
• packages/tsconfig/base.json
• packages/tsconfig/library.json
• packages/tsconfig/nextjs.json

This document describes the high-level architecture of the Sim platform, including the monorepo structure, major system components, technology stack, state management patterns, and real-time collaboration architecture. For specific implementation details of individual subsystems, see:

• Monorepo structure and workspace organization: Monorepo Structure
• Database schema and data model: Database Schema
• WebSocket collaboration system: Real-time Collaboration System
• Frontend state management: State Management Architecture
• API layer and conventions: API Layer
• Authentication and authorization model: Authentication & Authorization
• Security and CSP configuration: Security & CSP Configuration

System Overview

Sim is a full-stack TypeScript application built as a monorepo using Turborepo package.json12 The system follows a layered architecture with clear separation between frontend presentation, backend services, data persistence, and background job processing. All components communicate through well-defined interfaces and leverage real-time WebSocket connections for collaborative editing.

The platform consists of:

• Frontend application (apps/sim): Next.js 16.1.6 application serving the workflow editor and execution UI apps/sim/package.json145
• Documentation site (apps/docs): Next.js application with Fumadocs for public documentation apps/docs/package.json26-31
• Shared packages: Database schema (@sim/db), logger (@sim/logger), and configuration utilities package.json7-10

Monorepo Dependency Graph

Sources: package.json1-10 apps/sim/package.json1-187 apps/docs/package.json1-51 bun.lock1-15

Layer Architecture

The system is organized into major layers that handle distinct concerns:

Frontend Layer

The frontend layer runs as a Next.js application using React 19.2.4 and the App Router apps/sim/package.json161

Key components:

• Workflow Canvas: ReactFlow-based visual editor at apps/sim/app/workspace/[workspaceId]/w/[workflowId]/workflow.tsx apps/sim/app/workspace/[workspaceId]/w/[workflowId]/workflow.tsx:5-16.
• Workflow Blocks: Specialized React components for different block types apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/workflow-block/workflow-block.tsx:31-54.
• Real-time Presence: Collaborative cursors and user state managed via Cursors component apps/sim/app/workspace/[workspaceId]/w/[workflowId]/workflow.tsx:37.

Sources: apps/sim/app/workspace/[workspaceId]/w/[workflowId]/workflow.tsx:1-92, apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/workflow-block/workflow-block.tsx:1-56

Backend & API Layer

The backend uses Next.js API Routes and Better Auth for secure session management.

Core API functionality:

• Authentication: Managed via Better Auth apps/sim/package.json96
• Background Processing: BullMQ integration for task queue management apps/sim/package.json100
• Logging: Unified logging via @sim/logger apps/sim/package.json88

Sources: apps/sim/package.json96-100 apps/sim/next.config.ts157-174

Real-time Communication Layer

Real-time collaboration is powered by Socket.IO, enabling multi-user editing with conflict resolution via an operation queue pattern.

Socket client hook: apps/sim/hooks/use-collaborative-workflow.ts apps/sim/hooks/use-collaborative-workflow.ts34-127 Operation Constants: Targets and operations defined in socket/constants apps/sim/hooks/use-collaborative-workflow.ts11-19

Sources: apps/sim/hooks/use-collaborative-workflow.ts114-158 apps/sim/stores/operation-queue/store.ts1-22

State Management Architecture

The frontend uses Zustand stores organized by domain. State is split between local UI state, workflow structure, and collaborative values.

Core Store Hierarchy

Store	Purpose	Key File
useWorkflowRegistry	Manages workflow metadata and active selection	apps/sim/app/workspace/[workspaceId]/w/[workflowId]/workflow.tsx:88
useWorkflowStore	Manages nodes (blocks), edges, and workflow structure	apps/sim/stores/workflows/workflow/store.ts114
useSubBlockStore	Manages specific input values for block parameters	apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/workflow-block/workflow-block.tsx:52
useUndoRedoStore	Handles action history for undo/redo functionality	apps/sim/app/workspace/[workspaceId]/w/[workflowId]/workflow.tsx:85

Sources: apps/sim/stores/workflows/workflow/store.ts114-223 apps/sim/app/workspace/[workspaceId]/w/[workflowId]/workflow.tsx:79-91

Block Registry System

Blocks are the primary unit of the workflow. The system uses a centralized registry to manage block definitions.

Sources: apps/sim/app/workspace/[workspaceId]/w/[workflowId]/workflow.tsx:31-42, apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/workflow-block/workflow-block.tsx:38-53

Technology Stack Summary

Category	Technology
Framework	Next.js 16 (App Router), React 19 apps/sim/package.json145-161
Runtime	Bun 1.3.11 package.json3
Auth	Better Auth apps/sim/package.json96
Database	PostgreSQL + Drizzle ORM apps/sim/package.json112-155
Real-time	Socket.io apps/sim/package.json179
Workflow UI	ReactFlow apps/sim/app/workspace/[workspaceId]/w/[workflowId]/workflow.tsx:5-16
State	Zustand apps/sim/package.json186

Sources: apps/sim/package.json1-187 package.json1-52 apps/sim/next.config.ts1-120