Architecture Change Requests: Pull Requests for Your C4 Model

Last month, an engineer on a team I advise renamed a core service on their architecture diagram. No discussion. No review. The change was live instantly, and three teams spent the next standup confused about whether the actual service had been renamed or just the diagram. It hadn't. Someone just thought the label was unclear and "fixed" it.

That incident crystallized something we'd been thinking about for a while. Code has pull requests. Infrastructure has plan/apply. Database schemas have migrations. But architecture diagrams? Anyone with edit access can change anything, anytime, and the rest of the team finds out... eventually.

Today we're changing that. Architecture Change Requests bring the pull request workflow to your C4 model.

How It Works

The concept is deliberately familiar. If you've ever opened a pull request on GitHub, you already know how this works.

You start by creating a change request. Give it a title, describe what you're proposing and why. Then add your changes—create new systems, update existing containers, delete unused components, modify relationships. Each change is a discrete operation: create, update, or delete on a specific C4 element.

The change request starts as a draft. You can keep adding and refining changes until you're ready. When the proposal is complete, you open it for review.

Your teammates see the open request in the project's change request list. They can review each proposed change, see exactly what's being created, modified, or removed. They leave reviews: approve, request changes, or comment. Once the required number of approvals is met, the request can be merged—applying all changes to the live C4 model in one atomic operation.

Visual Preview

One thing we didn't want was a diff view that reads like a JSON blob. Architecture is visual, and reviewing architecture changes should be visual too.

Every change request includes a live preview of the diagram. The preview renders the current C4 model with all proposed changes overlaid. New elements appear with a green highlight. Modified elements get an amber ring. Deleted elements show a red indicator. You can navigate through the C4 levels—system, container, component, code—and see the full impact of the proposal at every depth.

This is the same interactive React Flow canvas you use for the live diagram, with the same drill-down, zoom, and pan. The only difference is the data: it's a computed projection of what the architecture will look like after the merge.

The Review Process

Reviews follow a straightforward model. A reviewer can:

• Approve — "This looks good, merge when ready."
• Request changes — "I have concerns, let's discuss before this goes in."
• Comment — "No objection, but here's some context."

Each review includes a free-text body for detailed feedback. The change request tracks its approval count against the project's required threshold. By default, one approval is needed, but you can configure this per project—zero approvals for small teams that want lightweight tracking, two or three for larger organizations that need formal sign-off.

Requests-Only Mode

For teams that want to go further, we've added a Requests-Only Mode in project settings. When enabled, direct edits to the C4 model are locked. The only way to modify the architecture is through a change request.

This doesn't mean the diagram becomes read-only. You can still navigate, explore, link ADRs and documentation to elements, add comments. You just can't move, rename, create, or delete elements without going through the change request workflow.

We built this for organizations where architecture governance matters—regulated industries, large engineering teams, platform teams managing shared infrastructure. The architecture becomes a controlled artifact, with every change traceable and reviewed.

Activity Tracking

Every change request lifecycle event shows up in the project's Activity tab. When a request is opened, closed, reopened, or merged, a history entry is recorded with the author, timestamp, and request title. This gives you a timeline of how the architecture evolved—not just what it looks like today, but the sequence of proposals and decisions that shaped it.

Combined with ADRs and documentation links, you get a complete narrative: what changed (the change request), why it changed (the ADR), and how it fits into the broader context (the documentation).

Building Changes

The change builder lets you construct proposals element by element. For each change, you specify:

• Operation: create, update, or delete
• Element type: system, container, component, code element, relationship, or overlay
• Element data: the full specification of the element—name, description, technology, type, and all the fields you'd set when creating it directly

For updates, the system captures both the current state and the proposed state, so reviewers see exactly what's changing. For deletes, the existing element data is preserved in the request for reference.

You can mix operations freely. A single change request might create two new containers, update a relationship, and delete an obsolete component. When merged, all changes apply together.

What This Means for Teams

Architecture change requests aren't about adding bureaucracy. They're about making architectural evolution intentional.

In a codebase, the pull request isn't just a gate—it's a communication tool. It says "here's what I'm proposing, here's why, what do you think?" It creates a natural moment for knowledge sharing, for catching mistakes early, for building shared understanding.

Architecture deserves the same treatment. When someone proposes adding a new service, that's a conversation worth having before it appears on the diagram. When someone wants to restructure the component hierarchy, the team should see the full picture before it becomes the new reality.

The change request is that conversation, made structured and traceable.

Getting Started

Architecture Change Requests are available now on all team plans. Navigate to any project, and you'll find the "Requests" section in the sidebar. Create your first request, add some changes, and open it for review.

If you want to enforce the workflow, enable Requests-Only Mode in your project settings. Configure the required approval count to match your team's governance needs.

Your architecture is a team decision. Now your tools make that explicit.

Want to understand more about collaborative architecture? Read about Real-Time Collaboration on C4 Diagrams, or learn how Architecture Decision Records complement change requests by capturing the "why" behind every architectural evolution.