Início/Trilha 1 · Fundamentos/Módulo 1.2
MÓDULO 1.2

🏗️ Arquitetura mental do OD

Desenhar de cabeça o data-flow: chat → skill picker → design-system picker → daemon → CLI → <artifact> → iframe preview, e saber onde cada peça é editável.

6
Tópicos
~50 min
Duração
Básico
Nível
Mapa
Foco

🏁 Resultado de aprendizagem: Você desenha o data-flow do OD em um guardanapo, identifica em qual peça cada problema vive, e sabe onde editar para mudar comportamento sem quebrar as outras.

1

🧩 As 5 peças que se combinam

Chat, skill, design system, agent CLI, iframe preview.

O que é

O OD não é um modelo nem uma UI — é a composição de 5 peças desacopladas. Chat coleta o brief e mantém estado. Skill (SKILL.md) define o workflow do tipo de artefato (deck, landing, mobile). Design System (DESIGN.md) define o vocabulário visual. Agent CLI é o motor que executa. Iframe preview é o sandbox onde o resultado roda em segurança.

Por que aprender

Quando algo dá errado, você precisa saber qual peça atacar. Output incoerente? Skill ou Design System. Agente lento ou mal-comportado? CLI. Render quebrado? parser/iframe. Sem esse mapa, todo bug vira "mexer no chat".

Conceitos-chave

Chat (Web/Next.js)

Estado, histórico, picker de skill+sistema

Skill

SKILL.md + assets + references

Design System

DESIGN.md em OKLch (9 seções)

Agent CLI

Claude Code, Codex, Gemini, etc.

Iframe preview (srcdoc)

Sandbox isolado para renderizar <artifact>

2

🌐 As 3 topologias de deploy

A: tudo local. B: Vercel + tunnel. C: browser-only (degradado).

O que é

O OD não é "uma" arquitetura — são 3, dependendo de onde a UI roda e onde o daemon está. A: UI Web em localhost:3000 + daemon em localhost:7331 (mesma máquina). B: UI hospedada em Vercel + tunnel (cloudflared) que expõe o daemon do laptop pra UI cloud. C: só browser, chamando API direto via BYOK proxy — sem skills, sem persistência local de SQLite (usa IndexedDB).

Por que aprender

Cada topologia atende um cenário. A para dev solo (laptop sempre ligado, tudo offline-capable). B para time (UI compartilhada, mas cada um tem seu daemon). C para demos rápidas (compartilhar uma URL, sem setup). Saber qual escolher = poupar horas de configuração.

Conceitos-chave

  • Topologia A: 100% local, sem internet obrigatória, full skills + SQLite
  • Topologia B: Web em Vercel, daemon local exposto via cloudflared tunnel
  • Topologia C: browser-only, IndexedDB fallback, sem skills/agentes locais
  • Trade-off A: melhor experiência, exige Node + dependências
  • Trade-off B: compartilhamento, exige tunnel sempre ativo
  • Trade-off C: zero setup, perde 70% das features
3

📦 Daemon vs Web vs Desktop

Quem é responsável por o quê.

O que é

Três processos com responsabilidade única. Daemon (apps/daemon): Node de longa duração, fala com a CLI/proxy, dona do SQLite e do filesystem. Web (apps/web): Next.js que renderiza UI, faz fetch ao daemon. Desktop (apps/desktop): Electron shell que descobre o Web via IPC e mostra como app nativo.

Por que aprender

Você nunca quer "mexer no daemon" pra trocar uma cor da UI, nem editar o Web pra adicionar suporte a uma CLI nova. Cada bug e cada feature têm um único endereço correto. Saber esse endereço evita PRs gigantes e regressões.

Conceitos-chave

  • apps/daemon: server.ts, agents.ts, skills.ts — autoridade sobre estado e CLIs
  • apps/web: Next.js + React, UI e UX, sem acesso direto ao filesystem
  • apps/desktop: Electron shell, faz IPC com daemon para descobrir URL
  • Sidecar IPC: sockets em /tmp/open-design/ipc/<namespace>/
  • Boundary clara: Web nunca toca SQLite direto; Desktop nunca chama API; Daemon não renderiza nada
4

🖼️ <artifact> parser e srcdoc iframe

O ciclo de render seguro.

O que é

O agente é instruído a emitir um único bloco <artifact>...HTML completo...</artifact> em vez de prosa solta. Um parser do OD (em apps/web/src/artifacts/parser.ts) extrai o conteúdo em streaming, e injeta em um iframe sandboxed via srcdoc — sem acesso a cookies, sem origin compartilhada, sem postMessage. É a fronteira de segurança entre o agente e a sua UI.

Por que aprender

