From fdf2e6897c44840efefa5e46983138535e95fdf2 Mon Sep 17 00:00:00 2001
From: NanaKay007 <jnranikuabe@gmail.com>
Date: Sat, 31 Jan 2026 09:58:53 -0800
Subject: [PATCH 1/2] Fix architecture overview diagram accuracy
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- React/Vite not Next.js, Express 5 not Next.js API
- Same-origin HTTP + WebSocket, not separate HTTPS
- MongoDB connected from Auth Service (users, sessions) and
  Chat Service (conversations, messages, pending actions),
  not just LangChain
- LLM provider shows both Gemini and Claude

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 system-design.md | 32 +++++++++++++++++---------------
 1 file changed, 17 insertions(+), 15 deletions(-)

diff --git a/system-design.md b/system-design.md
index f052bb2..0610895 100644
--- a/system-design.md
+++ b/system-design.md
@@ -5,7 +5,7 @@
 ```
 ┌─────────────────────────────────────────────────────┐
 │                   Frontend (SPA)                     │
-│         React / Next.js (static export)              │
+│              React 19 / Vite / Tailwind              │
 │  ┌───────────┐ ┌───────────┐ ┌────────────────────┐ │
 │  │ Auth View │ │ Calendar  │ │  Chat Panel         │ │
 │  │           │ │ Dashboard │ │  (collapsible side  │ │
@@ -15,25 +15,27 @@
 │  │           │ │           │ │   approval UI)      │ │
 │  └───────────┘ └───────────┘ └────────────────────┘ │
 └────────────────────┬────────────────────────────────┘
-                     │ HTTPS
+                     │ Same-origin HTTP + WebSocket
 ┌────────────────────▼────────────────────────────────┐
 │                 Backend API                          │
-│          Node.js (Express / Next.js API)             │
+│             Node.js / Express 5                      │
 │  ┌──────────┐ ┌──────────┐ ┌──────────────────────┐ │
 │  │ Auth     │ │ Calendar │ │  Agent / Chat        │ │
 │  │ Service  │ │ Service  │ │  Service (LangChain) │ │
-│  └──────────┘ └──────────┘ └──────────────────────┘ │
-└───┬──────────────┬──────────────────┬───────────────┘
-    │              │                  │
-    ▼              ▼                  ▼
-Google OAuth   Google Calendar    LangChain TS Agent
-  2.0 API        API              + LLM Provider
-                                  (e.g. Gemini free tier)
-                                      │
-                                      ▼
-                               MongoDB
-                              (conversations, pending
-                               actions, sessions)
+│  └────┬─────┘ └────┬─────┘ └──────────┬───────────┘ │
+└───────┼─────────────┼─────────────────┼─────────────┘
+        │             │                 │
+        ▼             ▼                 ▼
+   Google OAuth  Google Calendar   LangChain TS Agent
+    2.0 API        API             + LLM Provider
+                                   (Gemini / Claude)
+        │                               │
+        └───────────┐   ┌───────────────┘
+                    ▼   ▼
+                  MongoDB
+           (users, sessions,
+            conversations, messages,
+            pending actions)
 ```
 
 ## Data Models

From bd31e4b331c1a582b125f1c3255595aac0004902 Mon Sep 17 00:00:00 2001
From: NanaKay007 <jnranikuabe@gmail.com>
Date: Sat, 31 Jan 2026 10:02:37 -0800
Subject: [PATCH 2/2] Convert system-design diagrams to Mermaid where
 appropriate
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Architecture overview: Mermaid flowchart
- Auth flow: Mermaid sequence diagram
- Calendar viewing flow: Mermaid sequence diagram
- Chat HITL flow: Mermaid sequence diagram
- Production architecture: Mermaid flowchart
- Conversation memory flow: kept as ASCII (multi-line box
  labels are more readable this way); fixed entry point
  from POST /api/chat to WS /ws

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 system-design.md | 201 ++++++++++++++++++++++-------------------------
 1 file changed, 92 insertions(+), 109 deletions(-)

diff --git a/system-design.md b/system-design.md
index 0610895..a6c9161 100644
--- a/system-design.md
+++ b/system-design.md
@@ -2,40 +2,28 @@
 
 ## Architecture Overview
 
