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

> Explore the Openwork project structure a pnpm workspace monorepo featuring an Electron client a Den control plane shared TS packages and evaluation suites all managed by TurboRepo and secured by Warden.

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

---

**Openwork is organized as a pnpm workspace monoreo containing an Electron-based desktop client, a web-based Den control plane, shared TypeScript packages, and end-to-end evaluation suites that generate fraimz proofs, all orchestrated via TurboRepo and secured through the Warden static-analysis framework.**

The Openwork repository (different-ai/openwork) implements a modern monorepo architecture that separates runnable applications from reusable libraries while enforcing strict security and testing standards. Understanding how this codebase is structured is essential for contributors extending the desktop client, adding OpenCode skills, or troubleshooting build pipelines.

## Repository Layout Overview

The repository root organizes code into distinct functional domains. At the highest level, Openwork separates applications from shared libraries, testing infrastructure, and specialized configuration files.

### Applications (apps/)

The `apps/` directory houses the primary deliverables. The `apps/desktop/` folder contains the Electron-based client with its main process, preload scripts, and renderer code. The `apps/den/` folder hosts the web-based cloud control plane and API gateway. Each application maintains its own Vite configuration and entry points while importing shared components from the workspace.

### Shared Packages (packages/)

Reusable TypeScript libraries live in `packages/`, including the React component library at `packages/ui/` (based on shadcn/ui), state management stores, and API clients. These packages are published internally within the workspace and consumed by both the desktop and web applications.

### Testing & Validation (evals/)

The `evals/` directory contains end-to-end test suites that drive the Electron application via CDP (Chrome DevTools Protocol). These scripts generate **fraimz** proof-of-concept artifacts in `evals/results/<run-id>/fraimz.html` that serve as the canonical verification of UI behavior across changes.

### Documentation & Examples

Supporting materials include `docs/` for public documentation and tutorials, `examples/` for reference projects demonstrating skill embedding, and `prds/` containing product requirement documents that act as demo-first specifications for new features.

### Configuration & Tooling

Infrastructure folders include `.github/` for CI/CD workflows, `.devcontainer/` for standardized VS Code development environments, and `scripts/` for automation tasks like version bumping and changelog generation. The `.opencode/` directory stores skill registries and MCP (Model Container Protocol) definitions consumed by the runtime at execution time.

## Key Configuration Files

Several root-level files define how the monorepo behaves and orchestrates builds:

