ID,Component,Task,Input,Process,Output,Critical Notes
T1,AAF Filter,Extract CIN & Scope,HttpServletRequest,1. Extract CIN from X-CIN-ID header OR JSON body (use ContentCachingRequestWrapper)<br>2. Extract scope: JWT claim scope", header "X-Request-Scope", or derive from AD groups via security context"<br>3. Set attributes: "request.setAttribute(""cin"", cin)"", ""request.setAttribute(""scope"", scope)",cin" (String), "scope (String),• Fail fast if CIN missing (400)<br>• Scope may be null → use default later<br>• DO NOT consume body – use buffered wrapper
T2,AAF Filter,Agora Micro-Check (Non-Blocking),cin", "scope", request context",1. Call Agora Policy Engine API<br>2. Store decision in attribute: "request.setAttribute(""agora.decision"", PolicyDecision)"<br>3. Async log decision + metadata,PolicyDecision (ALLOW/DENY) in request attribute,• Non-blocking: Always proceed to next filter<br>• Timeout: 50ms max<br>• Circuit breaker on Agora failures
T3,EntitlementFilter,Safe CIN Extraction,HttpServletRequest,1. Prefer "request.getAttribute(""cin"")" (from AAF)<br>2. Fallback: Parse X-CIN-ID header<br>3. Validate format (regex: [A-Z]{3}\d+),Validated cin string,Avoids body re-parsing. Fail if invalid (400 INVALID_CIN)
T4,EntitlementFilter,Scope Resolution,HttpServletRequest", "PartyAggregate,1. Get scope: "request.getAttribute(""scope"")" → PartyAggregate.region" → default ""GLOBAL"""<br>"2. Normalize scope (e.g., ""UAE"" → ""uae"")",Resolved scopeKey (String),Critical for rule lookup. Log resolution path
T5,Rule Engine,RuleSet Lookup (Cached),scopeKey,1. Check Caffeine cache (key=scopeKey)<br>2. Cache miss? Query MongoDB entitlement_rules collection ({scope: scopeKey})<br>3. DB slow (>10ms) or error? Fallback to application.yml static rules<br>4. Cache hit/DB result → TTL 5m,RuleSet object (list of rule configs),• Schema: "{scope, rules: [{type, config}]}"<br>• Health check endpoint for cache status
T6,EntitlementChecker,Evaluate Composite Rules,PartyAggregate", "HttpServletRequest", "RuleSet,1. Build rule tree (AND/OR per config)<br>2. Execute: RegionalRule" (validate region), "ProductRule" (check entitled products), etc."<br>3. Short-circuit on first failure (AND logic)<br>4. Capture denial reasons internally,"EntitlementResult { granted: boolean, reasons: List<String> }",• Reasons never exposed in response<br>• Log SHA-256(CIN) + decision + scope
T7,EntitlementFilter,Enforce Decision,EntitlementResult", "HttpServletResponse,DENIED": Set status 403, body ""{""error"":""Access Denied""}"", return (no chain)"<br>GRANTED: Call filterChain.doFilter(),HTTP 403 (blocked) OR proceeds to controller,• 403 terminates filter chain immediately<br>• Metrics: "entitlement_decisions_total{scope, result}"
T8,AAF Filter,Final Response Handling,HttpServletResponse (post-chain),1. Log final status code + correlation ID<br>2. Inject audit header: "X-Entitlement-Audit: [timestamp, scope, decision-hash]",Response to client,Only logs – does not alter EF’s decision
T9,Infra,Rule Management Pipeline,Admin input (JSON),1. REST endpoint to update MongoDB entitlement_rules<br>2. Invalidate cache on update<br>3. Validate rule syntax before persisting,Updated rules in DB + cache,Requires RBAC. Audit trail for changes
T10,Infra,Resilience Hardening,Runtime metrics,1. Circuit breaker for MongoDB/Rule lookup (3 failures → fallback)<br>2. Timeout: Rule DB query ≤15ms<br>3. Alert if fallback usage >1% of requests,"Fail-fast responses, metrics",Critical for PR-02 latency budget