Source
Dyad repository
An open repository of local AI app builder with architectural notes and documentation.
Dyad - local AI app builder in desktop application format. From an architectural point of view, it is interesting due to its combination of local-first approach, agent-based orchestration and template design: the developer manages the intent, and the platform takes care of the systemic execution of changes and checks.
This chapter is compiled from public materials and architectural notes from the team, with a focus on engineering patterns that are useful to transfer to other AI-assisted platforms.
Dyad Architectural Patterns
Electron multi-process
Main process manages OS functions, files and integrations; The renderer process is responsible for the UI in React.
- Isolation of responsibility between the system layer and the interface.
- IPC events as a communication bus between processes.
Agent + Tool orchestration
LLM not only generates code, but also structured tool calls that Dyad interprets and applies.
- ReAct pattern: reasoning + action in one cycle.
- Controlled execution of model actions through a limited set of tools.
Local-first execution
Code and working artifacts remain on the user's machine, which reduces latency and simplifies privacy.
- There is no mandatory cloud-runtime for the core of the product.
- Easier to integrate into existing developer and IDE workflow.
Template + Rules
Project templates and AI_RULES.md define the code generation framework and technological limitations.
- Quick start through a scaffold, not from a blank sheet.
- Generation policies are set declaratively at the template level.
Versioned checkpoints
Changes in the code and database can be rolled back through the checkpoint approach (including through branching for Postgres).
- Undo/redo becomes an infrastructure capability rather than a manual procedure.
- Experimenting with AI changes becomes safer.
Application architecture visualization
Layer purpose
The UI layer accepts user intent and shows diffs and change results without direct access to system APIs.
Operational focus
Keep interface response fast and avoid blocking the UI with long-running operations.
Typical pitfall
Mixing UI logic with file operations and provider network calls.
Key repository modules
Core app
src + worker + preload: UI, main-process and background tasks (for example, heavy checks/builds).
Reusable packages
packages/@dyad-sh: Reusable SDKs/utilities for AI providers, common types, and integrations.
Scaffold and templates
scaffold + templates: starting application structures with generation rules (AI_RULES.md).
Quality and delivery
testing + e2e-tests + scripts: unit/integration/e2e checks, assembly via Electron Forge, CI automation.
How is the change going at Dyad?
Dyad change flow
From user intent to checkpoint and controlled rollbackPrompt and intent
The user describes a change: a new feature, UI update, or logic adjustment.
Context gathering
Dyad picks relevant project files, templates, and generation rules.
Agent plan + tool calls
The LLM builds a plan and returns structured tool calls for the platform.
Apply changes
The main process executes actions: patches, checks, and preview updates.
Checkpoint and rollback
State is saved as a checkpoint so regressions can be safely rolled back.
Prompt and intent
The user describes a change: a new feature, UI update, or logic adjustment.
Context gathering
Dyad picks relevant project files, templates, and generation rules.
Agent plan + tool calls
The LLM builds a plan and returns structured tool calls for the platform.
Apply changes
The main process executes actions: patches, checks, and preview updates.
Checkpoint and rollback
State is saved as a checkpoint so regressions can be safely rolled back.
Engineering Strengths
- Local-first execution with minimal vendor lock-in according to the project.
- Explicit tool boundaries reduce the chaotic execution of actions by the model.
- The template-driven approach speeds up the start and increases the repeatability of generation.
Assembly, tests and quality
- Electron Forge + Vite for local development and packaging of desktop assemblies.
- Playwright for e2e, Vitest for unit/integration tests.
- Husky and lint-staged for pre-commit style and quality checks.
- Separating OSS and Pro modules reduces the risk of license confusion.
Practical checklist
- Fix boundaries between UI, agent orchestration, and FS operations before adding new tools.
- Design rollback/checkpoint first, and only then expand the automation of agent actions.
- Keep templates and AI_RULES in the same lifecycle with the product: template version = generation expectations version.
- Cover the entire prompt -> patch -> preview path with e2e scripts for critical user scenarios.
- For Pro/OSS modules, maintain a strict integration contract so as not to break the open-source kernel.