Working with a repository

Your architecture model lives in your repository, next to the code. The web app is where you curate it — rename, describe, group, lay out, record decisions — and the VS Code extension and the crayon-c4 CLI are where it is generated and checked against the code. The three never talk to each other directly. A file in your repository is the only thing that travels, so this page is about moving that file back and forth without losing anyone's work.

The loop

  1. Generate in the repository — the extension's Generate Model or npx crayon-c4 . --apply.
  2. Bring it into the web app — Projects → New project → From file (or From code).
  3. Curate in the web app.
  4. Take it back to the repository — Export → Export to repository folder… (Chrome, Edge) or Export project JSON.
  5. Commit. When the code changes, generate again and use Update from code in the web app (step 2's project), which merges instead of starting over.

Everything below is the detail that makes steps 2, 4 and 5 safe.

Name the model file once

By default the generated model is crayon-c4-project.json, with crayon-c4-provenance.json and crayon-c4-enrichment.json beside it. If you would rather the file carried the project's name, say so in .crayon/config.json:

{
  "schema": 1,
  "output": { "model": "elsa-platform-workflows.json" }
}

The two sidecars follow it (elsa-platform-workflows.provenance.json, elsa-platform-workflows.enrichment.json). The CLI, the VS Code extension, the MCP server and the decisions tools all read and write that name; Export to repository folder uses it too. Leave it out and nothing changes.

If you open a model file in the VS Code viewer that is not the one the settings point at, the extension offers to make it the model file for you.

Importing: what to pick

On a project's page, Update from code takes several files in one pick. Select together:

FileWhy
the model (*.json)what the code says now
the provenance (*.provenance.json)which elements are generated, what the code last called them
the decision files (adr/*.md)decisions edited in the repository

Two things the web app does for you:

  • It remembers the provenance. Once you have given it, the project keeps it on this device and uses it on the next update without you picking it again. A file you pick always wins over the remembered one. If there is none at all, the review warns you that renamed elements may look like a removal plus an addition.
  • It is honest about what it will remove. The review counts only items you can actually remove ("N removable (opt-in)"). Anything you wrote by hand that the file does not mention is kept, and the header says how many.

The enrichment file (*.enrichment.json) is a to-do list for the AI filler and carries no model; the web app ignores it if you pick it by accident.

Exporting: choose where it goes

Export project JSON opens your browser's Save as dialog, already filled with the name the file came in with (elsa-platform-workflows.json) and the folder you used last. Saving over the file in your repository is one confirm — no name (3).json in Downloads.

  • Chrome and Edge show the dialog. Firefox and Safari download straight away; turn on their "always ask where to save files" setting to get the same control.
  • Closing the dialog exports nothing.

Export → Export to repository folder… writes the model and the decision files together into the folder you choose:

  • the model file, under the name from .crayon/config.json (or the name the project was imported under);
  • one adr/*.md file per decision, so the files your reviewers read in a pull request are never behind the model.

Before anything is written you see exactly which files are replaced, which decision files are added or removed, and which adr/ files are not this project's and are left alone. The folder is asked for only through the browser's own permission prompt, and only these files are touched.

Decisions: one source of truth, two copies

A decision exists twice in your repository: inside the model file (which is canonical) and as an adr/*.md file (derived from it, for people to read and review). The tools keep them in step — but the two copies share no history, so a tool that sees them differ cannot know which one is newer. That is the one place work can be lost, so each tool refuses to guess:

  • Web export compares each decision file that it would overwrite with the model file's age. A file edited after the model file was last written is listed under "Decision files changed in the repository", and the safe button is Cancel. Bring those edits in first (below), then export.
  • VS Code → Decisions: Sync always offers both directions, each saying what it overwrites, ordered by which copy was written last. It never runs one by itself.
  • CLI: adr export writes the model's decisions to adr/; adr import folds adr/*.md into the model. Both are a preview until you add --apply.

Which direction do I want?

You just…Do this
edited decisions in the web appExport to repository folder (or adr export --apply after saving the JSON)
edited an adr/*.md by hand or in a pull requestIn the web app, Update from code with the model and the adr/*.md files; for each decision choose Take the file's text. Or adr import --apply in the repository.
are not sureRun npx crayon-c4 adr check (nothing is written), look at git diff, then choose.

Accepted decisions are records: their text is not edited, only superseded, and their status only moves forward. An edit to an accepted decision's markdown is therefore ignored on import, and the review says so.

A worked example

You generated a model in VS Code, imported it, and added a decision in the web app.

  1. In the web app open the project → Export → Export to repository folder… and pick the repository. The review shows elsa-platform-workflows.json and the new adr/adr-0002-….md. Write files.
  2. In the repository, git diff shows the model and the one new decision file. Commit.
  3. A teammate edits adr/adr-0001-….md in a pull request and merges it.
  4. You open the project, Update from code, pick the model, the provenance and the adr/ files. The review lists the decision under Text from the file; choose Take the file's, Apply update.
  5. Export again: no warning — both copies agree.

If something looks wrong

  • "is not a CRAYON-C4 model" in the VS Code viewer — update the extension. Models exported from the web app (the project file format) are read by every tool from this version on.
  • The review shows many removals after a re-generate — only generated elements can be removed, and only if you tick them. If a whole branch looks removed, check that the provenance file is the one from the same repository and that .crayon/config.json's include/exclude did not change.
  • The export keeps warning about a decision file — you have not brought its edit in yet (see the table above), or the file's modified time is newer than the model file's. After an Update from code that takes the file's text, or after adr export --apply, the warning goes away.
  • No "Export to repository folder" entry — the browser does not offer folder access (Firefox, Safari). Use Export project JSON, then npx crayon-c4 adr export --apply in the repository to refresh adr/.

Where next