@startuml athena_auth_request_pipeline_ordering_sequence
title AthenaAuth Request Pipeline - Ordering and Ownership

actor "Client" as Client
participant "AthenaAuth::handle_request" as HandleRequest
participant "Middleware chain" as Middleware
participant "Path normalizer\n(strip base_path)" as Normalize
participant "Plugin before_request hooks" as BeforeHooks
participant "Core route dispatcher\nhandle_core_request" as Core
participant "Plugin route dispatcher\nplugin.on_request loop" as Plugins
participant "AuthError -> AuthResponse mapper" as ErrorMapper

Client -> HandleRequest: request (e.g. /api/auth/...)
HandleRequest -> Middleware: run_before(...)

alt middleware short-circuit
    Middleware --> HandleRequest: AuthResponse
    HandleRequest --> Client: response
else continue
    Middleware --> HandleRequest: continue
    HandleRequest -> Normalize: strip configured base_path
    Normalize --> HandleRequest: internal_req
    HandleRequest -> BeforeHooks: for each plugin before_request(internal_req)

    alt before_request responds/injects
        BeforeHooks --> HandleRequest: optional response or virtual session context
    else no hook output
        BeforeHooks --> HandleRequest: none
    end

    HandleRequest -> Core: handle_core_request(internal_req)
    alt core route matched
        Core --> HandleRequest: AuthResponse
        HandleRequest --> Client: response
    else not a core route
        Core --> HandleRequest: None
        HandleRequest -> Plugins: iterate plugin.on_request(internal_req)

        alt plugin matched
            Plugins --> HandleRequest: AuthResponse
            HandleRequest --> Client: response
        else no plugin matched
            Plugins --> HandleRequest: None
            HandleRequest -> ErrorMapper: AuthError::not_found
            ErrorMapper --> HandleRequest: 404 JSON response
            HandleRequest --> Client: 404 { message }
        end
    end
end

@enduml

