Open Design — Repository Analysis

Generated reading of the repo at /workspaces/open-design on 2026-05-02. Reads the source as it actually exists, not what the docs aspire to.

This folder is a structured walk-through of the codebase. Read top-to-bottom or jump around:

Core walk-through:

File	Topic
`00-overview.md`	This file — TL;DR, the "what & why"
`01-tech-stack.md`	Languages, frameworks, dependency choices
`02-architecture.md`	System topology, components, data flow, diagrams
`03-entry-points-and-execution.md`	Where execution starts and how a request flows
`04-llm-and-prompts.md`	How LLMs are leveraged, prompt stack, guardrails
`05-design-patterns.md`	Patterns, tradeoffs, clever bits
`06-key-files.md`	File-by-file map of the essential surfaces
`07-takeaways.md`	What's worth stealing; what to be careful of

Comparative & applied:

File	Topic
`08-comparison-claude-code.md`	Why OD-around-Claude-Code ≠ bare Claude Code; what the wrapping actually buys
`09-lessons-for-swisscheese.md`	Applying OD's patterns to Swisscheese (code-review-at-scale): what transfers, what adapts, what to avoid

1. Purpose & problem in one paragraph

Open Design (OD) is the open-source, self-hostable counterpart to Anthropic's Claude Design. The product turns natural-language briefs ("make me a magazine-style pitch deck for our seed round") into editable, previewable design artifacts — single-page HTML prototypes, multi-slide decks, mobile-app screens, dashboards, magazine pages, even short videos and audio clips. It refuses to own the agent loop: instead it auto-detects whichever code-agent CLI the user already has installed (Claude Code, Codex, Devin for Terminal, Cursor Agent, Gemini CLI, OpenCode, Qwen, GitHub Copilot CLI, Hermes, Kimi, Pi, Kiro — twelve in total) and drives that CLI through a curated stack of skills, design systems, and craft references. When no CLI is installed, an OpenAI-compatible BYOK proxy at /api/proxy/{anthropic,openai}/stream provides a degraded but working fallback (apps/daemon/src/server.ts:2209-2287).

The pain it solves: Claude Design is closed, paid, cloud-only, and locked to one model. The strongest agents are already on the user's laptop; what's missing is the integration shell — a designer-grade prompt stack, a skill protocol, a 72-system design library, an artifact preview pipeline, and a brokering daemon — that lets any of those agents produce design-quality output. OD is that shell.

2. Who it's for

Indie devs / designers who already pay for one coding agent and don't want a second subscription.
Design-system maintainers who want to write DESIGN.md once and have every artifact pick it up.
Skill authors who want to publish a forkable design skill (e.g. "SaaS marketing page with glassmorphism") that runs in any compatible agent.
Teams self-hosting AI tooling who need a Vercel deploy + local daemon, with keys staying in their own infra.

3. Mental model in 5 lines

Web app = chat UI + sandboxed iframe preview + artifact tree. Pure SPA; no API routes.
Local daemon = the only privileged process. Detects CLIs, scans skills, brokers HTTP/SSE, owns SQLite + the project filesystem.
Code-agent CLI = the agent loop. The daemon spawns it with cwd pinned to the project, streams its stdout (JSON Lines / ACP / Pi-RPC / plain text) back to the browser as Server-Sent Events.
Skills + design systems + craft = file-based extension points. A skill is <dir>/SKILL.md (Claude Code's convention) plus optional od: frontmatter. Drop a folder, it shows up in the picker.
Prompt composer at apps/daemon/src/prompts/system.ts stitches discovery directives → official designer prompt → DESIGN.md → craft refs → skill body → project metadata → deck framework → media contract — the order matters and is load-bearing.

4. What is unusually opinionated about this codebase

Choice	Where	Why it matters
Discovery form on turn 1, not free-text	`prompts/discovery.ts:34-71`	Locks brief in <30s of radio clicks before any pixel is written; the single biggest reduction in AI-slop variance.
Direction picker as a 2nd form	`prompts/discovery.ts:87-101`, `prompts/directions.ts:53-184`	When the user has no brand, the agent picks from 5 deterministic packages (Editorial Monocle / Modern Minimal / Warm Soft / Tech Utility / Brutalist Experimental). One radio click → an OKLch palette + font stack bound verbatim into `:root`. No model freestyle.
5-dimensional self-critique before emitting `<artifact>`	`prompts/discovery.ts:156-166`	Score yourself across Philosophy / Hierarchy / Execution / Specificity / Restraint; any dim < 3/5 triggers a fix pass.
Auto-enforced anti-AI-slop linter	`apps/daemon/src/lint-artifact.ts:124-387`	9 P0 patterns (Tailwind indigo, two-stop trust gradient, emoji-as-icon, sans-on-display, left-accent-card, invented metrics, filler copy, etc.) flagged on every artifact save. Findings feed back into the agent for self-correction.
Five-field sidecar process stamp	`packages/sidecar-proto/src/index.ts`	Every spawned process carries `--od-stamp-app=… --od-stamp-mode=… --od-stamp-namespace=… --od-stamp-ipc=… --od-stamp-source=…`, so multiple concurrent dev sessions don't collide.
Plain-files-on-disk artifact store	`apps/daemon/src/projects.ts`, `.od/projects/<id>/`	Project files are real files; SQLite holds metadata only. Users can `git add ./.od/`.
Media generation as agent-side shell call	`prompts/media-contract.ts:37-340`, `apps/daemon/src/cli.ts` (media subcommand)	The agent does not fabricate `<artifact>` bytes for image/video/audio; it dispatches `od media generate --surface … --model … --prompt …` which the daemon proxies to the right provider. Same loop across all 12 CLIs.

5. Repo size & shape (rough numbers)

Area	Size cue
`apps/daemon/src/*.ts`	~15,000 lines across 30 files (`server.ts` 2,433; `media.ts` 1,690; `lint-artifact.ts` 980; `db.ts` 941)
`apps/web/src/`	React 18 SPA — components, runtime, state, comments
`apps/desktop/`, `apps/packaged/`	Thin Electron shells; desktop discovers daemon via sidecar IPC
`packages/{contracts, sidecar-proto, sidecar, platform}`	Typed boundaries: web/daemon DTOs, sidecar protocol, generic OS primitives
`tools/dev`, `tools/pack`	Lifecycle CLIs (`pnpm tools-dev`, `pnpm tools-pack`)
`skills/`	31 skills in `prototype` + `deck` modes, plus html-ppt variants
`design-systems/`	129 systems (Linear, Stripe, Vercel, Airbnb, Notion, Anthropic, Apple, Cursor, Supabase, Figma, Xiaohongshu, …)
`craft/`	Universal brand-agnostic rules — `anti-ai-slop.md`, `color.md`, `typography.md`
`prompt-templates/`	93 prompt examples for image/video media surfaces
`scripts/`	13 maintenance scripts (sync design-systems, pets, litellm, residual-js check)

6. License and provenance

Apache-2.0. Stands on four open-source shoulders, credited explicitly in README.md:42-47:

alchaincyf/huashu-design — design philosophy, Junior-Designer workflow, 5-dim critique, anti-slop checklist, "5 schools × 20 philosophies" idea behind the direction picker.
op7418/guizang-ppt-skill — bundled verbatim under skills/guizang-ppt/ with original LICENSE preserved.
OpenCoworkAI/open-codesign — UX north star: streaming-artifact loop, sandboxed-iframe preview, live agent panel, 5-format export.
multica-ai/multica — daemon-and-runtime architecture: PATH-scan agent detection, daemon as the only privileged process.