From 74e21e9722d3af4da0ccddce4a94e46cadad26e3 Mon Sep 17 00:00:00 2001
From: Josh Creek <8179928+jcreek@users.noreply.github.com>
Date: Fri, 25 Apr 2025 23:39:02 +0100
Subject: [PATCH] docs(*): Add section for architecture diagram alongside
 system flow diagram

---
 README.md | 25 +++++++++++++++++++++++--
 1 file changed, 23 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index bfa251b..0c3f634 100644
--- a/README.md
+++ b/README.md
@@ -96,7 +96,9 @@ _Why is this different from other AI grading tools?_
 > Watch live tool use and reasoning.  
 > Review or clear past assessments directly in history.
 
-### Architecture Diagram
+### System Flow Diagram (with HITL)
+
+This shows how a user interacts with the system and how requests are processed, including HITL.
 
 ```mermaid
 flowchart TD
@@ -127,7 +129,26 @@ flowchart TD
     APIHITL -->|Returns final feedback| Results
 ```
 
-Assessment history is **only stored locally** (no external storage).
+### Architecture Diagram
+
+This shows the big-picture technical structure and how my chosen technologies fit together.
+
+The architecture includes:
+
+- Frontend: SvelteKit app (browser)
+   - Connects to PartyKit (for real-time events)
+   - Calls API endpoints (/api/grade, /api/hitl-review)
+   - Saves assessment history in browser localStorage
+- Backend: SvelteKit API routes (serverless functions, e.g., Netlify)
+   - /api/grade: Handles grading, talks to Azure OpenAI
+   - /api/hitl-review: Handles teacher review, resumes AI grading
+- Third-Party Services:
+   - Azure OpenAI (AI grading, feedback)
+   - Azure Cognitive Services (if used)
+   - PartyKit (WebSocket server for real-time updates)
+- Data Storage: Only in browser (localStorage), no backend DB
+
+Actual diagram - TODO 
 
 ---