Refactor diagrams for clarity and add setup timeline

Updated the Token Lifecycle diagram in `architecture-diagrams.md`:
- Added detailed states, transitions, and explanatory notes.
- Grouped related states into nested structures for readability.
- Enhanced the Token Lifecycle Stages section with step-by-step details.

Improved the Setup Flow Overview in `quick-start.md`:
- Renamed steps for consistency and clarity.
- Reorganized subgraphs with descriptive names.
- Added color-coded styles for visual distinction.
- Introduced a Setup Timeline summarizing configuration steps.

Streamlined both diagrams by removing redundant transitions and aligning with best practices for `mermaid` syntax.

Author: christiannagel

docs/authentication/architecture-diagrams.md

@@ -264,67 +264,104 @@ graph TB
 
 ```mermaid
 stateDiagram-v2
-    [*] --> Login: User Initiates Login
+    [*] --> Login
+    Login --> TokenIssuance
+    TokenIssuance --> TokenStorage
+    TokenStorage --> TokenUsage
+    TokenUsage --> TokenRefresh
+    TokenRefresh --> TokenUsage
+    TokenUsage --> TokenRevocation
+    TokenRevocation --> TokenExpiration
+    TokenExpiration --> [*]
     
-    Login --> TokenIssuance: Authenticate with External ID
-    TokenIssuance --> TokenStorage: Store Tokens Securely
+    state Login {
+        [*] --> UserInitiatesLogin
+    }
     
     state TokenIssuance {
-        [*] --> IDToken: ID Token (User Identity)
-        [*] --> AccessToken: Access Token (API Authorization)
-        [*] --> RefreshToken: Refresh Token (Long-lived)
+        [*] --> IDToken
+        [*] --> AccessToken
+        [*] --> RefreshToken
     }
     
     state TokenStorage {
-        [*] --> WebStorage: Web: HttpOnly Cookies/SessionStorage
-        [*] --> DesktopStorage: Desktop: Encrypted Cache (DPAPI/Keychain)
+        [*] --> WebStorage
+        [*] --> DesktopStorage
     }
     
-    TokenStorage --> TokenUsage: Attach to API Requests
-    
     state TokenUsage {
-        [*] --> RequestHeader: Authorization: Bearer <access_token>
-        RequestHeader --> GatewayValidation: Gateway Validates Token
-        
-        state GatewayValidation {
-            [*] --> VerifySignature: Verify Signature (Public Key)
-            VerifySignature --> CheckExpiration: Check Expiration (nbf, exp)
-            CheckExpiration --> ValidateIssuer: Validate Issuer (iss)
-            ValidateIssuer --> ValidateAudience: Validate Audience (aud)
-        }
-        
-        GatewayValidation --> ProcessRequest: Forward to Backend
+        [*] --> RequestHeader
+        RequestHeader --> GatewayValidation
+        GatewayValidation --> ProcessRequest
     }
     
-    TokenUsage --> TokenRefresh: Before Expiration
+    state GatewayValidation {
+        [*] --> VerifySignature
+        VerifySignature --> CheckExpiration
+        CheckExpiration --> ValidateIssuer
+        ValidateIssuer --> ValidateAudience
+    }
     
     state TokenRefresh {
-        [*] --> SilentAcquisition: Try Silent Token Acquisition
-        SilentAcquisition --> UseRefreshToken: Use Refresh Token if Needed
-        UseRefreshToken --> ReAuthenticate: Re-authenticate if Refresh Fails
+        [*] --> SilentAcquisition
+        SilentAcquisition --> UseRefreshToken
+        UseRefreshToken --> ReAuthenticate
     }
     
-    TokenRefresh --> TokenUsage: Continue with New Token
-    
-    TokenUsage --> TokenRevocation: User Logout
-    
     state TokenRevocation {
-        [*] --> ClearCache: Remove from Client Cache
-        ClearCache --> ClearSession: Clear Session
-        ClearSession --> SignOutEndpoint: Redirect to Sign-out Endpoint
+        [*] --> ClearCache
+        ClearCache --> ClearSession
+        ClearSession --> SignOutEndpoint
     }
     
-    TokenRevocation --> TokenExpiration: Token Becomes Invalid
-    
     state TokenExpiration {
-        [*] --> NaturalExpiration: Natural Expiration (1 hour)
-        [*] --> ManualRevocation: Manual Revocation
-        [*] --> SignOut: User Sign-out
+        [*] --> NaturalExpiration
+        [*] --> ManualRevocation
+        [*] --> SignOut
     }
     
-    TokenExpiration --> [*]
+    note right of Login
+        User clicks login button
+        or visits protected resource
+    end note
+    
+    note right of TokenIssuance
+        ID Token: User identity claims
+        Access Token: API authorization
+        Refresh Token: Long-lived renewal
+    end note
+    
+    note right of TokenStorage
+        Web: HttpOnly cookies or SessionStorage
+        Desktop: Encrypted cache (DPAPI/Keychain)
+    end note
+    
+    note right of TokenUsage
+        Authorization: Bearer access_token
+        Gateway validates all requests
+    end note
+    
+    note right of TokenRefresh
+        Before expiration (typically 1 hour)
+        Silent refresh when possible
+    end note
+    
+    note right of TokenRevocation
+        User logout or security event
+        Clear all cached tokens
+    end note
 ```
 
