Skip to content

docs: add architecture overview and participant architecture#475

Open
cgdusek wants to merge 1 commit intodigital-asset:mainfrom
cgdusek:claude/pedantic-tesla
Open

docs: add architecture overview and participant architecture#475
cgdusek wants to merge 1 commit intodigital-asset:mainfrom
cgdusek:claude/pedantic-tesla

Conversation

@cgdusek
Copy link
Copy Markdown

@cgdusek cgdusek commented Mar 28, 2026

Summary

  • Add an Architecture section to README.md with a Mermaid diagram showing how participant nodes, sequencers, and mediators interact within a synchronizer
  • Flesh out the previously empty participant-architecture.rst in docs-open/ with component descriptions, command processing flow, multi-synchronizer and HA cross-references

Closes #390

Context

PR #391 previously attempted to address this issue but was closed because:

  1. Docs were placed in docs/architecture/ instead of docs-open/
  2. The diagram contained architectural inaccuracies (topology manager, direct participant links, wrong mediator flow)
  3. At the time, docs lived in a separate repository

Per @soren-da's guidance, docs now live in docs-open/ and contributions are welcome there.

Changes

README.md — New Architecture section with:

  • Mermaid diagram matching the canonical example from protocol.rst (Alice multi-hosted on P1/P3, Bob on P1, Charlie on P2, two sequencers, one mediator)
  • Key architectural invariants (no direct participant communication, total-order multicast, two-phase commit via mediator)
  • Links to in-repo docs and published documentation

participant-architecture.rst — Replaced empty WIP stub with:

  • Overview of all major participant components (Ledger API, Admin API, Daml Engine, Synchronizer Router, Transaction Processor, Sequencer Client, Contract Store, Indexer)
  • 7-step command processing flow from submission to commit
  • Multi-synchronizer support and HA sections with cross-references to existing pages

Architectural accuracy

All content verified against protocol.rst, participant.rst, synchronizers.rst, and the maintainer review comments on #391:

  • No Topology Manager (removed in 3.x)
  • No direct participant-to-participant links
  • Mediator connects to sequencers (bidirectional), not to participants
  • Matches the Alice/Bob/Charlie/P1/P2/P3 example from protocol.rst

Test plan

  • Verify Mermaid diagram renders on GitHub (visible in PR diff or README preview)
  • Confirm RST cross-references resolve (synchronizer-architecture, protocol-sequencer-nodes, reassignment-protocol, multiple-synchronizers, participant-ha)
  • Review architectural accuracy against published docs

…rchitecture

Add a Mermaid diagram to README.md showing how participant nodes,
sequencers, and mediators interact within a synchronizer. Fill in the
previously empty participant-architecture.rst with component
descriptions, command processing flow, and cross-references.

Closes digital-asset#390
@github-actions
Copy link
Copy Markdown

github-actions bot commented Mar 28, 2026

✅ All required contributors have signed the CLA for this PR. Thank you!
Posted by the CLA Assistant Lite bot.

@cgdusek
Copy link
Copy Markdown
Author

cgdusek commented Mar 28, 2026

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add architecture overview (Mermaid diagram) and link from README

1 participant