Você está executando código que um modelo escreveu. Sandbox é a única coisa que separa "preview" de "comprometeu o navegador". Saber como o parser funciona ajuda a debugar artefatos travados (parsing errado), e a entender por que React+Babel são vendorizados (não há network no sandbox).

Conceitos-chave

  • srcdoc iframe: conteúdo passa como string, isolation total
  • sandbox attr: bloqueia top-navigation, form-submission, etc.
  • Streaming parse: tag aberta? começa o iframe vazio; chunks vão em append
  • React 18 + Babel vendorizados: sem CDN externa dentro do iframe
  • 1 artifact por mensagem: regra dura — agentes que emitem 2 levam refactor no prompt
5

🗄️ SQLite local — .od/app.sqlite

Projetos, conversas, mensagens, abas, templates.

O que é

Todo o estado do OD vive em um único arquivo SQLite no diretório do projeto: .od/app.sqlite. Cinco tabelas: projects, conversations, messages, tabs, templates. Você abre o repo amanhã, o daemon lê o arquivo e restaura tudo — projetos abertos, abas, histórico de chat, templates customizados.

Por que aprender

Two reasons. 1) Você consegue inspecionar/editar o estado direto com sqlite3 — útil para debug e migração. 2) O arquivo é a "verdade". Se sumir do .gitignore por engano, você commita o histórico inteiro do cliente. Saber onde o estado mora = saber o que proteger.

Conceitos-chave

  • better-sqlite3: driver síncrono usado pelo daemon
  • 5 tabelas: projects, conversations, messages, tabs, templates
  • OD_DATA_DIR: override do diretório padrão (útil em CI/Playwright)
  • .od/ é gitignored por default: nunca commita por acidente
  • Multi-namespace: --namespace experiments usa .od-experiments/
6

📥 Importação de ZIP do Claude Design

Migração sem dor — continuar onde a Anthropic parou.

O que é

O daemon expõe POST /api/import/claude-design que aceita um ZIP exportado do Claude Design. Ele descompacta, parseia o histórico de mensagens, cria um projeto OD novo e injeta um "prompt de continuidade" — assim o agente OD entende que ele está retomando uma conversa em andamento, não começando do zero.

Por que aprender

Converte usuários do Claude Design (cloud) sem fricção. "Trouxe seu trabalho? Joga o ZIP, segue editando." Esse import é o caminho mais comum de adoção corporativa: gente experimenta no cloud, decide escalar local, traz o histórico junto.

Conceitos-chave

  • ZIP parsing: extrai messages.json + artifacts/* do export
  • Auto-create project: nome derivado do ZIP
  • Continuity prompt: prefacio inserido na conversa para o agente OD
  • Mapping de artifacts: cada artifact vira tab
  • Sem upload pra cloud: tudo local, ZIP fica no .od/imports/

🛠️ Hands-on

Desenhe o data-flow no papel ou no Excalidraw — sem olhar a documentação. Inclua todas as 5 peças e mostre as setas de fluxo:

  1. Caixa 1: Chat (Web). Caixa 2: Skill. Caixa 3: Design System. Caixa 4: Daemon. Caixa 5: CLI. Caixa 6: Iframe.
  2. Setas: usuário escreve → chat compõe prompt (skill+design system) → fetch para daemon → daemon spawna CLI → CLI streama tokens → daemon repassa → chat injeta no iframe.
  3. Marque os 3 pontos editáveis: SKILL.md (workflow), DESIGN.md (visual), system.ts (identidade).

Verificação rápida do daemon (se já tiver OD instalado)

curl -s http://localhost:7331/api/health | jq
sqlite3 .od/app.sqlite ".tables"
ls -la .od/

📚 Fontes

No repositório open-design/

  • docs/architecture.md §1-§3
  • apps/daemon/src/server.ts
  • apps/web/src/artifacts/parser.ts
  • apps/desktop/src/main/

Externas

  • MDN: srcdoc iframe + sandbox attribute
  • better-sqlite3 docs
  • Cloudflared tunnel docs (Topologia B)

📌 Resumo do Módulo

1. 5 peças desacopladas: Chat, Skill, Design System, Agent CLI, Iframe — cada bug tem um endereço único.

2. 3 topologias de deploy: A (local), B (Vercel + tunnel), C (browser-only) — escolher por cenário.

3. Daemon, Web e Desktop têm responsabilidades isoladas; nunca misture.

4. <artifact> é parseado em streaming e renderizado em iframe srcdoc sandboxed — fronteira de segurança.

5. SQLite em .od/app.sqlite com 5 tabelas é o estado canônico — proteja, gitignore.

6. Import de ZIP do Claude Design via POST /api/import/claude-design = caminho de adoção mais comum.

Próximo módulo:

Módulo 1.3 · O Stack de Prompts é o Produto →
← Módulo 1.1 Módulo 1.3 →