OpenFlare/docs/superpowers/specs/2026-08-16-message-gateway-design.md

# Message Gateway Design (Wavelet)

**Date:** 2026-08-16  
**Status:** Approved for implementation planning  
**Scope:** Wavelet framework only (sub-project 1 of 3)  
**Product:** Wavelet scaffold — reusable inbound/outbound messaging channels

## 1. Goal

Give Wavelet a Hermes-style **message gateway**: admins configure Telegram and QQ bots in the admin UI; end users bind their private-chat identity with a one-time short code on the profile page. Inbound private messages become **domain events**. Products (Clipper later) subscribe and decide what to persist.

This spec does **not** write Clipper `c_items`. That is sub-project 3 after Wavelet is merged into Clipper.

### In scope (Wavelet)

- `pkg/message_gateway` + `channel/telegram` + `channel/qq`
- Admin UI `/admin/message-gateway` (empty state, add channel, per-type forms, cards)
- User profile card: bind / list / unbind
- Worker-hosted connections (Telegram long poll, QQ official WebSocket)
- Pairing codes, bindings, encrypted credentials
- Domain event on authorized inbound messages
- Text + image + file inbound/outbound at the adapter layer (v1 private chat only)

### Out of scope

- Group / guild / channel / @mention routing
- Hermes sessions, slash commands, STT, cron, circuit-breaker fleet, 20 platforms
- Telegram webhook mode (long poll only)
- Writing business tables (`c_*`) or calling `upload.Ingest` from `pkg/`
- Changing `pkg/push` (outbound notification remains a separate system)
- Multi-tenant hosted bots (`owner_scope=user`) — column exists, v1 only inserts `system`

### Later sub-projects (not this spec)

2. Clipper `git fetch upstream && git merge upstream/main`
3. Clipper listener: inbound event → `upload.Ingest` + `c_items` with `source=telegram|qq`

## 2. Decisions (locked)

