System Architecture
The Eloquent platform follows a microservices architecture with clear separation between frontend applications, an API gateway, backend services, and data stores.
Architecture Overview
Frontend Applications
| Application | Purpose |
|---|---|
| Users Portal | Main platform UI — agents, workflows, entities, chat |
| Administration Portal | Platform administration — organizations, users, analytics |
| Custom Agent UIs | Customer-built branded agent experiences using @elqnt packages |
| Custom Apps | Customer-built applications integrated with the platform |
All frontend applications communicate exclusively with the API Gateway over HTTPS. They never connect directly to backend services or data stores.
API Gateway
The API Gateway is the single entry point for all client requests. It handles:
- JWT Authentication — validates tokens on every request
- CORS — cross-origin request handling
- Rate Limiting — per-route request throttling
- Request Routing — proxies requests to the appropriate backend service
- Scope Authorization — validates user permissions per route
Backend Services
The platform is composed of multiple microservices organized into functional groups:
| Group | Capabilities |
|---|---|
| Core Platform | Organization and user management, platform provisioning |
| AI & Agents | Agent configuration, real-time chat, skill and tool orchestration, workflow automation |
| Data & Search | Knowledge graph, semantic search, dynamic entities, document ingestion |
| Integrations | Email and notifications, media processing, external service connectors |
| Processing | Document generation, scheduled tasks, background job execution |
Services communicate internally using a message-based architecture. This is fully managed — administrators do not need to configure inter-service communication.
Communication Patterns
Browser to Backend
All browser requests go through the API Gateway over HTTPS:
Browser → API Gateway (HTTPS) → Backend Service (internal)
The browser never communicates directly with backend services or databases.
Service to Service
Backend services communicate internally using a managed message queue for both synchronous and asynchronous operations. This is transparent to administrators — no configuration is required.
Chat Transport
The chat service supports two transport modes:
| Transport | Protocol | Session Handling | Recommended |
|---|---|---|---|
| SSE | HTTP Server-Sent Events | Stateless — any gateway pod can handle | Yes |
| WebSocket | Full-duplex WS | Requires sticky sessions (cookie affinity) | Legacy only |
SSE is the recommended transport. It is stateless, supports auto-reconnection, and works with standard HTTP load balancers without special configuration.
Infrastructure Components
| Component | Purpose | Persistence |
|---|---|---|
| PostgreSQL | Primary relational data store | Persistent (10Gi default) |
| ClickHouse | Analytics and knowledge graph | Persistent (20Gi default) |
| Redis | Cache, sessions, real-time data | Persistent (5Gi default) |
| Message Queue | Internal messaging, chat history, event streams | Persistent with file backing |
Multi-Tenancy
Every organization gets fully isolated resources:
- PostgreSQL — dedicated schema per organization
- ClickHouse — dedicated database per organization
- Message Queue — dedicated storage per organization
- Redis — isolated key space per organization
The API Gateway enforces organization context on every request through JWT claims. No cross-organization data access is possible at any layer.
See Organization & Multi-Tenancy for management details.