matrix/matrixbot/README.md

# Lotus Matrix Bot & Server Roadmap

Matrix bot and server improvements for the Lotus Guild homeserver (`matrix.lotusguild.org`).

**Repo**: https://code.lotusguild.org/LotusGuild/matrixBot

## Status: Phase 3 — Bot Features & SSO

---

## Priority Order (suggested)
1. ~~PostgreSQL migration~~
2. ~~TURN server~~
3. ~~Room structure + space setup~~
4. ~~Matrix bot (core + commands)~~
5. ~~LiveKit / Element Call~~
6. ~~SSO / OIDC (Authelia)~~
7. Custom Element Web (chat.lotusguild.org with branding)
8. Discord bridge (lets people transition gradually)
9. Custom emoji packs (makes it feel like home)
10. Moderation bot
11. Everything else

---

## Infrastructure

| Service | Host | IP | LXC | Notes |
|---------|------|-----|-----|-------|
| Synapse | micro1 | 10.10.10.29 | 151 | Homeserver + coturn + LiveKit |
| PostgreSQL 17 | micro1 | 10.10.10.44 | 109 | Synapse database backend |
| NPM | large1 | 10.10.10.27 | 139 | Reverse proxy + landing page |
| Authelia | compute-storage-01 | 10.10.10.36 | 167 | SSO/OIDC provider |
| LLDAP | large1 | 10.10.10.39 | 147 | LDAP user directory |

**Key paths on Synapse LXC (10.10.10.29):**
- Synapse config: `/etc/matrix-synapse/homeserver.yaml`
- Synapse venv: `/opt/venvs/matrix-synapse/`
- coturn config: `/etc/turnserver.conf`
- LiveKit config: `/etc/livekit/config.yaml`
- LiveKit service: `livekit-server.service` (systemd)
- Synapse admin UI: `/var/www/synapse-admin/` (nginx on :8080)
- Landing page: `/var/www/matrix-landing/index.html` (on NPM LXC 139)

**Port forwarding (router -> 10.10.10.29):**
- TCP+UDP 3478 (TURN signaling)
- TCP 7881 (LiveKit TCP)
- UDP 49152-65535 (media relay)
- UDP 50100-50200 (LiveKit WebRTC media)

---

## Rooms (all v12)

| Room | Room ID | Join Rule | Bot In |
|------|---------|-----------|--------|
| The Lotus Guild (space) | `!gSynpxmopNrtoxeSvj` | public | — |
| General | `!wfokQ1-pE896scu_AOcCBA2s3L4qFo-PTBAFTd0WMI0` | public | no |
| Welcome | `!Y-wvNosuytqBOWampH9k-ta7bYXW7okqwBQ7PuRVBWE` | public | yes |
| Commands | `!ou56mVZQ8ZB7AhDYPmBV5_BR28WMZ4x5zwZkPCqjq1s` | restricted | yes |
| Management | `!mEvR5fe3jMmzwd-FwNygD72OY_yu8H3UP_N-57oK7MI` | invite | no |
| Memes | `!GK6v5cLEEnowIooQJv5jECfISUjADjt8aKhWv9VbG5U` | public | no |
| Cool Kids | `!R7DT3QZHG9P8QQvX6zsZYxjkKgmUucxDz_n31qNrC94` | invite | no |

**Power level roles (Cinny tags):**
- 100: Owner (jared)
- 50: The Nerdy Council (enhuynh, lonely)
- 48: Panel of Geeks
- 35: Cool Kids
- 0: Member

