Technical architecture

Vaks PM · Technical architecture · June 2026

Overview

Vaks PM is a multi-user project-management web application built to run entirely on infrastructure the organization controls. It is on-premise, that is, it sits on the organization's own servers rather than on a third-party online service. The product ships as a small set of container images, and a complete installation has no mandatory dependency on any external online service.

The whole product reduces to a handful of container images plus three durable backing stores (a relational database, a cache, and an object store). Anything else the system needs, such as load balancing, failover coordination and real-time messaging, comes from components the installation hosts itself. Every outbound connection is optional, and the system runs without any of them:

• An email relay, SMTP (Simple Mail Transfer Protocol, the standard protocol for sending mail), used only to deliver notification emails; and webhook / notification endpoints the customer configures. Both are called from the background worker.
• A SIEM syslog forwarder, used only if audit-log forwarding to an external collector is configured. Also called from the worker.
• A corporate identity provider or collaboration platform — Microsoft Entra ID, Microsoft Graph/Teams, Slack or Google Workspace — used only if single sign-on or a collaboration/file-source integration is enabled. Single sign-on and file-source connector calls are made by the api; Microsoft Teams project provisioning is the one exception — it runs as a background job and calls Microsoft Graph directly from the worker, which fetches a short-lived app token from the api and never handles the client secret itself.

The application is API-first: the web front end and third-party integrations both consume the same REST (Representational State Transfer, the conventional style for HTTP web APIs) API surface, but third-party callers (API tokens) are restricted to routes explicitly marked as public, while the browser session can reach the full application surface. Authorization is enforced on the server for every request and every real-time event, and the front end is never trusted to police access on its own. The services that carry application logic, the API and the background worker, are stateless (they hold no local data) and so scale horizontally by simply running more copies.

Glossary

Acronyms used throughout this guide, defined once here for reference.

Technology stack

The system is TypeScript end to end: the same typed language spans the browser front end, the back end and the shared data contracts between them, so a single type definition can guarantee that client and server agree on every payload. The table below lists each layer and the technology that fills it.

What runs

Whichever orchestrator is used, the core application services are the same; the MCP / AI connector is currently Swarm-only. Application logic is kept stateless wherever possible: the api, web and worker services hold no local data and can be scaled simply by running more replicas. All durable state lives in the three backing stores (PostgreSQL, Redis and the object store).

Control plane and data plane

The architecture separates two responsibilities into two logical planes:

• The control plane is the shared front door: the reverse proxy (which terminates TLS and routes by host name) together with a shared authentication service. When a user signs in, this service issues a JWT (a signed session token) stamped with the tenant identity, so every later request already carries proof of which organization it belongs to.
• The data plane holds the business data, isolated per tenant, each organization in its own database with its own database role.

A single container image serves either role through a configuration flag; there is no separate product for the front door. In a single-organization on-premise install this distinction is essentially invisible, and it becomes meaningful only when one instance serves several organizations. The benefit of the split is containment. A flaw in one tenant's data access (a missed WHERE clause, an SQL injection, or an attempt to reach another user's object by its identifier) is confined to that single tenant's database, because the database role for one tenant cannot read another's.

Tenancy models

A tenant is one isolated organization served by the instance. A single configuration flag sets how many tenants an instance carries and how their data is isolated. There are two modes:

In both modes the rule is the same: one database per tenant, each with its own database role. The several databases can live inside a single highly available PostgreSQL cluster, which is shared infrastructure over separated data. The application never hard-codes which database to use; it obtains a connection through a tenant context. In dedicated mode that context always returns the single database; in pooled mode it returns <db>_<slug> for the resolved tenant.

The cells variant

The pooled model can be deployed in a stricter form called cells: instead of one shared application tier serving every tenant, each tenant gets its own application instance and its own database, sitting behind the same shared control plane. This trades some efficiency for maximum isolation, since a tenant's compute is no longer shared with anyone else's. The same image still runs everywhere; only the deployment shape differs. One useful property of this model is that a non-production tenant (for example a demo or test organization) is just another cell and is fully disposable: its database can be dropped and reseeded without touching any other tenant.

Hardware requirements

Sizing follows two principles inherited from the architecture. First, the stateless application tier (web, api, controlplane, worker) is light and roughly flat: it consumes little and absorbs load by adding replicas. What actually grows is the stateful data tier, of which PostgreSQL is by far the largest memory consumer. Second, the tenancy mode decides how that data tier grows: in dedicated it serves a single organization, whereas in pooled each tenant adds its own database, its own connection pool and its own share of working memory — so the data tier grows per tenant.

