This document describes the monorepo organization of the Sim Studio platform codebase. It covers the Bun workspace configuration, the separation of applications and packages, internal dependency management, and the Turbo-based build orchestration system. This structure supports a unified development experience for the main AI agent platform, its documentation, and shared internal libraries.
The Sim platform is organized as a Bun monorepo with a workspace-based architecture. The root package.json1-53 defines the workspace pattern:
The monorepo uses Bun 1.3.11 as its package manager, specified in package.json3 The workspace pattern allows multiple packages and applications to coexist in a single repository while maintaining isolated dependency trees and enabling efficient cross-package references via the workspace:* protocol.
The following diagram bridges the "Natural Language Space" (Logical Components) to the "Code Entity Space" (Package Names and File Paths).
Sources: package.json7-10 bun.lock4-51 apps/sim/package.json88-190 apps/docs/package.json18-38
The apps/ directory contains deployable applications that serve as end-user entry points.
The primary Next.js 16 application providing the visual workflow editor, AI agent execution runtime, and real-time collaboration.
| Property | Value |
|---|---|
| Package Name | sim apps/sim/package.json2 |
| Version | 0.1.0 apps/sim/package.json3 |
| Framework | Next.js 16.1.6, React 19.2.4 apps/sim/package.json145-161 |
| Runtime | Bun ≥1.2.13, Node ≥20.0.0 apps/sim/package.json7-8 |
Key Capabilities & Dependencies:
openai, @anthropic-ai/sdk, @google/genai, groq-sdk apps/sim/package.json38-152reactflow@^11.11.4 apps/sim/package.json168socket.io and socket.io-client apps/sim/package.json179-180better-auth@1.3.12 apps/sim/package.json96bullmq@5.71.0 apps/sim/package.json100Sources: apps/sim/package.json1-210 bun.lock52-203
Documentation site built with Fumadocs, providing API reference and user guides.
| Property | Value |
|---|---|
| Package Name | docs apps/docs/package.json2 |
| Framework | Next.js 16.1.6, Fumadocs 16.6.7 apps/docs/package.json24-29 |
Sources: apps/docs/package.json1-49 bun.lock16-51
The packages/ directory contains logic and configurations shared across the apps.
Internal packages use the workspace:* protocol to reference each other. This ensures that during development, changes in a package are immediately reflected in the apps without needing to publish to a registry.
Key Shared Resources:
@sim/db: Contains the PostgreSQL schema definitions and Drizzle migration configuration apps/docs/package.json18 docker/db.Dockerfile39@sim/logger: Unified logging interface used by both the Next.js app and the Socket.io server apps/sim/package.json88@sim/tsconfig: Base TypeScript configurations to ensure consistent compiler settings across the monorepo apps/sim/package.json190Sources: apps/sim/package.json88-190 apps/docs/package.json18-38 docker/db.Dockerfile38-45
The monorepo uses Turbo 2.9.1 package.json42 for task orchestration. Turbo manages the execution of scripts across all workspaces, providing caching and parallel execution.
Defined in the root package.json11-27:
| Script | Command | Description |
|---|---|---|
build | turbo run build | Builds all packages and apps in dependency order. |
dev | turbo run dev | Starts development servers for all workspaces. |
dev:full | cd apps/sim && bun run dev:full | Starts Next.js app, Socket server, and Worker concurrently apps/sim/package.json14 |
test | turbo run test | Runs Vitest suites across the monorepo. |
lint | turbo run lint | Runs Biome linting across all workspaces package.json19 |
Sources: package.json11-42 apps/sim/package.json14
To prevent "dependency hell" and ensure compatibility, the root package.json uses an overrides block to pin critical library versions across the entire monorepo package.json28-35
In apps/sim/next.config.ts, specific packages are marked as serverExternalPackages to prevent them from being bundled by the Next.js compiler, typically due to native binary requirements or isolated environment needs apps/sim/next.config.ts81-91:
@1password/sdkunpdfffmpeg-staticfluent-ffmpegisolated-vm (used for custom tool execution)Sources: package.json28-35 apps/sim/next.config.ts81-91
The monorepo is designed for containerized deployment using multi-stage Docker builds docker/app.Dockerfile1-145 When the DOCKER_BUILD environment variable is present, the main application switches to standalone mode apps/sim/next.config.ts77
The system is decomposed into several services in production docker-compose.prod.yml1-137:
simstudio: The main Next.js application docker-compose.prod.yml2sim-worker: Background job processor running apps/sim/worker/index.ts docker-compose.prod.yml43-45realtime: The dedicated Socket.io server running apps/sim/socket/index.ts docker-compose.prod.yml80-84migrations: A short-lived container that runs bun run db:migrate docker-compose.prod.yml107-116db: PostgreSQL 17 with pgvector support docker-compose.prod.yml118-119Sources: apps/sim/next.config.ts75-77 docker-compose.prod.yml1-137 docker/app.Dockerfile145 docker/realtime.Dockerfile84
Refresh this wiki