Architecture docs that change in the same pull request as the code

Architecture diagrams go stale because they live somewhere else: a drawing tool, a wiki, someone's laptop. The person changing the code can't update them, or doesn't know they exist. CoPage keeps the diagram's source in the repository, where the agent that changes the code can change the picture too.

#How it works

1. Put the diagrams in the repo.

   copage init                 # creates .copage/ in the project; commit it
   copage skill install        # your agent learns the copage commands

2. Draw the first version. Ask your agent: "Draw our architecture from the Terraform and the services in this repo, and put it in docs/architecture.svg." It draws, renders the result to look at it, runs the checks, fixes what they find and exports the SVG. Link that file from your README or docs.

3. Change code and diagram together. When a pull request adds a queue or splits a service, ask the agent to update the diagram as part of the change. It reads the diagram (copage diagram show <id>), applies its edits (copage diagram apply <id> ops.json) and rewrites the exported files (copage diagram export <id>). The pull request then holds the code, the diagram's JSON and the new SVG.

4. Review it like code. Reviewers see the SVG change in the diff, and the JSON shows exactly which elements moved or changed. Anyone can open the picture to adjust it: copage diagram open docs/architecture.svg.

5. Check it in CI. copage diagram check <id> needs no browser and no account, and its exit status is the result.

#What goes in git

.copage/.gitignore keeps working files (history, renders, the editor's state) out of git.

Exports are remembered: while the editor is running (copage open), any change to a diagram rewrites its exported files within a couple of seconds, whoever made it. Without the editor, copage diagram export <id> rewrites them; the CLI reminds the agent after each edit.

#Checks in CI

copage diagram check exits with:

• 0 when every check passes,
• 1 when a check found something,
• 2 when a check couldn't run (which is not a pass).

The default pack for diagrams, Diagram essentials, checks that connectors are attached at both ends, icons are labelled, nothing is stacked or left unconnected, and no placeholder text is left. A script that checks every diagram in the repo:

curl -fsSL https://copage.semerjyan.dev/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
status=0
for f in .copage/diagrams/*.json; do
  copage diagram check "$(basename "$f" .json)" || status=$?
done
exit $status

Builds exist for Linux x64, macOS (Apple silicon and Intel) and Windows x64. The CLI never looks for updates by itself in CI. AI checks, which would send a diagram's text to an AI model, are left out of the CLI: they run in the CoPage app.

#Client repositories

For a repository that must never leave your own machines, copage init --local-only writes "cloud": false to .copage/config.json. It is committed, so uploads to the CoPage app are refused for everyone working in the repo.

#Who it's for

Tech leads and developers who own a service's documentation, platform teams with architecture decision records, and consultancies working in a client's repository. The CLI is free and needs no account.

#Read more

• CoPage CLI documentation: every command, the .copage/ folder, exit codes, work computers.
• Checks: what each check looks for and which pack to use.
• Connecting your agent and Diagrams.
• Install the free CLI