> For the complete documentation index, see [llms.txt](https://docs.visdom.virtuslab.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.visdom.virtuslab.com/deployment-architecture.md). # Deployment architecture ## Topology The platform is installed on your **Kubernetes** cluster, on any conformant distribution (vanilla Kubernetes, OpenShift, Rancher or RKE2), using Helm charts, split across namespaces: | Namespace | Contents | | --------------------- | ------------------------------------------------------------------ | | `visdom-orchestrator` | Orchestrator controller (≥2 replicas, leader election), API and UI | | `visdom-runs` | Ephemeral agent pods (Kubernetes jobs), working volumes (PVC) | | `visdom-context` | Context Fabric services (indexing, MCP endpoint) | | `visdom-tracing` | AI Tracing: server, dashboard, SIEM exporter | | `visdom-vcr` | Code Review: findings API | | `visdom-controlplane` | Control Plane: API and UI | | `visdom-auth` | Identity broker, unless an existing instance is used | ![Deployment architecture, production environment](https://377380473-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2U8RqIIMUGxclsDYVNc3%2Fuploads%2FB8rovgV1At7wl6iyYImf%2Fdeployment.png?alt=media) Properties: * **All state in PostgreSQL** (version 17 or above, a separate database per component), with an HA cluster recommended, either operator-managed or your own database service. There are no external message brokers and no specialist datastores, which keeps the operational surface and maintenance requirements small. * **NetworkPolicy default-deny** in every namespace; communication between components is explicitly allowed; agent pods have no network access beyond the egress allowlist. * **Your image registry**: all platform images are delivered into an internal registry. Air-gapped environments are supported: installation and updates arrive as signed image bundles with no internet connection. Images are scanned under your policies and versions are pinned. * **Single-tenant isolation**: a dedicated instance with separate databases, separate configuration, and no data shared with any other installation. ## High availability The platform is stateless at the service level and keeps all state in PostgreSQL, which keeps the HA model simple: * The Orchestrator controller runs in at least 2 replicas with leader election based on PostgreSQL advisory locks (`pg_try_advisory_lock`). A replica failing does not interrupt running flows; the reconciler rebuilds state from the database. * PostgreSQL: an HA cluster managed by an operator (CloudNativePG, for example) or your existing database service. The platform requires no external message broker, because asynchronous work uses a transactional outbox plus `LISTEN`/`NOTIFY` in PostgreSQL. That eliminates a whole class of components that would each need their own HA story. * Agents execute as ephemeral Kubernetes jobs. A node failing means the job restarts under the `on_failure` policy defined in the flow; intermediate flow state is durable (database plus the shared working volume). * User interfaces are static single-page applications behind Ingress, scaled horizontally. * Graceful degradation: platform unavailability does not affect the tracker or source control. The integration is initiated one way, by webhooks with retries on the platform side, so lost events are redelivered and the inbound queue has a dead-letter queue with retries and a circuit breaker. ## Recovery objectives Recovery objectives follow the class of database service in use. With a PostgreSQL cluster and a synchronous replica the platform achieves RPO=0 and an RTO in minutes, bounded by service restart. The nature of the process, asynchronous issue handling rather than a transaction path, means a short outage delays work without losing it: issues wait in the tracker and are processed once service returns. ## Sizing The load profile differs from classic transactional systems: the dominant cost is **LLM inference**, which sits outside the platform behind your gateway, while the platform itself has moderate requirements. | Element | Initial sizing | | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | Platform services (controllers, API, UI) | 8–12 vCPU, 16–24 GB RAM in total | | Agent pods (`visdom-runs`) | 1–2 vCPU, 2–4 GB RAM *per concurrent flow*; at 50 concurrent flows roughly 64–128 vCPU and 128–256 GB RAM, elastic, jobs release resources when they finish | | PostgreSQL (3–4 HA instances) | 4–8 vCPU, 16–32 GB RAM, 200–500 GB SSD per instance | | Context Fabric indexes | Depends on how many repositories are actively covered; volume is estimated on a representative sample | At the scale of thousands of repositories, the key design parameter is the **incremental indexing strategy**: active repositories first, with cost proportional to the delta rather than to the size of the estate. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.visdom.virtuslab.com/deployment-architecture.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.