From 3401e2be8b3aee5dab4bb84e62378b672e95e4ce Mon Sep 17 00:00:00 2001
From: eric sciple <ericsciple@users.noreply.github.com>
Date: Fri, 5 Dec 2025 03:35:21 +0000
Subject: [PATCH] Add Mermaid architecture diagrams to README

---
 README.md | 86 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 86 insertions(+)

diff --git a/README.md b/README.md
index 8b25749..31bdfe7 100644
--- a/README.md
+++ b/README.md
@@ -41,6 +41,49 @@ Be more confident when authoring and modifying workflows. Find errors before com
 1. Open a GitHub repository.
 1. You will be able to utilize the syntax features in Workflow files, and you can find the GitHub Actions icon on the left navigation to manage your Workflows.
 
+## Key Components
+
+<!-- If the Mermaid diagrams below aren't rendering in VS Code preview, install the "Markdown Preview Mermaid Support" extension -->
+
+```mermaid
+graph LR
+    subgraph "User Interface"
+        WF[Workflows View]
+        CB[Current Branch View]
+        SET[Settings View]
+        EDITOR[Workflow Editor]
+    end
+    
+    subgraph "Core Features"
+        AUTH[Authentication]
+        MANAGE[Workflow Management]
+        LOGS[Log Viewing]
+        VALID[Validation & Completion]
+    end
+    
+    subgraph "Data Management"
+        STORE[Run Store]
+        SECRETS[Secrets/Variables]
+        PIN[Pinned Workflows]
+    end
+    
+    WF --> MANAGE
+    WF --> PIN
+    CB --> MANAGE
+    SET --> SECRETS
+    EDITOR --> VALID
+    
+    MANAGE --> STORE
+    MANAGE --> AUTH
+    LOGS --> STORE
+    VALID --> AUTH
+    SECRETS --> AUTH
+    PIN --> MANAGE
+    
+    style AUTH fill:#fd8c73
+    style MANAGE fill:#58a6ff
+    style VALID fill:#3fb950
+```
 
 ## Supported Features
 
@@ -57,6 +100,49 @@ We have enabled experimental functionality to support GitHub Enterprise Server,
 
 We currently do not have the capability to support Operating System (OS) certificates or enterprise proxies (we plan to support pulling from the VS Code proxy settings), but we have plans for it in the future and it is on our backlog! 
 
+## Architecture Overview
+
+```mermaid
+graph TB
+    subgraph "VS Code Extension"
+        EXT[Extension Host]
+        TV[Tree Views]
+        CMD[Commands]
+        TRACK[Workspace Tracker]
+    end
+    
+    subgraph "Language Support"
+        LC[Language Client]
+        LS[Language Server]
+        WP[Workflow Parser]
+        EE[Expression Engine]
+    end
+    
+    subgraph "External Services"
+        GH[GitHub API]
+        REPO[Git Repository]
+    end
+    
+    EXT --> LC
+    EXT --> TV
+    EXT --> CMD
+    EXT --> TRACK
+    
+    LC <--> LS
+    LS --> WP
+    LS --> EE
+    WP --> EE
+    
+    TV --> GH
+    CMD --> GH
+    TRACK --> REPO
+    LS --> GH
+    
+    style EXT fill:#2ea44f
+    style LS fill:#0969da
+    style GH fill:#8250df
+```
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md). A description of the architecture of the extension can be found [here](./docs/project-architecture.md).