System overview

LumicIQ is a multi-tenant, Azure-targeted, agent-primary retail-operations platform: a persistent LLM agent in every (tenant, store) watches the real-time event stream, reasons over composed context and scoped knowledge, and helps the manager — unsolicited (quantified, routed recommendations) and solicited (conversation). Reasoning lives in prompts + structured context, never hardcoded rules.

See it visually

This page is the written summary; the full interactive diagram is the architecture flow deck.

The decision funnel

Three stages turn raw events into a routed recommendation:

1. SafetyNet — a small set of hardcoded critical conditions; the floor the platform never misses.
2. InterestingnessDetector — a universal, learned attention gate (cheap statistics, no LLM) that decides what is worth the agent’s expensive reasoning. This is also the cost control that makes per-event LLM calls unnecessary at scale.
3. The Agent — a persistent reasoner per (tenant, store) that composes a layered prompt (platform → vertical → tenant → store → situation), retrieves scoped knowledge, calls an LLM via ILlmProvider, validates the output, and emits a Suggestion (or answers a Conversation).

The Router then resolves recipients + channels and delivers; the client is where a person acts.

The pieces

Layer	What it does
Event spine (Event Hubs)	One canonical RelayEvent stream; ULID idempotency; partitioned by (tenant, store).
StateProjection	Writes current truth to Cosmos / Redis / immutable Blob. Emits nothing back to the spine.
Knowledge (RAG)	Scoped retrieval — platform → enterprise → store — over SOPs, handbook, learnings.
LlmProvider	Vendor-agnostic LLM access; every call writes an immutable LlmCallRecord (the audit + backtest substrate).
Router + channels	Resolve recipient/channel from policy; deliver via SignalR / push / etc. Never edits agent content.

Non-negotiable invariants

• Agent-primary — no rules engine; per-tenant config describes the business, never encodes rules.
• Every LLM call is audited — immutable record; the backtest & prompt-evolution substrate.
• Fail-closed multi-tenancy, idempotent on eventId, traceable end-to-end.

This is a summary. The authoritative, granular spec lives in the product repo’s requirements suite (docs/requirements/); this page is the team-facing orientation.