Architecture
This page describes the architecture for fully self-hosted deployments where all services run in your environment. It is primarily a model of the Self-Managed on Your Kubernetes path, where the full stack runs in your cluster via the Helm chart. Under Serval-Managed in Your AWS, the same major components still run in an AWS account that you own, but Serval operates the platform for you remotely via an operator appliance provisioned in that account.
High-Level Overview
The Serval Helm chart deploys:- Backend API services — Core application logic (authentication, workflows, help desk, analytics, audit, and more)
- Temporal workers — Background job processors for each service
- Worker services — Isolated workflow execution for customer-defined workflows
- Web application — Reverse proxy serving the SPA and routing API calls
- Infrastructure dependencies — Optionally bundled PostgreSQL, Redis, and Temporal
Service Dependencies
All services depend on three core infrastructure components:| Dependency | Purpose | Options |
|---|---|---|
| PostgreSQL | Data storage (one logical database per service) | Bundled via Helm, or bring your own (RDS, Cloud SQL, Azure DB, etc.) |
| Redis | Caching and async queuing | Bundled via Helm, or bring your own (ElastiCache, Memorystore, etc.) |
| Temporal | Workflow orchestration and state management | Bundled via Helm, or bring your own (Temporal Cloud, self-managed) |
| OpenSearch (optional) | Lexical (BM25) search for help desk content | Bundled single-node for staging, or bring your own (AWS OpenSearch Serverless, etc.) |
Worker Architecture
Worker services execute user-defined workflows. They communicate with the backend services to retrieve workflow definitions, log actions and results, and proxy requests to integrated external services. In the single-cluster Helm deployment, workers run as standard Kubernetes deployments alongside the backend services.Web Application
The web application is served by a reverse proxy that serves the Serval single-page application (SPA), routes API requests to the appropriate backend services, and provides a single entry point for all traffic.Ingress
The Helm chart creates a Kubernetes Ingress resource that routes traffic to the web application and backend services. You can use any ingress controller (NGINX, Traefik, AWS ALB, etc.). The specific host scheme and ingress controller options are covered in the deployment guide on the customer documentation site.Database Architecture
Serval creates one logical PostgreSQL database per service for data isolation. A database initialization job runs on first install to create per-service logical databases, scoped database users, and required PostgreSQL extensions. All databases share a single PostgreSQL instance (or cluster), keeping operations simple while maintaining logical separation.Deployment Details
Detailed deployment content — including the full backend service inventory, Ingress host scheme, configuration reference, and operational runbooks — lives on the password-protected deployment architecture page. See Deployment instructions for how to get to it.Learn More
Self-Managed on Your Kubernetes — prerequisites
What you need in place before installing the Helm chart.
Deployment instructions
Step-by-step install, configuration reference, and production checklist — for customers and teams in onboarding.