Project Overview

Modules

The repository is a single Gradle build named promethist with six subprojects. Each is included under a promethist- prefix, so the module in engine/ is the Gradle project :promethist-engine.

Module Type Purpose

common

Library

Shared platform library: the persisted domain model, pipeline abstractions, memory, AI/LLM abstractions, storage, serialization and security utilities. Everything the engine and the bridge have in common lives here.

engine

Application

The platform server — a reactive Spring Boot (WebFlux) application that runs conversations, serves the REST API and the conversation sockets, and persists sessions, turns and memory.

lib

Library

The foundation layer: the wire protocol types exchanged between all components, audio/image/video utilities, resource storage abstractions and logging helpers. Has no dependency on any other module.

client

Application + library

Command-line reference client for the conversation protocols, and the reusable client-side I/O building blocks (socket transports, audio playback, microphone and camera capture) that the bridge also uses.

bridge

Application

Automated conversation testing service. Runs a tester agent against an application under test on a real device, a browser or another engine session, and records the outcome.

relay

Application

A minimal, stateless Socket.IO relay that forwards messages between two independent socket connections. Used when the bridge cannot drive a test device directly and has to reach it through a page running in a browser.

Dependency Graph

lib ──┬──> common ──┬──> engine
      │             └──> bridge
      └──> client ──┬──> engine
                    └──> bridge

relay   (standalone — no module dependencies)

In other words:

  • lib is the base and depends on nothing.

  • common and client are siblings: both depend only on lib. client does not depend on common.

  • engine and bridge both depend on client, common and lib.

  • relay is fully self-contained.

Deployable Applications

Four modules produce runnable artifacts:

Module Artifact Notes

engine

Spring Boot jar + container image

HTTP/WebSocket listener on port 9010, Socket.IO listener on port 9011. Deployed with the engine Helm chart.

bridge

Spring Boot jar + container image

Runs either as a web service (port 9013) or as a one-shot CLI test run.

relay

Spring Boot jar + container image

Socket.IO relay on port 9012.

client

Executable fat jar (shadowJar)

Command-line client; built and published by CI, not deployed as a service.

External Consumers of common

common is not only an internal Gradle dependency — it is also published as a Maven artifact to the repository configured for the build, so services outside this repository can build against the same domain model and abstractions.

One such consumer is the platform backend service (promethist-platform-backend), which lives in its own repository and depends on the published promethist-common artifact. Changes to the public types in common — the domain model in particular — therefore affect code outside this repository and should be treated as changes to a shared contract.

Build Configuration

  • settings.gradle.kts declares the subprojects and the Develocity build scan configuration.

  • buildSrc/ holds the internal convention plugins (for example ai.promethist.kotlin-jvm) that apply the shared Kotlin/JVM setup to each module.

  • gradle/libs.versions.toml is the version catalog — all dependency versions are declared there and referenced as libs.* from the module build scripts.

  • The root build.gradle.kts provides the KtLint tasks described in Code Conventions.