Under the hood

Your project folder

Every Patchwerk plugin is a folder of plain files — JSON, Svelte, Cmajor. What each one is, which are safe to edit by hand, and what Patchwerk rewrites for you.

Plugin makers who want to know exactly what is saved on disk and why.

Everything is a file you own

A Patchwerk project is one folder. Open it in any file browser and you can see your entire plugin — no database, no opaque bundle.

my-plugin/
  project.json          plugin identity: name, type, I/O, canvas size, stage
  CLAUDE.md             notes the AI assistant reads and keeps updated
  brief.md              your creative brief — the "why" of the plugin
  parameter-spec.md     the parameter contract: ids, ranges, defaults
  dsp/graph.json        the sound: every node, cable, and modulator
  presets/              saved sounds (.pwpreset files)
  blocks/               custom DSP blocks, if you've made any
  ui/                   your plugin's interface — a real Svelte app
  .gitignore            keeps generated files out of version control

blocks/ only appears once you create a custom block. Each block is its own subfolder with a block.json manifest and a dsp.cmajor source file — real, readable DSP code.

Which files are yours to edit

Everything is plain text, but some files are better edited through the app than by hand.

File	Edit by hand?	Notes
`brief.md`, `parameter-spec.md`	Yes, please	They are for you — the assistant builds from them
`CLAUDE.md`	Yes	Shared notebook between you and the assistant
`blocks/*/dsp.cmajor`	Yes	Custom block DSP source
`ui/src/Plugin.svelte` and `ui/src/components/`	Yes	Same files the design canvas edits
`project.json`	Carefully	Valid edits work; the app autosaves over it
`dsp/graph.json`	Carefully	Use the graph editor while the project is open
`presets/*.pwpreset`	Carefully	Plain JSON, but easiest to manage in-app
`ui/vite-plugins/`, `ui/src/lib/`	No	Patchwerk plumbing — overwritten on every open

Note Patchwerk rewrites some files automatically: project.json autosaves shortly after any change, dsp/graph.json persists as you edit the graph, and the plumbing under ui/vite-plugins/ and ui/src/lib/ is restored to stock every time the project opens. Hand edits to those plumbing files will not survive.

Your interface is a real app, not a skin

The ui/ folder is a complete Svelte project with its own package.json. When your project is open, Patchwerk runs it as a live preview inside the design canvas — and three editors share those same source files:

the design canvas, when you drag and resize controls,
the AI assistant, when you ask for UI changes,
you, in the script editor or any external editor.

ui/src/Plugin.svelte is the root of your interface; your own components live in ui/src/components/. Because it is ordinary source code, anything Svelte can render, your plugin can be.

Tip ui/node_modules is always safe to delete. Patchwerk reinstalls dependencies the next time it starts your UI preview.

What happens when a project opens

Opening a project is a short, predictable sequence:

Read the manifest. project.json tells Patchwerk what the plugin is — name, type, I/O, canvas size, and its current stage.
Load the graph. dsp/graph.json becomes the node graph you see and edit.
Load custom blocks. Anything in blocks/ joins the block library.
Start the UI preview. The ui/ app spins up and appears in the design canvas (plumbing files are refreshed to stock first).
Compile. The graph is translated to Cmajor and handed to the audio engine — and you have sound.

So a "project" is never loaded into some hidden state: what you hear and see is always a direct reading of the files above.

Projects are git-friendly by design

Everything meaningful is text: JSON, Markdown, Svelte, Cmajor. A scaffolded project even ships with a .gitignore that excludes the noise — node_modules/, ui/dist/ build output, and regenerated agent context (.patchwerk/, AGENTS.md).

That makes the usual workflows just work:

Diff a graph change before committing it.
Branch to try a risky redesign of the interface.
Revert anything — including edits the AI assistant made.
Share a plugin by pushing the folder to a repo; a collaborator opens it like any other project.

How the assistant sees your project

Three Markdown files at the project root are the assistant's working memory:

brief.md — what the plugin is for and how it should sound. Vague brief, vague results.
parameter-spec.md — the parameter table the graph and UI must satisfy.
CLAUDE.md — facts about the project plus running notes the assistant updates over time.

Keep these honest and the assistant builds toward your intent instead of guessing. They are checked into git like everything else, so your plugin's "spec" travels with its code.