Skip to main content
The atl.chat bridge is a Python application that connects Discord, IRC, and XMPP into a unified message bus. Each protocol is implemented as an independent adapter that emits and consumes normalised internal events.

​
Architecture

Discord Adapter  ←→  Internal Event Bus  ←→  IRC Adapter
                             ↕
                       XMPP Adapter
The event bus decouples adapters from each other: a message arriving on Discord is converted to an internal event and forwarded to IRC and XMPP adapters, which translate it into their respective protocol messages.

​
Technology

ComponentLibrary
Discord adapterdiscord.py
IRC adapterpydle
XMPP adapterslixmpp
Entry pointapps/bridge/src/bridge/__main__.py

​
Configuration schema

The bridge reads its configuration from apps/bridge/config.yaml, generated at init time from apps/bridge/config.template.yaml via envsubst. Sensitive values (tokens, passwords) come from environment variables defined in .env. The Config class in src/bridge/config/schema.py provides typed property access with defaults and environment variable overrides.

​
Channel mappings

The mappings list connects a Discord channel ID to an IRC channel and/or an XMPP MUC room JID. Each entry requires a discord_channel_id and optional irc and xmpp blocks: 
mappings:
  - discord_channel_id: "123456789012345678"
    irc:
      server: irc.example.com
      port: 6697
      tls: true
      channel: "#general"
    xmpp:
      muc_jid: general@muc.xmpp.example.com
Validation runs on load and on SIGHUP reload — every mapping must be a dict with a non-empty discord_channel_id.

​
Relay toggles

KeyTypeDefaultDescription
announce_joins_and_quitsbooltrueRelay join/part/quit events to other protocols
announce_extrasboolfalseRelay topic and mode changes
content_filter_regexlist[]Messages matching any regex pattern are not bridged

​
Identity and caching

KeyTypeDefaultDescription
identity_cache_ttl_secondsint3600TTL for Portal identity cache
avatar_cache_ttl_secondsint86400TTL for avatar URL cache
xmpp_avatar_base_urlstring—Base URL for XMPP avatar HEAD checks (use internal Docker hostname)

​
IRC adapter settings

KeyTypeDefaultDescription
irc_puppet_idle_timeout_hoursint24Disconnect idle puppet connections after this many hours
irc_puppet_ping_intervalint120Keep-alive PING interval in seconds
irc_puppet_prejoin_commandslist[]Commands sent after puppet connects (supports {nick} placeholder)
irc_puppet_postfixstring""Suffix appended to puppet nicknames
irc_throttle_limitint10IRC messages per second (token bucket)
irc_message_queueint30Maximum IRC outbound queue size
irc_rejoin_delayfloat5Seconds before rejoin after KICK or disconnect
irc_auto_rejoinbooltrueAuto-rejoin channels after KICK or disconnect

​
IRC TLS and authentication

KeyTypeDefaultDescription
irc_tls_verifybooltrueVerify IRC TLS certificates. Overridden by BRIDGE_IRC_TLS_VERIFY env var
irc_use_saslboolfalseUse SASL PLAIN for IRC authentication
irc_sasl_userstring""SASL username
irc_sasl_passwordstring""SASL password

​
IRC protocol features

KeyTypeDefaultDescription
irc_relaymsg_clean_nicksboolfalseUse /d suffix for RELAYMSG. Enable only if UnrealIRCd has allow-clean-nicks yes
irc_redact_enabledboolfalseSend REDACT when a Discord message is deleted. Disabled by default due to a known UnrealIRCd third/redact crash (exit 139)

​
Environment variable overrides

Several config keys can be overridden at runtime via environment variables without editing config.yaml:
Environment variableOverridesNotes
BRIDGE_IRC_TLS_VERIFYirc_tls_verifytrue/false
BRIDGE_IRC_REDACT_ENABLEDirc_redact_enabledtrue/false
BRIDGE_RELAYMSG_CLEAN_NICKSirc_relaymsg_clean_nickstrue/false

​
Config reload

The bridge supports live config reload via SIGHUP. On reload, the YAML file is re-read, env overrides are re-loaded, and validation runs. A ConfigReload event is dispatched to all adapters. 
# Reload config without restarting the container
docker kill --signal=SIGHUP atl-bridge