Common Library

Serialization

Two object mappers coexist, because the platform speaks two wire encodings, and a set of database converters handles the types Spring Data cannot map on its own.

JSON Mapper

common/configuration/JacksonConfiguration provides the primary JsonMapper bean (Jackson 3, tools.jackson) used for the REST API and for the JSON element format. It registers custom serializers and deserializers for the types that need a stable external representation:

Type Representation

Type	Representation
`Ref`	The ref string itself, not an object wrapper.
`Locale`	A BCP 47 language tag.
`Instant`, `ZonedDateTime`	ISO 8601 timestamps.
`NamedProperties` / `LLMComponents`	A map of component name to properties, where the provider-specific block deserializes into the matching `LLMConfiguration` variant.

Ref

The ref string itself, not an object wrapper.

Locale

A BCP 47 language tag.

Instant, ZonedDateTime

ISO 8601 timestamps.

NamedProperties / LLMComponents

A map of component name to properties, where the provider-specific block deserializes into the matching LLMConfiguration variant.

MessagePack Mapper

common/configuration/MessagePackConfiguration provides a second mapper bean, msgpackObjectMapper, built on the MessagePack data format. It exists for the binary MSGPACK element format used by the mobile clients.

Two things differ from the JSON mapper:

polymorphism is WRAPPER_OBJECT rather than a type property — an element encodes as a map with a single key naming its type, as described in Wire Formats. The mixin applies to Element, OutputElement, RelayElement, NavigationSpecification, EvaluationSection and MultimodalInteractionSpecification.
it registers the serializers in serialization/legacy/ — parallel implementations for Instant, Locale, Ref, ZonedDateTime and the LLM components — which keep the binary representation compatible with clients built against the earlier format.

ElementMapper (ai.promethist.pipeline.service) is the single class that uses both mappers and implements all three formats for input and output. See Wire Formats for the resulting encodings and Socket Handlers for where it is applied.

Database Converters

Converter Purpose

Converter	Purpose
`RefReadConverter`, `RefWriteConverter`	`Ref` as a plain string in MongoDB.
`ZonedDateTimeReadConverter`, `ZonedDateTimeWriteConverter`	Timestamps with zone in MongoDB.
`MongoConfiguration.LocaleReader` / `LocaleWriter`	Locales in MongoDB.
`MongoConfiguration.ChatMessageReader` / `ChatMessageWriter`	Spring AI `Message` instances as BSON documents, dispatching on the stored class so `InstructionMessage`, `UserMessage`, `SystemMessage`, `AssistantMessage` and `ToolResponseMessage` round-trip with their subtype intact.

RefReadConverter, RefWriteConverter

Ref as a plain string in MongoDB.

ZonedDateTimeReadConverter, ZonedDateTimeWriteConverter

Timestamps with zone in MongoDB.

MongoConfiguration.LocaleReader / LocaleWriter

Locales in MongoDB.

MongoConfiguration.ChatMessageReader / ChatMessageWriter

Spring AI Message instances as BSON documents, dispatching on the stored class so InstructionMessage, UserMessage, SystemMessage, AssistantMessage and ToolResponseMessage round-trip with their subtype intact.