Add architecture diagrams to your PRs. Architecture diffs alongside code diffs — review, comment, and merge structural changes with full context.
Architecture changes should ship with the code that implements them.
Diagram changes appear as text diffs. See new services, removed links, and renamed components at a glance.
GitHub and GitLab render Mermaid in Markdown preview. See the actual diagram alongside the diff.
Comment directly on diagram lines: "Should this service call the cache or the DB?" Same UX as code review.
Architecture changes ship in the same PR as the code change. One review, one merge, one record.
Describe the change in English. Cybewave updates the Mermaid or PlantUML code for you.
Require architect approval for diagram files. Same CODEOWNERS rules you already use for critical paths.
When your code changes affect the architecture, update the corresponding Mermaid or PlantUML diagram files in the same feature branch. This ensures architectural changes are proposed alongside the code that implements them.
Open your pull request with both code and diagram changes. Reviewers see the architectural modifications as part of the same review, not as a separate afterthought living in a different tool or wiki.
Reviewers can evaluate whether the code changes align with the architectural intent, catching mismatches between design and implementation before they ever reach the main branch.
When splitting or merging microservices, include updated service diagrams showing the new boundaries, communication patterns, and data ownership in the PR.
Document new third-party integrations or internal service connections with diagrams that show data flow, authentication mechanisms, and failure handling paths.
Pair database migration code with updated entity relationship diagrams showing how the schema changes affect the overall data model and service dependencies.
Include updated sequence diagrams or interface diagrams when modifying API contracts to show how the changes affect upstream and downstream consumers.
Document infrastructure-as-code changes with architecture diagrams that visualize the before and after states of your cloud resources and networking topology.
When modifying authentication flows, authorization rules, or network policies, include diagrams showing the updated security boundaries and trust relationships.
Pull requests without diagrams force reviewers to mentally reconstruct the architecture from code alone. A reviewer reading a hundred-line infrastructure change has to imagine how load balancers, services, and databases connect—a task that takes minutes with a diagram but hours without one. Diagrams make the architectural impact of code changes visible and immediate.
Including diagrams in PRs creates a culture where architectural documentation is not a separate chore but an integral part of the development process. When updating a diagram is as natural as writing a test, teams stop treating documentation as optional overhead and start treating it as an essential quality signal.
PR diagrams also serve as a historical record. When you browse through merged pull requests months later, the diagrams show you exactly what the architecture looked like at each significant change. This visual history is invaluable for onboarding new engineers, debugging production issues, and planning future migrations.
Free to start. 50 AI credits/month. No credit card required.
Get started for free →