VegaDūta Platform Documentation

The complete engineering reference for the VegaDūta agentic-AI platform — from the Spring AI LLM layer through the modular monolith, the satellite services, and self-hosting with Docker Compose or Helm. Compiled from the repository source, Compose files and Helm charts.

42

Maven modules

One Spring Boot 3.4 deployable (core/app) plus dedicated worker/jobs assemblies

14

LLM providers

BYOK + platform-hosted pool + on-device edge tier, all behind Spring AI ChatClients

3

Ways to run it

Compose Lite (5 containers), Compose Full (10 core, up to 36 with profiles), or Helm on Kubernetes

10

Channel types

WhatsApp, Telegram, Slack, Discord, Messenger, Instagram, X, Email, Teams, Voice

Deployment options

OptionWhat you getConfig lives inStatus
Compose Lite Agents, chat, knowledge, graph memory on one machine (scripts/vegaduta up --lite) deploy/compose/lite.yml + deploy/compose/.env supported
Compose Full Everything, with opt-in profiles; optional public HTTPS on your domain via Caddy (--domain) deploy/compose/docker-compose*.yml + deploy/compose/.env supported
Kubernetes (Helm) Umbrella chart; bundled or bring-your-own Postgres, Valkey, S3, OIDC deploy/helm/ preview

Documentation map

SectionContentsStart with
00 · OverviewWhat the platform is, who uses it, terminologyPlatform at a Glance
01 · ArchitectureLayered system design, the 42-module core, the Spring AI / LLM layer, data and identity architectureSystem Architecture
02 · DecisionsArchitecture Decision Records — every consequential choice and the problem that motivated itADR Index
03 · FunctionalPersonas and functional specification by domain: agents, workflows, channels, knowledge, governanceFunctional Overview
04 · APIREST surface, JWT auth, SSE/AG-UI streaming, webhooks, developer APIAPI Overview
05 · DeploymentCompose and Helm, CI/CD, local development, Keycloak, rollbackDeployment Guide
06 · OperationsObservability (Prometheus, Grafana, Loki, Langfuse), backupsObservability
07 · SecuritySecurity architecture, secrets and key management, compliance posture, threat modelSecurity Architecture
08 · DevelopmentGetting started, build/test, repository map, conventions, contribution workflowGetting Started
09 · RFCRequest-for-comments process and template for proposalsRFC Index
10 · TestingTest strategy, the three Playwright suites, quality gatesTest Strategy
11 · AppendixEvery command A–Z, environment variables, ports/services matrixCommand Reference

How to read the verification markers

These pages distinguish what was checked against the code from what is assumed. Throughout this documentation set:

MarkerMeaning
verifiedChecked against the repository on the stated date
unverifiedBelieved true but not re-checked — treat as a lead, not a fact
live / referenceA supported deployment path
draftAuthored but never deployed/applied — aspirational, not real
retiredWas real, no longer is — kept for history
Non-negotiable operating rules
  1. Back up deploy/compose/.env (or your Kubernetes Secrets) together with the data. APP_ENCRYPTION_KEY must be identical everywhere core boots, or every stored credential becomes undecryptable.
  2. Never point a browser-facing or token-issuer URL (PUBLIC_*) at localhost on a server. Never bake a localhost NEXT_PUBLIC_* into an image you deploy.
  3. The issuer core validates must match the one Keycloak stamps; extra issuers go in KEYCLOAK_ADDITIONAL_ISSUERS — otherwise every token 401s.
  4. A hung service is evidence to collect (logs, container state, memory) before you restart anything; docker compose down -v deletes data.
  5. Pin VEGADUTA_VERSION; read the release notes before scripts/vegaduta upgrade.

Conventions used across every page