# opencoworkai/open-codesign architecture

> Architecture diagram of the GitHub repository opencoworkai/open-codesign, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/opencoworkai/open-codesign
- Repository: https://github.com/opencoworkai/open-codesign

## Overview

1. **Repository shape**
   This is a pnpm monorepo centered on a local desktop app. The main product lives in `apps/desktop`, while reusable logic is split into packages for the agent engine, providers, runtime, exports, shared types, UI primitives, templates, and i18n. The repo also includes a VitePress marketing/docs site and packaging manifests for desktop distribution.

2. **Primary product boundary: Electron desktop app**
   `apps/desktop` is an Electron app with a strict three-part boundary: `main` process for OS access and orchestration, `preload` for the safe bridge, and `renderer` for the React UI. The renderer is the visible product; the main process owns filesystem, credentials, IPC, updates, diagnostics, and process control.

3. **User-facing workflow**
   The app is built around a prompt-to-artifact flow. A user picks or imports a provider, starts a design session, and the app generates and iterates on a local workspace containing files for the artifact. The UI emphasizes live agent activity, previews, comments, tweaks, file inspection, and export rather than a simple chat-only interaction.

4. **Agent and tool engine**
   `packages/core` is the orchestration layer. It defines the agent session model, run protocol, prompt composition, memory/context pruning, skills loading, tool manifests, and the built-in tools such as `ask`, `done`, `scaffold`, `preview`, `skill`, `text-editor`, `inspect-workspace`, `generate-image-asset`, and `tweaks`. This package is the core “brain” that turns a prompt into a controlled sequence of file and preview operations.

5. **Local workspace as the source of truth**
   The v0.2 architecture is workspace-backed: each design is a session plus a directory on disk, with JSONL history and editable files such as `DESIGN.md`. Main-process modules like `workspace-*`, `session-chat`, `generation-workspace`, `design-workspace`, `workspace-reader`, and `workspace-watcher` manage persistence, naming, inspection, and synchronization. This makes iteration and history local-first rather than cloud-state-driven.

6. **Provider abstraction and model access**
   `packages/providers` normalizes many model backends behind a unified interface: Claude, OpenAI, Gemini, OpenRouter, DeepSeek, SiliconFlow, Ollama, and OpenAI-compatible relays. It also includes Codex OAuth/token handling and subscription sign-in support. In the app, provider settings, key resolution, validation, diagnostics, and import flows live in `apps/desktop/src/main/*` and feed the agent engine with the chosen model config.

7. **Onboarding, imports, and credentials**
   There is a dedicated onboarding path for bringing in existing provider configs from Claude Code, Codex, Gemini CLI, and OpenCode-like setups. The main process handles config parsing, safe reads, storage, and OAuth bridge logic, while the renderer provides the onboarding UI. Credentials are kept local in config files and the app’s token store, with diagnostics and redaction support to avoid exposing secrets.

8. **Preview/runtime boundary**
   Artifact rendering is split from the main app. `packages/runtime` provides the sandboxed runtime for live previews, including iframe error handling and tweak bridging. The renderer preview area consumes workspace files and renders them in a controlled iframe/sandbox, while the main process supports preview orchestration and document/preview file access.

9. **Renderer architecture**
   The renderer is a React + Vite UI organized into reusable components, state slices, hooks, and view-level screens. It contains the app shell, sidebar, tabs, chat, comment mode, design switcher, settings, diagnostics panels, previews, and toasts. State is centralized in store slices for designs, chat, comments, generation, snapshots, tabs, theme, usage, and errors, which keeps the UI responsive while the main process owns durable state and side effects.

10. **Shared contracts and formatting**
    `packages/shared` holds cross-cutting data models and utilities that need to be consistent across app, core, and packages: artifacts, snapshots, fingerprints, config, error codes, edit-mode state, resource manifests, tool manifests, diagnostics, and source entries. This package is effectively the contract layer between renderer, main, core, and providers.

11. **Artifacts, exporters, and outputs**
    Generated content can be exported through `packages/exporters` into HTML, PDF, PPTX, ZIP, and Markdown. These exporters sit outside the agent loop and consume the produced files/rendered output. The repo’s architecture treats export as a downstream packaging step, not as part of generation itself.

12. **Templates, skills, and design system inputs**
    The app ships a large built-in template library under `apps/desktop/resources/templates` and `packages/templates`, plus design skills and prompt sections in `packages/core/src/design-skills` and `packages/core/src/prompts`. These resources shape generation quality by providing structured starting points, UI patterns, brand references, and style guidance that the agent can inject into prompts.

