Architecture Change Requests - Archyl Docs

Propose, review, and merge changes to your C4 architecture model through a structured change request workflow

Architecture Change Requests

Architecture Change Requests let you propose modifications to your C4 model through a structured review workflow. Instead of editing the architecture directly, team members create requests that can be reviewed, discussed, and merged.

How It Works

A change request groups one or more proposed changes to your architecture model. It follows a lifecycle similar to a pull request in code repositories:

  1. Create a request with a title and description
  2. Add changes — create, update, or delete C4 elements (systems, containers, components, code elements, relationships, overlays)
  3. Open for review when the proposal is ready
  4. Review — team members approve, request changes, or leave comments
  5. Merge to apply all changes to the live architecture

Request Lifecycle

Each request moves through these statuses:

Status Description
Draft Work in progress. Only the author can see and edit changes.
Open Submitted for review. Team members can review and comment.
Approved Has received approvals and is ready to merge.
Merged Changes have been applied to the architecture model.
Closed Declined or abandoned. Can be reopened by the author.

Creating a Request

From the Requests Tab

  1. Navigate to your project
  2. Open the Requests tab
  3. Click New Request
  4. Enter a title (max 200 characters) and optional description
  5. The request starts in Draft status

Adding Changes

Within a draft or open request, add changes by selecting:

  • Operation: Create, Update, or Delete
  • Element type: System, Container, Component, Code, Relationship, or Overlay
  • Element data: The properties for the new or modified element

Changes are grouped by operation type (creates, updates, deletes) for easy review.

Editing a Request

The author can edit the title and description of a request at any time, as long as it has not been merged. Click the pencil icon next to the title to enter edit mode.

Reviewing a Request

Submitting a Review

Team members with edit access can review open requests:

  • Approve — the proposal looks good
  • Request Changes — modifications are needed before merging
  • Comment — leave feedback without a formal decision

Activity Feed

The activity tab shows all reviews and comments in chronological order. Use the comment composer at the bottom to leave quick comments without a formal review.

Merging a Request

When a request has been reviewed and approved:

  1. Open the request detail page
  2. Click Merge
  3. All changes are applied atomically to the C4 model

Only team members with edit permissions can merge requests.

Previewing Changes

The Preview tab shows a visual representation of what the architecture will look like after the changes are applied, so reviewers can understand the impact before merging.

Best Practices

Write Clear Titles

Use descriptive titles that explain the intent:

  • "Add payment service and Stripe integration"
  • "Split monolithic API into user and order services"
  • "Remove deprecated notification component"

Keep Requests Focused

  • One logical change per request
  • Avoid mixing unrelated modifications
  • Smaller requests are easier to review

Use Descriptions

Explain the reasoning behind the proposed changes:

  • Why this architectural change is needed
  • What alternatives were considered
  • Links to related ADRs or documentation

Review Before Merging

  • At least one approval is recommended
  • Use comments to discuss trade-offs
  • Check the preview tab to verify the result

Next Steps