security-architecture
Architecture overview
VaultTerm is a modular monolith — one Fastify and TypeScript backend with auth, vault, ssh, terminal, and audit modules — over Postgres and Redis, with a same-origin web portal and a separate admin plane.
Updated Jun 23, 2026
VaultTerm is built as a modular monolith, not a constellation of microservices. There is one backend process, organized internally into clear modules. This keeps the system simple to deploy, reason about, and run — a single binary plus its datastores — while still keeping the codebase modular.
The backend
The backend is a single Fastify + TypeScript application. Inside it, functionality is split into cohesive modules:
| Module | Responsibility |
|---|---|
auth | Authentication, sessions, tokens, and access control. |
vault | Storing and serving secrets under envelope encryption. |
ssh | Brokering SSH access and certificates. |
terminal | Terminal sessions and recording. |
audit | The tamper-evident audit log and checkpoint chain. |
The modules share one process and one deployment unit. There are no inter-service network calls between them and no Kubernetes orchestration to operate — deliberately. The design avoids the operational weight of microservices for a system that does not need it.
Datastores
VaultTerm depends on two datastores:
- Postgres — the system of record for tenants, secrets (ciphertext), audit logs, and configuration. Tenant isolation is enforced here via row-level security; see Tenant isolation.
- Redis — caching and ephemeral coordination.
There is no per-app or embedded database; the backend connects to Postgres and Redis as external services.
Web portal and admin plane
- The web portal is served same-origin with the API, so the product is a single origin to the browser.
- Administration runs on a separate plane — its own listener, bound to loopback by default, with its own RBAC and step-up gating. It is not the same surface as the product. See admin console.
The System Context diagram
The authoritative System Context diagram for the architecture lives in the repository (maintained as a draw.io diagram) and is kept current as the architecture changes — new modules, datastores, external services, or topology changes. It is the canonical picture of how the pieces fit together.
Related pages
- Self-hosting overview — how to run the monolith and its datastores.
- Security model — the broker model the architecture serves.
- Tenant isolation — multi-tenancy at the database layer.