| Topic | Choice |
|---|---|
| Ownership | Instance-level shared bots; users pair to them |
| Pairing | 8-char one-time code, 15 minutes, consumed on success |
| Profile | Show bound platform user ID; user can unbind |
| Surface | Private chat / C2C only; groups ignored + logged |
| Runtime | Worker process starts the gateway; API does not poll |
| Events | Bound inbound → `internal/listener` domain event |
| Telegram SDK | `gopkg.in/telebot.v4` (tucnak/telebot current module) |
| QQ SDK | Official QQ Bot Go SDK (`botgo` / [docs](https://bot.q.qq.com/wiki/develop/gosdk/)) |
| Hermes | Adapter shape only (`Connect`/`Disconnect`/`Send`/inbound event/capabilities) |

## 3. Architecture

```
Admin UI ──CRUD──► API ──w_message_channels──► Worker Gateway
                                                      │
User DM ──telebot / botgo──► Channel adapter ─────────┤
                                                      ▼
                                         unbound? mint pairing code, reply
                                         bound?   emit InboundMessage event
                                                      │
User profile ──bind/unbind──► API ──w_message_bindings / pairing_codes
                                                      │
                                         product listener (Clipper later)
```

`pkg/message_gateway` has **no** Gin, GORM, sessions, or `internal/apps` imports. Persistence lives in `internal/repository`. Encryption of credentials uses existing Wavelet secret helpers from apps/repository, not from `pkg`.

### 3.1 Packages

```
pkg/message_gateway/
  types.go          # Message, Attachment, Capability, ChannelType
  channel.go        # Channel interface
  registry.go       # Register / Lookup
  pairing.go        # GenerateCode (alphabet, length) — no storage
  channel/telegram/ # telebot private chat
  channel/qq/       # official botgo C2C
internal/apps/admin/message_gateway/
internal/apps/message_gateway/   # user bind/unbind
internal/listener/               # InboundMessage event type + dispatch
internal/model/                  # channel, binding, pairing row types
internal/repository/             # CRUD
```

Frontend:

```
frontend/lib/services/message-gateway/
frontend/app/(main)/admin/message-gateway/
  page.tsx
  components/channel-card.tsx
  components/add-channel-dialog.tsx
  channels/telegram/form.tsx
  channels/qq/form.tsx
frontend/components/common/settings/   # profile bind card
```

Sidebar admin item: `titleKey: 'messageGateway'`, url `/admin/message-gateway`, placed next to push.

### 3.2 Channel interface

```go
type Channel interface {
    Type() string
    Connect(ctx context.Context) error
    Disconnect(ctx context.Context) error
    Send(ctx context.Context, to Recipient, msg OutboundMessage) error
    Capabilities() Capability
}

type Capability struct {
    Text, Image, File, Reply bool
    Group bool // always false in v1 adapters
}

type InboundMessage struct {
    ChannelID      uint64
    ChannelType    string
    PlatformUserID string
    ChatID         string
    MessageID      string
    Text           string
    Attachments    []Attachment // local temp paths + mime; no upload package
    BindingUserID  *uint64      // nil if unbound
}

type Handler func(ctx context.Context, msg InboundMessage) error
```

Gateway runner (Worker) constructs adapters from DB rows, calls `Connect`, and registers one `Handler` that implements pairing + event emit.

### 3.3 Process model

- `internal/cmd` Worker path: after bootstrap, `messagegateway.Start(ctx)`.
- API process never starts adapters.
- Enable / disable / credential change: Worker watches DB (poll every few seconds or Redis pub/sub already used by the platform). v1 may poll `updated_at` every 5s. Hot-reload only the changed channel.
- Single Worker assumed. If a second Worker starts, it tries a Redis/DB lock keyed by `channel_id` + token fingerprint; failure → skip that channel and log.
- Per-channel reconnect with exponential backoff; one channel crash must not stop others.

## 4. Data model

All tables `w_*`. Dual goose SQL (Postgres + SQLite). No physical FKs.

### 4.1 `w_message_channels`

| Column | Type | Notes |
|---|---|---|
| id | snowflake | PK |
| name | string | admin display name |
| type | string | `telegram` \| `qq` |
| owner_scope | string | v1 always `system` |
| owner_id | bigint null | reserved; null in v1 |
| enabled | bool | |
| credentials | text | encrypted JSON; never returned raw |
| extra | text | optional JSON (base URL, sandbox host) |
| created_at, updated_at | timestamptz | |

### 4.2 `w_message_bindings`

| Column | Type | Notes |
|---|---|---|
| id | snowflake | PK |
| user_id | bigint | Wavelet user |
| channel_id | bigint | |
| platform_user_id | string | Telegram user id / QQ OpenID |
| created_at | timestamptz | |

Unique `(channel_id, platform_user_id)`. A user may bind many channels; a platform identity binds to at most one user per channel.

### 4.3 `w_message_pairing_codes`

| Column | Type | Notes |
|---|---|---|
| code | string | PK, 8 chars |
| channel_id | bigint | |
| platform_user_id | string | |
| expires_at | timestamptz | now + 15m |
| created_at | timestamptz | |

Delete row on successful bind. Expired rows ignored and cleaned by a small periodic delete (may live in the Worker loop).

**Code alphabet:** `ABCDEFGHJKLMNPQRSTUVWXYZ23456789` (no `0O1I`). Format displayed as `XXXX-XXXX`.

## 5. Pairing and profile

1. Unbound private message arrives.
2. Worker upserts a pairing row (if an unexpired code already exists for that pair, reuse it).
3. Bot replies with the code and “Settings → Profile → Bind a bot”.
4. User opens profile card, picks an **enabled** channel, submits the code.
5. API validates, inserts binding, deletes the code.
6. Profile lists bindings: channel name, type, **platform user ID**, unbind button.

Unauthorized/unbound never emit `InboundMessage` to product listeners.

## 6. Admin UI and credentials

Empty state + “Add channel”. Dialog: choose `telegram` | `qq`, then that type’s form.

| Type | Required | Optional |
|---|---|---|
| telegram | name, bot token | API base URL (default `https://api.telegram.org`) |
| qq | name, App ID, App Secret | sandbox / portal host (default `q.qq.com`) |

Cards: name, type, enabled toggle, connected/disconnected (best-effort from Worker), edit, delete. Edit never echoes raw secrets; empty secret field means “keep current”.

Create: validate field shape, optional SDK probe (`getMe` / token), then insert. Probe failure → 400, no row.

## 7. HTTP API

Admin (admin middleware), prefix `/api/v1/admin/message-gateway`:

- `GET /channels` — list (secrets masked)
- `GET /channels/definitions` — form schema per type
- `POST /channels` — create
- `PATCH /channels/:id` — update
- `DELETE /channels/:id` — delete (cascade bindings + pairing rows in logics)
- `POST /channels/:id/test` — optional probe

User (login required), prefix `/api/v1/message-gateway`:

- `GET /bindings` — current user’s bindings
- `POST /bindings` — `{ channel_id, code }`
- `DELETE /bindings/:id` — unbind own row only

Errors via `response.Abort*`. Invalid/expired code → 400. Platform identity already bound → 409.

## 8. Inbound media and reply

Adapters accept private-chat **text, images, files**. Voice/STT is out of scope; a voice message is treated as a file attachment if the SDK delivers bytes, otherwise ignored with a log.

Attachments are written under `t.TempDir()`-equivalent process temp (`os.MkdirTemp`) and passed as filesystem paths on `InboundMessage`. The product listener (Clipper later) must `upload.Ingest` and then delete the temp file. Gateway deletes leftovers older than 1 hour.

If the product handler returns an error, the bot sends a generic “could not save your message” (no internal error text). Success ACK is a single short reply when `Capabilities().Reply` is true. ACK can be disabled later via extra JSON; v1 always ACKs.

Group / non-C2C updates: log and drop. Do not mint pairing codes.

## 9. Domain event

Name: `message_gateway.inbound` (exact string in `internal/listener`).

Payload: `InboundMessage` plus `BindingUserID` set. Register in `internal/platform/bootstrap` (no `init()`). Wavelet ships a no-op or log-only listener. Clipper will register the clip writer in sub-project 3.

## 10. Error handling

- Adapter panics: recover in the gateway runner, mark channel disconnected, backoff reconnect.
- Media download failure: keep text; attachment entry has `Error` string; still emit if bound.
- Encrypt/decrypt failure: treat channel as disabled, log, do not start adapter.
- i18n: all new UI strings in `zh-CN.json` + `en.json` (`admin.messageGateway`, `settings.botBinding`).

## 11. Testing and done criteria

| Gate | Pass |
|---|---|
| Fake channel + pairing | generate, reuse unexpired, expire, consume, conflict 409 |
| Telegram adapter unit | mock telebot updates: text, photo, document; groups dropped |
| QQ adapter unit | mock C2C event; non-C2C dropped |
| API tests | admin CRUD, bind/unbind, bad code |
| `go test ./...` | pass |
| Frontend | `pnpm tsc --noEmit --jsx preserve`, `check-i18n-keys.mjs` |
| Manual | add TG channel → DM gets code → profile bind → second DM emits event in logs |

## 12. Risks

- **Official QQ Bot** requires a published/sandbox app at q.qq.com; local dev may only test Telegram.
- **telebot v4 module path** is `gopkg.in/telebot.v4`; pin a version in `go.mod`.
- **One poller per token:** documented; second Worker skips the channel.
- **Token leak in logs:** never log raw credentials or pairing codes at info level (debug only, redacted).