-```
-┌─────────────────────────────────────────────────────┐
-│                   Frontend (SPA)                     │
-│              React 19 / Vite / Tailwind              │
-│  ┌───────────┐ ┌───────────┐ ┌────────────────────┐ │
-│  │ Auth View │ │ Calendar  │ │  Chat Panel         │ │
-│  │           │ │ Dashboard │ │  (collapsible side  │ │
-│  │           │ │           │ │   panel / mobile    │ │
-│  │           │ │           │ │   full-screen       │ │
-│  │           │ │           │ │   overlay, HITL     │ │
-│  │           │ │           │ │   approval UI)      │ │
-│  └───────────┘ └───────────┘ └────────────────────┘ │
-└────────────────────┬────────────────────────────────┘
-                     │ Same-origin HTTP + WebSocket
-┌────────────────────▼────────────────────────────────┐
-│                 Backend API                          │
-│             Node.js / Express 5                      │
-│  ┌──────────┐ ┌──────────┐ ┌──────────────────────┐ │
-│  │ Auth     │ │ Calendar │ │  Agent / Chat        │ │
-│  │ Service  │ │ Service  │ │  Service (LangChain) │ │
-│  └────┬─────┘ └────┬─────┘ └──────────┬───────────┘ │
-└───────┼─────────────┼─────────────────┼─────────────┘
-        │             │                 │
-        ▼             ▼                 ▼
-   Google OAuth  Google Calendar   LangChain TS Agent
-    2.0 API        API             + LLM Provider
-                                   (Gemini / Claude)
-        │                               │
-        └───────────┐   ┌───────────────┘
-                    ▼   ▼
-                  MongoDB
-           (users, sessions,
-            conversations, messages,
-            pending actions)
+```mermaid
+graph TD
+    subgraph Frontend["Frontend (SPA) — React 19 / Vite / Tailwind"]
+        AuthView[Auth View]
+        CalendarDash[Calendar Dashboard]
+        ChatPanel["Chat Panel<br/>(collapsible side panel /<br/>mobile full-screen overlay,<br/>HITL approval UI)"]
+    end
+
+    Frontend -->|"Same-origin HTTP + WebSocket"| Backend
+
+    subgraph Backend["Backend API — Node.js / Express 5"]
+        AuthSvc[Auth Service]
+        CalSvc[Calendar Service]
+        ChatSvc["Agent / Chat Service<br/>(LangChain)"]
+    end
+
+    AuthSvc --> GoogleOAuth[Google OAuth 2.0 API]
+    CalSvc --> GoogleCal[Google Calendar API]
+    ChatSvc --> LLM["LLM Provider<br/>(Gemini / Claude)"]
+
+    AuthSvc --> MongoDB
+    ChatSvc --> MongoDB["MongoDB<br/>(users, sessions, conversations,<br/>messages, pending actions)"]
 ```
 
 ## Data Models
@@ -174,75 +162,82 @@ The agent is built using **LangChain.js** with the following components:
 
 ### Authentication Flow
 
-```
-User          Frontend         Backend           Google
- │               │                │                │
- │──click login─▶│                │                │
- │               │──GET /auth/login──▶             │
- │               │◀─redirect URL──│                │
- │◀──redirect────│                │                │
- │──consent──────────────────────────────────────▶│
- │◀─────────────────────auth code─────────────────│
- │──callback─────▶               │                │
- │               │──GET /auth/callback?code=──────▶│
- │               │               │──exchange code─▶│
- │               │               │◀─tokens────────│
- │               │               │ (store tokens)  │
- │               │◀─session/JWT──│                │
- │◀──logged in───│               │                │
+```mermaid
+sequenceDiagram
+    actor User
+    participant Frontend
+    participant Backend
+    participant Google
+
+    User->>Frontend: Click login
+    Frontend->>Backend: GET /auth/login
+    Backend-->>Frontend: Redirect URL
+    Frontend-->>User: Redirect to Google
+    User->>Google: Consent
+    Google-->>User: Auth code
+    User->>Frontend: Callback
+    Frontend->>Backend: GET /auth/callback?code=
+    Backend->>Google: Exchange code
+    Google-->>Backend: Tokens
+    Note over Backend: Store tokens in session
+    Backend-->>Frontend: Session cookie
+    Frontend-->>User: Logged in
 ```
 
 ### Calendar Viewing Flow
 
