docs: add architecture overview and participant architecture

README.md

@@ -23,6 +23,55 @@ authorization and privacy faithfully.
 
 Refer to the [Canton Whitepaper](https://www.canton.io/publications/canton-whitepaper.pdf) for further details.
 
+## Architecture
+
+The diagram below shows how participants, sequencers, and mediators interact within a single synchronizer.
+
+```mermaid
+flowchart TB
+  subgraph Sync["Synchronizer"]
+    direction TB
+    SQ1[Sequencer 1]
+    SQ2[Sequencer 2]
+    MED[Mediator]
+  end
+
+  subgraph Parties
+    direction TB
+    A((Alice))
+    B((Bob))
+    C((Charlie))
+  end
+
+  P1[Participant P1<br/><i>hosts Alice, Bob</i>]
+  P2[Participant P2<br/><i>hosts Charlie</i>]
+  P3[Participant P3<br/><i>hosts Alice</i>]
+
+  A -.-|hosted on| P1
+  A -.-|hosted on| P3
+  B -.-|hosted on| P1
+  C -.-|hosted on| P2
+
+  P1 -->|sends & receives messages| SQ1
+  P2 -->|sends & receives messages| SQ1
+  P2 -->|sends & receives messages| SQ2
+  P3 -->|sends & receives messages| SQ2
+
+  MED <-->|sends & receives messages| SQ1
+  MED <-->|sends & receives messages| SQ2
+```
+
+Key points:
+
+- **Participant nodes never communicate directly** with each other; all messages flow through sequencers.
+- **Sequencers** provide a total-order multicast with privacy: recipients do not learn the sender's identity.
+- The **mediator** coordinates a two-phase commit protocol to achieve consensus, connecting to sequencers (not directly to participants).
+- A party can be **multi-hosted** across several participant nodes (e.g., Alice on P1 and P3).
+- Participants can connect to **multiple synchronizers** to address scalability, regulatory, or trust requirements. Contracts can be reassigned between synchronizers.
+
+For the full architecture reference, see the [in-repo documentation](docs-open/src/sphinx/overview/explanations/canton/protocol.rst)
+or the published [Canton documentation](https://docs.digitalasset.com/).
+
 ## Documentation
 
 Please refer to the [Documentation](https://docs.digitalasset.com/) for

docs-open/src/sphinx/participant/explanations/participant-architecture.rst

@@ -3,12 +3,86 @@
 ..
    SPDX-License-Identifier: Apache-2.0
 
-.. wip::
-    Document the high-level participant architecture.
-    Link to participant HA architecture for details on replication.
-
 .. _participant-architecture:
 
 Participant Architecture
 ========================
 
+A Participant Node hosts Daml parties and allows them to synchronize state changes
+with other participants through one or more :ref:`synchronizers <synchronizer-architecture>`.
+This page describes the main components of a participant and how they interact.
+
+Overview
+--------
+
+A participant node consists of the following high-level components:
+
+* **Ledger API** -- the gRPC interface through which applications submit commands and
+  subscribe to events. Access is scoped per user, and each user is associated with
+  one or more Daml parties.
+
+* **Admin API** -- the operator-facing interface for node management tasks such as
+  party and package management, synchronizer connections, and pruning.
+
+* **Daml Engine** -- evaluates Daml commands into full transactions by interpreting
+  the smart-contract logic. A submitted command contains only a root action; the engine
+  expands it into a complete transaction tree with all consequences.
+
+* **Synchronizer Router** -- selects which synchronizer to use for executing a given
+  transaction, based on where the input contracts are currently assigned.
+
+* **Transaction Processor** -- the core protocol component. It translates a transaction
+  into a confirmation request (computing the view decomposition and Merkle tree),
+  sends the request through the sequencer client, collects confirmation responses from
+  validating participants, and processes result messages from the mediator.
+
+* **Sequencer Client** -- maintains the authenticated connection to one or more
+  :ref:`sequencer nodes <protocol-sequencer-nodes>` on each connected synchronizer.
+  All communication with other participants and with the mediator flows through this
+  client.
+
+* **Contract Store** -- persists the contracts that are relevant to the hosted parties.
+  The *active contract set* (ACS) contains only currently active contracts, while the
+  full *private contract store* (PCS) also retains archived contracts for
+  historical queries.
+
+* **Indexer** -- reads committed events from the record-order publisher and stores them
+  in a format optimized for fast Ledger API reads. It feeds the transaction service,
+  the command completion service, and the active contract service.
+
+Command Processing Flow
+-----------------------
+
+When an application submits a command through the Ledger API, the participant processes
+it through the following stages:
+
+1. The **command submission service** authenticates and validates the command.
+2. The **Daml Engine** interprets the command to produce a full transaction.
+3. The **synchronizer router** identifies the appropriate synchronizer.
+4. The **transaction processor** prepares a confirmation request (view decomposition,
+   encryption, Merkle tree) and sends it via the **sequencer client**.
+5. Validating participants receive the request from the sequencer, validate the
+   transaction views they can see, and send their confirmation responses to the
+   **mediator** (again through the sequencer).
+6. The **mediator** collects responses and publishes a result message (approve or reject).
+7. On approval, each participant updates its contract store and the **indexer** makes
+   the committed transaction available through the Ledger API.
+
+Multi-Synchronizer Support
+--------------------------
+
+A participant can be connected to multiple synchronizers simultaneously. Each active
+contract is *assigned* to exactly one synchronizer at any point in time. If a transaction
+requires contracts that are assigned to different synchronizers, those contracts must
+first be *reassigned* to a common synchronizer using the
+:ref:`reassignment protocol <reassignment-protocol>`.
+
+For details on multi-synchronizer operation, see :ref:`multiple-synchronizers`.
+
+High Availability
+-----------------
+
+Participant nodes can be deployed in a high-availability (HA) configuration with active
+and passive replicas sharing a common database. For details on replication and failover,
+see :ref:`participant-ha`.
+