| 1 | # Accept & Execute — C4 Diagrams (Graphviz DOT)
|
| 2 |
|
| 3 | ## Level 1: System Context
|
| 4 |
|
| 5 | ```graphviz
|
| 6 | digraph C4_Context {
|
| 7 | graph [rankdir=TB, fontname="Helvetica", fontsize=12, nodesep=1.0, ranksep=1.0, pad=0.5]
|
| 8 | node [fontname="Helvetica", fontsize=11, shape=box, style="rounded,filled", margin="0.3,0.2"]
|
| 9 | edge [fontname="Helvetica", fontsize=9, color="#707070"]
|
| 10 |
|
| 11 | user [label="Developer", shape=box, style="rounded,filled", fillcolor="#08427b", fontcolor=white]
|
| 12 |
|
| 13 | web [label="PAS Web\n[Leptos WASM + Axum SSR]", fillcolor="#1168bd", fontcolor=white]
|
| 14 | cli [label="PAS CLI\n[decompose & scaffold]", fillcolor="#999999", fontcolor=white]
|
| 15 | fs [label="Filesystem\n[specs, pipelines, issues]", fillcolor="#999999", fontcolor=white, shape=cylinder]
|
| 16 |
|
| 17 | user -> web [label="Approve & Execute"]
|
| 18 | web -> user [label="SSE progress stream", style=dashed]
|
| 19 | web -> cli [label="child process"]
|
| 20 | web -> fs [label="read / write"]
|
| 21 | cli -> fs [label="write .dot"]
|
| 22 | }
|
| 23 | ```
|
| 24 |
|
| 25 | ## Level 2: Container
|
| 26 |
|
| 27 | ```graphviz
|
| 28 | digraph C4_Container {
|
| 29 | graph [rankdir=TB, fontname="Helvetica", fontsize=12, nodesep=1.0, ranksep=1.2, pad=0.5, compound=true]
|
| 30 | node [fontname="Helvetica", fontsize=11, shape=box, style="rounded,filled", margin="0.3,0.2"]
|
| 31 | edge [fontname="Helvetica", fontsize=9, color="#707070"]
|
| 32 |
|
| 33 | user [label="Developer", fillcolor="#08427b", fontcolor=white]
|
| 34 |
|
| 35 | subgraph cluster_web {
|
| 36 | label="PAS Web"
|
| 37 | style=dashed
|
| 38 | color="#1168bd"
|
| 39 | fontname="Helvetica"
|
| 40 | fontsize=12
|
| 41 | fontcolor="#1168bd"
|
| 42 |
|
| 43 | wasm [label="Browser Client\n[Leptos WASM, xterm.js]", fillcolor="#1168bd", fontcolor=white]
|
| 44 | axum [label="Axum Server\n[Leptos SSR]", fillcolor="#1168bd", fontcolor=white]
|
| 45 | broadcast [label="Broadcast Channels\n[tokio, in-memory]", fillcolor="#438dd5", fontcolor=white, shape=cylinder]
|
| 46 | }
|
| 47 |
|
| 48 | cli [label="PAS CLI", fillcolor="#999999", fontcolor=white]
|
| 49 | fs [label="Filesystem", fillcolor="#999999", fontcolor=white, shape=cylinder]
|
| 50 |
|
| 51 | user -> wasm [label="click button"]
|
| 52 | wasm -> axum [label="POST server fn"]
|
| 53 | axum -> wasm [label="HTTP + SSE", style=dashed]
|
| 54 | axum -> cli [label="tokio::process"]
|
| 55 | axum -> fs [label="std::fs"]
|
| 56 | axum -> broadcast [label="publish_event()"]
|
| 57 | broadcast -> axum [label="BroadcastStream", style=dashed]
|
| 58 | }
|
| 59 | ```
|
| 60 |
|
| 61 | ### Container Legend
|
| 62 |
|
| 63 | | Container | Technology | Responsibility |
|
| 64 | |-----------|-----------|----------------|
|
| 65 | | Browser Client | Leptos WASM, xterm.js | Renders UI, dispatches server fns, subscribes to SSE |
|
| 66 | | Axum Server | Rust, Leptos SSR | Handles server fns, spawns CLI processes, streams events |
|
| 67 | | Broadcast Channels | tokio::broadcast | Session-keyed event bus with 100-event replay buffer |
|
| 68 | | PAS CLI | Rust binary | `decompose` specs into epics, `scaffold` pipeline .dot files |
|
| 69 | | Filesystem | Local disk | `.pas/spec.md`, `pipelines/*.dot`, beads issues |
|
| 70 |
|
| 71 | ## Level 3: Component
|
| 72 |
|
| 73 | ```graphviz
|
| 74 | digraph C4_Component {
|
| 75 | graph [rankdir=TB, fontname="Helvetica", fontsize=12, nodesep=0.8, ranksep=1.0, pad=0.5, compound=true]
|
| 76 | node [fontname="Helvetica", fontsize=10, shape=box, style="rounded,filled", margin="0.25,0.15"]
|
| 77 | edge [fontname="Helvetica", fontsize=9, color="#707070"]
|
| 78 |
|
| 79 | subgraph cluster_browser {
|
| 80 | label="Browser (WASM)"
|
| 81 | style=dashed
|
| 82 | color="#1168bd"
|
| 83 | fontname="Helvetica"
|
| 84 | fontsize=11
|
| 85 | fontcolor="#1168bd"
|
| 86 |
|
| 87 | approval [label="ApprovalBar", fillcolor="#1168bd", fontcolor=white]
|
| 88 | exec_panel [label="ExecutionPanel", fillcolor="#1168bd", fontcolor=white]
|
| 89 | exec_node [label="ExecutionNode", fillcolor="#1168bd", fontcolor=white]
|
| 90 | }
|
| 91 |
|
| 92 | subgraph cluster_server {
|
| 93 | label="Axum Server (SSR)"
|
| 94 | style=dashed
|
| 95 | color="#438dd5"
|
| 96 | fontname="Helvetica"
|
| 97 | fontsize=11
|
| 98 | fontcolor="#438dd5"
|
| 99 |
|
| 100 | start_exec [label="start_execution()", fillcolor="#438dd5", fontcolor=white]
|
| 101 | cli_path [label="pas_cli_path()", fillcolor="#438dd5", fontcolor=white]
|
| 102 | runner [label="PipelineRunner", fillcolor="#438dd5", fontcolor=white]
|
| 103 | stream [label="stream_events()", fillcolor="#438dd5", fontcolor=white]
|
| 104 | publish [label="publish_event()", fillcolor="#438dd5", fontcolor=white]
|
| 105 | replay [label="SESSION_STATE\n[replay buffer]", fillcolor="#438dd5", fontcolor=white, shape=cylinder]
|
| 106 | }
|
| 107 |
|
| 108 | cli [label="PAS CLI", fillcolor="#999999", fontcolor=white]
|
| 109 | registry [label="Handler Registry", fillcolor="#999999", fontcolor=white]
|
| 110 |
|
| 111 | approval -> start_exec [label="POST"]
|
| 112 | start_exec -> cli_path [label="resolve path"]
|
| 113 | start_exec -> cli [label="decompose / scaffold"]
|
| 114 | start_exec -> runner [label="tokio::spawn"]
|
| 115 | start_exec -> approval [label="ExecutionResponse", style=dashed]
|
| 116 | approval -> exec_panel [label="on_approve(session_id)"]
|
| 117 | exec_panel -> stream [label="SSE EventSource"]
|
| 118 | exec_panel -> exec_node [label="renders"]
|
| 119 | runner -> registry [label="resolve + execute"]
|
| 120 | runner -> publish [label="events"]
|
| 121 | publish -> replay [label="buffer"]
|
| 122 | stream -> replay [label="reconnect replay", style=dashed]
|
| 123 | stream -> exec_panel [label="SSE events", style=dashed]
|
| 124 | }
|
| 125 | ```
|
| 126 |
|
| 127 | ### Component Legend
|
| 128 |
|
| 129 | | Component | File | Responsibility |
|
| 130 | |-----------|------|----------------|
|
| 131 | | ApprovalBar | `components/approval_bar.rs` | Button, dispatches `start_execution()`, shows phase spinner |
|
| 132 | | ExecutionPanel | `components/execution_panel.rs` | Subscribes to SSE, renders node list with live status |
|
| 133 | | ExecutionNode | `components/execution_node.rs` | Single node: status badge, cost, notes |
|
| 134 | | start_execution() | `server/execute.rs` | Orchestrates decompose, scaffold, parse, spawn |
|
| 135 | | pas_cli_path() | `server/execute.rs` | Resolves CLI binary from `PAS_CLI_PATH` env var |
|
| 136 | | PipelineRunner | `server/execute.rs` | Walks graph, executes handlers, publishes events |
|
| 137 | | stream_events() | `server/stream.rs` | SSE endpoint, bridges broadcast to EventSource |
|
| 138 | | publish_event() | `server/stream.rs` | Writes to broadcast channel + replay buffer |
|
| 139 | | SESSION_STATE | `server/stream.rs` | Last 100 events per session for reconnect replay |
|
| 140 |
|
| 141 | ## Sequence (as DOT)
|
| 142 |
|
| 143 | ```graphviz
|
| 144 | digraph Sequence {
|
| 145 | graph [rankdir=LR, fontname="Helvetica", fontsize=12, nodesep=0.6, ranksep=0.5, pad=0.5]
|
| 146 | node [fontname="Helvetica", fontsize=10, shape=box, style="rounded,filled", fillcolor="#f0f0f0", margin="0.2,0.1"]
|
| 147 | edge [fontname="Helvetica", fontsize=8, color="#707070"]
|
| 148 |
|
| 149 | // Actors / participants
|
| 150 | User [label="Developer", fillcolor="#08427b", fontcolor=white]
|
| 151 | AB [label="ApprovalBar", fillcolor="#1168bd", fontcolor=white]
|
| 152 | SE [label="start_execution()", fillcolor="#438dd5", fontcolor=white]
|
| 153 | CLI [label="PAS CLI", fillcolor="#999999", fontcolor=white]
|
| 154 | FS [label="Filesystem", fillcolor="#999999", fontcolor=white, shape=cylinder]
|
| 155 | PR [label="PipelineRunner", fillcolor="#438dd5", fontcolor=white]
|
| 156 | BC [label="Broadcast", fillcolor="#438dd5", fontcolor=white, shape=cylinder]
|
| 157 | SSE [label="stream_events()", fillcolor="#438dd5", fontcolor=white]
|
| 158 | EP [label="ExecutionPanel", fillcolor="#1168bd", fontcolor=white]
|
| 159 |
|
| 160 | // Flow
|
| 161 | User -> AB [label="1. Click"]
|
| 162 | AB -> SE [label="2. POST server fn"]
|
| 163 | SE -> FS [label="3. Check spec.md"]
|
| 164 | SE -> CLI [label="4. decompose"]
|
| 165 | CLI -> SE [label="5. epic_id", style=dashed]
|
| 166 | SE -> CLI [label="6. scaffold"]
|
| 167 | CLI -> FS [label="7. write .dot"]
|
| 168 | SE -> FS [label="8. read .dot"]
|
| 169 | SE -> PR [label="9. tokio::spawn"]
|
| 170 | SE -> AB [label="10. ExecutionResponse", style=dashed]
|
| 171 | AB -> EP [label="11. on_approve"]
|
| 172 | EP -> SSE [label="12. EventSource"]
|
| 173 |
|
| 174 | // Pipeline loop
|
| 175 | PR -> BC [label="13. node_start"]
|
| 176 | BC -> SSE [label="14. broadcast", style=dashed]
|
| 177 | SSE -> EP [label="15. SSE event", style=dashed]
|
| 178 | PR -> PR [label="16. execute handler"]
|
| 179 | PR -> BC [label="17. node_complete"]
|
| 180 | BC -> SSE [label="18. broadcast", style=dashed]
|
| 181 | SSE -> EP [label="19. SSE event", style=dashed]
|
| 182 |
|
| 183 | // Completion
|
| 184 | PR -> BC [label="20. pipeline_complete"]
|
| 185 | BC -> SSE [label="21. broadcast", style=dashed]
|
| 186 | SSE -> EP [label="22. Done", style=dashed]
|
| 187 | }
|
| 188 | ```
|