Stack & deployment

Technology stack

Backend: Scala 2.13, Apache Pekko (actors and crash resilience), PostgreSQL, Redis (optional). LLM layer: multi-provider proxy (OpenAI, Anthropic, local models, custom base URLs). Frontend: React 18, TypeScript, Vite, MUI (Material UI), TanStack Query, React Router. Auth: Keycloak (JWT / OIDC) for the console and Admin API. Encryption: AES-256-GCM envelope encryption with deployment-supplied KEK material or customer KMS integration. Containerisation: Docker; frontend builds with Vite.

Configuration Reference

PlanVault is configured at two levels. Organisation settings define shared resources (providers, org tool catalog, OpenAPI Auto-Healer, MCP, knowledge providers, inbound webhooks, org-wide scenarios, secrets, models, spend and budgets subject to role, users, audit). Project settings control per-project models, LLM, retrieval, knowledge, tool integrations, **project** scenarios, secrets, Runtime keys, lifecycle webhooks, operations, and budget.

Organisation settings

Organisation settings sidebar (console order): General · Data export · Providers · LLM · Models (shown for roles with Developer access or higher) · Tools (org catalog) · OpenAPI Auto-Healer · MCP · Knowledge providers · Webhooks · Scenarios · Secrets · Users · Audit · Audit webhooks (**Owner/Admin only**) · Spend · Budget limit (Developer+). Some entries are hidden for lower roles.

Project settings

Project settings sidebar (console order): General · Data export · Models · LLM · Tool retrieval · Knowledge · Debug: tools and plan (**Owner/Admin only**) · Tool integrations · Project scenarios · Secrets · Keys · Session lifecycle webhooks · Audit (**Owner/Admin**) · Operations (**Owner/Admin**) · Budget limit.

Knowledge base

Knowledge base support in PlanVault is an external retrieval layer that adds domain documents, policies, runbooks, or customer-specific knowledge to planning. It complements tool retrieval: tool retrieval decides which tools the agent may call, while knowledge retrieval gives the agent context about what it should take into account.

How it works during a session: • Runtime reads the user prompt before tool selection. • If the project has an enabled knowledge provider binding, PlanVault calls the provider with query, topK, scoreThreshold, and context limits. • Returned chunks are filtered by scoreThreshold and bounded by configured caps. • Short knowledge excerpts may be appended to the tool-selection query so tool selection sees relevant domain context. • A bounded <kb_context> can be prepended to the planner message when includePlannerKbContext is enabled. • Retrieval outcome is recorded as an admin-only runtime diagnostic: providerType, latency, chunkCount, score metadata, and outcome.

How to configure

Configuration has two levels: 1. Organisation settings → Knowledge providers: create a provider, choose type, endpoint, auth mode, API key, timeout/topK/context limits, and adapter config. 2. Project settings → Knowledge: bind one org-level provider to the project, enable the binding, and optionally override providerConfig, timeoutMs, topK, scoreThreshold, maxContextChars, toolSelectionKbChars, failurePolicy, and includePlannerKbContext. 3. Use Test on the org or project page: it calls the same dispatcher and shows status, latency, chunks, and context preview.

Provider parameters

Main provider parameters: • providerType — custom_http, dify_dataset, or ragflow_retrieval. • endpointUrl — provider base URL; use HTTPS in production. HTTP/private targets require explicit outbound URL policy allowance in the environment. • providerConfig — non-secret JSON for adapter settings: Dify datasetId / dataset_id; RAGFlow datasetIds / dataset_ids or datasetId; for custom_http, your own non-secret flags. • authMode — none, bearer, or header. The API key is stored encrypted with the organisation DEK; authHeaderName is used for custom header mode. • timeoutMs — upstream call timeout, capped by runtime config. • topK — how many chunks to request and consider for context. • scoreThreshold — minimum score; chunks without score do not pass filtering when a threshold is set. • maxContextChars — maximum <kb_context> size for the planner. • toolSelectionKbChars — how much knowledge excerpt to add to the tool-selection query. • failurePolicy — fail_open continues planning without KB on provider failure; fail_closed stops the run when KB is unavailable. • enabled — globally turns the provider on or off.

Supported providers

Supported types: • custom_http — your endpoint receives a normalized POST from PlanVault and returns normalized chunks. This is the most flexible option for your own RAG/search and enterprise data boundary. • dify_dataset — PlanVault calls the Dify Dataset Retrieval API: {base}/datasets/{datasetId}/retrieve. datasetId can live on the org provider or be overridden in the project binding. • ragflow_retrieval — PlanVault calls RAGFlow /api/v1/retrieval. datasetIds or datasetId are required; the project binding may override datasets for a specific project.

Custom solution

A custom knowledge base is not a document store embedded inside PlanVault. It is your HTTPS retrieval service. It can read from PostgreSQL/pgvector, Elasticsearch/OpenSearch, S3, Confluence, Notion, an internal RAG service, or any other index. PlanVault handles the call, limits, authentication, chunk normalization, and injection into planning context.

{
  "query": "What is the refund policy?",
  "projectId": "uuid-or-null",
  "sessionId": "uuid-or-null",
  "messageId": "uuid-or-null",
  "topK": 5,
  "scoreThreshold": 0.2,
  "maxContextChars": 4000,
  "filters": {}
}

Return JSON in PlanVault-normalized shape: status plus a chunks array. The text field is the minimum useful field; id, documentId, title, section, url, score, updatedAt, and metadata are optional but useful for diagnostics and references in context.

{
  "status": "ok",
  "chunks": [
    {
      "id": "chunk-1",
      "documentId": "doc-42",
      "title": "Refund policy",
      "section": "Returns",
      "url": "https://example.com/docs/refunds",
      "text": "Relevant excerpt...",
      "score": 0.91,
      "updatedAt": "2026-05-15T00:00:00Z",
      "metadata": {}
    }
  ]
}

Deployment

PlanVault ships as containerised services (API, Keycloak, LLM proxy, PostgreSQL, optional Redis) for customer-controlled operation. Operators choose session-store modes, ingress, monitoring, backups, and key-management wiring per environment.

Prerequisites: • Container runtime (Docker, Kubernetes, or equivalent) • JVM 21 for the published API image (Dockerfile.api uses Eclipse Temurin 21); local builds may use another compatible LTS JDK per your toolchain • Node.js 20+ (frontend build, or use the pre-built Docker image) • A Keycloak realm configured for PlanVault (realm name, client IDs) • LLM provider credentials (OpenAI, Anthropic, or a custom base URL for local models) • Key encryption key wiring for organisation DEKs through deployment-supplied KEK material or customer KMS integration, plus a dedicated HMAC signing key

PlanVault can run in a private VPC with air-gapped LLM backends (e.g. Ollama via custom api_base in the LLM proxy layer). Enterprise deployments may include billing via AWS Marketplace for existing procurement budgets — confirm availability with your vendor or account team. For production hardening, see the production checklist and configuration reference in the repository documentation.

Troubleshooting

Execution and events

If execution looks stuck: check the SSE connection chip, enable debug mode with the event graph, or refresh and inspect the latest session events.

LLM, models, and tools

If the LLM rejected or oversimplified a plan: review the project system prompt, allowed models and quotas; reduce scenario complexity or tool count. If the wrong tools are shortlisted, check Tool retrieval (mode, thresholds), scenarios, and test-selection / Debug.