Platform Core

Engine Application

The engine is the platform server: a reactive Spring Boot (WebFlux) application that executes conversations, exposes the REST API and the conversation sockets, and persists everything a conversation produces.

This module documents the engine from the inside. The externally visible API and protocols are documented separately in Core Documentation.

Architecture at a Glance

Layer Contents

Layer	Contents
Controllers	Reactive REST controllers under `/api`, the SPA host page and the exception handlers.
Socket handlers	The plain WebSocket handler, the Twilio Media Streams handler and the Socket.IO service. All three converge on the pipeline service.
Interaction Pipeline	The conversation runtime: configuration, session state machine, contexts and the realtime manager that orchestrates a turn.
Interaction pipeline components	Pluggable parts of a conversation — speech recognizers and synthesizers, interaction and planning managers, extractors, filters, processors, action mappers and aggregators.
Services	Everything the pipeline and the controllers rely on: agents and sessions, prompts, memory, evaluation, storage, billing, integrations.
AI layer	Language model wiring, tool boxes exposed to agents, prompt handling and LLM logging.
Security Implementation	Authentication filters, role mapping and the consumer authorization rules.
Observability	Telemetry, metrics, health checks, usage records and the session debugger.

Controllers

Reactive REST controllers under /api, the SPA host page and the exception handlers.

Socket handlers

The plain WebSocket handler, the Twilio Media Streams handler and the Socket.IO service. All three converge on the pipeline service.

Interaction Pipeline

The conversation runtime: configuration, session state machine, contexts and the realtime manager that orchestrates a turn.

Interaction pipeline components

Pluggable parts of a conversation — speech recognizers and synthesizers, interaction and planning managers, extractors, filters, processors, action mappers and aggregators.

Services

Everything the pipeline and the controllers rely on: agents and sessions, prompts, memory, evaluation, storage, billing, integrations.

AI layer

Language model wiring, tool boxes exposed to agents, prompt handling and LLM logging.

Security Implementation

Authentication filters, role mapping and the consumer authorization rules.

Observability

Telemetry, metrics, health checks, usage records and the session debugger.

Entry Point and Bootstrap

EngineApplication.kt is a plain @SpringBootApplication that imports the Jackson and MessagePack configurations from common and enables caching. All real wiring happens in EngineConfiguration, which is the composition root:

@ComponentScan over ai.promethist.**.configuration, .controller, .component and .service. The wildcard is deliberate — components declared in common and lib are picked up the same way as the engine’s own.
@Enable*Repositories for Elasticsearch and MongoDB (reactive and blocking variants) over ai.promethist.**.repository.
@EnableConfigurationProperties for the properties classes that carry the engine’s configuration: AiProperties, PipelineProperties, ProcessorProperties, EmbeddingProperties, EmotionMixerProperties, IndexerProperties, StorageProperties, SecurityProperties, HttpProxyProperties, SlackProperties, SonioxProperties, ElevenLabsProperties and TwilioProperties.
Beans for the Socket.IO server, the shared WebClient builders (with JWT forwarding and optional HTTP proxy), the WebFlux codecs, the resource storage, the Pebble engine and the WebSocket handler mapping.
CORS is opened for /api/; view resolution uses FreeMarker; static resources and the SPA fallback for /client/ are served from the classpath.

Its @PostConstruct also sizes the Reactor event loops and the bounded elastic scheduler from PipelineProperties, and forces the FFmpeg/JavaCV native libraries to load on the startup thread — lazily loading them on a request thread can leave the native classes unusable if that request is cancelled mid-initialization.

Listeners

Port Served content

Port	Served content
9010	REST API (`/api/`), plain WebSocket (`/socket/pipeline/`), Twilio WebSocket (`/socket/twilio/`), the SPA (`/client/`), static resources and the Actuator endpoints.
9011	Socket.IO server, namespace `/socket/io/pipeline`.

9010

REST API (/api/), plain WebSocket (/socket/pipeline/), Twilio WebSocket (/socket/twilio/), the SPA (/client/), static resources and the Actuator endpoints.

9011

Socket.IO server, namespace /socket/io/pipeline.

WebSocket upgrades use the Reactor Netty strategy with a 1 MB maximum frame size; the Socket.IO server applies the same 1 MB limit to frames and HTTP content.

Other Configuration Classes

Class Responsibility

Class	Responsibility
`MemoryConfiguration`	Declares the Elasticsearch-backed scoped memories — session, short-term and knowledge memory — with their embedding models.
`LinkValidationConfiguration`	A dedicated `WebClient` with browser-like headers and a short timeout, used to verify links before they are shown to a user.
`SwaggerConfiguration`	Augments the generated OpenAPI document (`/api/schema.json`) with the bearer security scheme and the authorization requirements derived from `@PreAuthorize`.
`SecurityConfiguration`	The security filter chain — see Security Implementation.
`OAuthClientConfiguration`	Supplies an empty client registration repository so the application starts even when no third-party OAuth providers are configured.

MemoryConfiguration

Declares the Elasticsearch-backed scoped memories — session, short-term and knowledge memory — with their embedding models.

LinkValidationConfiguration

A dedicated WebClient with browser-like headers and a short timeout, used to verify links before they are shown to a user.

SwaggerConfiguration

Augments the generated OpenAPI document (/api/schema.json) with the bearer security scheme and the authorization requirements derived from @PreAuthorize.

SecurityConfiguration

The security filter chain — see Security Implementation.

OAuthClientConfiguration

Supplies an empty client registration repository so the application starts even when no third-party OAuth providers are configured.

Configuration Properties

Defaults live in engine/src/main/resources/application.properties; environments override them with an additional properties file (see Development Setup and Core Deployment). The main namespaces are:

Prefix Configures

Prefix	Configures
`spring.mongodb.`, `spring.elasticsearch.`	Data store connections.
`promethist.storage.*`	Resource storage backend (`file`, `s3`, `azure`), endpoint and credentials.
`promethist.pipeline.setup.*`	The available pipeline setups — see Interaction Pipeline.
`promethist.pipeline.tts.`, `promethist.pipeline.emotional`, `promethist.pipeline.recording`	Speech synthesis defaults and optional pipeline features.
`promethist.ai.llm-components.*`	Per-component language model selection and parameters — see AI Layer.
`promethist.embedding.*`	Embedding provider and model dimensions.
`promethist.security.`, `spring.security.oauth2.resourceserver.`	API keys and the JWT issuer.
`promethist.indexer.`, `management.`	Indexing and telemetry — see Observability.

spring.mongodb., spring.elasticsearch.

Data store connections.

promethist.storage.*

Resource storage backend (file, s3, azure), endpoint and credentials.

promethist.pipeline.setup.*

The available pipeline setups — see Interaction Pipeline.

promethist.pipeline.tts., promethist.pipeline.emotional, promethist.pipeline.recording

Speech synthesis defaults and optional pipeline features.

promethist.ai.llm-components.*

Per-component language model selection and parameters — see AI Layer.

promethist.embedding.*

Embedding provider and model dimensions.

promethist.security., spring.security.oauth2.resourceserver.

API keys and the JWT issuer.

promethist.indexer., management.

Indexing and telemetry — see Observability.

In this section

Interaction Pipeline