How opencoworkai/open-codesign works
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: renderer/src Renderer UI · main Main process · core/src Agent core · shared/src Shared contracts
Components 18
Monorepo
pnpm workspace coordinating app, packages, packaging, and site.
- open-codesign · Workspace root for the desktop product, shared packages, docs, and release tooling.
Desktop App
Electron product boundary with main, preload, and renderer.
- Main process · Owns OS integration, IPC, credentials, diagnostics, updates, workspace persistence, and process control.
apps/desktop/src/main - Preload bridge · Safe boundary exposing a constrained API from Electron main to renderer.
apps/desktop/src/preload/index.ts - Renderer UI · Visible desktop experience with shell, chat, previews, comments, settings, and design navigation.
apps/desktop/src/renderer/src - Workspace layer · Session-backed on-disk designs, history, inspection, naming, watching, and sync.
apps/desktop/src/main/workspace-reader.ts - Provider layer · Unified model/provider settings, validation, auth, key resolution, and onboarding imports.
apps/desktop/src/main/provider-context.ts - Preview boundary · 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 · Session model, run protocol, prompt composition, context pruning, memory, skills, and built-in tools.
packages/core/src - Core tools · Controlled operations such as ask, done, scaffold, preview, skill, text editing, inspection, image asset generation, and tweaks.
packages/core/src/tools - Shared contracts · Artifacts, snapshots, config, diagnostics, error codes, edit mode, resource manifests, and tool manifests.
packages/shared/src - Providers · Backend adapters for Claude, OpenAI, Gemini, OpenRouter, DeepSeek, SiliconFlow, Ollama, and compatible relays.
packages/providers/src - Runtime · Iframe error handling, overlay behavior, and tweaks bridging for live artifact previews.
packages/runtime/src - Exporters · Downstream packaging into HTML, PDF, PPTX, ZIP, and Markdown exports.
packages/exporters/src - Templates · Built-in examples, scaffolds, localized prompts, and thumbnails that seed generation quality.
packages/templates/src - UI kit · Shared visual primitives, fonts, icons, and tokens used by the desktop renderer.
packages/ui/src - i18n · Locale strings and error/message translation resources shared across the workspace.
packages/i18n/src
Docs Site
VitePress marketing and documentation site.
- Website · Marketing, quickstart, roadmap, and architecture documentation for the product.
website
Release Ops
Packaging manifests and GitHub automation for distribution.
- Packaging · Electron-builder manifests and platform packaging files for desktop releases.
packaging
Connections 31
- 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.