> 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/logical-architecture.md).

# Logical architecture

All components run inside your Kubernetes cluster. The only traffic that leaves is model calls, and those go through a gateway you control.

![Platform architecture, end to end. Context Fabric feeds the coding agent and every gate from Jira, Git history, review comments, repositories, docs and ownership; the Orchestrator drives the agent through Testing, Code Review and Security to a risk gate, with human approval for high-risk changes; AI Tracing records the whole run.](https://377380473-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2U8RqIIMUGxclsDYVNc3%2Fuploads%2Fgit-blob-b154e0672799e1ae72d313546a7e2bfa83f68dbf%2Foverview.png?alt=media)

| Component                 | Role in the issue-to-pull-request flow                                                                                                                                                       |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Visdom Orchestrator**   | Flow engine and agent harness: flow definitions (a graph of steps), triggers (webhook, cron, manual), agents run as Kubernetes jobs, approval gates, failure handling, versioned definitions |
| **Visdom Context Fabric** | The organisational knowledge layer: repository index, dependency and ownership graph, conventions, decision history, served to agents over MCP and as generated rule files                   |
| **Visdom Code Review**    | Multi-layer pre-review of a pull request: deterministic gate, risk classification, LLM review through fixed lenses, confidence level per finding                                             |
| **Visdom Testing**        | Quality gates independent of the code's author: architecture tests, property-based tests, mutation testing, contract tests                                                                   |
| **Visdom AI Tracing**     | Audit trail and AI observability: prompts, calls, tools and changes recorded, Ed25519-signed chain, policies, cost, attribution of AI-written code, SIEM export                              |
| **Visdom Security**       | Runtime isolation of agents (sandbox with egress control and secret substitution) and AppSec scanning of the change                                                                          |
| **Visdom Control Plane**  | The shared skeleton: projects, repositories, users, RBAC per project and repository, secrets, and per-repository opt-in                                                                      |
| **Identity broker**       | OIDC/SSO, MFA, synchronisation with your directory, shipped with the platform or integrated with your existing instance                                                                      |


---

# 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/logical-architecture.md?ask=<question>&goal=<endgoal>
```

`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.