Container footprint (reference)

The reference stack sets per-service memory ceilings, sized to fit on modest hosts. These are ceilings (upper limits), not reservations: in high availability the replicas spread across hosts, so the reference development cluster fits on hosts of roughly 2 GB of RAM each.

The sum of the ceilings across the whole application tier (two replicas of each) is around 3 GB; spread over three hosts, that leaves each host comfortable even on 2 GB. Redis and the object store are deliberately left without a ceiling: an out-of-memory (OOM) kill there would cost data.

Sizing matrix

The four combinations of deployment mode (single-host versus high availability) and tenancy mode (dedicated versus pooled). "Eval." targets an evaluation or a small team; "Recommended" targets production at ~200 active users per organization.

Login & routing

The reverse proxy routes incoming traffic by the Host HTTP header, the domain name the browser asked for. The crucial property is that the tenant is resolved before authentication: the proxy hands the Host to the back end, which derives which organization the request belongs to, and only then does it attempt to find the user. This ordering keeps one organization's users from being matched against another organization's accounts.

The behaviour differs between the two tenancy modes, but the infrastructure (the proxy, its routers and the TLS certificates) is identical in both. A single configuration flag flips the behaviour; in dedicated mode the host-based routing simply stays inert.

Real-time channel

Beyond ordinary request/response calls, the application maintains a persistent WebSocket connection (a two-way, always-open browser-to-server channel) so that changes such as a moved task, a new comment or a status update appear live without the page being reloaded. The transport is Socket.IO, a widely used WebSocket library that adds reconnection and fallback handling.

• Authentication is required at the handshake. The connection must present a valid JWT as it opens; an unauthenticated socket is refused before it can join anything. The connection is therefore tied to a known user and tenant from its first moment.
• Events are grouped into a room per project. A client receives updates only for the projects it has joined, rather than a firehose of everything happening on the instance.
• Authorization is enforced on every event. The server applies the same role-based access checks to each real-time event that it applies to REST calls; joining a project's room and receiving its events both require the appropriate rights. The live channel is never a way around the permission model.

Network & ports

The exposure surface is deliberately small. Only ports 80 and 443 need to be reachable from clients; the reverse proxy redirects plain HTTP (80) to HTTPS (443) and terminates TLS there. Every other service, including the database, the cache, the object store and the application tier, communicates on the cluster's internal overlay network and is never published to the outside. The connections that leave the cluster are all optional: the SMTP relay, webhook/notification endpoints and the SIEM syslog forwarder originate from the background worker; calls to a corporate identity provider or collaboration platform (Entra ID, Slack, Google Workspace) for single sign-on or a collaboration/file-source integration originate from the api — with one exception: Microsoft Teams project provisioning runs as a background job and calls Microsoft Graph directly from the worker, which fetches a short-lived app token from the api rather than holding the client secret itself.

In the HA topology shown above, two helpers sit between the application and PostgreSQL: HAProxy, a load balancer that always points to the current writable database node, and etcd, a DCS (distributed configuration store) that holds cluster state and elects the database leader. The application never connects to a PostgreSQL node directly. It goes through the load balancer, so a failover is transparent to it.

Two-datacenter model

For disaster resilience, an instance can be spread across two datacenters (DC) in an active / passive arrangement: one DC serves all traffic, the other stays ready to take over. The guiding constraints are:

• One orchestrator per DC, never stretched. A single Docker Swarm must not span both sites: its consensus quorum is fragile over a long-distance link and risks split-brain (two halves each believing they lead). Each DC therefore runs its own independent cluster, with its own local quorum.
• One writable PostgreSQL. PostgreSQL accepts writes on a single node only. The primary DC is read/write; the standby DC runs a Patroni standby cluster fed by asynchronous replication, so writes are copied over with a slight delay.
• One object store across both sites, in zones. The S3-compatible store spans both DCs as a single cluster, using a zone per site so each object is replicated geographically.
• GeoDNS in front. A geographic DNS service (or a global load balancer) sits ahead of the two control planes and steers visitors to the active DC.

Because replication is asynchronous, a failover (promoting the standby) carries a non-zero RPO (Recovery Point Objective, the maximum tolerated data loss): the few seconds of writes not yet replicated may be lost. The stateless application tier, by contrast, runs identically in both DCs and poses no such constraint. Two genuinely active sites serving writes at once are out of scope, because PostgreSQL is single-writer; that would require geo-distributing the tenants so each one is primary in a single DC.

Related: The product · Docker Swarm deployment · Kubernetes deployment · Security · Operations · Demo