Manage projects

A project is everything you've modeled — structure, deployment, and flows together. This page covers where projects live and how to manage them.

Where your work lives

The tier you're on determines where your work is stored and how you access it:

You are…	Your projects live…	Limits (typical)
Anonymous (no account)	In this browser only	Small diagrams
Free account	In this browser, with JSON export/import	Bigger diagrams, up to 5 named projects
Pro	In the cloud — any browser, any machine	Large diagrams, more projects, team features

Anonymous and free work is saved automatically as you edit — but it belongs to this browser on this machine. Clearing browser data clears your work; use JSON export as your backup.

The projects hub

Open Projects from the menu. Here you can create, open, rename, duplicate, or delete your projects. Clicking a project opens it for editing.

For quick switching you don't even need the hub: the hamburger menu (top-left) lists your three most recently updated projects right under Projects, with the active one marked. Clicking a project there makes it the active project and opens its detail page; a +N more… row takes you to the full hub when you have more.

Along the top of the list sit New project, Back up all, and Restore — the latter two back up or restore your whole account in one step, on every tier (see Back up and restore all projects).

Create a new project

When you create a project, the New Project modal offers four sources:

Quick open from the projects hub

Each project row displays three model chips — C4 Model, D4 Deployment, and F4 Processes. Each chip shows a summary (how many nodes or activities, and how many diagrams), plus two buttons:

• View — open the diagram in read-only mode
• Edit — open the diagram editor (hidden if your role is Viewer-only)

Use these shortcuts to jump directly into a specific model without opening the detail page.

Project detail page

Click a project name to open its detail page at /projects/[id]. Here you can:

• Rename the project
• Delete the project (irreversible). Deleting the active project leaves the diagram screens showing a Create a project card until you open or create another one — nothing is loaded in its place automatically
• Export the project — choose JSON (model file, every tier), Markdown bundle, or PDF (the document exports are Pro)
• Promote to cloud (local projects only) — move a local project to your cloud account
• Update from code — refresh the model from a newly generated model file, reviewing any adds, changes, or removals before applying (works for local and cloud projects)
• Version history & restore (cloud projects) — view recent snapshots and revert to one. Snapshots are kept for a limited time only; export regularly for real backups

Updating from code

First regenerate the model file from your repository (with the crayon-c4 CLI or the VS Code extension — the web app never scans your codebase itself). Then click Update from code, pick the new model file, and the app compares it to your current model. A review modal shows every add, change, and removal:

Conflicts appear first — these are elements where both you and the code made changes. For each conflict (usually a rename), you pick which version to keep:

• Keep mine — use your hand-authored name
• Take code — accept the code's name

Removals are shown as an opt-in list. Check the Remove box only for elements you want to delete — code-derived elements are deletable, but hand-authored ones are always preserved. By default, removals are unchecked, so your manual edits stay safe.

Adds and modifications are shown for review but don't require input — adds land automatically, and modifications apply the code changes to fields you haven't edited.

Once all conflicts are resolved, click Apply update to merge the changes into your project.

Save and sync

How your work is saved depends on where it lives.

Local projects (anonymous and free accounts) autosave on-device as you edit. There's nothing to click — every change is saved to your browser's local storage within a few hundred milliseconds.

Cloud projects (Pro) follow a checkout model: you edit on-device, and changes are saved locally first. To push changes to the cloud, click Save to cloud — the orange button in the header, just before your profile menu. It shows a subtle pulsing halo whenever you have unsaved cloud changes. The app confirms the save succeeded or alerts you if there's a conflict.

In addition to explicit Save, cloud projects also sync at natural boundaries: when you blur the editor, hide the tab, stay idle for a while, or navigate away. These automatic syncs happen quietly in the background if there's nothing new on the server.

The save indicator

Alongside the Save to cloud button, a colored pill in the top bar shows your save state. When the cloud copy is ahead of this device, a Load latest or Review & save button appears beside the pill (see Remote newer below):

• Saved — all changes are on the cloud
• Dirty — you have unsaved changes on this device
• Saving — a save is in progress
• Save failed — the last save didn't succeed (you can retry, or save as a local copy if the cloud project is no longer available)
• Remote newer — the cloud has newer changes. If you have no local edits, a Load latest button appears next to the pill — click it to restore this device from the newer cloud version. If you do have unsaved local edits, the button instead reads Review & save and opens the resolve-changes modal so nothing is overwritten silently

If a save fails because the project was deleted or your membership ended, you can choose to keep the work as a local project so you don't lose your edits.

Promote a local project to the cloud

Open a local project's detail page and click Promote to cloud. Your work moves to your Pro account's cloud storage and is now accessible from any browser or machine. You can then invite teammates to edit with you.

Update from code

Open the project detail page and click Update from code. This refreshes your model from a regenerated model file:

1. Regenerate the model file from your repository (CLI or VS Code extension), then pick it in the file dialog
2. A review screen shows adds, changes, and removals
3. You pick which changes to apply (resolve any conflicts where code and you both renamed the same element)
4. Click Apply update to merge the changes into your project — local projects update in place; cloud projects stage the update on-device until you Save

This keeps your model in sync as the code evolves, without losing your manual descriptions or diagram layouts.

JSON backup and import

Export your whole project as a single JSON file, and import one back anytime. The JSON holds the complete model — every node, layer, relationship, and layout choice.

Use JSON export to:

• Back up before big restructuring
• Move work between browsers or machines
• Version the model file in a repository next to the code it describes — diagram changes then show up in the same review as code changes
• Hand-author or generate a model file using the published JSON schema

To export, open the project detail page, click Export, and choose JSON model file. To import, create a new project and select From file. Both directions are available on every tier.

Importing validates the file first — a malformed file is reported, not half-loaded. See Troubleshooting if an import is refused.

Back up and restore all projects

Beyond exporting a single project, you can back up every project at once and restore them later — a safety net for your whole account, not just one model. Available on every tier.

• Back up all — click Back up all in the hub toolbar to download one backup file (crayon-c4-backup-<date>.json) containing every project you can see: all of your local projects plus — on Pro — every cloud project on your account. Store it somewhere safe, or commit it alongside your code.
• Restore — click Restore, choose a backup file, then review the projects it holds. Every project is listed with a checkbox (all selected by default); tick the ones you want and click Restore.

A few things to know about restore:

• It never overwrites. Restored projects always come back as new local projects, so a restore can't clobber work you already have. Rename or delete the originals afterwards if you only wanted the restored copies.
• It respects your project limit. Each restored project counts toward your local-project limit. If a restore would exceed it, the projects that fit are restored and the rest are reported as skipped — promote some to the cloud to free space, then restore again.
• It validates every project. Each project in the backup is checked the same way an imported file is. A single corrupt project — or one made with a newer version of CRAYON-C4 — is flagged and skipped, and the rest restore normally.

Where next

• Share & collaborate — work with others on one project.
• Export diagrams — images, Markdown, PDF.