OpenWork Services Directory Structure: A Complete Monorepo Guide

OpenWork organizes its runtime services as independent packages within a monorepo, where each service resides under packages/ or ee/, maps directly to Docker Compose containers, and follows a consistent structure with its own source code, dependencies, and configuration.

The different-ai/openwork repository uses a service-centric monorepo layout that isolates each runtime component into its own package. Understanding the OpenWork services directory structure is essential for developers contributing to the core backend, deploying enterprise editions, or self-hosting the platform locally.

Top-Level Directory Layout

OpenWork follows a standard monorepo pattern with distinct folders for applications, core services, enterprise extensions, and infrastructure configuration.

• apps/ – Contains the desktop-first UI and demo applications, including the Electron-based interface in apps/electron/ and demonstration setups in apps/ui-demo/.

• packages/ – Houses the core back-end services, shared libraries, and UI components. This is where the primary runtime services like den-api, den-web, and den-mcp reside.

• ee/ – Stores Enterprise Edition extensions that wrap core services with additional scaling and policy logic, located under ee/apps/.

• packaging/docker/ – Contains Docker Compose definitions that spin up services locally, with files like docker-compose.yml and docker-compose.dev.yml referencing the same service names used in the source packages.

• docs/ – Architecture and deployment documentation, including docs/start-here/self-host.mdx and docs/cloud/run-in-the-cloud/cloud-mcp.mdx, which describe service boundaries and cloud deployment strategies.

Core Service Packages

The packages/ directory contains the fundamental runtime components that power both the desktop application and cloud gateway. Each service maintains its own package.json, source directory, and service-specific configuration.

Key services include:

• den-api/ – The core API service handling business logic and data persistence. Located at packages/den-api/, it declares its runtime dependencies and build scripts in packages/den-api/package.json.

• den-web/ – The web UI service that serves the OpenWork front-end, defined in packages/den-web/package.json.

• den-mcp/ – The Model Context Protocol (MCP) gateway service that facilitates cloud deployments, documented in docs/cloud/run-in-the-cloud/cloud-mcp.mdx.

• enterprise-mcp-mock-server/ and enterprise-mcp-client/ – Enterprise-grade MCP implementations for testing and client connections.

• email/ – Service handling email notifications and transactional messaging.

• ui/ – Shared UI component library used across multiple applications.

Enterprise Edition Extensions

The ee/ directory contains thin wrapper packages that extend core functionality for paid deployments. These packages import from the open-source core while adding enterprise-specific features.

Enterprise services mirror the core structure under ee/apps/:

• ee/apps/den-api/ – Enterprise wrapper around the core API with additional authentication and scaling capabilities.

• ee/apps/den-web/ – Enhanced web interface with enterprise policy controls.

This architecture allows the same codebase to serve both open-source users and enterprise customers without duplicating core logic.

Docker Compose Integration

Service orchestration is defined in packaging/docker/, where Docker Compose files map directly to the package structure. The compose configurations use service names that match the directory names in packages/, ensuring a one-to-one relationship between source code and running containers.

The docker-compose.dev.yml file defines services including den-api, den-web, and den-mcp, referencing build contexts that point to the corresponding package directories. This guarantees that code edited in packages/den-api/ runs directly in the den-api container during local development.

How Services Are Structured

Each OpenWork service follows a consistent organizational pattern that promotes isolation and reusability.

Package Independence – Every service lives in its own package with dedicated source code in a src/ directory and dependency management via package.json.

Docker Mapping – Service names in Docker Compose targets correspond exactly to package names, creating a transparent path from source to container.

Import Resolution – The monorepo uses workspace imports configured in pnpm-workspace.yaml, allowing cross-service dependencies via scoped packages like @openwork/den-api.

Running Services Locally

To start the core services for local development, use the Docker Compose configuration that references the package structure:

# From the repository root

docker compose -f packaging/docker/docker-compose.dev.yml up -d den-api den-web den-mcp

This command launches containers named den-api, den-web, and den-mcp, mapping to their respective packages in packages/.

When importing service functionality in another package, use the workspace-scoped import:

// Example: a plugin that needs to talk to the Den API
import { createClient } from '@openwork/den-api/client';

const api = createClient({ baseUrl: process.env.DEN_API_URL! });
await api.healthCheck();

The import path @openwork/den-api resolves to packages/den-api according to the monorepo's workspace configuration.

Summary

• OpenWork uses a monorepo structure with services organized under packages/ (core) and ee/ (enterprise).

• Each service is a self-contained package with its own package.json, source directory, and configuration files.

• Service names align with Docker Compose targets in packaging/docker/, ensuring consistent deployment from development to production.

• The Enterprise Edition re-exports core services from ee/apps/ with additional scalability and policy features.

• Documentation in docs/start-here/self-host.mdx explains service boundaries for self-hosted deployments.

Frequently Asked Questions

Where are the core backend services located in OpenWork?

The core backend services reside in the packages/ directory at the repository root. Key services include den-api (business logic), den-web (frontend server), and den-mcp (MCP gateway), each maintained as an independent package with its own dependencies and build configuration.

How do enterprise edition services differ from core services?

Enterprise services are thin wrappers located in ee/apps/ that import and extend the core packages from packages/. They add enterprise-specific functionality like advanced authentication and scaling policies while reusing the same underlying codebase, allowing unified maintenance of core features across both open-source and paid versions.

What is the relationship between package names and Docker services?

There is a direct one-to-one mapping between package directory names and Docker Compose service names. The packaging/docker/docker-compose.dev.yml file defines services named den-api, den-web, and den-mcp that build from the corresponding directories in packages/, ensuring that source changes reflect immediately in the running containers.

How do I start the OpenWork services locally for development?

Run docker compose -f packaging/docker/docker-compose.dev.yml up -d den-api den-web den-mcp from the repository root. This command uses the Docker Compose configuration to build and start the three core services, mounting the package directories so that code changes in packages/den-api/, packages/den-web/, or packages/den-mcp/ are reflected in the running containers without rebuilding.

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