# Design: Matrix-Native MusicLink Routing

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

## Background
Legacy deployment used Matterbridge as an API gateway. When multiple Matrix rooms were configured in a single Matterbridge gateway, messages fanned out to other rooms, causing unintended cross-posting (including DM leakage). The system is now Matrix-native.

## Objectives
- **Correct routing:** Responses go back to the originating room (no cross-room fan-out).
- **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 (follow-up message)
  -> mautrix-slack -> Slack
```

## Current Implementation

### 1) Matrix Client
- Uses mautrix-go with a bot access token.
- Syncs events from configured rooms.
- Ignores messages from the bot itself.
- Posts responses as standalone messages in the same room (no reply/thread relation).

### 2) Room Configuration
Matrix allowlist in config:

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

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

### 4) Loop Prevention
- Ignore events from `@musiclink`.
- Ignore events without link matches.
- Rate limit handling with retry/backoff.

## Risks
- Token handling and access permissions for the bot user.
- Message deduplication and race conditions in sync processing.

## Status
- Matrix-native mode implemented.
- Matterbridge routing removed.