@startuml
title Demo Auth Proxy 404 Behavior (After)
skinparam backgroundColor #FFFFFF
skinparam sequence {
  ArrowColor #1D4ED8
  LifeLineBorderColor #1E3A8A
  LifeLineBackgroundColor #EFF6FF
  ParticipantBorderColor #1E3A8A
  ParticipantBackgroundColor #DBEAFE
  ParticipantFontColor #0F172A
  ActorBorderColor #0F172A
  ActorBackgroundColor #DCFCE7
}

actor "apps/demo UI" as UI
participant "Next.js API\n/api/auth/[...path]" as Proxy #BAE6FD
participant "athena-auth upstream\n(configured origin)" as Upstream #E2E8F0

UI -> Proxy: POST /api/auth/sign-in/email
activate Proxy
Proxy -> Upstream: POST attempted upstreamRoute
activate Upstream
Upstream --> Proxy: 404 Not Found\n(original upstream payload)
deactivate Upstream
Proxy -> Proxy: If needed, build fallback route using auth base path (default /api/auth)
Proxy -> Upstream: Retry once on fallbackUpstreamRoute
activate Upstream
Upstream --> Proxy: 200/401/... OR 404
deactivate Upstream
alt Fallback resolves route
  Proxy --> UI: Forward fallback response
  Proxy -> Proxy: Add headers:\n- x-athena-proxy-fallback-attempted=true\n- x-athena-proxy-fallback-used=true
else Still 404
  Proxy -> Proxy: Build structured UPSTREAM_ROUTE_NOT_FOUND payload
  Proxy -> Proxy: Add headers:\n- x-athena-proxy-request-id\n- x-athena-proxy-incoming-path\n- x-athena-proxy-upstream-route\n- x-athena-proxy-upstream-source\n- x-athena-proxy-error=upstream_route_not_found
  Proxy --> UI: 404 JSON diagnostics\n{ code, message, incomingPath, upstreamRoute, fallbackUpstreamRoute, requestId, ... }
end
note right of Proxy #DCFCE7
After change:
- Automatic one-shot fallback reduces base-path mismatch breakage
- Exact attempted route(s) are returned to caller
- Request ID + route metadata align UI, logs, and HTTP traces
end note
deactivate Proxy
@enduml
