Skip to content

Commit 22a4580

Browse files
nficanoclaude
nficano
and
claude
committed
docs(diagrams): replace ASCII architecture diagram with Graphviz
Adds docs/diagrams/ with paired light/dark .dot sources and rendered SVGs for the architecture diagram, embedded via <picture> for prefers-color-scheme switching. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent e4c40e5 commit 22a4580

6 files changed

Lines changed: 470 additions & 21 deletions

File tree

‎README.md‎

Lines changed: 4 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -37,27 +37,10 @@ bin/arcp serve --host 127.0.0.1 --port 8765
3737

3838
## Architecture
3939

40-
```
41-
+-----------------------------+
42-
| Capability Layer |
43-
| (MCP Compatible) |
44-
+-----------------------------+
45-
+-----------------------------+
46-
| ARCP Runtime Layer |
47-
| - Identity & Sessions |
48-
| - Streams |
49-
| - Jobs |
50-
| - Subscriptions |
51-
| - Events |
52-
| - Permissions & Leases |
53-
| - Artifacts |
54-
| - Tracing & Metrics |
55-
+-----------------------------+
56-
+-----------------------------+
57-
| Transport Layer |
58-
| WebSocket / stdio (mandatory)|
59-
+-----------------------------+
60-
```
40+
<picture>
41+
<source media="(prefers-color-scheme: dark)" srcset="docs/diagrams/architecture-dark.svg">
42+
<img alt="ARCP PHP SDK architecture — Capability Layer (MCP-compatible) on top of the ARCP Runtime Layer (identity/sessions, streams, jobs, subscriptions, events, permissions & leases, artifacts, tracing & metrics) on top of the Transport Layer (WebSocket / stdio)" src="docs/diagrams/architecture-light.svg">
43+
</picture>
6144

6245
The runtime is `Arcp\Runtime\ARCPRuntime`; the client is
6346
`Arcp\Client\ARCPClient`. Both are async (Amp v3 + fibers) and both take a

‎docs/diagrams/README.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Diagrams
2+
3+
Paired light/dark Graphviz diagrams for the ARCP PHP SDK. Edit the
4+
`.dot` sources; render with `dot -Tsvg`.
5+
6+
## Architecture
7+
8+
<picture>
9+
<source media="(prefers-color-scheme: dark)" srcset="architecture-dark.svg">
10+
<img alt="ARCP PHP SDK architecture" src="architecture-light.svg">
11+
</picture>
12+
13+
## Render
14+
15+
```sh
16+
cd docs/diagrams
17+
for f in *.dot; do dot -Tsvg "$f" -o "${f%.dot}.svg"; done
18+
```
19+
20+
`graphviz` provides `dot`. On macOS: `brew install graphviz`. On
21+
Debian/Ubuntu: `apt-get install -y graphviz`.

‎docs/diagrams/architecture-dark.dot‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
// ARCP PHP SDK architecture stack (dark)
2+
digraph PhpSdkArchitecture {
3+
rankdir=TB; bgcolor="transparent"; compound=true; fontname="Helvetica";
4+
splines=ortho; nodesep=0.32; ranksep=0.45; pad="0.35,0.25";
5+
6+
node [shape=box, style="rounded,filled", fillcolor="#334155", color="#475569",
7+
fontname="Helvetica", fontsize=11, fontcolor="#F1F5F9",
8+
margin="0.22,0.11", penwidth=1.0];
9+
edge [fontname="Helvetica", fontsize=9, fontcolor="#94A3B8", color="#64748B",
10+
penwidth=1.1, arrowsize=0.75, arrowhead=vee];
11+
12+
Capability [
13+
label=<<FONT POINT-SIZE="12"><B>Capability Layer</B></FONT><BR/><FONT POINT-SIZE="9" COLOR="#CBD5E1">MCP compatible</FONT>>,
14+
fillcolor="#3B82F6", color="#2563EB", fontcolor="white", penwidth=1.4
15+
];
16+
17+
subgraph cluster_runtime {
18+
label=<<TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0" CELLSPACING="0"><TR><TD COLSPAN="3" HEIGHT="8"></TD></TR><TR><TD WIDTH="8"></TD><TD><FONT POINT-SIZE="12"><B>ARCP Runtime Layer</B></FONT></TD><TD WIDTH="8"></TD></TR></TABLE>>;
19+
style="rounded,filled";
20+
fillcolor="#0F172A"; color="#334155";
21+
fontname="Helvetica"; fontcolor="#94A3B8";
22+
margin=14; labeljust=l; penwidth=1.0;
23+
24+
Runtime [
25+
label=<<FONT POINT-SIZE="12"><B>ARCPRuntime</B></FONT>>,
26+
fillcolor="#F59E0B", color="#D97706", fontcolor="white", penwidth=1.4
27+
];
28+
29+
Identity [label="Identity & Sessions"];
30+
Streams [label="Streams"];
31+
Jobs [label="Jobs"];
32+
Subscriptions [label="Subscriptions"];
33+
Events [label="Events"];
34+
Permissions [label="Permissions & Leases"];
35+
Artifacts [label="Artifacts"];
36+
Tracing [label="Tracing & Metrics"];
37+
}
38+
39+
subgraph cluster_transport {
40+
label=<<TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0" CELLSPACING="0"><TR><TD COLSPAN="3" HEIGHT="8"></TD></TR><TR><TD WIDTH="8"></TD><TD><FONT POINT-SIZE="12"><B>Transport Layer</B></FONT></TD><TD WIDTH="8"></TD></TR></TABLE>>;
41+
style="rounded,filled";
42+
fillcolor="#1E293B"; color="#334155";
43+
fontname="Helvetica"; fontcolor="#94A3B8";
44+
margin=14; labeljust=l; penwidth=1.0;
45+
46+
Ws [label="WebSocket"];
47+
Stdio [label="stdio"];
48+
49+
Ws -> Stdio [style=invis];
50+
{ rank=same; Ws; Stdio; }
51+
}
52+
53+
edge [color="#94A3B8", penwidth=1.2];
54+
Capability -> Runtime [lhead=cluster_runtime];
55+
Runtime -> Ws [lhead=cluster_transport];
56+
57+
edge [color="#475569", penwidth=1.0];
58+
Runtime -> Identity;
59+
Runtime -> Streams;
60+
Runtime -> Jobs;
61+
Runtime -> Subscriptions;
62+
Runtime -> Events;
63+
Runtime -> Permissions;
64+
Runtime -> Artifacts;
65+
Runtime -> Tracing;
66+
}

