Understanding the `src` Directory in OpenWork: A Complete Guide to the Monorepo Source Structure

The src directory in OpenWork contains the actual TypeScript implementation code for every package and application in the repository, organized as a multi-package workspace with separate source folders for server, UI, and enterprise utilities.

OpenWork is an open-source AI-powered workspace platform developed by different-ai. The repository follows a monorepo architecture where source code lives in src folders across multiple packages rather than a single root-level directory. This design enables independent builds, clear separation of concerns, and scalable code sharing between the desktop application and MCP gateway.

What the src Directory Contains in OpenWork

Each package in the OpenWork monorepo maintains its own src folder holding uncompiled TypeScript source files. This structure appears in three main locations:

• apps/server/src — Back-end server implementation
• packages/ui/src — Shared React UI component library
• ee/packages/utils/src — Enterprise-edition utility functions

The src directories are intentionally separate from build artifacts. Compiled output goes to dist/ or build/ folders, while node_modules/ holds external dependencies. This separation ensures clean imports and predictable build behavior across the workspace.

Server Application: apps/server/src

The server's src directory houses the core back-end infrastructure. According to the OpenWork source code, this includes workspace management, routing logic, and persistence layers.

Key Files in apps/server/src

File Path	Purpose
apps/server/src/server.ts	Main server entry point — wires routes and runtime configuration
apps/server/src/workspace-kv-store.ts	Per-workspace key/value storage utility

The workspace KV store demonstrates how server-side utilities expose clean APIs for other packages:

// Import pattern used throughout the monorepo
import { getWorkspaceKVStore } from '@openwork/server/workspace-kv-store';

// Retrieve a value from a specific workspace
const value = await getWorkspaceKVStore('my-workspace').get('myKey');

This file (apps/server/src/workspace-kv-store.ts) provides typed persistence that the MCP gateway and desktop app consume through workspace-scoped isolation.

UI Package: packages/ui/src

The packages/ui/src directory contains React components and platform-detection utilities shared across OpenWork's front-end applications.

Platform Detection Example

From packages/ui/src/react/platform-detect.ts:

import { PlatformDetect } from '@openwork/ui/react/platform-detect';

function App() {
  const platform = PlatformDetect();
  return <div>You are on: {platform}</div>;
}

This utility illustrates the cross-package import pattern: UI components are consumed via @openwork/ui namespace mappings defined in the workspace's TypeScript configuration. The src folder structure enables this by providing a consistent entry point for the build toolchain.

Enterprise Utilities: ee/packages/utils/src

The ee/ directory contains enterprise-edition code with its own src folder structure. The ee/packages/utils/src/typeid.ts file demonstrates how utility functions are organized:

import { typeId } from '@openwork/utils/typeid';

const id = typeId('User');
console.log(id); // → "User_12345"

This helper generates stable type identifiers and shows that enterprise packages follow identical src conventions to ensure consistency across licensing tiers.

Why OpenWork Uses Multiple src Directories

The distributed src structure serves four architectural goals:

1. Independent package builds — Each src folder compiles to its own dist/ output via pnpm workspace scripts
2. Explicit API boundaries — Only exports from src/index.ts or designated entry points are publicly accessible
3. TypeScript path mapping — Workspace aliases like @openwork/server resolve to specific src directories
4. Clean dependency graphs — Tools like Turborepo can cache builds per-package based on src file changes

How src Directories Map to Consumable Packages

OpenWork's build pipeline transforms src content into distributable code through this flow:

apps/server/src/          →  dist/  →  @openwork/server (npm/workspace link)
packages/ui/src/react/    →  dist/  →  @openwork/ui/react
ee/packages/utils/src/    →  dist/  →  @openwork/utils

The src folder naming convention makes this transformation predictable. Developers always know that human-editable code lives in src while generated code belongs elsewhere.

Summary

• The src directory in OpenWork appears in every package and contains uncompiled TypeScript source code
• Server code lives in apps/server/src/ with workspace management and KV storage utilities
• UI components reside in packages/ui/src/react/ for cross-platform React consumption
• Enterprise utilities follow the same pattern in ee/packages/utils/src/
• Build outputs go to dist/ folders, keeping src clean and import-friendly
• TypeScript path mappings enable clean imports like @openwork/server/workspace-kv-store

Frequently Asked Questions

How do I import code from an OpenWork src directory?

Use the package's workspace alias rather than relative paths. For server utilities: import { getWorkspaceKVStore } from '@openwork/server/workspace-kv-store'. The src folder is transparently mapped through TypeScript configuration and pnpm workspace settings.

Can I modify code directly in src folders?

Yes — src directories contain the authoritative source that you should edit. Changes require rebuilding the package (pnpm build or via Turborepo) to update the corresponding dist/ output that runtime code executes.

What's the difference between apps/ and packages/ src directories?

apps/ (apps/server/src) contains deployable applications with server entry points. packages/ (packages/ui/src, ee/packages/utils/src) contains library code consumed by those applications. Both use identical src conventions but serve different architectural roles in the monorepo.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}