Retail-API Middleware Architecture

Retail-API is a Laravel application with a comprehensive middleware architecture containing 40+ custom middleware components. This documentation is organized by functional categories for easier navigation.

Request Flow

Request Flow:
┌─────────────────────────────────────────────────────────────────┐
│                     Global Middleware                            │
│  (InjectTraceId → TrustProxies → CORS → Cache → Accept/UA)     │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                   Middleware Groups                              │
│  web: Session + Auth + Locality + CircuitBreaker + Lock        │
│  api: Throttle + Bindings + Locality + Lock                    │
│  webhooks: Throttle + Lock                                      │
│  internal: Throttle(120/min) + Lock                             │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                   Route Middleware (Aliases)                     │
│  auth, guest, scope, feature, privilege, user_type, etc.       │
└─────────────────────────────────────────────────────────────────┘

Topic Documents

Document	Description
[global.md](../global/	Global middleware applied to every request
[authentication.md](../authentication/	Session, token, and internal service authentication
[authorization.md](../authorization/	Scopes, privileges, roles, and user type validation
[rate-limiting.md](../rate-limiting/	Rate limiting and circuit breaker protection
[locality-context.md](../locality-context/	Advisor, household, organization context management
[feature-flags.md](../feature-flags/	Feature flag middleware at various levels
[partner-api.md](../partner-api/	Partner API versioning and access control
[impersonation.md](../impersonation/	Employee impersonation and permission controls
[distributed-lock.md](../distributed-lock/	Distributed request locking mechanism
[packages.md](../packages/	Package-level middleware (APM, caching, Sentry)

Code Locations

Category	Path
Kernel	`app/Http/Kernel.php`
Core Middleware	`app/Http/Middleware/` (38 files)
Partner API	`app/Http/Middleware/Partner/`
Attributes	`app/Http/Middleware/Attributes/`
Extended Framework	`app/Extensions/Illuminate/`
Distributed Lock	`app/Support/DistributedLock/`
Rate Limiters	`app/Providers/RateLimiterServiceProvider.php`
Locality	`app/Locality/`

Middleware Groups

web Group

'web' => [
    AddQueuedCookiesToResponse::class,       // Cookie handling
    StartSession::class,                      // Session initialization
    AddXRightCapitalUserInfoHeader::class,   // User context headers
    InitializeLocality::class,               // Advisor/household context from URL
    SubstituteBindings::class,               // Route model binding
    AddXRightCapitalCalculationId::class,    // Calculation tracking header
    RequestCircuitBreaker::class,            // Circuit breaker protection
    CheckImpersonatorEmployeePermission::class, // Impersonation validation
    LockRequestMiddleware::class,            // Distributed request locking
]

api Group

'api' => [
    ThrottleRequests::class . ':api',        // 600 requests/minute
    SubstituteBindings::class,
    InitializeLocality::class,
    LockRequestMiddleware::class,
]

webhooks Group

'webhooks' => [
    ThrottleRequests::class . ':webhooks',   // 600 requests/minute per IP
    LockRequestMiddleware::class,
]

internal Group

'internal' => [
    ThrottleRequests::class . ':120,1',      // 120 requests/minute (fixed)
    LockRequestMiddleware::class,
]

Middleware Priority

protected $middlewarePriority = [
    StartSession::class,           // 1. Session first
    ShareErrorsFromSession::class, // 2. Error sharing
    Authenticate::class,           // 3. Authentication
    ThrottleRequests::class,       // 4. Rate limiting (early)
    AuthenticateSession::class,    // 5. Session auth
    InitializeLocality::class,     // 6. Context setup
    UserType::class,               // 7. User type check
    SubstituteBindings::class,     // 8. Model binding (late)
    Authorize::class,              // 9. Authorization (last)
];

Middleware Aliases Quick Reference

Alias	Class	Category
`auth`	`Authenticate`	[Authentication](../authentication/
`auth.internal`	`AuthenticateInternalApplication`	[Authentication](../authentication/
`guest`	`Unauthenticated`	[Authentication](../authentication/
`azure_ad`	`CheckAzureAd`	[Authentication](../authentication/
`scope`	`CheckForAnyScope`	[Authorization](../authorization/
`scopes`	`CheckScopes`	[Authorization](../authorization/
`privilege`	`Privilege`	[Authorization](../authorization/
`advisor_role`	`CheckAdvisorRole`	[Authorization](../authorization/
`user_type`	`UserType`	[Authorization](../authorization/
`can`	`Authorize`	[Authorization](../authorization/
`throttle`	`ThrottleRequests`	[Rate Limiting](../rate-limiting/
`feature`	`Feature`	[Feature Flags](../feature-flags/
`organization.feature`	`OrganizationFeature`	[Feature Flags](../feature-flags/
`partner.access_permission`	`Partner\CheckAccessPermission`	[Partner API](../partner-api/
`partner.supported_versions`	`Partner\CheckEndpointVersion`	[Partner API](../partner-api/
`prevent_privileged_impersonation`	`PreventPrivilegedImpersonation`	[Impersonation](../impersonation/

Response Headers

Header	Middleware	Purpose
`Trace-Id`	`InjectTraceId`	APM trace correlation
`X-RightCapital-UserID`	`AddXRightCapitalUserInfoHeader`	Access log user tracking
`X-RightCapital-Employee-Email`	`AddXRightCapitalUserInfoHeader`	Impersonation tracking
`X-RightCapital-CalculationID`	`AddXRightCapitalCalculationId`	Calculation tracking
`X-RightCapital-EngineVersion`	`SetCalcEngineVersion`	Engine version (staging)