LumaCogent Returns Suite — Phase 3 Technical Architecture

System Interaction Diagram

All components across four layers with directed, typed arrows — event bus as central nervous system
DocumentSystem Interaction Diagram V1
OwnerSolutions Architect
StatusIn Review
Architecture RefTechnical Architecture V2
Date2026-04-30
Interaction Type Key
Event (SQS) — async message published to or consumed from the event bus
API Call — synchronous REST call to or from an external system
OI Core Query — synchronous agent → OI Core context fetch (<500ms SLA)
Proactive Signal — OI Core → agent mesh (ANOMALY_DETECTED, RMA_STALL_RISK, etc.)
Tool Invocation — agent → capability layer service (code-level enforced via tool access registry)
Learning Signal — human override captured by Learning Agent → OI Core learning pipeline
Full System Interaction Map — V2 Architecture
All layers, all components, all interaction types. Arrows are directed. SQS is the central nervous system — all capability layer services publish here; all agents and OI Core subscribe.
EXTERNAL WORLD LAYER 4 — HUMAN INTERFACE LAYER LAYER 3 — AGENT MESH SQS EVENT BUS — CENTRAL NERVOUS SYSTEM All Capability Layer services publish here · All agents and OI Core subscribe · Event deduplication on event_id · DLQ for failed events LAYER 2 — OPERATIONS INTELLIGENCE CORE (OI CORE) LAYER 1 — CAPABILITY LAYER EXTERNAL SYSTEMS Shopper Returns initiator Claude API claude-sonnet-4-6 Merchant Admin Policy · Config · Users AI Conversation Agent Shopper-facing · NLP Embedded JS widget Fallback: structured form MVP Ops Supervisor Assistant (Diana) Anomaly alerts · SLA breach Morning briefing · Staffing rec Threshold config · Approvals MVP Inspector Assistant (Elena) Grade rec · Pre-inspect brief Fraud flag · High-value alert [Confirm] / [Override] UI MVP Finance Assistant (Rachel) Liability briefing · BNPL recon Chargeback window alert Pre-assembled evidence pkg MVP Merchandising Assistant (Priya) Buying intel · Defect alerts Restock signals · Sell-through Requires 6+ mo OI Core data Phase 2 Returns Intelligence Dashboard Agent activity log · Audit trail SLA queue · Threshold config Role-based views (5 roles) MVP Orchestration Agent RMA_CREATED trigger Monitors all open RMAs Stall detection · Routing Refund gating MVP Disposition Agent INSPECTION_COMPLETED Restock/liquidate/discard SKU demand · Days staging Jordan approval gate MVP Inspection Guidance Agent ITEM_RECEIVED trigger Grade recommendation Fraud signal check Reference photo lookup MVP Anomaly Detection Agent FRAUD_CLUSTER signal Return rate spikes Operational degradation Diana alert dispatch MVP Merchant Insight Agent MERCHANDISING_SIGNAL Stakeholder routing Daily briefing compose Role-specific intel pkg MVP Exception Agent No-RMA · Wrong item Carrier exceptions Resolution proposal Diana approval gate MVP Ops Agent CREDENTIAL_EXPIRY signal Self-healing · Failover 15-min health sweep ECS scale · DLQ monitor MVP Learning Agent HUMAN_OVERRIDE events 4-hr OI Core model update No Capability Layer access Authority boundary expands MVP Knowledge Model & Event Ingestion SKU patterns · Fraud model Reason classifier · NLP engine Subscribes all SQS events Merchant-specific baselines OI Core API (Sync Query) POST /oi/classify-reason GET /oi/sku-profile GET /oi/fraud-signal <500ms p95 · Redis cache Proactive Signal Publisher ANOMALY_DETECTED RMA_STALL_RISK FRAUD_CLUSTER_FORMING MERCHANDISING_SIGNAL · CRED_EXPIRY Learning Pipeline LEARNING_SIGNAL ingestion 4-hr model update batch Confidence score refinement Authority boundary expansion System Health Model Integration latency tracking Queue depth · Error rates Credential expiry timestamps Feeds Ops Agent signals Cold Start & Bootstrap 60–90d historical ingest Supervised mode Day 0–30 LOW_CONFIDENCE tag on recs COLD_START_COMPLETE signal RMA Engine Create/update RMA State transitions Optimistic locking Publishes RMA events MVP Inspection Engine Grade records · Photos CV layer (Phase 2) INSPECTION_COMPLETED MVP Refund Engine Payment routing Stripe · Shopify Pay BNPL (Klarna/Afterpay) REFUND_ISSUED event MVP Label Engine EasyPost (primary) ShipStation (fallback) Tracking webhooks CARRIER_EXCEPTION event MVP Notification Engine AWS SES (email) Twilio (SMS) Shopper + merchant comms MVP OMS Adapters Shopify (MVP) WooCommerce · Magento NetSuite (later phases) IOrderManagement iface MVP WMS Adapters ShipBob · Deposco Extensiv (3PL Central) IWarehouseManagement ARN dispatch on RMA_CREATED MVP Payment & Accounting Adapters Stripe · Klarna · Afterpay QuickBooks · NetSuite IPaymentRefund · IAcctSync MVP CS Tool Adapters Zendesk · Gorgias ICustomerServiceTool RETURN_ESCALATED trigger Full convo transcript sent MVP Shopify / OMS Webhooks + REST ShipBob / WMS REST API Stripe / BNPL REST API EasyPost Labels · Tracking Zendesk/Gorgias CS ticketing QuickBooks Accounting sync API call (NLP / conversation reasoning) policy config tool: create RMA RMA_CREATED INSPECTION_COMPLETED ITEM_RECEIVED ORDER_UPDATED REFUND_ISSUED RETURN_ESCALATED all events RMA_CREATED INSP_COMPLETED ITEM_RECEIVED NO_RMA / EXCEPTION FRAUD_CLUSTER RMA_STALL_RISK CRED_EXPIRY MERCH_SIGNAL OI query: context SKU demand query adjudication history tool: log tool: holding notice tool: on-call escalation LEARNING_SIGNAL (4-hr batch) HUMAN_OVERRIDE captured by Learning Agent role-specific insight pkg grade rec exception resolution proposal AUTHORITY BOUNDARY Code-level enforcement Each agent has a tool access registry. LLM output is validated against this registry before any tool call executes. Out-of-registry calls are rejected and logged as AUTHORITY_BOUNDARY_BREACH. AGENT RUNTIME CYCLE 1. Receive SQS event or OI Core proactive signal 2. Query OI Core for context 3. LLM reasoning (Claude API) 4. Validate vs. tool registry 5. Execute approved tools 6. Log to Learning Agent queue 7. Publish output events to SQS
Changelog
DateUpdate
2026-04-30 V1 created — system interaction diagram produced from V2 Technical Architecture (agent-first, OI Core-driven). Shows all four layers, SQS event bus as central nervous system, eight agents, six OI Core subsystems, nine capability layer services, five Human Interface components, and six external system groups. All interaction types typed and directed: event, API call, OI Core query, proactive signal, tool invocation, learning signal. Callouts: agent runtime cycle and authority boundary enforcement.