# 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 ` — Magic 8-ball - [x] `!fortune` — Fortune cookie message - [x] `!flip` — Coin flip - [x] `!roll ` — Dice roller - [x] `!random ` — Random number generator - [x] `!rps ` — Rock Paper Scissors - [x] `!poll ` — 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 ` — RCON whitelist - [x] `!ask ` — 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 `` tiles instead of ``) - [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 ```