‎docs/diagrams/architecture-dark.svg‎

Lines changed: 156 additions & 0 deletions
Loading

‎docs/diagrams/architecture-light.dot‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
// ARCP PHP SDK architecture stack (light)
2+
// Capability Layer (MCP) → ARCP Runtime Layer → Transport Layer.
3+
digraph PhpSdkArchitecture {
4+
rankdir=TB; bgcolor="transparent"; compound=true; fontname="Helvetica";
5+
splines=ortho; nodesep=0.32; ranksep=0.45; pad="0.35,0.25";
6+
7+
node [shape=box, style="rounded,filled", fillcolor="white", color="#CBD5E1",
8+
fontname="Helvetica", fontsize=11, fontcolor="#1F2937",
9+
margin="0.22,0.11", penwidth=1.0];
10+
edge [fontname="Helvetica", fontsize=9, fontcolor="#64748B", color="#94A3B8",
11+
penwidth=1.1, arrowsize=0.75, arrowhead=vee];
12+
13+
Capability [
14+
label=<<FONT POINT-SIZE="12"><B>Capability Layer</B></FONT><BR/><FONT POINT-SIZE="9" COLOR="#CBD5E1">MCP compatible</FONT>>,
15+
fillcolor="#3B82F6", color="#2563EB", fontcolor="white", penwidth=1.4
16+
];
17+
18+
subgraph cluster_runtime {
19+
label=<<TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0" CELLSPACING="0"><TR><TD COLSPAN="3" HEIGHT="8"></TD></TR><TR><TD WIDTH="8"></TD><TD><FONT POINT-SIZE="12"><B>ARCP Runtime Layer</B></FONT></TD><TD WIDTH="8"></TD></TR></TABLE>>;
20+
style="rounded,filled";
21+
fillcolor="#F1F5F9"; color="#E2E8F0";
22+
fontname="Helvetica"; fontcolor="#475569";
23+
margin=14; labeljust=l; penwidth=1.0;
24+
25+
Runtime [
26+
label=<<FONT POINT-SIZE="12"><B>ARCPRuntime</B></FONT>>,
27+
fillcolor="#F59E0B", color="#D97706", fontcolor="white", penwidth=1.4
28+
];
29+
30+
Identity [label="Identity & Sessions"];
31+
Streams [label="Streams"];
32+
Jobs [label="Jobs"];
33+
Subscriptions [label="Subscriptions"];
34+
Events [label="Events"];
35+
Permissions [label="Permissions & Leases"];
36+
Artifacts [label="Artifacts"];
37+
Tracing [label="Tracing & Metrics"];
38+
}
39+
40+
subgraph cluster_transport {
41+
label=<<TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0" CELLSPACING="0"><TR><TD COLSPAN="3" HEIGHT="8"></TD></TR><TR><TD WIDTH="8"></TD><TD><FONT POINT-SIZE="12"><B>Transport Layer</B></FONT></TD><TD WIDTH="8"></TD></TR></TABLE>>;
42+
style="rounded,filled";
43+
fillcolor="#F8FAFC"; color="#E2E8F0";
44+
fontname="Helvetica"; fontcolor="#475569";
45+
margin=14; labeljust=l; penwidth=1.0;
46+
47+
Ws [label="WebSocket"];
48+
Stdio [label="stdio"];
49+
50+
Ws -> Stdio [style=invis];
51+
{ rank=same; Ws; Stdio; }
52+
}
53+
54+
edge [color="#64748B", penwidth=1.2];
55+
Capability -> Runtime [lhead=cluster_runtime];
56+
Runtime -> Ws [lhead=cluster_transport];
57+
58+
edge [color="#CBD5E1", penwidth=1.0];
59+
Runtime -> Identity;
60+
Runtime -> Streams;
61+
Runtime -> Jobs;
62+
Runtime -> Subscriptions;
63+
Runtime -> Events;
64+
Runtime -> Permissions;
65+
Runtime -> Artifacts;
66+
Runtime -> Tracing;
67+
}

0 commit comments

Comments
 (0)