Architecture

Vesicle is a Matrix homeserver split into four first-party services plus a small set of platform components. Helm is the supported way to run this layout in Kubernetes.

The four first-party services are Gateway, Client API, Federation API, and Auth. Each is a separate Deployment with its own replica count, so you can scale the busy path without scaling a monolith.

Inbound traffic flow

HTTPS for the homeserver host (<serverName>) lands on your ingress (Traefik or Gateway API), then on vesicle-gateway. The gateway serves well-known locally and forwards the rest over NATS request/reply.

flowchart LR
  clients[Clients and remote homeservers]
  ingress[Ingress HTTPS]
  gw[Gateway]
  nats[NATS]
  cs[Client API]
  ss[Federation API]
  auth[Auth]
  clients --> ingress --> gw --> nats
  nats --> cs
  nats --> ss
  nats --> auth

Path	Where it goes
/.well-known/matrix/client, /.well-known/matrix/server	Gateway, locally
GET /	302 to Element Web (chat.<serverName>)
/_matrix/client/… login, logout, refresh	HTTP reverse-proxy to MAS (compat)
/_matrix/client/… (rest)	NATS → Client API
/_matrix/federation/…, /_matrix/key/…	NATS → Federation API
/_synapse/admin/…	NATS → Client API
/_synapse/mas/…	NATS → Auth

Auth is not a public HTTP API. The gateway and peers call it over NATS (matrix.internal.auth.*).

Satellite hostnames do not go through the gateway app. They are separate ingress routes:

Host	Target
account.<serverName>	Matrix Authentication Service
chat.<serverName>	Element Web
admin.<serverName>	Element Admin
mrtc.<serverName>	Matrix RTC authorisation and LiveKit SFU

See DNS and hostnames and Ingress.

First-party services

Component	Pod	Role
Gateway	vesicle-gateway	Public entry for client-server and federation HTTP, well-known, and root redirect to Element Web
Client API	vesicle-client-api	Matrix client-server API and related persistence
Federation API	vesicle-fed-api	Server-server federation
Auth	vesicle-auth	Authentication integration with Matrix Authentication Service

Platform

Component	Pod	Role
Matrix Authentication Service (MAS)	vesicle-matrix-authentication-service	OIDC / account flows (account.<serverName>)
PostgreSQL	vesicle-postgresql	Databases for client-api, federation, and MAS
NATS	vesicle-nats	Messaging between first-party services

vesicle-nats-box is a NATS utility sidecar from the NATS chart, not a Vesicle microservice.

User-facing add-ons

These are optional in chart values and enabled in a typical full install:

Component	Pod	Role
Element Web	vesicle-element-web	Matrix client (chat.<serverName>)
Element Admin	vesicle-element-admin	Admin console (admin.<serverName>)
Matrix RTC	vesicle-matrix-rtc-authorisation, vesicle-matrix-rtc-sfu	lk-jwt-service plus LiveKit SFU (mrtc.<serverName>)

What a full install looks like

A typical Helm install in the vesicle namespace looks like this. Replica counts for the four first-party services default to 2.

flowchart TB
  subgraph firstParty [First-party services]
    gw2[Gateway x2]
    cs2[Client API x2]
    ss2[Federation API x2]
    auth2[Auth x2]
  end
  subgraph platform [Platform]
    mas[MAS]
    pg[PostgreSQL]
    nats2[NATS]
  end
  subgraph addons [Optional add-ons]
    ew[Element Web]
    ea[Element Admin]
    rtc[Matrix RTC]
  end
  gw2 --> nats2
  nats2 --> cs2
  nats2 --> ss2
  nats2 --> auth2
  cs2 --> pg
  ss2 --> pg
  auth2 --> mas
  mas --> pg

Example kubectl output after a full install (pod hashes will differ):

kubectl -n vesicle get pods
NAME                                           READY   STATUS    RESTARTS   AGE
vesicle-auth-…                                 1/1     Running   0          …
vesicle-auth-…                                 1/1     Running   0          …
vesicle-client-api-…                           1/1     Running   0          …
vesicle-client-api-…                           1/1     Running   0          …
vesicle-element-admin-…                        1/1     Running   0          …
vesicle-element-web-…                          1/1     Running   0          …
vesicle-fed-api-…                              1/1     Running   0          …
vesicle-fed-api-…                              1/1     Running   0          …
vesicle-gateway-…                              1/1     Running   0          …
vesicle-gateway-…                              1/1     Running   0          …
vesicle-matrix-authentication-service-…        1/1     Running   0          …
vesicle-matrix-rtc-authorisation-…             1/1     Running   0          …
vesicle-matrix-rtc-sfu-…                       1/1     Running   0          …
vesicle-nats-0                                 2/2     Running   0          …
vesicle-nats-box-…                             1/1     Running   0          …
vesicle-postgresql-0                           1/1     Running   0          …

See Install with Helm for the install path that produces this layout.

Independent scaling

Each first-party service is its own Kubernetes Deployment with replicaCount (default 2) and a PodDisruptionBudget (minAvailable: 1). They share NATS (queue groups) and PostgreSQL, so you scale:

Service	Scale when
Gateway	Ingress concurrency / HTTP edge load
Client API	Client-server API, sync, and room load
Federation API	Server-server federation traffic
Auth	Token verification and MAS integration load

Platform pieces (PostgreSQL, NATS, MAS) and add-ons (Element Web/Admin, Matrix RTC) have their own replica knobs. They are not part of the four-service product plane.