# OpenWork Services Directory Structure: A Complete Monorepo Guide

> Explore the OpenWork Services directory structure within its monorepo. Understand how each service package maps to Docker Compose containers for efficient development.

- Repository: [Different AI/openwork](https://github.com/different-ai/openwork)
- Tags: deep-dive
- Published: 2026-08-13

---

**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`](https://github.com/different-ai/openwork/blob/main/docker-compose.yml) and [`docker-compose.dev.yml`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/packages/den-api/package.json).

- **`den-web/`** – The web UI service that serves the OpenWork front-end, defined in [`packages/den-web/package.json`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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:

```bash

# 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:

```typescript
// 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`](https://github.com/different-ai/openwork/blob/main/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`](https://github.com/different-ai/openwork/blob/main/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.