172 lines
7.1 KiB
Plaintext
172 lines
7.1 KiB
Plaintext
Project: Lumi Bot (Discord + Twitch + YouTube) — WebUI-first management
|
||
|
||
Purpose of this file
|
||
- Single source of truth for cross‑conversation context, conventions, and packaging.
|
||
- Update when project behavior changes (routes, APIs, packaging, DB schema).
|
||
- Refer back here before making changes.
|
||
|
||
Repository layout
|
||
- Core:
|
||
- src/main.js (entry)
|
||
- src/web/server.js (WebUI + routes + wizards)
|
||
- src/services (auth, platforms, users, plugins, update-manager, etc.)
|
||
- src/web/views (EJS pages, partials/layout)
|
||
- src/web/public (styles.css, app.js)
|
||
- Plugins: plugins/<plugin-id>/ (plugin.json + index.js + optional views/)
|
||
- Data: data/app.db (SQLite), snapshots, uploads (should be excluded from updates)
|
||
- Updates output: updates/ (all update zips go here)
|
||
|
||
Platform integration (current)
|
||
- Discord, Twitch, YouTube supported; modular via src/services/platforms.js
|
||
- Wizards in /setup/*:
|
||
- /setup/discord, /setup/twitch, /setup/youtube (cancelable)
|
||
- OAuth routes in /auth/*:
|
||
- /auth/discord, /auth/twitch, /auth/youtube
|
||
- Role mapping:
|
||
- Discord roles from settings discord_admin_role_id / discord_mod_role_id (supports comma-separated)
|
||
- Twitch: broadcaster/admin/mod via tags/badges
|
||
- YouTube: chat owner/moderator flags
|
||
|
||
WebUI key routes (core)
|
||
- / (home)
|
||
- /commands, /leaderboards, /stats, /profile
|
||
- /moderator (Mods List)
|
||
- /admin
|
||
- /admin/settings
|
||
- /admin/navigation
|
||
- /admin/theming
|
||
- /admin/privileges
|
||
- /admin/logs
|
||
- /admin/updates
|
||
- /admin/commands
|
||
- /admin/pages
|
||
- /admin/users
|
||
- /admin/plugins
|
||
|
||
WebUI profile hook (core)
|
||
- web.addProfileSection({ id, label, view?, content?, role?, order?, locals? })
|
||
- view: EJS include path; content: raw HTML string
|
||
- role defaults to "public" if omitted
|
||
- In profile template, sections render under "Personalized"
|
||
- Profile view receives: user, profile, accounts + section.locals
|
||
|
||
Update system (core)
|
||
- applyBotUpdate(zipPath, { mode: "full"|"patch" })
|
||
- Full update requires: package.json, safe-mode.js, src/main.js, src/web/server.js
|
||
- Patch mode accepts any files and overlays them (no deletes)
|
||
- applyPluginUpdate(zipPath) expects plugin.json in root + entry file
|
||
- Snapshots: data/snapshots (keeps last 20 successful)
|
||
- Safe Mode: safe-mode.js supports rollback
|
||
|
||
Update packaging standards
|
||
- Always place update zips in updates/
|
||
- Core full update (default):
|
||
- Zip from repo root EXCLUDING: .git, node_modules, data, plugins, updates
|
||
- Filename: updates/lumi-update-<topic>.zip
|
||
- Core patch update:
|
||
- Zip only changed files/folders
|
||
- Use Patch Mode in UI
|
||
- Filename: updates/lumi-update-<topic>-patch.zip (or similar)
|
||
- Plugin update:
|
||
- Zip contents of plugins/<plugin-id>/ (root = plugin folder)
|
||
- Filename: updates/lumi-plugin-<plugin-id>-vX.Y.Z.zip
|
||
- Preferred zip tool on Windows:
|
||
- tar -a -c -f <zip> -C <folder> .
|
||
|
||
Command framework (core)
|
||
- commandRouter.registerCommands(pluginId, [{ id, triggers, platforms, handler }])
|
||
- Platforms enumerated by services/platforms.js
|
||
- Plugins can expose cmds.json for admin command list ingestion
|
||
- Core dynamic command: !top <category> (categories pulled from leaderboards/providers via src/services/top.js)
|
||
|
||
Database schema (core)
|
||
- data/app.db (SQLite)
|
||
- user_profiles table includes:
|
||
- internal_username (unique, NOCASE)
|
||
- username_updated_at (added for 90‑day cooldown)
|
||
- user_identities: provider/user mapping
|
||
- plugin_settings: plugin key/value store
|
||
- plugins: plugin registry
|
||
|
||
Profile username cooldown (core)
|
||
- User can update once every 90 days
|
||
- Stored in user_profiles.username_updated_at
|
||
- /profile/username checks cooldown server‑side
|
||
- UI: modal with disabled button + hint when on cooldown
|
||
|
||
Sidebar UX standards (core)
|
||
- User chip is clickable to /profile
|
||
- Collapsed sidebar:
|
||
- Icons centered, tooltips on items/sections
|
||
- Subitem icons remain visible (default or admin-uploaded)
|
||
- Consistent padding/width
|
||
- Enable/disable inputs should use green/red switch toggles (not plain checkboxes)
|
||
- /admin/navigation uses drag-and-drop layout with an Advanced JSON editor
|
||
|
||
Plugins (important)
|
||
- Plugin system loads from plugins/ directory
|
||
- Each plugin:
|
||
- plugin.json with id, name, version, main (index.js)
|
||
- index.js exports { id, init(...) }
|
||
- web.mount("/plugins/<id>", router, navItem) to add nav entry
|
||
- Plugins should avoid core edits unless explicitly requested
|
||
|
||
Current notable plugins
|
||
- echonomy-framework:
|
||
- Currency framework only (no items/betting)
|
||
- Banking UI: /profile/banking (plugin)
|
||
- Response templates with random/weighted replies
|
||
- Community funds (renamable)
|
||
- Commands under root (default "coins")
|
||
- Activity rewards (discord/twitch messages, discord voice) are queued per user per hour and flushed as one hourly transaction note "Activity Reward" with metadata breakdown
|
||
- echonomy-games:
|
||
- Uses echonomy-framework currency
|
||
- Hot Potato / Coinflip / Mystery Box
|
||
- Per-platform enable + configurable triggers/aliases
|
||
- Admin UI at /plugins/echonomy-games
|
||
- Stats stored in echonomy_game_stats (plays, coins won/lost, last played)
|
||
- moderation:
|
||
- Global moderation actions, notes, sanctions
|
||
- Ban/timeout UI at /plugins/moderation
|
||
- TOs & Bans view at /plugins/moderation/tos-bans
|
||
- Login gating shows moderation status screen
|
||
- Evidence uploads stored in data/moderation/evidence (download via /plugins/moderation/evidence/:id)
|
||
- quotes:
|
||
- Quote storage/search with WebUI at /plugins/quotes
|
||
- quotes table fields include quoter_user_id (internal user id) + game_name
|
||
- Stats provider adds total quotes, top quoters, and top quoted games
|
||
|
||
Database schema (core)
|
||
- mod_role_periods table tracks mod/admin time for Mods List
|
||
- auto-vc:
|
||
- Auto VC creation based on lobby channels
|
||
- Game name detection uses Discord presence PLAYING/STREAMING/COMPETING only
|
||
- expression-interaction:
|
||
- Action commands with stats tracking
|
||
|
||
Important settings keys (core)
|
||
- discord: discord_client_id, discord_client_secret, discord_bot_token, discord_guild_id, discord_admin_role_id, discord_mod_role_id, discord_redirect_uri
|
||
- twitch: twitch_client_id, twitch_client_secret, twitch_bot_username, twitch_bot_oauth, twitch_channels, twitch_redirect_uri
|
||
- youtube: youtube_client_id, youtube_client_secret, youtube_bot_refresh_token, youtube_bot_channel_id, youtube_redirect_uri
|
||
- site: site_title, bot_avatar_url, command_prefix
|
||
- nav: nav_item_icons (map of nav item id -> filename in data/nav-icons), nav_structure (custom sidebar layout)
|
||
|
||
Known file locations
|
||
- Layout partials: src/web/views/partials/layout-top.ejs, layout-bottom.ejs
|
||
- Global CSS: src/web/public/styles.css
|
||
- Global JS: src/web/public/app.js
|
||
- Asset versioning: res.locals.assetVersion (cache-bust for styles/app)
|
||
- Nav icons: src/web/public/icons/nav (defaults), data/nav-icons (admin uploads)
|
||
|
||
Packaging sanity checks (before shipping)
|
||
- Plugin zips contain plugin.json at root
|
||
- Core zip contains package.json and src/main.js
|
||
- No data/ or node_modules included
|
||
- Update zip placed in updates/
|
||
|
||
TODOs / Open questions
|
||
- Align plugin profile sections with new core hook (replace direct injection if used)
|
||
- Standardize plugin response templates UI to avoid duplication
|
||
- Consider centralized search API for profile user lookup
|
||
- Add docs for web.addProfileSection usage (when stable)
|