Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
suckmydiscoteque wants to merge 3 commits into
base: main
Choose a base branch
from
Open

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

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c9420f9
docs: add architecture overview page with Mermaid diagram
suckmydiscoteque Oct 23, 2025
77b1636
docs: link architecture overview from README
suckmydiscoteque Oct 23, 2025
1de2a98
docs: fix architecture diagram per review (remove TM, no PN-PN link, …
suckmydiscoteque Oct 27, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,8 @@ privacy faithfully.
Refer to the [Canton Whitepaper](https://www.canton.io/publications/canton-whitepaper.pdf) for further details.

## Availability

For a high-level overview of Canton’s core components and how synchronization domains and participants interact, see
👉 [Architecture Overview](docs/architecture/overview.md)
This repository hosts the open source version of Canton. The Enterprise version can be purchased from [Digital Asset](https://digitalasset.com/products).

## Running
Expand Down
27 changes: 27 additions & 0 deletions docs/architecture/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
# Canton Architecture Overview

This page gives a high-level view of key components and how they interact.

```mermaid
flowchart LR
subgraph Domain["Synchronization Domain"]
SQ[Sequencer]:::comp
MED[Mediator]:::comp
TM[Topology Mgmt]:::comp
Copy link
Collaborator

@soren-da soren-da Oct 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

in Canton 3.x there is no more topology manager

Copy link
Author

@suckmydiscoteque suckmydiscoteque Oct 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Author

@suckmydiscoteque suckmydiscoteque Oct 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed the topology manager reference from the diagram.

Copy link
Collaborator

@soren-da soren-da Oct 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 🙏

end

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

SQ --> MED
Copy link
Collaborator

@soren-da soren-da Oct 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Author

@suckmydiscoteque suckmydiscoteque Oct 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Author

@suckmydiscoteque suckmydiscoteque Oct 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

MED --> SQ

subgraph Ext["Other Domain / External Ledger"]
Copy link
Collaborator

@soren-da soren-da Oct 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

what do you mean by "other domain"?

Copy link
Author

@suckmydiscoteque suckmydiscoteque Oct 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Author

@suckmydiscoteque suckmydiscoteque Oct 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

X1[Participant Node / Bridge]
end

PN1 <--> PN2
Copy link
Collaborator

@soren-da soren-da Oct 24, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

there's no connection between participant nodes directly

Copy link
Author

@suckmydiscoteque suckmydiscoteque Oct 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Author

@suckmydiscoteque suckmydiscoteque Oct 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

SQ <--> X1

classDef comp fill:#eee,stroke:#999,color:#000;
classDef node fill:#f7f7f7,stroke:#777,color:#000;
Loading