# OpenWork Project Structure: A Complete Guide to the Monorepo Architecture

> Explore the OpenWork project structure, a pnpm workspace monorepo. Understand its apps, packages, and integration with TurboRepo, Warden, and OpenCode for efficient development.

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

---

**OpenWork is organized as a pnpm workspace monorepo with distinct directories for applications (`apps/`), shared libraries (`packages/`), end-to-end tests (`evals/`), and configuration files that integrate TurboRepo, Warden security scanning, and OpenCode skill registries.**

The **openwork project structure** follows a modular monorepo pattern that consolidates a desktop Electron client, a cloud control plane (Den), reusable skills, and plugins into a single cohesive repository. Built as a **pnpm workspace**, the codebase enforces strict separation between runnable applications, shared TypeScript packages, documentation, and infrastructure tooling. This architecture enables rapid iteration across multiple targets while maintaining consistent build pipelines and security policies.

## Top-Level Directory Layout

The repository root contains eight primary directories that define the project boundaries, alongside specialized configuration folders for development environments and security policies.

| Path | Purpose |
|------|---------|
| `apps/` | Runnable applications including the **Electron desktop client** and the **Den web control plane** |
| `packages/` | Reusable TypeScript libraries shared across apps (UI components, state stores, API clients) |
| `evals/` | End-to-end test suites and **fraimz** proof-of-concept scripts that drive the UI via CDP |
| `scripts/` | CI helpers, publishing automation, and repo maintenance utilities |
| `docs/` | Public documentation and Markdown guides powering the OpenWork website |
| `examples/` | Reference projects demonstrating how to embed OpenWork skills (e.g., Rust sandbox) |
| `.devcontainer/` | VS Code DevContainer definition for consistent development environments |
| `.github/` | GitHub Actions workflows, issue templates, and CI configuration |

Specialized configuration directories include `.opencode/` for skill registries and MCP definitions, `.warden/` for security-review skill definitions, and `patches/` for Yarn/PNPM patches that modify third-party dependencies without forking.

## Applications and Packages

The `apps/` directory houses the two primary entry points, while `packages/` contains the shared logic consumed by both.

### Desktop and Den Applications

- **`apps/desktop/`** – The Electron-based desktop client containing the main process, preload scripts, and renderer UI. This package imports components from `packages/ui` and state management from `packages/store`.
- **`apps/den/`** – The web-based cloud control plane and API gateway that manages remote skill execution.

### Shared Libraries

The `packages/` directory hosts reusable TypeScript libraries including:

- **`packages/ui/`** – A shared React component library based on shadcn/ui, providing consistent design tokens across the desktop and web interfaces
- **`packages/store/`** – Centralized state management utilities used by both applications
- Core API clients and utility functions that abstract platform-specific operations

New components are scaffolded under `packages/ui/` and imported using workspace aliases:

```typescript
import { Button } from '@openwork/ui/button';

```

## Configuration and Workspace Management

The openwork project structure relies on four critical root-level configuration files to orchestrate builds, dependencies, and security policies.

### Workspace Definition ([`pnpm-workspace.yaml`](https://github.com/different-ai/openwork/blob/main/pnpm-workspace.yaml))

