Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:
Matterbridge is a multi-protocol chat bridge designed to connect various chat platforms, allowing users on different services to communicate seamlessly. It functions by relaying messages, media, and events between natively supported protocols and third-party services via a dedicated API. The system is built in Go and emphasizes flexibility through a gateway-based routing system.
The architecture centralizes message handling, where incoming data from one protocol is normalized and then dispatched to other configured protocols through defined gateways. This allows for complex bridging scenarios, such as linking IRC, Slack, and Discord into a single unified conversation stream.
Sources: README.md:1-20, contrib/api.yaml:1-5
Core Components and Message Flow
The system architecture relies on three primary abstractions: Bridges, Gateways, and the API. Bridges act as the interface to specific chat protocols (e.g., Discord, Slack, IRC), while Gateways define the routing logic between these bridge instances.
Message Pipeline
When a message is received by a native bridge, it is converted into a standardized IncomingMessage format. This message is then passed through the configured gateways to find target accounts and channels.
The diagram illustrates how messages flow from specific protocol bridges into the Gateway Router, which then distributes them to all other connected bridges.
Sources: README.md:104-143, contrib/api.yaml:61-100
API and External Integration
Matterbridge provides a read/write API that allows third-party applications to interact with the bridge. The API supports listing new messages, streaming real-time events, and posting messages back to the chat networks.
API Endpoints
| Endpoint | Method | Description |
|---|---|---|
/health | GET | Checks if the server is alive. |
/messages | GET | Lists new messages (polling). |
/stream | GET | Streams real-time messages via application/x-json-stream. |
/message | POST | Creates and sends a message to a specific gateway. |
Sources: contrib/api.yaml:12-60
Message Data Structures
The API uses standardized JSON objects to represent communication. A key component is the config.IncomingMessage, which contains the following metadata:
- username: The human-readable name of the sender.
- text: The actual content of the message.
- gateway: The specific bridge gateway the message belongs to.
- protocol: The source protocol (e.g., "slack").
- extra: A container for additional data such as base64 encoded files or platform-specific metadata.
Sources: contrib/api.yaml:62-100
Configuration and Multi-Gateway Support
The system is configured via a TOML file that defines account credentials and gateway mappings. Gateways act as the "glue," specifying which accounts and channels are linked together.
Configuration Structure
- Protocol Definitions: Setup for specific accounts (e.g.,
[irc.my-server]). - General Settings: Global behavior such as
RemoteNickFormat. - Gateway Definitions: Using
[[gateway]]blocks to map source/destination pairs.
This flow shows how the configuration file organizes accounts and their relationships within gateways.
Sources: README.md:200-245
Build and Dependency Management
Matterbridge utilizes Go's build system and leverages a variety of third-party libraries for protocol support. The project requires Go 1.18+ and supports conditional compilation via build tags.
Build Tags
To reduce binary size or memory requirements (which can reach 3GB for all bridges), specific bridges can be excluded or included during the build process:
nomsteams: Excludes Microsoft Teams support.nozulip: Excludes Zulip support.whatsappmulti: Explicitly enables WhatsApp multi-device support (beta).
Sources: README.md:158-185
Unix System Interface
For low-level operations and system calls, the project relies on golang.org/x/sys/unix. This package provides raw access to underlying OS interfaces, used for file handling and network communication across different architectures.
Sources: vendor/golang.org/x/sys/unix/README.md:1-20
Implementation Details
Message Formatting
Matterbridge supports complex message rendering, including Markdown parsing and HTML rendering through components like gomarkdown. This allows the bridge to handle extensions such as tables, fenced code blocks, and autolinks when translating between platforms that support different formatting standards.
Sources: vendor/github.com/gomarkdown/markdown/README.md:10-50, vendor/github.com/russross/blackfriday/markdown.go:20-50
Event Handling
The Discord implementation, as an example, uses an event-driven architecture where structure names like InteractionCreate map directly to gateway internal naming (INTERACTION_CREATE). This pattern is consistent across native bridges to ensure predictable event propagation.
Sources: vendor/github.com/bwmarrin/discordgo/CONTRIBUTING.md:75-85
Summary
The Matterbridge architecture is a hub-and-spoke model where the Gateway Router serves as the central hub connecting diverse chat protocol spokes. By normalizing messages into a common format and providing a robust API, it enables seamless cross-platform communication while remaining highly configurable and extensible through its native Go implementation.
Sources: README.md:1-50, contrib/api.yaml:1-10