Architecture
Platform Architecture
A high-level tour of how Versus is built. Enough to inform an architecture or security review — without internal implementation detail. The guiding principle is boring on purpose: mature, well-understood building blocks arranged in clean layers, so the interesting engineering goes into the automation rather than the plumbing.
Architecture at a glance
Versus is a layered, API-first system:
- A single-page web application — the front end you interact with in the browser.
- An application core — an API-first back end that holds all business logic.
- A relational system of record — the durable store for inventory, policy, and history.
- A workflow & automation engine — runs multi-step changes as durable, auditable jobs.
- A collector plane — lightweight agents that reach into your network from the inside.
- A dedicated identity provider — SSO and MFA for every sign-in.
Every layer talks to the next through a stable, versioned contract, so each can scale, deploy, and evolve independently.
Front end
The user interface is a single-page application (SPA) written in TypeScript with React.
- Component-driven UI. A shared design system gives every workspace — ADC, firewall, certificates, vault, observability, service desk — a consistent look and behavior.
- API-only. The browser never touches the database or internal services directly. It speaks exclusively to the back end over a versioned REST/JSON API, which keeps a clean trust boundary and lets the same API serve integrations and automation.
- Live, cached views. Server state is fetched and cached on the client with background refresh, so lists and run status stay current without heavy page reloads.
- Role-aware. Navigation and actions adapt to the signed-in user's permissions; the UI only offers what the API will authorize.
- Statically served. The app compiles to static assets delivered behind the same TLS front door as the API — a single origin to secure.
Back end
The application core is API-first and written in Python (Django and the Django REST Framework).
- Stateless request handlers. The API runs as stateless workers behind a reverse proxy, so it scales horizontally — add workers for more throughput.
- One source of truth for logic. Authorization, validation, and business rules live in the back end, not the client, so the web UI, integrations, and automation all get the same guarantees.
- Tenant isolation in the data layer. Multi-tenant deployments enforce separation with row-level security in the database — defense in depth beneath application checks.
- Asynchronous work. Long-running jobs — discovery, upgrades, migrations, deployments — run as background tasks rather than blocking API requests.
- Extensible by design. An App Builder layer lets customers define their own forms, dashboards, and workflow steps on top of the platform without forking it.
The workflow & automation engine
Automation is a first-class subsystem, not a script runner bolted on the side.
- Multi-step changes execute as durable runs — each records its steps, inputs, outputs, and status, so it can be paused, resumed, retried, and audited.
- Steps range from device operations (discover, deploy, upgrade) to git operations, approvals, and integrations with external systems (ticketing, IPAM, DNS).
- Runs can be built visually, generated with AI assistance, scheduled, or triggered from the API — the same engine underneath.
Reaching your network — the collector plane
Versus never needs an inbound path into your network. Instead, lightweight collector agents run inside your environment and do the reaching.
- Collectors are compact, self-updating agents (built in Go) deployed close to your devices.
- They connect outbound-only to Versus over a bearer-authenticated TLS channel on 443 — no inbound firewall exceptions to your devices.
- A control plane brokers work to the right collector and streams results back; device credentials can be resolved locally on the collector so they never leave your network.
Identity
Every sign-in goes through a dedicated identity provider speaking OIDC, with single sign-on and mandatory multi-factor authentication. It can run bundled with Versus or federate to your corporate IdP, and it's the single place session, MFA, and account policy are enforced — the application core simply trusts the tokens it issues.
Data & storage
- PostgreSQL is the system of record — inventory, policy, workflow history, and audit.
- Object storage holds larger artifacts and backups, with a local-disk fallback for self-hosted installs.
- Secrets live in the Versus Vault with envelope encryption (per-secret data keys wrapped by a master key) and a tamper-evident, hash-chained audit trail. See A Day in the Life of a Secret.
How it's deployed
The same codebase runs in two form factors:
- Cloud (managed) — a multi-tenant service Versus operates for you.
- Self-hosted (on-premise) — the full stack packaged as a virtual appliance, a Kubernetes/Helm chart, or Docker Compose.
Everything is containerized, with a reverse proxy terminating TLS in front of the app and API. Because the front end, back end, workflow engine, and collector plane all communicate through stable contracts, the cloud and on-premise deployments are the same software arranged the same way — only the operator changes. See Deployment Options and the On-Premise Hardening Guide.
Design principles