-```
-User          Frontend              Backend          Google Calendar API
- │               │                     │                    │
- │──view cals───▶│                     │                    │
- │               │──GET /api/calendars─▶                    │
- │               │                     │──list calendars───▶│
- │               │                     │◀─calendar list─────│
- │               │◀─calendars JSON─────│                    │
- │◀──render──────│                     │                    │
- │               │                     │                    │
- │──click cal───▶│                     │                    │
- │               │──GET /api/calendars/{id}/events─────────▶│
- │               │                     │──list events──────▶│
- │               │                     │◀─events───────────│
- │               │◀─events JSON────────│                    │
- │◀──render──────│                     │                    │
+```mermaid
+sequenceDiagram
+    actor User
+    participant Frontend
+    participant Backend
+    participant GoogleCal as Google Calendar API
+
+    User->>Frontend: View calendars
+    Frontend->>Backend: GET /api/calendars
+    Backend->>GoogleCal: List calendars
+    GoogleCal-->>Backend: Calendar list
+    Backend-->>Frontend: Calendars JSON
+    Frontend-->>User: Render calendar list
+
+    User->>Frontend: Click calendar
+    Frontend->>Backend: GET /api/calendars/{id}/events
+    Backend->>GoogleCal: List events
+    GoogleCal-->>Backend: Events
+    Backend-->>Frontend: Events JSON
+    Frontend-->>User: Render calendar view
 ```
 
 ### Chat with Human-In-The-Loop Flow
 
-```
-User          Frontend              Backend             LLM           Google Cal API
- │               │                     │                  │                │
- │──"schedule    │                     │                  │                │
- │  meeting"────▶│                     │                  │                │
- │               │──WS send_message───▶                   │                │
- │               │                     │──prompt + ───────▶                │
- │               │                     │  conversation    │                │
- │               │                     │  history         │                │
- │               │                     │◀─tool call───────│                │
- │               │                     │  (create_event)  │                │
- │               │                     │                  │                │
- │               │                     │ (save PendingAction)              │
- │               │◀─reply + pending────│                  │                │
- │◀──show action │  action             │                  │                │
- │   for approval│                     │                  │                │
- │               │                     │                  │                │
- │──approve─────▶│                     │                  │                │
- │               │──POST /api/actions/{id}/approve────────▶                │
- │               │                     │──create event────────────────────▶│
- │               │                     │◀─event created───────────────────│
- │               │◀─confirmation───────│                  │                │
- │◀──"Done!"─────│                     │                  │                │
+```mermaid
+sequenceDiagram
+    actor User
+    participant Frontend
+    participant Backend
+    participant LLM
+    participant GoogleCal as Google Calendar API
+
+    User->>Frontend: "Schedule meeting"
+    Frontend->>Backend: WS send_message
+    Backend->>LLM: Prompt + conversation history
+    LLM-->>Backend: Tool call (create_event)
+    Note over Backend: Save PendingAction to MongoDB
+    Backend-->>Frontend: Reply + pending action
+    Frontend-->>User: Show action for approval
+
+    User->>Frontend: Approve
+    Frontend->>Backend: POST /api/actions/{id}/approve
+    Backend->>GoogleCal: Create event
+    GoogleCal-->>Backend: Event created
+    Backend-->>Frontend: Confirmation
+    Frontend-->>User: "Done!"
 ```
 
 ### Conversation Memory Flow (LangChain)
 
 ```
-POST /api/chat
+WS /ws (send_message)
      │
      ▼
 ┌──────────────────────────┐
@@ -304,25 +299,13 @@ POST /api/chat
 
 Single-service deployment on Railway — the Express backend serves the built React SPA as static files, eliminating cross-origin complexity.
 
-```
-┌─────────────────────────────────┐
-│      Railway (Single Service)   │
-│  ┌───────────────────────────┐  │
-│  │  Express Backend          │  │
-│  │  - API routes (/api/*)    │  │
-│  │  - WebSocket (/ws)        │  │
-│  │  - Static files (app/dist)│  │
-│  │  - SPA fallback           │  │
-│  └─────────────┬─────────────┘  │
-│                │                │
-└────────────────┼────────────────┘
-                 │
-                 ▼
-       ┌──────────────────────┐
-       │  MongoDB Atlas (M0)   │
-       │  Sessions, Users,     │
-       │  Conversations, etc.  │
-       └──────────────────────┘
+```mermaid
+graph TD
+    subgraph Railway["Railway (Single Service)"]
+        Express["Express Backend<br/>• API routes (/api/*)<br/>• WebSocket (/ws)<br/>• Static files (app/dist)<br/>• SPA fallback"]
+    end
+
+    Express --> Mongo["MongoDB Atlas (M0)<br/>Sessions, Users,<br/>Conversations, Pending Actions"]
 ```
 
 ### Production Configuration