matrix/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 1 Complete (Database + Voice/Video)

---

## Priority Order (suggested)
1. ~~PostgreSQL migration (SQLite will bottleneck everything else)~~
2. ~~TURN server (makes voice/video actually reliable)~~
3. Custom Element Web (chat.lotusguild.org with branding)
4. Discord bridge (lets people transition gradually)
5. Custom emoji packs (makes it feel like home)
6. Room structure + space setup
7. Moderation bot
8. Matrix bot
9. Everything else

---

## Infrastructure

| Service | Host | IP | LXC | Notes |
|---------|------|-----|-----|-------|
| Synapse | storage-01 | 10.10.10.29 | 151 | Homeserver + coturn |
| PostgreSQL 17 | storage-01 | 10.10.10.44 | 109 | Synapse database backend |
| NPM | large1 | 10.10.10.27 | 139 | Reverse proxy for matrix.lotusguild.org |

**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`
- SQLite backup: `/var/lib/matrix-synapse/homeserver.db`

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

---

## Server - Quality of Life
- [x] Migrate from SQLite to PostgreSQL (critical for performance at any real scale)
- [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)
- [ ] Enable push notifications gateway for mobile clients
- [ ] Configure media retention policy (auto-cleanup old remote media)
- [ ] Set up sliding sync proxy (faster room loading in Element)

## Server - Hardening
- [ ] Rate limiting configuration in Synapse
- [ ] Federation allow/deny lists (decide if you want open federation or Lotus-only)
- [ ] E2EE by default for private rooms
- [ ] Regular Synapse version updates
- [ ] Monitoring with Prometheus + Grafana (you already have both at 10.10.10.x)
- [ ] Synapse worker mode if performance becomes an issue

## Server - Admin & Moderation
- [ ] Set up Mjolnir or Draupnir (moderation bot for ban lists, spam protection)
- [ ] Configure proper power levels per room (mimic Discord role hierarchy)
- [ ] Invite-only registration flow (already have token-based registration)
- [ ] Set up room ACLs for federation control (block known-bad servers)
- [ ] Synapse admin API dashboard (synapse-admin web UI)
- [ ] 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
- [ ] Create room directory matching Discord channel layout
- [ ] Set up a Space for "Lotus Guild" as the top-level container
- [ ] Sub-spaces for categories (General, Gaming, Media, Admin, etc.)
- [ ] Welcome room with pinned onboarding instructions
- [ ] Read-only announcements room
- [ ] Audit/logging room (admin-only, for the bot)
- [ ] Off-topic / memes room
- [ ] Game-specific rooms (Minecraft, Valorant, League, Hytale, etc.)
- [ ] Bot commands room (keep bot spam contained)
- [ ] Voice/video call room

## 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
- [ ] Look into maunium/stickerpicker for a self-hosted sticker server

## Element/Client Customization
- [ ] Custom Element Web instance (self-hosted on chat.lotusguild.org)
- [ ] Custom theme with #980000 branding (Element supports custom CSS themes)
- [ ] Custom welcome/home page in Element Web
- [ ] Set default room list to show Lotus Guild space on first login
- [ ] Configure .well-known to point clients to custom Element Web instance
- [ ] Custom app name and branding in Element Web config.json

## Widgets & Integrations
- [ ] Dimension integration manager (self-hosted, replaces Scalar)
- [ ] Jitsi widget for group voice/video calls (self-hosted)
- [ ] Etherpad widget for collaborative notes
- [ ] RSS bot for game news feeds (Minecraft updates, Valorant patches, etc.)
- [ ] GitHub/Gitea notifications bot (push events to a dev room)

## Fun Stuff
- [ ] Custom room avatars with Lotus Guild branding
- [ ] Animated room banners
- [ ] Welcome bot message for new members joining the space
- [ ] Daily adjective posting (port from Discord bot)
- [ ] Game night scheduling bot/widget
- [ ] Karma/points system via bot reactions
- [ ] Custom Matrix "profile badges" via bot (similar to Discord roles showing on profile)

---

## Bot - Core Setup
- [ ] Project scaffolding (`bot.py`, config, `.env`, requirements)
- [ ] matrix-nio async client with E2EE support
- [ ] Device verification / trust storage
- [ ] Logging (rotating file + stdout, matching Discord bot pattern)
- [ ] Config validation (homeserver URL, access token, room IDs)
- [ ] Graceful shutdown and reconnection handling

## Bot - Command Porting (from Discord bot)
- [ ] `!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 (using reactions)
- [ ] `!trivia` - Trivia game (using reactions for answers)
- [ ] `!champion` - Random LoL champion picker

## Bot - Integrations
- [ ] `!minecraft <username>` - RCON whitelist (Mojang API validation + RCON)
- [ ] `!hytale <username>` - Hytale whitelist request (audit log to admin room)
- [ ] `!ask <question>` - Ollama LLM integration (lotusllm model)

## Bot - Admin Commands
- [ ] `!clear <count>` - Redact messages (requires power level)
- [ ] `!health` - Bot stats (uptime, command counts, service status)
- [ ] Power level checks (Matrix equivalent of Discord role checks)

## Bot - Audit Logging
- [ ] Member join/leave events
- [ ] Message edits and redactions
- [ ] Room state changes
- [ ] Batched audit log posting to admin room

## Bot - Deployment
- [ ] Systemd service (`matrixbot.service`)
- [ ] Auto-deploy from Gitea webhook (matching Discord bot pattern)
- [ ] Deployment script (`/usr/local/bin/matrix_bot_deploy.sh`)
- [ ] Determine host LXC (new container or colocate with Synapse on 10.10.10.29)

## Bot - Not Porting (Discord-specific)
- Reaction roles (no Matrix equivalent)
- 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)
- **Dependencies**: matrix-nio[e2ee], aiohttp, python-dotenv, mcrcon

## Production Server
- **Host**: TBD
- **Bot Directory**: TBD
- **Service**: `matrixbot.service`