This file lists every folder containing a [`package.json`](https://github.com/different-ai/openwork/blob/main/package.json), enabling **pnpm** to hoist shared dependencies and run commands across the entire repository:

```bash

# Install all workspace dependencies

pnpm install

# Start the default development profile (desktop + Vite dev server)

pnpm dev

```

The `pnpm dev` command prints a banner indicating the CDP debugging endpoint: `[openwork] dev profile=default cdp=http://127.0.0.1:9223`.

### Build Orchestration ([`turbo.json`](https://github.com/different-ai/openwork/blob/main/turbo.json))

**TurboRepo** pipelines defined in [`turbo.json`](https://github.com/different-ai/openwork/blob/main/turbo.json) manage the dependency graph between install, build, and test tasks. This configuration ensures only packages with changes are rebuilt, dramatically accelerating CI cycles.

### Security Policy ([`warden.toml`](https://github.com/different-ai/openwork/blob/main/warden.toml))

The [`warden.toml`](https://github.com/different-ai/openwork/blob/main/warden.toml) file configures the **Warden** static-analysis framework. Combined with definitions in `.warden/skills/`, this provides automated diff-security reviews during pull requests, scanning for vulnerabilities before code reaches the main branch.

## Testing and Evaluation Framework

The `evals/` directory contains the end-to-end validation suite that generates **fraimz** proof artifacts—canonical verification files that demonstrate UI behavior.

To execute the evaluation suite:

```bash

# Run the demo-flow fraimz test

pnpm run eval:demo-flow

```

This script, located in `evals/demo-flow/`, launches the Electron application, drives interactions via the Chrome DevTools Protocol (CDP), and produces `evals/results/<run-id>/fraimz.html` as definitive proof of functionality.

## Security and Skill Integration

Two specialized directories integrate OpenWork with external frameworks:

### OpenCode Configuration (`.opencode/`)

The `.opencode/` directory holds skill registries and Model-Container-Protocol (MCP) definitions consumed by the desktop client at runtime. Skills are defined as JSON descriptors:

```json
{
  "name": "my-skill",
  "description": "Performs a custom transformation on text.",
  "inputSchema": { "type": "object", "properties": { "text": { "type": "string" } } },
  "outputSchema": { "type": "object", "properties": { "result": { "type": "string" } } }
}

```

These definitions are referenced in [`AGENTS.md`](https://github.com/different-ai/openwork/blob/main/AGENTS.md), which documents built-in agents and MCP endpoints.

### Product Requirements (`prds/`)

The `prds/` directory contains "product requirement documents" that serve as demo-first specifications for new features, bridging the gap between planning and implementation.

## Key Files in the Root Directory

| File | Role |
|------|------|
| [`package.json`](https://github.com/different-ai/openwork/blob/main/package.json) | Root-level scripts, workspace metadata, and top-level dependencies |
| [`pnpm-workspace.yaml`](https://github.com/different-ai/openwork/blob/main/pnpm-workspace.yaml) | Workspace package locations for pnpm |
| [`turbo.json`](https://github.com/different-ai/openwork/blob/main/turbo.json) | TurboRepo pipeline configuration (build, lint, test) |
| [`warden.toml`](https://github.com/different-ai/openwork/blob/main/warden.toml) | Security-policy configuration for Warden static analysis |
| [`skills-lock.json`](https://github.com/different-ai/openwork/blob/main/skills-lock.json) | Lock file for skill versioning and integrity |
| [`AGENTS.md`](https://github.com/different-ai/openwork/blob/main/AGENTS.md) | Documentation of built-in OpenWork agents and MCP endpoints |
| [`README.md`](https://github.com/different-ai/openwork/blob/main/README.md) | High-level project overview and installation quick-start |
| `changelog/` | Structured changelog entries feeding auto-generated release notes |

## Summary

- **OpenWork** uses a **pnpm workspace** monorepo structure with clear separation between `apps/` (runnable targets) and `packages/` (shared libraries).
- **TurboRepo** orchestrates builds via [`turbo.json`](https://github.com/different-ai/openwork/blob/main/turbo.json), while **Warden** enforces security through [`warden.toml`](https://github.com/different-ai/openwork/blob/main/warden.toml) and `.warden/skills/`.
- The **`evals/`** directory contains fraimz-based end-to-end tests that generate proof artifacts via CDP automation.
- **`.opencode/`** stores skill registries and MCP definitions that the desktop client consumes at runtime.
- Root configuration files ([`pnpm-workspace.yaml`](https://github.com/different-ai/openwork/blob/main/pnpm-workspace.yaml), [`package.json`](https://github.com/different-ai/openwork/blob/main/package.json)) enable cross-repository commands like `pnpm dev` and `pnpm run eval:demo-flow`.

## Frequently Asked Questions

### What build system does OpenWork use?

OpenWork uses **pnpm** for package management and **TurboRepo** for build orchestration. The [`turbo.json`](https://github.com/different-ai/openwork/blob/main/turbo.json) file defines pipelines that cache and parallelize tasks across the monorepo, ensuring only changed packages are rebuilt during development and CI.

### How are new skills added to the OpenWork ecosystem?

Skills are added by creating JSON descriptors in `.opencode/skills/` and referencing them in [`AGENTS.md`](https://github.com/different-ai/openwork/blob/main/AGENTS.md). The CI pipeline automatically validates these definitions against the MCP schema, making them available to the desktop client runtime without requiring application rebuilds.

### What is the purpose of the `evals/` directory?

The `evals/` directory contains end-to-end test suites that use the Chrome DevTools Protocol (CDP) to drive the Electron application programmatically. These tests generate **fraimz** HTML files—proof artifacts that serve as canonical verification that the UI behaves as expected across changes.

### Where is the desktop application source code located?

The Electron-based desktop client resides in **`apps/desktop/`**, which contains the main process entry point, preload scripts, and renderer code. This application imports shared UI components from `packages/ui/` and state management from `packages/store/`.