# element-hq/synapse architecture

> Architecture diagram of the GitHub repository element-hq/synapse, 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/element-hq/synapse
- Repository: https://github.com/element-hq/synapse

## Overview

Synapse is a Matrix homeserver: it serves client and administrative APIs, manages room events and user activity, federates with other homeservers, and persists server state. The tree shows distinct API, event/handler, federation, media, push, and storage subsystems, with worker processes supporting deployment across instances. The excerpts confirm homeserver setup and typing-state behavior; the source index provides additional import evidence. Many runtime connections are not shown, so the graph omits uncertain links rather than inferring a complete request pipeline.

Main entry points: [`synapse/server.py`](https://github.com/element-hq/synapse/blob/develop/synapse/server.py) (Homeserver), [`synapse/federation/federation_client.py`](https://github.com/element-hq/synapse/blob/develop/synapse/federation/federation_client.py) (Federation client), [`synapse/rest/client`](https://github.com/element-hq/synapse/tree/develop/synapse/rest/client) (Client API), [`synapse/handlers/typing.py`](https://github.com/element-hq/synapse/blob/develop/synapse/handlers/typing.py) (Typing state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP APIs"]
  node_client_api["Client API"]
  node_admin_api["Admin API"]
  node_http_server["HTTP server<br/>[server.py]"]
end

subgraph group_domain["Rooms and Users"]
  node_event_builder["Event builder<br/>[builder.py]"]
  node_room_versions["Room versions<br/>[room_versions.py]"]
  node_typing["Typing state<br/>[typing.py]"]
  node_sync["Sync handlers<br/>[sync.py]"]
end

subgraph group_federation["Federation"]
  node_federation_client["Federation client"]
  node_federation_transport["Federation transport<br/>[client.py]"]
  node_transaction_manager["Outbound transactions"]
end

subgraph group_storage["Persistence and Runtime"]
  node_homeserver["Homeserver<br/>[server.py]"]
  node_configuration["Configuration<br/>[homeserver.py]"]
  node_event_store[("Event storage<br/>[events_worker.py]")]
  node_database[("Database layer<br/>[database.py]")]
  node_replication["Worker replication<br/>[handler.py]"]
  node_logging_context["Logging context<br/>[context.py]"]
  node_tracing["Tracing<br/>[opentracing.py]"]
  node_metrics["Metrics<br/>[__init__.py]"]
end

subgraph group_capabilities["Media and Notifications"]
  node_media_api["Media API"]
  node_media_storage["Media storage<br/>[media_storage.py]"]
  node_push["Push notifications"]
end

node_clients(("Matrix clients"))

node_clients -.->|"sends requests"| node_client_api
node_client_api -.->|"uses HTTP"| node_http_server
node_homeserver -->|"uses config"| node_configuration
node_homeserver -->|"sets up stores"| node_database
node_event_store -->|"uses database"| node_database
node_federation_client -->|"uses transport"| node_federation_transport
node_transaction_manager -->|"uses client"| node_federation_client
node_media_storage -.->|"supports media"| node_media_api
node_homeserver -->|"provides builder"| node_event_builder
node_federation_client -->|"uses builder"| node_event_builder
node_homeserver -->|"provides services"| node_typing
node_typing -.->|"reads state"| node_event_store
node_homeserver -.->|"sets up metrics"| node_metrics

click node_client_api "https://github.com/element-hq/synapse/tree/develop/synapse/rest/client"
click node_admin_api "https://github.com/element-hq/synapse/tree/develop/synapse/rest/admin"
click node_http_server "https://github.com/element-hq/synapse/blob/develop/synapse/http/server.py"
click node_homeserver "https://github.com/element-hq/synapse/blob/develop/synapse/server.py"
click node_configuration "https://github.com/element-hq/synapse/blob/develop/synapse/config/homeserver.py"
click node_event_builder "https://github.com/element-hq/synapse/blob/develop/synapse/events/builder.py"
click node_room_versions "https://github.com/element-hq/synapse/blob/develop/synapse/api/room_versions.py"
click node_typing "https://github.com/element-hq/synapse/blob/develop/synapse/handlers/typing.py"
click node_sync "https://github.com/element-hq/synapse/blob/develop/synapse/handlers/sync.py"
click node_federation_client "https://github.com/element-hq/synapse/blob/develop/synapse/federation/federation_client.py"
click node_federation_transport "https://github.com/element-hq/synapse/blob/develop/synapse/federation/transport/client.py"
click node_transaction_manager "https://github.com/element-hq/synapse/blob/develop/synapse/federation/sender/transaction_manager.py"
click node_event_store "https://github.com/element-hq/synapse/blob/develop/synapse/storage/databases/main/events_worker.py"
click node_database "https://github.com/element-hq/synapse/blob/develop/synapse/storage/database.py"
click node_replication "https://github.com/element-hq/synapse/blob/develop/synapse/replication/tcp/handler.py"
click node_media_api "https://github.com/element-hq/synapse/tree/develop/synapse/rest/media"
click node_media_storage "https://github.com/element-hq/synapse/blob/develop/synapse/media/media_storage.py"
click node_push "https://github.com/element-hq/synapse/tree/develop/synapse/push"
click node_logging_context "https://github.com/element-hq/synapse/blob/develop/synapse/logging/context.py"
click node_tracing "https://github.com/element-hq/synapse/blob/develop/synapse/logging/opentracing.py"
click node_metrics "https://github.com/element-hq/synapse/blob/develop/synapse/metrics/__init__.py"

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_client_api,node_admin_api,node_http_server,node_clients toneBlue
class node_event_builder,node_room_versions,node_typing,node_sync toneAmber
class node_federation_client,node_federation_transport,node_transaction_manager toneMint
class node_homeserver,node_configuration,node_event_store,node_database,node_replication,node_logging_context,node_tracing,node_metrics toneRose
class node_media_api,node_media_storage,node_push toneIndigo
```

## Components

### HTTP APIs

- [Client API](https://github.com/element-hq/synapse/tree/develop/synapse/rest/client): `synapse/rest/client`
- [Admin API](https://github.com/element-hq/synapse/tree/develop/synapse/rest/admin): `synapse/rest/admin`
- [HTTP server](https://github.com/element-hq/synapse/blob/develop/synapse/http/server.py): `synapse/http/server.py`

### Rooms and Users

- [Event builder](https://github.com/element-hq/synapse/blob/develop/synapse/events/builder.py): `synapse/events/builder.py`
- [Room versions](https://github.com/element-hq/synapse/blob/develop/synapse/api/room_versions.py): `synapse/api/room_versions.py`
- [Typing state](https://github.com/element-hq/synapse/blob/develop/synapse/handlers/typing.py): `synapse/handlers/typing.py`
- [Sync handlers](https://github.com/element-hq/synapse/blob/develop/synapse/handlers/sync.py): `synapse/handlers/sync.py`

### Federation

- [Federation client](https://github.com/element-hq/synapse/blob/develop/synapse/federation/federation_client.py): `synapse/federation/federation_client.py`
- [Federation transport](https://github.com/element-hq/synapse/blob/develop/synapse/federation/transport/client.py): `synapse/federation/transport/client.py`
- [Outbound transactions](https://github.com/element-hq/synapse/blob/develop/synapse/federation/sender/transaction_manager.py): `synapse/federation/sender/transaction_manager.py`

### Persistence and Runtime

- [Homeserver](https://github.com/element-hq/synapse/blob/develop/synapse/server.py): `synapse/server.py`
- [Configuration](https://github.com/element-hq/synapse/blob/develop/synapse/config/homeserver.py): `synapse/config/homeserver.py`
- [Event storage](https://github.com/element-hq/synapse/blob/develop/synapse/storage/databases/main/events_worker.py): `synapse/storage/databases/main/events_worker.py`
- [Database layer](https://github.com/element-hq/synapse/blob/develop/synapse/storage/database.py): `synapse/storage/database.py`
- [Worker replication](https://github.com/element-hq/synapse/blob/develop/synapse/replication/tcp/handler.py): `synapse/replication/tcp/handler.py`
- [Logging context](https://github.com/element-hq/synapse/blob/develop/synapse/logging/context.py): `synapse/logging/context.py`
- [Tracing](https://github.com/element-hq/synapse/blob/develop/synapse/logging/opentracing.py): `synapse/logging/opentracing.py`
- [Metrics](https://github.com/element-hq/synapse/blob/develop/synapse/metrics/__init__.py): `synapse/metrics/__init__.py`

### Media and Notifications

- [Media API](https://github.com/element-hq/synapse/tree/develop/synapse/rest/media): `synapse/rest/media`
- [Media storage](https://github.com/element-hq/synapse/blob/develop/synapse/media/media_storage.py): `synapse/media/media_storage.py`
- [Push notifications](https://github.com/element-hq/synapse/tree/develop/synapse/push): `synapse/push`

### Other components

- **Matrix clients**

## Connections

- Matrix clients → Client API: sends requests
- Client API → HTTP server: uses HTTP
- Homeserver → Configuration: uses config (evidence: `synapse/server.py`)
- Homeserver → Database layer: sets up stores (evidence: `synapse/server.py`)
- Event storage → Database layer: uses database (evidence: `synapse/storage/database.py`)
- Federation client → Federation transport: uses transport (evidence: `synapse/federation/federation_client.py`)
- Outbound transactions → Federation client: uses client (evidence: `synapse/federation/sender/transaction_manager.py`)
- Media storage → Media API: supports media (evidence: `synapse/rest/media/v1/media_storage.py`)
- Homeserver → Event builder: provides builder (evidence: `synapse/server.py`)
- Federation client → Event builder: uses builder (evidence: `synapse/federation/federation_client.py`)
- Homeserver → Typing state: provides services (evidence: `synapse/handlers/typing.py`)
- Typing state → Event storage: reads state (evidence: `synapse/storage/databases/main/events_worker.py`)
- Homeserver → Metrics: sets up metrics
