matrix/matrixbot

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

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

Server - Auth & SSO

• Token-based registration (registration tokens shared in Discord)
• SSO/OIDC via Authelia (oidc_providers in homeserver.yaml)
• allow_existing_users: true for linking existing accounts to SSO
• Password auth remains enabled alongside SSO

Server - Hardening

• Rate limiting configuration in Synapse
• 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

• Synapse admin API dashboard (synapse-admin v0.11.1 at http://10.10.10.29:8080)
• Power levels configured per room (Cinny tags for role hierarchy)
• 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

• Set up "The Lotus Guild" space as top-level container
• General, Welcome, Commands, Management, Memes, Cool Kids rooms
• Welcome room with react-to-join onboarding
• Bot commands room (Commands — keeps bot spam contained)
• Voice/video call room (Element Call via LiveKit)
• 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

• 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

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

Bot - Commands (all implemented)

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

Bot - Integrations

• !minecraft <username> — RCON whitelist
• !ask <question> — Ollama LLM integration (lotusllm, 2min cooldown)

Bot - Admin Commands

• !health — Bot stats (uptime, command counts, service status)

Bot - Welcome System

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

Bot - Wordle

• Daily puzzles with proper two-pass letter evaluation
• Hard mode with constraint validation
• Statistics tracking with persistence (wordle_stats.json)
• Cinny-compatible rendering (inline <span> tiles instead of <table>)
• DM-based gameplay (games happen in DMs, !wordle share posts to public room)
• 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