- **[`pnpm-workspace.yaml`](https://github.com/different-ai/openwork/blob/main/pnpm-workspace.yaml)**: Declares all package locations, enabling pnpm to hoist shared dependencies and execute commands across the entire repository using `pnpm dev` or `pnpm build`.
- **[`turbo.json`](https://github.com/different-ai/openwork/blob/main/turbo.json)**: Configures TurboRepo pipelines with dependency graphs for install, build, lint, and test tasks, ensuring only modified packages trigger rebuilds and dramatically speeding up CI.
- **[`warden.toml`](https://github.com/different-ai/openwork/blob/main/warden.toml)**: Defines security policies for the **Warden** static-analysis framework, which performs automated diff-security reviews during pull requests by evaluating definitions in `.warden/skills/`.
- **[`package.json`](https://github.com/different-ai/openwork/blob/main/package.json)**: Contains root-level scripts, workspace metadata, and top-level dependencies that apply across all packages.
- **[`AGENTS.md`](https://github.com/different-ai/openwork/blob/main/AGENTS.md)**: Documents built-in Openwork agents, available skills, and MCP endpoints for the OpenCode integration.

## How the Architecture Fits Together

The Openwork project structure follows a specific orchestration pattern that connects development, security, and runtime components:

1. **Workspace Resolution**: [`pnpm-workspace.yaml`](https://github.com/different-ai/openwork/blob/main/pnpm-workspace.yaml) identifies all folders containing [`package.json`](https://github.com/different-ai/openwork/blob/main/package.json) files, establishing the pnpm workspace boundaries and internal package linking.

2. **Build Orchestration**: TurboRepo reads [`turbo.json`](https://github.com/different-ai/openwork/blob/main/turbo.json) to parallelize builds across the dependency graph, caching results to accelerate both local development and CI pipelines.

3. **Security Enforcement**: Warden evaluates [`warden.toml`](https://github.com/different-ai/openwork/blob/main/warden.toml) and `.warden/skills/` definitions to lint code for security issues before merge, providing automated diff reviews.

4. **Runtime Integration**: The desktop client loads skills from `.opencode/skills/` via MCP definitions referenced in [`AGENTS.md`](https://github.com/different-ai/openwork/blob/main/AGENTS.md), enabling dynamic agent capabilities.

5. **Verification**: The `evals/` suite launches the built Electron application, drives interactions through CDP, and generates fraimz HTML reports that verify UI behavior.

## Working with the Openwork Codebase

### Starting Development

Install dependencies and launch the default development profile:

```bash
pnpm install
pnpm dev

```

This starts the Vite dev server and Electron client, printing a banner with the CDP endpoint:

```

[openwork] dev profile=default cdp=http://127.0.0.1:9223

```

### Running End-to-End Evaluations

Execute the evaluation suite to generate fraimz proof artifacts:

```bash
pnpm run eval:demo-flow

```

This script located in `evals/demo-flow/` produces verification reports at `evals/results/<run-id>/fraimz.html`.

### Adding a New UI Component

Create shared components using the workspace scaffolding:

```bash
pnpm exec nx generate @nrwl/react:library button --directory=packages/ui

```

Then import the component into the desktop application:

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

```

### Registering an OpenCode Skill

Add skill descriptors to `.opencode/skills/`:

```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" } } }
}

```

Reference the skill in [`AGENTS.md`](https://github.com/different-ai/openwork/blob/main/AGENTS.md) and commit to trigger automatic validation via the CI pipeline defined in `.github/workflows/`.

## Summary

- Openwork uses a **pnpm workspace** monorepo structure separating `apps/`, `packages/`, and `evals/` into distinct functional domains.
- **TurboRepo** orchestrates builds via [`turbo.json`](https://github.com/different-ai/openwork/blob/main/turbo.json), caching incremental changes to optimize CI performance.
- **Warden** provides automated security analysis through [`warden.toml`](https://github.com/different-ai/openwork/blob/main/warden.toml) and `.warden/skills/` definitions.
- The **OpenCode runtime** consumes skill definitions from `.opencode/` and MCP configurations referenced in [`AGENTS.md`](https://github.com/different-ai/openwork/blob/main/AGENTS.md).
- **Fraimz** proofs in `evals/` provide end-to-end verification via CDP automation, generating HTML reports in `evals/results/`.

## Frequently Asked Questions

### What is the purpose of the Den application in Openwork?

The Den application (`apps/den/`) serves as the web-based cloud control plane and API gateway, complementing the desktop Electron client by providing browser-accessible management interfaces and backend services for remote skill orchestration.

### How does Openwork handle package dependencies across the monorepo?

Openwork leverages pnpm workspaces defined in [`pnpm-workspace.yaml`](https://github.com/different-ai/openwork/blob/main/pnpm-workspace.yaml) to hoist shared dependencies and link internal packages, allowing consistent versioning across `apps/desktop/` and `apps/den/` while preventing duplicate installations of common libraries like React or TypeScript.

### What are fraimz proofs in the evals directory?

Fraimz proofs are HTML artifacts generated by end-to-end tests in `evals/` that drive the Electron application via Chrome DevTools Protocol (CDP). These files provide visual and functional verification of UI behavior, serving as the definitive proof that features work correctly before merging changes.

### Where are OpenCode skills defined in the repository?

Skills are defined as JSON descriptors in `.opencode/skills/` and referenced in [`AGENTS.md`](https://github.com/different-ai/openwork/blob/main/AGENTS.md). The desktop client loads these at runtime through the Model Container Protocol (MCP), enabling dynamic skill registration and extending agent capabilities without recompiling the application.