Concierge Architecture & Specs

The fundamental flaw of external automation tools (like Zapier or Make) is their reliance on REST API polling or brittle HTTP webhooks. - Native event bus: Concierge agents are wired directly into the platform's real-time event bus. When an order is paid by the Commerce module, the payload hits the Concierge agent in single-digit milliseconds without ever traversing the public internet. - Strict payload validation: Event payloads are inherently weakly typed at runtime. Every Concierge agent validates its input against a strict schema at the entry point before executing any cross-module logic.

Concierge does not own business data; it is purely a logic orchestrator, built on a consistent pattern that makes it straightforward to add new agents over time. - Consistent agent shape: Every agent — built-in or added later — follows the same pattern: watch for a trigger, validate the input, call the AI, orchestrate the resulting actions, and write to the shared audit log. - Graceful Degradation: Because Concierge orchestrates across the OS, it must handle diverse tenant deployments. If a tenant hasn't installed the Inbox module, the VIP Welcome Agent gracefully skips the email-drafting phase but successfully completes the CRM tagging and Task generation. - Loyalty Liaison Specifics: Despite its name, the Loyalty Liaison Agent reacts to hotel check-ins rather than commerce orders — it welcomes returning Platinum or Diamond loyalty-tier guests the moment they check in.

Every agent invocation creates an entry before the AI is ever called. That entry is both the deduplication key for cross-module idempotency AND the audit trail for operator review.

What's captured on every entry: - Which agent ran, and what triggered it (an order paid, a message received, a scheduled run, etc.) - The input it acted on, for full traceability - Its status: pending, completed, or failed - On success: the AI's result, an "AI Generated" flag, a human-readable impact summary, and a confidence score (0-100) - On failure: a plain-language reason — no AI provider connected, provider timed out, response failed validation, a dependent module is missing, or confidence too low - Timestamps for when it started and completed

Built-in reporting: operators can run their own reports against the audit log — grouped by agent and status over the last 24 hours, isolating an agent that's been silently failing and why, or pulling the queue of confidence-flagged items waiting for human review.

The admin UI surfaces quick-filters for AI Generated, Failed Actions, and Pending. Operators get explicit visibility into every autonomous decision the agents made — and every one they didn't make and why.