# Design: Matrix-Native MusicLink Routing

## Goal
Make MusicLink a native Matrix bot that listens to multiple rooms and replies in the **same room** that originated the message. This removes Matterbridge from the routing path and eliminates cross-room fan-out.

## Background
Current deployment uses Matterbridge as an API gateway. When multiple Matrix rooms are configured in a single Matterbridge gateway, messages fan out to other rooms. This causes unintended cross-posting (including DM leakage) when MusicLink is enabled in more than one room.

## Objectives
- **Correct routing:** Replies must go back to the originating room (and thread when applicable).
- **Multi-room support:** One MusicLink instance can monitor multiple Matrix rooms.
- **No fan-out bus:** Remove Matterbridge dependency for routing.
- **Minimal operational complexity:** Single service, single config, single token.

## Non-Goals
- Replacing mautrix-slack (Slack ↔ Matrix bridge remains).
- Adding new link providers beyond current MusicLink behavior.

## High-Level Architecture

```
Slack Room
  -> mautrix-slack (Matrix portal room)
  -> MusicLink (Matrix-native bot)
  -> same Matrix portal room (reply)
  -> mautrix-slack -> Slack thread
```

## Proposed Implementation

### 1) Matrix Client
Use a Matrix SDK (mautrix-go or matrix-nio) to:
- Login using a bot token (or access token from config).
- Sync events from configured rooms.
- Ignore messages from the bot itself.
- Post replies to the same room.

### 2) Room Configuration
Extend config with explicit room allowlist:

```toml
[matrix]
server = "https://clarun.xyz"
accessToken = "..."
userId = "@musiclink:clarun.xyz"
rooms = [
  "!DPQveBnfuDrbgOe6dm:clarun.xyz",
  "!dT40EUcemb8e6bPiig:clarun.xyz"
]
```

### 3) Threading Support
If the incoming event references a thread (e.g., `m.relates_to` with `rel_type=m.thread`), reply into that thread; otherwise post a standard room message.

### 4) Message Handling
- Parse message body for supported music links.
- Call `idonthavespotify` (existing behavior).
- Post formatted reply in the same room.

### 5) Loop Prevention
- Ignore events from `@musiclink`.
- Optionally ignore events without link matches.
- Add a small delay/backoff on rate limit responses.

## Migration Plan
1. **Add Matrix client support behind a feature flag** (e.g., `matrix.enabled`).
2. **Deploy in parallel with Matterbridge** to validate routing and threading.
3. **Disable Matterbridge** once Matrix-native mode is verified.

## Risks
- Matrix SDK differences in threading or formatting.
- Token handling and access permissions for the bot user.
- Message deduplication and race conditions in sync processing.

## Open Questions
- Which Matrix SDK should we standardize on (mautrix-go vs matrix-nio)?
- Do we need explicit thread support in Slack via mautrix-slack mapping?
- Should we persist a small state store for sync tokens?

## Appendix: Why Not Multiple Gateways?
Multiple gateways in Matterbridge solve cross-posting, but still rely on the fan-out bus model and add operational overhead. A Matrix-native bot is simpler and more correct for routing semantics.