Platform Backend

Studio Backend

The platform backend is a single Spring Boot application (PlatformApplication, started through ai.promethist.platform.PlatformApplicationKt) built on WebFlux and Project Reactor. There are no blocking request threads, so service methods return Mono/Flux. Besides the Studio’s REST API it runs the AI Assistant’s Socket.IO server and the hosted MCP server, which are described under AI Interfaces.

Packages

Its sources live in ai.promethist.platform, split by role:

Package Contents

Package	Contents
`controller`	REST controllers (`*RestController`), the Stripe webhook, the Socket.IO handler of the assistant. Authorization is declared here with `@PreAuthorize` (see Authentication and Authorization).
`service`	Business logic: projects, agents, evaluations, knowledge, analytics, billing, test suites, the assistant’s turn processing, exports and uploads.
`component`	Spring components that are not services — above all the AI Assistant’s tool classes (`Tools.kt`) and the MCP tool providers (`McpTools.kt`), plus startup migrations and the `PermissionEvaluator` bean named `permission`.
`repository`	Reactive Spring Data repositories for MongoDB, plus hand-written aggregation repositories for analytics.
`model`, `dto`	Documents owned by the platform, and the request/response types of the API and of the assistant’s Socket.IO events.
`llm`	The language-model layer of the assistant: `LLMService`, the Azure OpenAI client wrapper, prompts (`llm/constants/Prompts.kt`) and output converters.
`configuration`	Spring configuration: security, MongoDB converters, Socket.IO, the MCP server, and the `@ConfigurationProperties` classes.
`util`	Helpers and extension functions — for example the derivation of the engine URL and the turn arithmetic of the analytics in `util/Functions.kt` — and the scheduled jobs (`util/Schedulers.kt`).
`exception`, `validation`, `enumeration`	`ExceptionResolver`, which turns exceptions into error responses (Requests and Responses); the `ValidRef` constraint of request bodies and the `Url` type of normalized web addresses; the integration types of the integration endpoints (`pre`, `during`, `post`, `connector`).

controller

REST controllers (*RestController), the Stripe webhook, the Socket.IO handler of the assistant. Authorization is declared here with @PreAuthorize (see Authentication and Authorization).

service

Business logic: projects, agents, evaluations, knowledge, analytics, billing, test suites, the assistant’s turn processing, exports and uploads.

component

Spring components that are not services — above all the AI Assistant’s tool classes (*Tools.kt) and the MCP tool providers (Mcp*Tools.kt), plus startup migrations and the PermissionEvaluator bean named permission.

repository

Reactive Spring Data repositories for MongoDB, plus hand-written aggregation repositories for analytics.

model, dto

Documents owned by the platform, and the request/response types of the API and of the assistant’s Socket.IO events.

llm

The language-model layer of the assistant: LLMService, the Azure OpenAI client wrapper, prompts (llm/constants/Prompts.kt) and output converters.

configuration

Spring configuration: security, MongoDB converters, Socket.IO, the MCP server, and the @ConfigurationProperties classes.

util

Helpers and extension functions — for example the derivation of the engine URL and the turn arithmetic of the analytics in util/Functions.kt — and the scheduled jobs (util/Schedulers.kt).

exception, validation, enumeration

ExceptionResolver, which turns exceptions into error responses (Requests and Responses); the ValidRef constraint of request bodies and the Url type of normalized web addresses; the integration types of the integration endpoints (pre, during, post, connector).

@SpringBootApplication scans ai.promethist.platform with all its sub-packages, so a bean anywhere in it is picked up. PlatformConfiguration adds a second scan of ai.promethist.**.{configuration,controller,component,service,repository}, which is what turns the services, repositories and configurations of promethist-common into beans of the platform — and what picks up test classes in packages of those names, see Beans and Component Scanning.

Shared Libraries

The domain types shared with the engine (tenants, projects, agents, sessions, turns, evaluation definitions, access control lists) and several services — AclService, the user and MCP connector services, Mailgun — come from promethist-common and promethist-lib, the libraries the engine is built on. Their version is pinned in gradle/libs.versions.toml; upgrading them is how the platform follows changes of the engine’s data model.

Subsystems

Authentication and Authorization: Sign-in, tokens, the role model, project access through identity providers and the staff gates.
Domain Model: Accounts, projects, agents and their revisions, project assets, evaluations, and which collections hold them.
REST API: Conventions of the /api/v1 API, the OpenAPI description and a map of the endpoint groups.
Knowledge Processing: How files and web pages become knowledge chunks and embeddings that agents retrieve from.
Integrations and External Services: Session webhooks, MCP servers and connectors, identity providers, secrets, email, storage and the re-encoding of uploaded videos.
Analytics Suite: What the analytics endpoints compute, from which data, the exports, and the account settings that restrict them.
Test Suites: Simulated users, agent evaluations, test suites and how they run on the bridge, and live agent tests.
Usage and Billing: From the engine’s usage records to Stripe meter events, subscriptions, checkout and invoices.

Studio Backend

Packages

Shared Libraries

Subsystems

In this section