diff --git a/README.md b/README.md
index 791ec47d..c069d964 100644
--- a/README.md
+++ b/README.md
@@ -47,6 +47,10 @@ For the full setup walkthrough — projects, credentials, webhooks, and triggers
## 🏗️ Architecture
+
+ 
+
+
Cascade runs as three independent services:
| Service | Entry Point | Role |
diff --git a/docs/architecture.d2 b/docs/architecture.d2
new file mode 100644
index 00000000..e426e2c9
--- /dev/null
+++ b/docs/architecture.d2
@@ -0,0 +1,75 @@
+vars: {
+ d2-config: {
+ theme-id: 300
+ }
+}
+
+SCM: {
+ github
+ style: {
+ shadow: true
+ fill: DarkBlue
+ }
+}
+
+PM: {
+ trello
+ jira
+ style: {
+ shadow: true
+ fill: Orange
+ }
+}
+
+CASCADE: {
+ router
+ api
+ worker manager: {
+ worker1: {
+ agent harness
+ cascade tools
+ checked out repo
+ }
+ worker2: {
+ "..."
+ }
+ worker N: {
+ "..."
+ }
+ }
+
+ router -> QUEUE
+ QUEUE -> worker manager
+
+ api <-> DB
+ router <-> DB
+ worker manager <-> DB
+
+ DB: {
+ shape: cylinder
+ }
+
+ QUEUE: {
+ shape: queue
+ }
+}
+
+client: {
+ style: {
+ shadow: true
+ fill: Beige
+ }
+ dashboard
+ cli
+}
+
+client.dashboard <-> CASCADE.api
+client.cli <-> CASCADE.api
+
+SCM -> CASCADE.router: webhook triggers
+PM -> CASCADE.router: webhook triggers
+
+CASCADE.worker manager -> PM: updates, comments
+CASCADE.worker manager -> SCM: PRs, reviews, comments
+SCM -> CASCADE.worker manager: repo + PR contents
+
diff --git a/docs/architecture.svg b/docs/architecture.svg
new file mode 100644
index 00000000..5b20125a
--- /dev/null
+++ b/docs/architecture.svg
@@ -0,0 +1,154 @@
+