Key files
open-design
Key files
A targeted file map. Read in roughly this order to build a working mental model.
Tier 1 — start here
| File | Lines | Why it's load-bearing |
|---|---|---|
AGENTS.md |
~150 | Single source of truth for agents entering the repo. Lifecycle rules, boundary constraints, FAQ. |
docs/spec.md |
143 | Product definition, scenarios, non-goals, positioning. |
docs/architecture.md |
340 | Topologies, components, data flow, file layout, security boundaries. |
docs/skills-protocol.md |
356 | What a skill is, how OD discovers them, the od: frontmatter extensions. |
docs/agent-adapters.md |
291 | Per-CLI invocation contract; the "talk to all of them" thesis. |
docs/modes.md |
274 | Prototype / Deck / Template / Design System modes. |
Tier 2 — the daemon (where most of the work lives)
| File | Lines | Responsibility |
|---|---|---|
apps/daemon/src/server.ts |
2,433 | Express + SSE surface; /api/chat orchestration; ~70 routes; BYOK proxy. Read startChatRun() at 1856-2080 first. |
apps/daemon/src/cli.ts |
421 | od daemon entry; od media generate / wait subcommands. |
apps/daemon/src/agents.ts |
751 | 12 AGENT_DEFS, detectAgents(), capability probing, model listing, buildArgs() per CLI. |
apps/daemon/src/db.ts |
941 | SQLite schema + CRUD: projects, conversations, messages, tabs, templates, preview_comments, deployments. |
apps/daemon/src/runs.ts |
154 | In-memory chat-run service; SSE attach/emit; lifecycle states. |
apps/daemon/src/projects.ts |
300 | Path-traversal-safe filesystem CRUD for .od/projects/<id>/. |
Stream parsers
| File | Lines | For |
|---|---|---|
apps/daemon/src/claude-stream.ts |
218 | Claude Code line-delimited JSON; tool_use accumulation. |
apps/daemon/src/copilot-stream.ts |
130 | GitHub Copilot CLI JSONL → unified events. |
apps/daemon/src/acp.ts |
423 | Agent Client Protocol JSON-RPC for Devin / Hermes / Kimi / Kiro. Auto-approves permission requests. |
apps/daemon/src/pi-rpc.ts |
335 | Pi RPC; auto-replies to extension UI methods. |
apps/daemon/src/json-event-stream.ts |
331 | Generic JSON-line + plain-text fallbacks for Codex / Gemini / OpenCode / Cursor / Qwen. |
Prompts (the most distinctive part)
| File | Lines | What it injects |
|---|---|---|
apps/daemon/src/prompts/system.ts |
397 | The composer. composeSystemPrompt() at 109-191, metadata block at 193-374, pre-flight derivation at 388-397. |
apps/daemon/src/prompts/discovery.ts |
263 | Turn-1 question-form, turn-2 brand branch, TodoWrite + 5-dim critique, anti-AI-slop checklist. |
apps/daemon/src/prompts/directions.ts |
284 | 5 design directions (Editorial Monocle / Modern Minimal / Warm Soft / Tech Utility / Brutalist Experimental); renderDirectionFormBody() + renderDirectionSpecBlock(). |
apps/daemon/src/prompts/deck-framework.ts |
374 | Verbatim 1920×1080 deck skeleton with scaling JS, prev/next, counter, position-restore, @media print. Lists 9 drift modes to avoid. |
apps/daemon/src/prompts/media-contract.ts |
340 | Image/video/audio agents must dispatch via od media generate; allowed model IDs; long-running task loop with od media wait. |
apps/daemon/src/prompts/official-system.ts |
118 | OD-adapted "expert designer" base prompt: identity, workflow, content philosophy, do-not-divulge, React/Babel pinned versions. |
Other daemon subsystems
| File | Lines | Purpose |
|---|---|---|
apps/daemon/src/skills.ts |
249 | Scan <projectRoot>/skills/<id>/SKILL.md; parse frontmatter; merge od.* extensions with sniffed defaults. |
apps/daemon/src/design-systems.ts |
167 | Scan DESIGN.md files; regex-extract title / category / 4-color signature. |
apps/daemon/src/craft.ts |
46 | Load craft/<slug>.md files for od.craft.requires. Missing files are silent. |
apps/daemon/src/lint-artifact.ts |
980 | Anti-AI-slop linter; 9 P0 + N P1 + N P2 patterns. Findings feed back into agent context via renderFindingsForAgent(). |
apps/daemon/src/media.ts |
1,690 | Image/video/audio dispatcher: OpenAI / Volcengine / Grok / HyperFrames. Path-traversal guard + clampNumber for hallucinated args. |
apps/daemon/src/media-models.ts |
130 | Provider/model registry with caps flags (t2i / i2i / inpaint / t2v / i2v / audio / tts / music / sfx). |
apps/daemon/src/media-config.ts |
180 | Provider key storage; redacted reads. |
apps/daemon/src/deploy.ts |
616 | Vercel deployment; HTML reference rewriting; deploy hook injection. |
apps/daemon/src/claude-design-import.ts |
145 | ZIP unpack with zip-slip / encryption / size guards. |
apps/daemon/src/codex-pets.ts + community-pets-sync.ts |
278 + 311 | Codex sprite sheets and registry sync (mascots in the UI). |
apps/daemon/src/document-preview.ts |
294 | Preview rendering for non-HTML artifacts. |
apps/daemon/src/design-system-preview.ts |
620 | Renders a DESIGN.md as a sample-components page. |
apps/daemon/src/design-system-showcase.ts |
723 | Renders a showcase gallery for a design system. |
apps/daemon/src/artifact-manifest.ts |
259 | Validates artifact metadata before write. |
apps/daemon/src/frontmatter.ts |
137 | YAML frontmatter parser. |
apps/daemon/src/app-version.ts |
104 | Version info surfacing. |
Tier 3 — the web
| File | Purpose |
|---|---|
apps/web/app/[[...slug]]/page.tsx |
Catch-all SPA entry — generates one static export, renders <ClientApp />. |
apps/web/app/[[...slug]]/client-app.tsx |
Client-side bootstrap. |
apps/web/src/App.tsx |
App shell. |
apps/web/src/router.ts |
Reads window.location to decide which view to render. |
apps/web/next.config.ts |
Dev-mode rewrites /api/*, /artifacts/*, /frames/* → daemon OD_PORT. |
apps/web/sidecar/server.ts |
Web sidecar; resolveDaemonProxyTarget() validates allowlisted proxy paths and prevents SSRF. |
apps/web/src/sidecar-proxy.test.ts |
Tests the proxy allowlist. |
UI components (apps/web/src/components/)
| Component | Role |
|---|---|
EntryView.tsx |
Skill picker, design-system picker, brief textarea — the first thing the user sees. |
ProjectView.tsx |
Project workspace shell wrapping the chat + workspace + preview. |
ChatPane.tsx, ChatComposer.tsx |
Message list and input box. |
AssistantMessage.tsx |
Renders agent text + tool calls + artifacts. |
ToolCard.tsx |
Per-tool-call card; consumes runtime/tool-renderers.ts registry. |
QuestionForm.tsx |
Renders the agent's <question-form> blocks; submits answers as the next user turn. |
AgentPicker.tsx, AgentIcon.tsx, modelOptions.tsx |
Agent + model selectors. |
FileWorkspace.tsx, FileViewer.tsx |
Project files panel; click-to-open. |
PreviewModal.tsx |
Full-screen iframe preview. |
DesignSystemsTab.tsx, DesignSystemPreviewModal.tsx, DesignSpecView.tsx, DesignFilesPanel.tsx |
Design-system browsing. |
PromptTemplatesTab.tsx, PromptTemplatePreviewModal.tsx, ExamplesTab.tsx, DesignsTab.tsx |
Galleries for prompt templates / examples / designs. |
NewProjectPanel.tsx |
Project creation; metadata capture. |
SettingsDialog.tsx |
API keys, model overrides, theme. |
PasteTextDialog.tsx, SketchEditor.tsx |
Input modalities for image/wireframe attachments. |
Loading.tsx, Icon.tsx, AppChromeHeader.tsx, AvatarMenu.tsx, ConversationsMenu.tsx, LanguageMenu.tsx |
Chrome. |
pet/ |
Codex pet companion (separate sub-package). |
Runtime helpers (apps/web/src/runtime/)
| File | Role |
|---|---|
srcdoc.ts |
Wraps HTML for sandboxed <iframe sandbox="allow-scripts">; injects localStorage shim. |
react-component.ts |
Loads React 18 + Babel Standalone via CDN; transpiles user JSX inline. |
tool-renderers.ts |
Hook-free registry of per-tool UI renderers. |
todos.ts |
Parses TodoWrite tool calls into the live Todos card. |
markdown.tsx |
Hand-rolled mini-markdown parser for chat output. |
exports.ts |
HTML / ZIP / JSX downloads via Blob URLs. |
zip.ts |
Pure-client stored-mode ZIP encoder with CRC32. |
State + comments
| File | Role |
|---|---|
apps/web/src/state/config.ts |
App config (api keys, model selection, theme, agent ids) — localStorage. |
apps/web/src/state/projects.ts |
REST helpers for /api/projects. |
apps/web/src/state/maxTokens.ts + litellm-models.json |
Model context/output caps. |
apps/web/src/comments.ts |
Snapshot a clicked DOM element → PreviewCommentTarget → commentAttachment for the next chat turn. |
Tier 4 — desktop / packaged
| File | Role |
|---|---|
apps/desktop/src/main/index.ts |
Electron main; runDesktopMain(); queries web URL via sidecar IPC; self-terminates if parent dies. |
apps/packaged/ (AGENTS.md + src/) |
Packaged Electron entry; starts daemon + web sidecars; registers od://. |
Tier 5 — the workspace packages
| File | Role |
|---|---|
packages/contracts/src/index.ts |
Re-exports DTOs from common, api/*, sse/*, prompts/*. |
packages/contracts/src/api/chat.ts |
ChatRequest, ChatRunCreateRequest, PersistedAgentEvent. |
packages/contracts/src/sse/chat.ts |
ChatSseEvent discriminated union. |
packages/sidecar-proto/src/index.ts |
5-field stamp definition; namespace validation; IPC message types. |
packages/sidecar/src/index.ts |
Generic bootstrapSidecarRuntime(), createJsonIpcServer(), port allocation. |
packages/platform/src/index.ts |
createProcessStampArgs(), readProcessStamp(), matchesStampedProcess(), cross-platform listProcessSnapshots(). |
Tier 6 — orchestration
| File | Role |
|---|---|
tools/dev/src/index.ts |
pnpm tools-dev CLI: start / stop / run / status / logs / inspect / check. |
tools/pack/ |
pnpm tools-pack CLI: packaged build/install/start/stop/logs/cleanup; mac beta release. |
Tier 7 — content
| Path | What's there |
|---|---|
skills/ |
31 skill folders (web-prototype, saas-landing, dashboard, mobile-app, gamified-app, magazine-poster, dating-web, sprite-animation, motion-frames, critique, tweaks, wireframe-sketch, …, plus guizang-ppt and html-ppt-* deck variants). |
design-systems/ |
129 DESIGN.md folders (Linear, Stripe, Vercel, Airbnb, Tesla, Notion, Anthropic, Apple, Cursor, Supabase, Figma, Xiaohongshu, …). |
craft/ |
Universal rules: anti-ai-slop.md, color.md, typography.md, README.md. |
prompt-templates/ |
93 prompt examples for image/video media surfaces. |
templates/ |
deck-framework.html, kami-deck.html — referenced by deck skills. |
assets/ |
Banner, frames (iPhone 15 Pro, Pixel, iPad Pro, MacBook, browser chrome), screenshots. |
Tier 8 — scripts
| Script | Purpose |
|---|---|
scripts/check-residual-js.ts |
Validate no .js/.mjs outside generated/vendor allowlist. |
scripts/sync-design-systems.ts |
Sync 70 product systems from awesome-design-md package. |
scripts/sync-litellm-models.ts |
Sync litellm-models.json model caps from BerriAI/litellm. |
scripts/bake-community-pets.ts, sync-community-pets.ts |
Codex pet sprite registry sync. |
scripts/bake-html-ppt-examples.mjs |
Generate example.html for each html-ppt skill. |
scripts/scaffold-html-ppt-skills.mjs |
Generate skill skeletons from upstream html-ppt templates. |
scripts/import-prompt-templates.mjs |
Fetch upstream prompt corpora into prompt-templates/. |
scripts/sync-hyperframes-skill.mjs |
Refresh vendored HyperFrames skill. |
scripts/verify-media-models.mjs |
Drift check between browser and daemon media-model registries. |
scripts/release-beta.ts, release-stable.ts |
Tag git, build, publish. |
scripts/postinstall.mjs |
Workspace bin-link refresh after pnpm install. |
Important prompt files (reading order)
If you want to understand the LLM stack, read these six files in this order:
apps/daemon/src/prompts/official-system.ts— base identity (60 sec read).apps/daemon/src/prompts/discovery.ts— the dominant layer; turn-1 form, turn-2 branches, TodoWrite, anti-slop, 5-dim critique (5 min read).apps/daemon/src/prompts/directions.ts— 5 deterministic visual directions (3 min read).apps/daemon/src/prompts/system.ts— the composer that wires it all together (3 min read).apps/daemon/src/prompts/deck-framework.ts— opinionated contract for decks (5 min read; mostly HTML).apps/daemon/src/prompts/media-contract.ts— shell-dispatch contract for image/video/audio (3 min read).craft/anti-ai-slop.md+apps/daemon/src/lint-artifact.ts— the rules and their auto-enforcement (5 min read).
That's about 25 minutes of reading and you'll understand the whole prompt-side of OD.