diff --git a/README.md b/README.md
index 07a49d7..5248acb 100644
--- a/README.md
+++ b/README.md
@@ -106,3 +106,57 @@ npm run dev
 - PostgreSQL runs on port 5432 (internal) 
 
 
+## Sequence Diagram of the Flow
+
+```mermaid
+
+sequenceDiagram
+    participant Browser as Frontend #40;React#41;
+    participant YARP as BFF/YARP Proxy
+    participant TokenHandler as Token Handler Middleware
+    participant Cache as Hybrid Cache
+    participant Keycloak as Keycloak #40;IdP#41;
+    participant API as Backend API
+
+    Note over Browser,API: Initial Authentication Flow
+    
+    Browser->>YARP: 1. Access protected resource
+    YARP->>TokenHandler: 2. Check authentication
+    TokenHandler->>Browser: 3. Redirect to /Account/Login
+    Browser->>YARP: 4. GET /Account/Login
+    YARP->>Keycloak: 5. OIDC Authorization Request
+    Keycloak->>Browser: 6. Login page
+    Browser->>Keycloak: 7. Submit credentials
+    Keycloak->>YARP: 8. Authorization code #40;callback#41;
+    
+    Note over YARP,Keycloak: Token Exchange
+    YARP->>Keycloak: 9. Exchange code for tokens<br/>#40;OnAuthorizationCodeReceived#41;
+    Keycloak->>YARP: 10. Access + Refresh tokens
+    
+    Note over YARP,Cache: Token Storage
+    YARP->>Cache: 11. Store tokens with session-id<br/>#40;OnTokenValidated#41;
+    YARP->>Browser: 12. Set session-id cookie #40;HttpOnly, Secure#41;
+    YARP->>Browser: 13. Redirect to original URL
+
+    Note over Browser,API: Subsequent API Calls
+
+    Browser->>YARP: 14. API request with session-id cookie
+    YARP->>TokenHandler: 15. AuthenticationHeaderSubstitutionMiddleware
+    TokenHandler->>Cache: 16. Retrieve tokens by session-id
+    Cache->>TokenHandler: 17. Return OAuthTokenResponse
+    TokenHandler->>TokenHandler: 18. Add Authorization: Bearer {#35;access_token{#35;}
+    TokenHandler->>API: 19. Proxied request with Bearer token
+    API->>API: 20. Validate JWT token
+    API->>TokenHandler: 21. API response
+    TokenHandler->>Browser: 22. Response #40;without tokens#41;
+
+    Note over Browser,API: Token Refresh #40;if needed#41;
+    
+    Browser->>YARP: 23. API request #40;expired token#41;
+    TokenHandler->>Cache: 24. Get tokens
+    TokenHandler->>Keycloak: 25. Refresh token request
+    Keycloak->>TokenHandler: 26. New access token
+    TokenHandler->>Cache: 27. Update cached tokens
+    TokenHandler->>API: 28. Retry with new token
+
+```
\ No newline at end of file