Overview
LuMay's architecture is a six-layer reference model with strict contracts between layers. Each layer has a single responsibility, an internal API, and defined inputs and outputs. When you change a model, replace a connector, add a new channel, or swap an observability backend, only that layer changes. Everything above and below it continues to work.
This matters because AI infrastructure changes faster than enterprise procurement cycles. The model you deploy today will be superseded in six to twelve months. The CRM connector you start with might not be the one you scale with. The observability tool your team uses today might be replaced. LuMay's architecture absorbs all of those changes without rewriting agents, flows, or governance.
This is what 'platform, not project' means in practice.
The Six Layers
| # | Layer | Responsibility | Components |
|---|---|---|---|
| 01 | Interface | Channels agents are reached through | Voice (Twilio WebSocket), Chat, Microsoft Teams, Web portal, REST API |
| 02 | Intelligence | Reasoning and understanding | RAG, LLM reasoning (OpenAI / Anthropic), intent classification, structured outputs |
| 03 | Orchestration | Workflow execution and multi-agent coordination | Conversation flows, multi-agent delegation, HITL gates, versioning, NL builder |
| 04 | Integration | Connecting agents to external systems | Connectors (CRM, ticketing, email, docs), OAuth vault, MCP servers |
| 05 | Governance | Trust, compliance, and control | RBAC, Row-Level Security, audit logs, PII controls, guardrails, secrets management |
| 06 | Analytics & ROI | Measurement and value demonstration | KPIs, cost tracking, ROI dashboard, sentiment, quality scores, OTel traces, Prometheus metrics |
What You Can Swap Without Breaking Anything
Because each layer has clean contracts, changes are contained to the layer being modified:
| You want to… | Layer affected | Everything else |
|---|---|---|
| Change LLM provider (OpenAI → Anthropic) | 02 Intelligence | Unchanged - agents, flows, connectors unaffected |
| Add a new channel (e.g. WhatsApp) | 01 Interface | Unchanged - reasoning, flows, connectors unaffected |
| Replace a CRM connector (HubSpot → Salesforce) | 04 Integration | Unchanged - agent flows reference tool names, not vendor names |
| Move from SaaS to on-prem | Infrastructure (below all layers) | All six layers unchanged - same code, same behaviour |
| Add a new governance rule | 05 Governance | Unchanged - enforcement is added at the layer without touching application code |
| Switch observability backend | 06 Analytics | Unchanged - OTel instrumentation is vendor-agnostic |
Runtime Architecture
The platform runs as two cooperating services that share one library:
- Management API - FastAPI, port 8080. Handles agent configuration, flow authoring, connector management, RBAC, and all administrative operations. 35+ feature routers with JWT/RBAC middleware on every route.
- Voice Agent Engine - Pipecat AI, port 8001. Handles WebSocket connections from Twilio for inbound and outbound calling. Scales independently based on concurrent active calls.
Both services share the following infrastructure:
- PostgreSQL with Row-Level Security - tenant isolation enforced at the database layer.
- Redis - configuration cache; degrades gracefully if unavailable.
- RabbitMQ - event bus for cache invalidation, async workflows, and outbound scheduling.
- OpenTelemetry Collector - exports to Grafana Tempo (traces), Prometheus (metrics), and Loki (logs).
Related
- Core Engine - the Intelligence layer (02) in detail
- Security & Governance - the Governance layer (05) in detail
- Deployment - how the architecture maps to infrastructure across deployment models
- Enterprise AI Framework - the broader operating model that this architecture sits within
- Platform overview - all four engines and four trust pillars