From fac740f36233c3b8e3ec8f5b2b02abaeb85ca83e Mon Sep 17 00:00:00 2001
From: William Valentin <william.valentin.info@gmail.com>
Date: Sun, 15 Feb 2026 10:39:46 -0800
Subject: [PATCH] docs(architecture): add trust-boundary system map diagram

---
 docs/architecture/AGENT_DIAGRAM.md | 55 ++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)

diff --git a/docs/architecture/AGENT_DIAGRAM.md b/docs/architecture/AGENT_DIAGRAM.md
index 6c5b887..542f677 100644
--- a/docs/architecture/AGENT_DIAGRAM.md
+++ b/docs/architecture/AGENT_DIAGRAM.md
@@ -4,6 +4,61 @@ This is a high-signal, agent-oriented view of Flynn's structure and execution fl
 
 If you're new to the codebase, start here, then jump to the referenced files.
 
+## System Map (Boundaries + Trust)
+
+This is the fastest way to understand what runs where, and where the security boundaries sit.
+
+```mermaid
+flowchart LR
+  subgraph EXT[External Systems]
+    MP[Model Providers\nAnthropic/OpenAI/Gemini/...\nvia ModelClient]
+    CH[Chat Networks\nTelegram/Discord/Slack/WhatsApp/...]
+    WEB[Web\nsearch/fetch targets]
+  end
+
+  subgraph HOST[Host (Flynn Daemon)]
+    CA[ChannelAdapters]
+    GW[Gateway\nHTTP + WS JSON-RPC + Web UI]
+    RT[Routing\ncreateMessageRouter()]
+    SM[SessionManager\nSQLite]
+    OR[AgentOrchestrator]
+    NA[NativeAgent\n(tool loop)]
+    MR[ModelRouter]
+    TP[ToolPolicy + ToolRegistry]
+    TE[ToolExecutor\nhooks + enforcement + audit]
+    MEM[Memory Store\nfiles + vector/keyword]
+    AU[Audit Logger\nredacted]
+    HS[Hooks/Autonomy\nconfirm/log/silent]
+  end
+
+  subgraph SBX[Sandbox (per-session Docker)]
+    ST[Sandboxed Tools\nshell/process/fs writes]
+    FS[Sandbox FS\nworkspace mount (scoped)]
+    NET[Sandbox Network\n(egress policy)]
+  end
+
+  CH --> CA
+  GW --> RT
+  CA --> RT
+  RT --> SM
+  RT --> OR
+  OR --> NA
+  NA --> MR
+  MR --> MP
+
+  NA --> TP
+  TP --> TE
+  TE --> HS
+  TE --> AU
+  TE --> MEM
+
+  TE -->|high-risk tools| ST
+  ST --> FS
+  ST --> NET
+
+  TE -->|web tools| WEB
+```
+
 ## Big Picture (Runtime Data Flow)
 
 ```text