Platform Backend

Project Overview

The promethist-platform repository contains Promethist Studio — the back-office where customers build, test, publish and analyze their voice-first AI agents — together with the services around it that are not part of the conversational runtime:

  • the Studio frontend, a Next.js application that also signs users in and acts as the OAuth authorization server of the hosted MCP server,

  • the platform backend, a reactive Spring Boot service that owns the Studio’s REST API, the AI Assistant (the in-app copilot) and the hosted MCP server that Claude connects to,

  • the Helm charts and the GitLab pipeline that build and deploy both.

The conversations themselves run in the engine, which lives in the promethist repository and is documented in the Platform Core documentation. The two systems share the promethist-common library and, in every deployed environment, the same MongoDB database: Studio writes the configuration the engine executes (projects, agents and their assets) and reads back what the engine records (sessions, turns, evaluation results, usage records).

This documentation covers the platform repository: how it is put together, how to run and deploy it, and how its larger subsystems work. End-user documentation of the Studio is the Platform User’s Guide; the customer-facing part of this component — connecting Claude to the platform — is its public module.

Repository Layout

Path Contents

backend/

The platform backend (Gradle module :promethist-platform-backend): Kotlin, Spring Boot WebFlux, Spring Security, Spring AI. Sources live in ai.promethist.platform, split by role into configuration, controller, component, service, repository, model, dto, llm, util, exception, validation and enumeration (Studio Backend).

backend/src/main/resources/mcp-guides/

The operating guides the hosted MCP server serves through its get_guide tool.

frontend/

The Studio web application: Next.js (App Router), React, TanStack Query, NextAuth with Keycloak.

deploy/

Helm charts for the backend and the frontend (deploy/backend/helm, deploy/frontend/helm), and the Azure Key Vault secret provider and namespace bootstrap used by CI.

buildSrc/, gradle/

The shared Gradle convention plugin and the version catalog (gradle/libs.versions.toml), which pins promethist-common and promethist-lib.

docs/

This documentation (an Antora component named platform).

CLAUDE.md

The rules Claude Code follows in this repository, above all for keeping this documentation current.

docker-compose.yml

Local MongoDB and Elasticsearch for development.

Documentation Map

Architecture

The deployed components, how a request travels through them, which data store holds what, and how the platform talks to the engine.

Technology Stack

Languages, frameworks and external services, and the role each of them plays.

Development Setup

Running the backend and the Studio locally, the local infrastructure, and the tests.

Code Conventions

The rules the backend and Studio code follow, the traps they avoid, and the formatting and lint checks that enforce them.

Configuration

Backend configuration properties and frontend environment variables, and how deployments layer them.

Platform Deployment

Container images, the GitLab pipeline, the environments and the release flow — with the Helm Charts, Observability and the Documentation Sites this documentation is published on.

Studio Backend

How the backend is organized, and its subsystems: authentication and authorization, the domain model, the REST API, knowledge processing, integrations, the analytics suite, test suites, and usage and billing.

AI Interfaces

The two ways language models operate the platform: the AI Assistant inside the Studio and the hosted MCP server Claude connects to, together with the Claude plugin that registers it.

Studio Frontend

Structure of the Next.js application, its data fetching, authentication and the two UI surfaces.

General

The public module: connecting Claude to Promethist, written for customers.

Building This Documentation

The documentation is an Antora component. Its sources live in docs/; the playbook antora-playbook.yml in the repository root builds this component on its own:

npx antora antora-playbook.yml

The site is written to build/site; the entry point is build/site/platform/index.html. A clean run prints nothing — every line of output is a warning to fix. The published sites are assembled by the promethistai/promethist-documentation project from the documentation of all platform repositories, see Documentation Sites.

Pages in the public module are written for the public documentation site, which shows a component’s public module only. A public page therefore must not link to a page outside modules/public, and never links source code. The rules for writing and maintaining these pages are in CLAUDE.md at the repository root.

In this section