# xataio/xata architecture

> Architecture diagram of the GitHub repository xataio/xata, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xataio/xata
- Repository: https://github.com/xataio/xata

## Overview

Xata is a Kubernetes-based Postgres-as-a-Service platform centered on creating and managing projects and database branches. The control-plane API authenticates users and provisions branches; the branch operator manages their Kubernetes resources, while the SQL gateway routes client connections and can wake scaled-to-zero branches. The README also documents branching, backups, high availability, and serverless SQL. Connections below rely mainly on README-level architecture statements; sampled implementation confirms API routing and serverless entry points, but not most cross-service wiring.

Main entry points: [`services/gateway/serverless/server.go`](https://github.com/xataio/xata/blob/main/services/gateway/serverless/server.go) (HTTP / WebSocket SQL), [`services/projects/api/handler.go`](https://github.com/xataio/xata/blob/main/services/projects/api/handler.go) (Projects REST API), [`services/projects/projects.go`](https://github.com/xataio/xata/blob/main/services/projects/projects.go) (Projects service), [`services/branch-operator/pkg/reconciler/reconciler.go`](https://github.com/xataio/xata/blob/main/services/branch-operator/pkg/reconciler/reconciler.go) (Branch operator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Control plane"]
  node_projects_api["Projects REST API<br/>[handler.go]"]
  node_projects["Projects service<br/>[projects.go]"]
  node_project_store[("Project store<br/>[store_sql.go]")]
  node_clusters["Clusters service<br/>[clusters.go]"]
end

subgraph group_provision["Branch lifecycle"]
  node_branch_operator["Branch operator<br/>[reconciler.go]"]
  node_postgres[("Postgres branches")]
  node_sidecar["Scale-to-zero sidecar<br/>[sidecar.go]"]
end

subgraph group_connect["SQL connectivity"]
  node_gateway["SQL gateway<br/>[gateway.go]"]
  node_serverless["HTTP / WebSocket SQL<br/>[server.go]"]
  node_session["Branch sessions<br/>[session.go]"]
end

subgraph group_identity["Identity and access"]
  node_auth_api["Auth REST API<br/>[handler.go]"]
  node_auth["Auth service<br/>[auth.go]"]
end

node_user(("Platform user"))
node_cli["Xata CLI"]
node_keycloak["Keycloak"]
node_kubernetes["Kubernetes"]
node_cnpg["CloudNativePG"]
node_object_store[("Backup object storage")]

node_user -->|"manages via"| node_cli
node_cli -->|"calls REST"| node_projects_api
node_projects_api -.->|"handles requests"| node_projects
node_projects -.->|"persists projects"| node_project_store
node_projects -.->|"provisions branches"| node_clusters
node_user -->|"authenticates"| node_auth_api
node_auth_api -.->|"handles identity"| node_auth
node_auth -->|"uses identity provider"| node_keycloak
node_projects_api -.->|"requires API authentication"| node_auth
node_clusters -.->|"requests branch management"| node_branch_operator
node_branch_operator -->|"manages resources"| node_kubernetes
node_kubernetes -->|"runs database operator"| node_cnpg
node_cnpg -->|"operates instances"| node_postgres
node_branch_operator -.->|"manages backup resources"| node_object_store
node_user -->|"sends SQL"| node_serverless
node_gateway -->|"serves SQL transport"| node_serverless
node_serverless -->|"resolves connections"| node_session
node_session -.->|"routes database traffic"| node_postgres
node_serverless -.->|"wakes inactive branch"| node_sidecar
node_sidecar -.->|"scales branch resources"| node_kubernetes

click node_projects_api "https://github.com/xataio/xata/blob/main/services/projects/api/handler.go"
click node_projects "https://github.com/xataio/xata/blob/main/services/projects/projects.go"
click node_project_store "https://github.com/xataio/xata/blob/main/services/projects/store/sqlstore/store_sql.go"
click node_clusters "https://github.com/xataio/xata/blob/main/services/clusters/clusters.go"
click node_auth_api "https://github.com/xataio/xata/blob/main/services/auth/api/handler.go"
click node_auth "https://github.com/xataio/xata/blob/main/services/auth/auth.go"
click node_branch_operator "https://github.com/xataio/xata/blob/main/services/branch-operator/pkg/reconciler/reconciler.go"
click node_gateway "https://github.com/xataio/xata/blob/main/services/gateway/gateway.go"
click node_serverless "https://github.com/xataio/xata/blob/main/services/gateway/serverless/server.go"
click node_session "https://github.com/xataio/xata/blob/main/services/gateway/session/session.go"
click node_sidecar "https://github.com/xataio/xata/blob/main/services/scale-to-zero-sidecar/internal/sidecar/sidecar.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_projects_api,node_projects,node_project_store,node_clusters,node_user toneBlue
class node_branch_operator,node_postgres,node_sidecar,node_object_store toneAmber
class node_gateway,node_serverless,node_session toneMint
class node_auth_api,node_auth toneRose
class node_cli,node_keycloak,node_kubernetes,node_cnpg toneIndigo
```

## Components

### Control plane

- [Projects REST API](https://github.com/xataio/xata/blob/main/services/projects/api/handler.go): `services/projects/api/handler.go`
- [Projects service](https://github.com/xataio/xata/blob/main/services/projects/projects.go): `services/projects/projects.go`
- [Project store](https://github.com/xataio/xata/blob/main/services/projects/store/sqlstore/store_sql.go): `services/projects/store/sqlstore/store_sql.go`
- [Clusters service](https://github.com/xataio/xata/blob/main/services/clusters/clusters.go): `services/clusters/clusters.go`

### Branch lifecycle

- [Branch operator](https://github.com/xataio/xata/blob/main/services/branch-operator/pkg/reconciler/reconciler.go): `services/branch-operator/pkg/reconciler/reconciler.go`
- **Postgres branches**
- [Scale-to-zero sidecar](https://github.com/xataio/xata/blob/main/services/scale-to-zero-sidecar/internal/sidecar/sidecar.go): `services/scale-to-zero-sidecar/internal/sidecar/sidecar.go`

### SQL connectivity

- [SQL gateway](https://github.com/xataio/xata/blob/main/services/gateway/gateway.go): `services/gateway/gateway.go`
- [HTTP / WebSocket SQL](https://github.com/xataio/xata/blob/main/services/gateway/serverless/server.go): `services/gateway/serverless/server.go`
- [Branch sessions](https://github.com/xataio/xata/blob/main/services/gateway/session/session.go): `services/gateway/session/session.go`

### Identity and access

- [Auth REST API](https://github.com/xataio/xata/blob/main/services/auth/api/handler.go): `services/auth/api/handler.go`
- [Auth service](https://github.com/xataio/xata/blob/main/services/auth/auth.go): `services/auth/auth.go`

### Other components

- **Platform user**
- **Xata CLI**
- **Keycloak**
- **Kubernetes**
- **CloudNativePG**
- **Backup object storage**

## Connections

- Platform user → Xata CLI: manages via
- Xata CLI → Projects REST API: calls REST
- Projects REST API → Projects service: handles requests
- Projects service → Project store: persists projects
- Projects service → Clusters service: provisions branches
- Platform user → Auth REST API: authenticates
- Auth REST API → Auth service: handles identity
- Auth service → Keycloak: uses identity provider
- Projects REST API → Auth service: requires API authentication
- Clusters service → Branch operator: requests branch management
- Branch operator → Kubernetes: manages resources
- Kubernetes → CloudNativePG: runs database operator
- CloudNativePG → Postgres branches: operates instances
- Branch operator → Backup object storage: manages backup resources
- Platform user → HTTP / WebSocket SQL: sends SQL
- SQL gateway → HTTP / WebSocket SQL: serves SQL transport
- HTTP / WebSocket SQL → Branch sessions: resolves connections (evidence: `services/gateway/serverless/server.go`)
- Branch sessions → Postgres branches: routes database traffic
- HTTP / WebSocket SQL → Scale-to-zero sidecar: wakes inactive branch
- Scale-to-zero sidecar → Kubernetes: scales branch resources