**Welcome room** has `events_default: 50` (users can't message) but `m.reaction: 0` (users can react to the welcome message to get invited to channels).

---

## Server - Quality of Life
- [x] Migrate from SQLite to PostgreSQL
- [x] Set up TURN/STUN server (coturn) for reliable voice/video calls behind NAT
- [x] Enable URL previews in Synapse
- [x] Increase upload size limit for media/GIFs (200MB)
- [x] Enable message search (full-text search with PostgreSQL backend)
- [x] Configure media retention policy (remote: 1yr, local: 3yr)
- [x] Set up sliding sync (native in Synapse, no proxy needed)
- [x] LiveKit server with systemd service for Element Call video rooms
- [x] Default room version set to v12, all rooms upgraded
- [x] Room publishing rules (jared + lotusbot can publish to directory)
- [ ] Enable push notifications gateway for mobile clients

## Server - Auth & SSO
- [x] Token-based registration (registration tokens shared in Discord)
- [x] SSO/OIDC via Authelia (`oidc_providers` in homeserver.yaml)
- [x] `allow_existing_users: true` for linking existing accounts to SSO
- [x] Password auth remains enabled alongside SSO

## Server - Hardening
- [x] Rate limiting configuration in Synapse
- [x] E2EE enabled on all rooms
- [ ] Federation allow/deny lists (decide if you want open federation or Lotus-only)
- [ ] Regular Synapse version updates
- [ ] Monitoring with Prometheus + Grafana
- [ ] Synapse worker mode if performance becomes an issue

## Server - Admin & Moderation
- [x] Synapse admin API dashboard (synapse-admin v0.11.1 at http://10.10.10.29:8080)
- [x] Power levels configured per room (Cinny tags for role hierarchy)
- [x] Invite-only registration flow (token-based)
- [ ] Set up Mjolnir or Draupnir (moderation bot for ban lists, spam protection)
- [ ] Set up room ACLs for federation control (block known-bad servers)
- [ ] Automated backups of Synapse database and media

## Bridging (Transition Period)
- [ ] Set up mautrix-discord bridge so messages flow between Discord and Matrix
- [ ] Bridge key channels (general, gaming, memes, etc.)
- [ ] Bridge voice channels if possible (experimental, may not be worth it)
- [ ] Puppet bridging so Discord users appear as Matrix users and vice versa

## Room Structure
- [x] Set up "The Lotus Guild" space as top-level container
- [x] General, Welcome, Commands, Management, Memes, Cool Kids rooms
- [x] Welcome room with react-to-join onboarding
- [x] Bot commands room (Commands — keeps bot spam contained)
- [x] Voice/video call room (Element Call via LiveKit)
- [x] Custom room avatars with Lotus Guild branding
- [ ] Sub-spaces for categories (Gaming, Media, etc.)
- [ ] Read-only announcements room
- [ ] Game-specific rooms (Minecraft, Valorant, League, Hytale, etc.)

## Custom Emoji & Stickers
- [ ] Export all custom emojis from Discord server
- [ ] Create Matrix emoji packs (per-room or space-wide)
- [ ] Set up sticker picker widget in Element
- [ ] Import/create Lotus Guild sticker pack

## Element/Client Customization
- [x] Landing page at matrix.lotusguild.org with client recommendations (Cinny, Commet, Element)
- [ ] Custom Element Web instance (self-hosted on chat.lotusguild.org)
- [ ] Custom theme with #980000 branding
- [ ] Configure .well-known to point clients to custom Element Web instance

## Widgets & Integrations
- [ ] RSS bot for game news feeds
- [ ] GitHub/Gitea notifications bot (push events to a dev room)

---

## Bot - Core Setup
- [x] Project scaffolding (`bot.py`, config, `.env`, requirements)
- [x] matrix-nio async client with E2EE support
- [x] Device verification / trust storage (auto-trust all devices)
- [x] Logging (rotating file + stdout)
- [x] Config validation (homeserver URL, access token, device ID)
- [x] Graceful shutdown handling (SIGTERM/SIGINT)
- [x] Initial sync with startup token (ignores old messages)
- [x] Auto-accept room invites

## Bot - Commands (all implemented)
- [x] `!help` — List all available commands
- [x] `!ping` — Bot latency check
- [x] `!8ball <question>` — Magic 8-ball
- [x] `!fortune` — Fortune cookie message
- [x] `!flip` — Coin flip
- [x] `!roll <NdS>` — Dice roller
- [x] `!random <min> <max>` — Random number generator
- [x] `!rps <choice>` — Rock Paper Scissors
- [x] `!poll <question>` — Poll (reactions)
- [x] `!trivia` — Trivia game (reactions, 30s reveal)
- [x] `!champion [lane]` — Random LoL champion picker
- [x] `!agent [role]` — Random Valorant agent picker
- [x] `!wordle` — Full Wordle game (daily puzzles, hard mode, stats, share)

## Bot - Integrations
- [x] `!minecraft <username>` — RCON whitelist
- [x] `!ask <question>` — Ollama LLM integration (lotusllm, 2min cooldown)

## Bot - Admin Commands
- [x] `!health` — Bot stats (uptime, command counts, service status)

## Bot - Welcome System
- [x] Auto-post welcome message in Welcome room on startup
- [x] React-to-join: users react with checkmark, bot invites to General, Commands, Memes
- [x] Welcome message event ID persisted to `welcome_state.json`
- [x] Reaction handler via `UnknownEvent` callback for `m.reaction` events

## Bot - Wordle
- [x] Daily puzzles with proper two-pass letter evaluation
- [x] Hard mode with constraint validation
- [x] Statistics tracking with persistence (`wordle_stats.json`)
- [x] Cinny-compatible rendering (inline `<span>` tiles instead of `<table>`)
- [x] DM-based gameplay (games happen in DMs, `!wordle share` posts to public room)
- [x] Virtual keyboard display with letter state tracking

## Bot - Deployment
- [ ] Systemd service (`matrixbot.service`)
- [ ] Auto-deploy from Gitea webhook
- [ ] Deployment script
- **Bot lives in**: Welcome (react-to-join) and Commands (all commands)

## Bot - Not Porting (Discord-specific)
- Reaction roles (replaced by react-to-join in Welcome room)
- Status cycling (Matrix presence is simpler)
- Guild-specific event handlers (channel create/delete, boost, etc.)

---

## Tech Stack
- **Language**: Python 3
- **Library**: matrix-nio (with E2EE)
- **Homeserver**: matrix.lotusguild.org (Synapse on 10.10.10.29)
- **Database**: PostgreSQL 17 on 10.10.10.44
- **TURN**: coturn on 10.10.10.29 (colocated with Synapse)
- **LiveKit**: livekit-server on 10.10.10.29 (systemd, public IP 162.192.14.139)
- **SSO**: Authelia on 10.10.10.36 (OIDC provider, backed by LLDAP)
- **Dependencies**: matrix-nio[e2ee], aiohttp, python-dotenv, mcrcon

## Bot Files
```
matrixBot/
├── bot.py              # Entry point, client setup, event callbacks
├── callbacks.py        # Message + reaction event handlers
├── commands.py         # Command registry + all command implementations
├── config.py           # Environment config + validation
├── utils.py            # send_text, send_html, send_reaction, get_or_create_dm
├── welcome.py          # Welcome message + react-to-join logic
├── wordle.py           # Full Wordle game engine
├── wordlist_answers.py # Wordle answer word list
├── wordlist_valid.py   # Wordle valid guess word list
├── .env.example        # Environment template
└── requirements.txt    # Python dependencies
```