diff --git a/README.md b/README.md
index 92b722334..8513cd563 100644
--- a/README.md
+++ b/README.md
@@ -367,9 +367,11 @@ nodes:
 
 ## Architecture
 
-```
-CLI  -->  Coordinator  -->  Daemon(s)  -->  Nodes / Operators
-             (orchestration)  (per machine)    (user code)
+```mermaid
+flowchart LR
+    CLI[CLI<br/>dora] --> Coordinator[Coordinator<br/>orchestration]
+    Coordinator --> Daemons[Daemon(s)<br/>per machine]
+    Daemons --> Nodes[Nodes / Operators<br/>user code]
 ```
 
 | Layer | Protocol | Purpose |
diff --git a/docs/architecture.md b/docs/architecture.md
index 470330e60..1f13b559f 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -13,16 +13,31 @@ Dora is built on four core principles:
 
 ### Architecture Stack
 
-```
-┌─────────────────────────────────────────────────┐
-│  CLI (dora)          Coordinator (orchestrator) │  Layer 4: Orchestration
-├─────────────────────────────────────────────────┤
-│  Daemon (per-machine)    Runtime (operators)     │  Layer 3: Execution
-├─────────────────────────────────────────────────┤
-│  dora-core    shared-memory-server    Node API  │  Layer 2: Core Libraries
-├─────────────────────────────────────────────────┤
-│  dora-message (protocol + Arrow types)          │  Layer 1: Protocol
-└─────────────────────────────────────────────────┘
+```mermaid
+flowchart TB
+    subgraph L4[Layer 4: Orchestration]
+        CLI[CLI<br/>dora]
+        Coordinator[Coordinator<br/>orchestrator]
+    end
+
+    subgraph L3[Layer 3: Execution]
+        Daemon[Daemon<br/>per machine]
+        Runtime[Runtime<br/>operators]
+    end
+
+    subgraph L2[Layer 2: Core Libraries]
+        Core[dora-core]
+        Shmem[shared-memory-server]
+        NodeApi[Node API]
+    end
+
+    subgraph L1[Layer 1: Protocol]
+        Message[dora-message<br/>protocol + Arrow types]
+    end
+
+    L4 --> L3
+    L3 --> L2
+    L2 --> L1
 ```
 
 ## Workspace Structure
diff --git a/docs/quickstart.md b/docs/quickstart.md
index 14de996fc..acd19e82d 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -77,6 +77,28 @@ dora stop --all
 dora down
 ```
 
+```mermaid
+sequenceDiagram
+    participant User
+    participant CLI as dora CLI
+    participant Coordinator
+    participant Daemon
+    participant Nodes
+
+    User->>CLI: dora up
+    CLI->>Coordinator: start coordinator
+    CLI->>Daemon: start local daemon
+    Daemon->>Coordinator: register
+    User->>CLI: dora start dataflow.yml
+    CLI->>Coordinator: submit dataflow
+    Coordinator->>Daemon: spawn node processes
+    Daemon->>Nodes: start nodes
+    Nodes->>Nodes: exchange messages
+    User->>CLI: dora stop --all
+    CLI->>Coordinator: stop dataflow
+    Coordinator->>Daemon: stop nodes
+```
+
 ## Next Steps
 
 - **Examples**: Browse `examples/` for service, action, streaming, and Python patterns