Skip to content

API Gateway: Sequence Diagrams

Version Date Author Change Description
1.0 2025-09-11 Senior Systems Analyst Initial diagrams for the Google SSO architecture.

1.0 Overview

This document contains sequence diagrams for the most critical interaction flows involving the API Gateway. These diagrams illustrate the step-by-step process of requests, showing how the gateway interacts with the user's browser, the frontend application, backend services, and external providers.

2.0 Successful User Login (First Time - JIT Provisioning)

This diagram shows the complete end-to-end flow for a new user logging in for the first time. It covers the OAuth 2.0 redirect, the callback handling, and the Just-In-Time (JIT) creation of the user account in our system.

sequenceDiagram
    participant User as User's Browser
    participant Frontend
    participant Gateway as API Gateway
    participant Google
    participant AuthService
    participant Database

    User->>Frontend: Clicks "Sign in with Google"
    Frontend->>Gateway: GET /api/v1/auth/google/login
    Gateway-->>User: HTTP 302 Redirect to Google OAuth URL
    User->>Google: Authenticates with Google credentials
    Google-->>User: HTTP 302 Redirect to callback URL with authorization_code
    User->>Gateway: GET /api/v1/auth/google/callback?code=...
    Gateway->>AuthService: gRPC: HandleGoogleAuthCallback(authorization_code)
    AuthService->>Google: Exchange authorization_code for user info
    Google-->>AuthService: Return user profile (email, name, google_id)
    AuthService->>Database: Check if user with google_id exists
    Database-->>AuthService: User does not exist
    AuthService->>Database: Create new user record (JIT Provisioning)
    Database-->>AuthService: New user created
    AuthService->>AuthService: Create new application session
    AuthService-->>Gateway: Return session_token
    Gateway-->>User: HTTP 302 Redirect to /dashboard (with Set-Cookie: session_token)
    User->>Frontend: GET /dashboard
    Frontend-->>User: Renders dashboard

3.0 Successful User Login (Returning User)

This diagram shows the flow for a returning user. It is similar to the first-time login, but instead of creating a new user, the system finds the existing record and updates their last login time.

sequenceDiagram
    participant User as User's Browser
    participant Frontend
    participant Gateway as API Gateway
    participant Google
    participant AuthService
    participant Database

    %% ... Initial steps are identical to the JIT flow ... %%
    User->>Frontend: Clicks "Sign in with Google"
    Frontend->>Gateway: GET /api/v1/auth/google/login
    Gateway-->>User: HTTP 302 Redirect to Google
    User->>Google: Authenticates
    Google-->>User: HTTP 302 Redirect to callback
    User->>Gateway: GET /api/v1/auth/google/callback?code=...
    Gateway->>AuthService: gRPC: HandleGoogleAuthCallback(authorization_code)
    AuthService->>Google: Exchange code for user info
    Google-->>AuthService: Return user profile
    AuthService->>Database: Check if user with google_id exists
    Database-->>AuthService: User exists
    AuthService->>Database: Update user's last_login_at timestamp
    AuthService->>AuthService: Create new application session
    AuthService-->>Gateway: Return session_token
    Gateway-->>User: HTTP 302 Redirect to /dashboard (with Set-Cookie: session_token)

4.0 Authenticated API Call (Permission Granted)

This diagram illustrates how the API Gateway protects a backend resource. It shows the session validation and permission check steps that occur before the request is forwarded to the appropriate backend service.

sequenceDiagram
    participant Frontend
    participant Gateway as API Gateway
    participant AuthService

    Frontend->>Gateway: GET /api/v1/users (with session_token cookie)
    Gateway->>AuthService: gRPC: ValidateSession(session_token)
    AuthService-->>Gateway: { is_valid: true, user_id: "..." }
    Gateway->>Gateway: Check routing rules for required permission ("admin:user:list")
    Gateway->>AuthService: gRPC: CheckPermission(user_id, "admin:user:list")
    AuthService-->>Gateway: { granted: true }
    Gateway->>AuthService: gRPC: ListUsers(...)
    AuthService-->>Gateway: List of users
    Gateway->>Gateway: Transform gRPC response to JSON
    Gateway-->>Frontend: HTTP 200 OK with JSON payload

5.0 Authenticated API Call (Permission Denied)

This diagram shows what happens when a valid, authenticated user tries to access a resource they are not authorized to view.

sequenceDiagram
    participant Frontend
    participant Gateway as API Gateway
    participant AuthService

    Frontend->>Gateway: GET /api/v1/users (with session_token cookie)
    Gateway->>AuthService: gRPC: ValidateSession(session_token)
    AuthService-->>Gateway: { is_valid: true, user_id: "..." }
    Gateway->>Gateway: Check routing rules for required permission ("admin:user:list")
    Gateway->>AuthService: gRPC: CheckPermission(user_id, "admin:user:list")
    AuthService-->>Gateway: { granted: false }
    Gateway->>Gateway: Construct error response
    Gateway-->>Frontend: HTTP 403 Forbidden with error JSON