13. **UI kit and brand layer**
    `packages/ui` contains shared visual primitives such as buttons, cards, icon buttons, tooltips, fonts, and tokens. This package supports consistent styling across the desktop app and is paired with Tailwind and design tokens, so the renderer’s visual language is standardized rather than ad hoc.

14. **Operational concerns: diagnostics, updates, and packaging**
    The main process includes diagnostics collection, log rotation, update wiring, permissions, keychain access, and process registry management. Distribution is handled through `electron-builder` plus platform packaging folders and GitHub Actions release workflows. The repo therefore has a clear split between runtime orchestration inside Electron and release automation outside the app.

15. **Documentation and website**
    The `website` directory is a separate VitePress site for product marketing, docs, quickstart, roadmap, and architecture notes. It is not part of the runtime app, but it documents the same system boundaries and serves as the public-facing explanation of the product architecture.

Main entry points: [`apps/desktop/src/renderer/src`](https://github.com/opencoworkai/open-codesign/tree/main/apps/desktop/src/renderer/src) (Renderer UI), [`apps/desktop/src/main`](https://github.com/opencoworkai/open-codesign/tree/main/apps/desktop/src/main) (Main process), [`packages/core/src`](https://github.com/opencoworkai/open-codesign/tree/main/packages/core/src) (Agent core), [`packages/shared/src`](https://github.com/opencoworkai/open-codesign/tree/main/packages/shared/src) (Shared contracts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_repo["Monorepo"]
  node_root["open-codesign<br/>pnpm monorepo"]
end

subgraph group_desktop["Desktop App"]
  node_desktop_main["Main process<br/>electron orchestration"]
  node_desktop_preload["Preload bridge<br/>secure bridge<br/>[index.ts]"]
  node_desktop_renderer["Renderer UI<br/>react app"]
  node_workspace_layer[("Workspace layer<br/>local state")]
  node_provider_layer["Provider layer<br/>model access"]
  node_preview_boundary["Preview boundary<br/>sandbox runtime<br/>[preview-runtime.ts]"]
end

subgraph group_packages["Shared Packages"]
  node_core_engine["Agent core<br/>orchestration engine"]
  node_core_tools["Core tools<br/>toolset"]
  node_shared_contracts["Shared contracts<br/>cross-package models"]
  node_providers_pkg["Providers<br/>model adapters"]
  node_runtime_pkg["Runtime<br/>preview sandbox"]
  node_exporters_pkg["Exporters<br/>artifact outputs"]
  node_templates_pkg["Templates<br/>starter library"]
  node_ui_pkg["UI kit<br/>design system"]
  node_i18n_pkg["i18n<br/>localization"]
end

subgraph group_website["Docs Site"]
  node_website_site["Website<br/>VitePress site"]
end

subgraph group_release["Release Ops"]
  node_packaging_ops["Packaging<br/>distribution"]
end

node_root -->|"contains"| node_desktop_main
node_root -->|"contains"| node_desktop_preload
node_root -->|"contains"| node_desktop_renderer
node_root -->|"contains"| node_core_engine
node_root -->|"contains"| node_providers_pkg
node_root -->|"contains"| node_runtime_pkg
node_root -->|"contains"| node_exporters_pkg
node_root -->|"contains"| node_templates_pkg
node_root -->|"contains"| node_ui_pkg
node_root -->|"contains"| node_shared_contracts
node_root -->|"contains"| node_i18n_pkg
node_root -->|"contains"| node_website_site
node_root -->|"contains"| node_packaging_ops
node_desktop_main -->|"owns"| node_workspace_layer
node_desktop_main -->|"feeds"| node_provider_layer
node_desktop_main -->|"orchestrates"| node_preview_boundary
node_desktop_main -->|"invokes"| node_core_engine
node_desktop_preload -->|"bridges"| node_desktop_renderer
node_desktop_renderer -->|"uses"| node_shared_contracts
node_desktop_renderer -->|"composes"| node_ui_pkg
node_desktop_renderer -->|"renders in"| node_runtime_pkg
node_desktop_renderer -->|"drives"| node_core_tools
node_core_engine -->|"registers"| node_core_tools
node_core_engine -->|"shares"| node_shared_contracts
node_core_engine -->|"injects"| node_templates_pkg
node_core_engine -->|"calls"| node_providers_pkg
node_providers_pkg -->|"normalizes"| node_shared_contracts
node_runtime_pkg -->|"embeds"| node_desktop_renderer
node_exporters_pkg -->|"consumes"| node_shared_contracts
node_website_site -.->|"documents"| node_shared_contracts
node_packaging_ops -->|"packages"| node_desktop_main

click node_desktop_main "https://github.com/opencoworkai/open-codesign/tree/main/apps/desktop/src/main"
click node_desktop_preload "https://github.com/opencoworkai/open-codesign/blob/main/apps/desktop/src/preload/index.ts"
click node_desktop_renderer "https://github.com/opencoworkai/open-codesign/tree/main/apps/desktop/src/renderer/src"
click node_workspace_layer "https://github.com/opencoworkai/open-codesign/blob/main/apps/desktop/src/main/workspace-reader.ts"
click node_provider_layer "https://github.com/opencoworkai/open-codesign/blob/main/apps/desktop/src/main/provider-context.ts"
click node_preview_boundary "https://github.com/opencoworkai/open-codesign/blob/main/apps/desktop/src/main/preview-runtime.ts"
click node_core_engine "https://github.com/opencoworkai/open-codesign/tree/main/packages/core/src"
click node_core_tools "https://github.com/opencoworkai/open-codesign/tree/main/packages/core/src/tools"
click node_shared_contracts "https://github.com/opencoworkai/open-codesign/tree/main/packages/shared/src"
click node_providers_pkg "https://github.com/opencoworkai/open-codesign/tree/main/packages/providers/src"
click node_runtime_pkg "https://github.com/opencoworkai/open-codesign/tree/main/packages/runtime/src"
click node_exporters_pkg "https://github.com/opencoworkai/open-codesign/tree/main/packages/exporters/src"
click node_templates_pkg "https://github.com/opencoworkai/open-codesign/tree/main/packages/templates/src"
click node_ui_pkg "https://github.com/opencoworkai/open-codesign/tree/main/packages/ui/src"
click node_i18n_pkg "https://github.com/opencoworkai/open-codesign/tree/main/packages/i18n/src"
click node_packaging_ops "https://github.com/opencoworkai/open-codesign/tree/main/packaging"
click node_website_site "https://github.com/opencoworkai/open-codesign/tree/main/website"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_root toneBlue
class node_desktop_main,node_desktop_preload,node_desktop_renderer,node_workspace_layer,node_provider_layer,node_preview_boundary toneAmber
class node_core_engine,node_core_tools,node_shared_contracts,node_providers_pkg,node_runtime_pkg,node_exporters_pkg,node_templates_pkg,node_ui_pkg,node_i18n_pkg toneMint
class node_website_site toneRose
class node_packaging_ops toneIndigo
```

## Components

### Monorepo

pnpm workspace coordinating app, packages, packaging, and site.

- **open-codesign**: pnpm monorepo · Workspace root for the desktop product, shared packages, docs, and release tooling.

### Desktop App

Electron product boundary with main, preload, and renderer.

- [Main process](https://github.com/opencoworkai/open-codesign/tree/main/apps/desktop/src/main): electron orchestration · Owns OS integration, IPC, credentials, diagnostics, updates, workspace persistence, and process control. · `apps/desktop/src/main`
- [Preload bridge](https://github.com/opencoworkai/open-codesign/blob/main/apps/desktop/src/preload/index.ts): secure bridge · Safe boundary exposing a constrained API from Electron main to renderer. · `apps/desktop/src/preload/index.ts`
- [Renderer UI](https://github.com/opencoworkai/open-codesign/tree/main/apps/desktop/src/renderer/src): react app · Visible desktop experience with shell, chat, previews, comments, settings, and design navigation. · `apps/desktop/src/renderer/src`
- [Workspace layer](https://github.com/opencoworkai/open-codesign/blob/main/apps/desktop/src/main/workspace-reader.ts): local state · Session-backed on-disk designs, history, inspection, naming, watching, and sync. · `apps/desktop/src/main/workspace-reader.ts`
- [Provider layer](https://github.com/opencoworkai/open-codesign/blob/main/apps/desktop/src/main/provider-context.ts): model access · Unified model/provider settings, validation, auth, key resolution, and onboarding imports. · `apps/desktop/src/main/provider-context.ts`
- [Preview boundary](https://github.com/opencoworkai/open-codesign/blob/main/apps/desktop/src/main/preview-runtime.ts): sandbox runtime · Orchestrates document previews and sandboxed artifact rendering outside the main app UI. · `apps/desktop/src/main/preview-runtime.ts`

### Shared Packages

Reusable engine, runtime, providers, exports, contracts, UI, templates, and i18n.

- [Agent core](https://github.com/opencoworkai/open-codesign/tree/main/packages/core/src): orchestration engine · Session model, run protocol, prompt composition, context pruning, memory, skills, and built-in tools. · `packages/core/src`
- [Core tools](https://github.com/opencoworkai/open-codesign/tree/main/packages/core/src/tools): toolset · Controlled operations such as ask, done, scaffold, preview, skill, text editing, inspection, image asset generation, and tweaks. · `packages/core/src/tools`
- [Shared contracts](https://github.com/opencoworkai/open-codesign/tree/main/packages/shared/src): cross-package models · Artifacts, snapshots, config, diagnostics, error codes, edit mode, resource manifests, and tool manifests. · `packages/shared/src`
- [Providers](https://github.com/opencoworkai/open-codesign/tree/main/packages/providers/src): model adapters · Backend adapters for Claude, OpenAI, Gemini, OpenRouter, DeepSeek, SiliconFlow, Ollama, and compatible relays. · `packages/providers/src`
- [Runtime](https://github.com/opencoworkai/open-codesign/tree/main/packages/runtime/src): preview sandbox · Iframe error handling, overlay behavior, and tweaks bridging for live artifact previews. · `packages/runtime/src`
- [Exporters](https://github.com/opencoworkai/open-codesign/tree/main/packages/exporters/src): artifact outputs · Downstream packaging into HTML, PDF, PPTX, ZIP, and Markdown exports. · `packages/exporters/src`
- [Templates](https://github.com/opencoworkai/open-codesign/tree/main/packages/templates/src): starter library · Built-in examples, scaffolds, localized prompts, and thumbnails that seed generation quality. · `packages/templates/src`
- [UI kit](https://github.com/opencoworkai/open-codesign/tree/main/packages/ui/src): design system · Shared visual primitives, fonts, icons, and tokens used by the desktop renderer. · `packages/ui/src`
- [i18n](https://github.com/opencoworkai/open-codesign/tree/main/packages/i18n/src): localization · Locale strings and error/message translation resources shared across the workspace. · `packages/i18n/src`

### Docs Site

VitePress marketing and documentation site.

- [Website](https://github.com/opencoworkai/open-codesign/tree/main/website): VitePress site · Marketing, quickstart, roadmap, and architecture documentation for the product. · `website`

### Release Ops

Packaging manifests and GitHub automation for distribution.

- [Packaging](https://github.com/opencoworkai/open-codesign/tree/main/packaging): distribution · Electron-builder manifests and platform packaging files for desktop releases. · `packaging`

## Connections

- open-codesign → Main process: contains · Workspace root includes the Electron main process boundary.
- open-codesign → Preload bridge: contains · Workspace root includes preload bridge code.
- open-codesign → Renderer UI: contains · Workspace root includes the React renderer UI.
- open-codesign → Agent core: contains · Workspace root includes agent orchestration package.
- open-codesign → Providers: contains · Workspace root includes model adapters.
- open-codesign → Runtime: contains · Workspace root includes preview runtime.
- open-codesign → Exporters: contains · Workspace root includes export formats.
- open-codesign → Templates: contains · Workspace root includes generation templates.
- open-codesign → UI kit: contains · Workspace root includes shared UI primitives.
- open-codesign → Shared contracts: contains · Workspace root includes shared cross-package contracts.
- open-codesign → i18n: contains · Workspace root includes localization resources.
- open-codesign → Website: contains · Workspace root includes docs site.
- open-codesign → Packaging: contains · Workspace root includes release packaging assets.
- Main process → Workspace layer: owns · Main process manages local design sessions and on-disk workspace state.
- Main process → Provider layer: feeds · Main process resolves provider settings and credentials for runs.
- Main process → Preview boundary: orchestrates · Main process coordinates preview runtime and file access.
- Main process → Agent core: invokes · Main process delegates generation to the agent engine.
- Preload bridge → Renderer UI: bridges · Preload exposes safe APIs to the renderer.
- Renderer UI → Shared contracts: uses · Renderer reads shared artifact, snapshot, and diagnostics contracts.
- Renderer UI → UI kit: composes · Renderer builds the UI with shared primitives.
- Renderer UI → Runtime: renders in · Preview area consumes the sandbox runtime.
- Renderer UI → Core tools: drives · UI actions map to agent tools and session operations.
- Agent core → Core tools: registers · Engine defines and executes built-in tools.
- Agent core → Shared contracts: shares · Engine and app share session, tool, and artifact contracts.
- Agent core → Templates: injects · Engine composes prompts with templates and skills resources.
- Agent core → Providers: calls · Engine uses model adapters for generation.
- Providers → Shared contracts: normalizes · Providers expose validated configs and common error shapes.
- Runtime → Renderer UI: embeds · Preview runtime is consumed by the renderer preview pane.
- Exporters → Shared contracts: consumes · Exporters consume generated artifact and snapshot data.
- Website → Shared contracts: documents · Docs explain the same architecture and product contracts.
- Packaging → Main process: packages · Release tooling bundles the Electron app for distribution.
