docs: add architecture overview (Mermaid) and link from README #391

suckmydiscoteque · 2025-10-23T08:55:09Z

Summary
Adds a repo-local architecture overview at docs/architecture/overview.md using a Mermaid diagram, and links it from README.

Details

Diagram shows participant nodes, synchronization domain (sequencer, mediator, topology), and external domain/bridge interaction.
Keeps the high-level picture close to the code while complementing the external documentation.

Why

Improves onboarding and cross-team alignment on Canton concepts (privacy, synchronization domains, interoperability).
Zero impact on build artifacts; docs-only.

Verification

GitHub renders Mermaid diagrams natively in Markdown previews.
Open docs/architecture/overview.md and confirm the diagram renders.

Closes #390

This document provides a high-level overview of the Canton architecture, including key components and their interactions using a flowchart.

github-actions · 2025-10-23T08:55:27Z

🎉 Thank you for your contribution! It appears you have not yet signed the Agreement DA Contributor License Agreement (CLA), which is required for your changes to be incorporated into an Open Source Software (OSS) project. Please kindly read the and reply on a new comment with the following text to agree:

I have hereby read the Digital Asset CLA and agree to its terms

_{You can retrigger this bot by commenting recheck in this Pull Request. Posted by the CLA Assistant Lite bot.}

suckmydiscoteque · 2025-10-23T10:48:08Z

Hi! I tried to sign the CLA, but the link seems to be broken ("There is no CLA to sign for digital-asset/canton").
Please advise or mark CLA as manually accepted. Thanks!

suckmydiscoteque · 2025-10-23T11:08:30Z

Hi team 👋

Added a new architecture overview document (docs/architecture/overview.md) with a Mermaid diagram
and linked it from the main README for easier discovery.

This helps newcomers quickly grasp Canton’s synchronization model.
Let me know if you’d like any adjustments to the diagram or section placement.

Thanks!

soren-da

Hey, thanks for making a contribution! I left some comments to clarify some misunderstandings how Canton works.

In general we keep documentation on Canton in a separate repository. For instance you can find a description of the high-level architecture and what the individual components do here: https://docs.digitalasset.com/overview/3.3/explanations/canton/protocol.html#protocols-on-one-synchronizer

To keep the canton docs consistent in a single repository, I won't merge your PR here. But please do let me know if the architecture description from the docs page above is not clear enough.

soren-da · 2025-10-24T08:42:44Z

docs/architecture/overview.md

+  subgraph Domain["Synchronization Domain"]
+    SQ[Sequencer]:::comp
+    MED[Mediator]:::comp
+    TM[Topology Mgmt]:::comp


in Canton 3.x there is no more topology manager

Thanks a lot, @soren-da, for the detailed feedback and clarification! 🙏
I completely understand, keeping the high-level architecture docs in a separate repository makes perfect sense for consistency.

I’ll close this PR and explore contributing to the external documentation repo instead.
Appreciate your time and clear explanations - this was a great learning step to better understand Canton’s architecture.

If you’re open to suggestions, I’d be happy to help improve the section you linked (especially around synchronization domains and node interactions).
Would it be best to open an issue or a PR in that docs repository?

Removed the topology manager reference from the diagram.

I just merged a PR that includes the canton docs sources in this repo too, you can find them under https://github.com/digital-asset/canton/tree/main/docs-open/src/sphinx . It's unfortunately not the complete tooling for building the docs, but smaller changes to the text, graphics, or mermaid diagrams are still possible. I'd definitely appreciate it if you would like to contribute on improving the docs and open a PR 🙏

soren-da · 2025-10-24T08:43:47Z

docs/architecture/overview.md

+  PN1[Participant Node A]:::node -->|Authenticated messages| SQ
+  PN2[Participant Node B]:::node -->|Authenticated messages| SQ
+
+  SQ --> MED


the mediator initiates the connection to the sequencer, but then it's a bidirectional flow. the sequencer never initiates a connection to the mediator.

Got it, thnx for the clarification,.
You're right - the mediator initiates the connection to the sequencer, and the flow is bidirectional afterward.
I’ll correct that in my next update to keep the diagram accurate.

Updated the mediator→sequencer flow to show correct initiation and bidirectional communication.

soren-da · 2025-10-24T08:43:59Z

docs/architecture/overview.md

+    X1[Participant Node / Bridge]
+  end
+
+  PN1 <--> PN2


there's no connection between participant nodes directly

yeap, you're absolutely right, participant nodes don’t communicate directly.
I’ll remove that connection in the next update to keep the diagram aligned with Canton’s actual interaction model.

Removed the direct participant-to-participant link from the diagram.

soren-da · 2025-10-24T08:44:35Z

docs/architecture/overview.md

+  SQ --> MED
+  MED --> SQ
+
+  subgraph Ext["Other Domain / External Ledger"]


what do you mean by "other domain"?

by “Other Domain” I meant to illustrate a possible connection or interaction between a Canton domain and an external system (for instance, an integration bridge or a different ledger network).

I agree that this label might be misleading here, I can rename or remove it to keep the diagram focused only on internal Canton components if that’s preferred.

Removed the “other domain” placeholder to keep the focus on the synchronization domain only.

…mediator→sequencer) Updated architecture overview to match current Canton 3.x behavior: - Removed Topology Manager - Corrected mediator → sequencer initiation flow - Removed participant-to-participant connection

suckmydiscoteque · 2025-10-27T17:47:54Z

Hey, thanks for making a contribution! I left some comments to clarify some misunderstandings how Canton works.

In general we keep documentation on Canton in a separate repository. For instance you can find a description of the high-level architecture and what the individual components do here:
https://docs.digitalasset.com/overview/3.3/explanations/canton/protocol.html#protocols-on-one-synchronizer

To keep the canton docs consistent in a single repository, I won't merge your PR here. But please do let me know if the architecture description from the docs page above is not clear enough.

Thanks a lot for the detailed feedback, @soren-da
I’ve updated the diagram according to your notes - removed the topology manager, fixed the mediator → sequencer initiation flow, and eliminated the participant-to-participant link.
Let me know if it looks good now, and I’ll be happy to iterate further if needed 🙌

docs: add architecture overview page with Mermaid diagram

c9420f9

This document provides a high-level overview of the Canton architecture, including key components and their interactions using a flowchart.

docs: link architecture overview from README

77b1636

soren-da reviewed Oct 24, 2025

View reviewed changes

docs: add architecture overview (Mermaid) and link from README #391

Are you sure you want to change the base?

docs: add architecture overview (Mermaid) and link from README #391

Uh oh!

Conversation

suckmydiscoteque commented Oct 23, 2025

Uh oh!

github-actions bot commented Oct 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

suckmydiscoteque commented Oct 23, 2025

Uh oh!

suckmydiscoteque commented Oct 23, 2025

Uh oh!

soren-da left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

suckmydiscoteque commented Oct 27, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

github-actions bot commented Oct 23, 2025 •

edited

Loading