+**Token Lifecycle Stages:**
+
+1. **Login**: User initiates authentication with Microsoft Entra External ID
+2. **Token Issuance**: External ID returns ID, Access, and Refresh tokens
+3. **Token Storage**: Secure storage based on platform (web vs desktop)
+4. **Token Usage**: Tokens attached to API requests for authorization
+5. **Token Refresh**: Silent renewal before expiration using refresh tokens
+6. **Token Revocation**: Manual logout or automatic cleanup
+7. **Token Expiration**: Natural expiration or forced invalidation
+
 ## Comparison: Azure AD B2C vs Microsoft Entra External ID
 
 ```mermaid

docs/authentication/quick-start.md

@@ -73,24 +73,24 @@ var app = PublicClientApplicationBuilder
 
 ```mermaid
 flowchart TD
-    Start[Start Setup] --> Azure[1. Azure Portal Setup<br/>2 minutes]
-    Azure --> Gateway[2. Gateway Configuration<br/>1 minute]
-    Gateway --> Client[3. Client Configuration<br/>2 minutes]
+    Start[Start Setup] --> Azure[Step 1: Azure Portal Setup<br/>2 minutes]
+    Azure --> Gateway[Step 2: Gateway Configuration<br/>1 minute]
+    Gateway --> Client[Step 3: Client Configuration<br/>2 minutes]
     Client --> Test[Test Implementation]
     
-    subgraph "Azure Setup"
+    subgraph "Azure Setup Steps"
         CreateApp[Create App Registration]
         GetIDs[Get Client ID & Tenant ID]
         CreateApp --> GetIDs
     end
     
-    subgraph "Gateway Setup"
+    subgraph "Gateway Setup Steps"
         AppSettings[Update appsettings.json]
         ProgramCS[Configure Program.cs]
         AppSettings --> ProgramCS
     end
     
-    subgraph "Client Setup"
+    subgraph "Client Setup Steps"
         BlazorConfig[Blazor WASM Config]
         DesktopConfig[WPF/MAUI Config]
     end
@@ -99,8 +99,19 @@ flowchart TD
     Gateway -.-> AppSettings
     Client -.-> BlazorConfig
     Client -.-> DesktopConfig
+    
+    style Azure fill:#e3f2fd
+    style Gateway fill:#e8f5e8
+    style Client fill:#fff3e0
+    style Test fill:#f3e5f5
 ```
 
+**Setup Timeline:**
+- **Step 1**: Azure Portal Setup (2 minutes)
+- **Step 2**: Gateway Configuration (1 minute)  
+- **Step 3**: Client Configuration (2 minutes)
+- **Total**: ~5 minutes
+
 ## Common Configuration Patterns
 
 ### Pattern 1: Gateway Only Authentication