File Reference

Quick reference for the purpose of each major file and directory in the project.

Backend Root Files

File	Purpose
`config.example.yml`	Template configuration - copy to `config.yml`
`config.yml`	Active bot configuration (DO NOT COMMIT)
`package.json`	Node.js dependencies and npm scripts
`tsconfig.json`	TypeScript compiler configuration
`Dockerfile`	Docker image build definition
`.env`	Environment variable overrides (TOKEN, etc.)
`.gitignore`	Git ignore rules
`mewwme.database.json`	JSON database file (when using JSON driver)
`patreon_cache.json`	Cached Patreon pledge data

Backend Source (`src/`)

Core

File	Purpose
`index.ts`	Entry point - creates Manager and attaches global error handlers
`manager.ts`	Manager class - extends discord.js Client, orchestrates all services

Types (`@types/`)

File	Purpose
`Config.ts`	TypeScript interface mapping `config.yml` structure
`Button.ts`	Player button type definitions
`Cluster.ts`	Cluster/shard type definitions
`Emoji.ts`	Emoji configuration types
`Interaction.ts`	Interaction handling types
`Lavalink.ts`	Lavalink connection types

Guild Helpers (`@guild-helpers/`)

File	Purpose
`AssistanceHandler.ts`	Helpdesk/ticket assistance automation
`StatisticsHandler.ts`	User and guild statistics tracking

Commands (`commands/`)

Directory	Count	Purpose
`Filter/`	26	Audio filter toggle commands
`Games/`	12	Interactive Discord games
`Info/`	13	Information and statistics commands
`Music/`	25	Music playback and queue management
`Playlist/`	10	Personal playlist CRUD
`Settings/`	14	Guild and bot configuration

Database (`database/`)

File	Purpose
`index.ts`	DatabaseService - selects and initializes driver
`@types.ts`	DatabaseTable type with all table references
`handler.ts`	Post-connection handler (cleanup, migrations)
`keyChecker.ts`	Validates database config keys at startup
`driver/json.ts`	JSON file driver
`driver/mongodb.ts`	MongoDB driver
`driver/mysql.ts`	MySQL driver
`driver/postgres.ts`	PostgreSQL driver
`setup/table.ts`	Registers all database tables
`setup/setup.ts`	Initial setup routines
`setup/premium.ts`	Premium expiry cleanup
`setup/lavalink.ts`	Lavalink node persistence

Handlers (`handlers/`)

File	Purpose
`index.ts`	Master handler - loads all sub-handlers
`loadCheck.ts`	Lavalink autofix checker
`loadCommand.ts`	Command and button loader
`loadEvents.ts`	Event listener loader
`loadPlayer.ts`	Player event loader

Mewslink (`mewslink/`)

File/Dir	Purpose
`Mewslink.ts`	Main Mewslink class - manages nodes and players
`main.ts`	MewslinkPlayer class with custom data store
`metadata.ts`	Version metadata
`Manager/`	Node registry and player allocation
`Node/`	Node connection and communication
`Player/`	Player state, queue, filters
`Drivers/`	Lavalink v4 protocol drivers
`Library/`	Discord.js adapter
`Plugin/`	Plugin system
`Utilities/`	Shared utilities

Services (`services/`)

File	Purpose
`ConfigDataService.ts`	Parses config.yml with env var interpolation
`DeployService.ts`	Registers slash commands globally
`LoggerService.ts`	Winston logger with daily rotation
`ManifestService.ts`	Reads package.json metadata
`PatreonService.ts`	Patreon pledge management
`KofiService.ts`	Ko-fi subscription management
`TopggService.ts`	Top.gg vote tracking
`MysqlBackup.ts`	Scheduled MySQL database backups
`TempVoiceService.ts`	Temporary voice channel management
`FilterMenuService.ts`	Audio filter select menu builder
`MusicTriviaService.ts`	Music trivia game logic, scoring, badges
`MusicTriviaSongBank.ts`	Curated song bank (600+ tracks, 12 genres)
`SpotifyTopChartService.ts`	Spotify top chart data

Structures (`structures/`)

File	Purpose
`Command.ts`	Base command class
`CommandHandler.ts`	Command execution router
`Collection.ts`	Extended Collection
`Localization.ts`	i18n wrapper
`Mewslink.ts`	Mewslink initializer
`Page.ts`	Embed pagination
`PageQueue.ts`	Queue pagination
`QuickDatabasePlus.ts`	Enhanced QuickDB wrapper with cache

Utilities (`utilities/`)

File	Purpose
`ConvertTime.ts`	Time conversion helpers
`FormatDuration.ts`	Duration formatting
`ProgressBar.ts`	Track progress bar renderer
`RadioStations.ts`	Radio station list
`ScrobbleToLastFM.ts`	Last.fm scrobble utility
`SpotifygetAccessToken.ts`	Spotify token refresh
`TopArtist.ts`	Listening stats: top artists
`TopTrack.ts`	Listening stats: top tracks
`BroadcastConfig.ts`	Broadcast tips configuration
`NormalizeTrackMetadata.ts`	Track metadata normalization and lyrics queries

Web Layer (`web/`)

File	Purpose
`RestAPI.ts`	Fastify REST API server (port 2555)
`WebServer.ts`	Express webhook server (port 2444)
`player.ts`	Player REST routes
`websocket.ts`	Internal WebSocket route

Dashboard (`web/dashboard/`)

File	Purpose
`DashboardPlugin.ts`	Fastify plugin - OAuth2, sessions, CORS, Socket.IO, all /api/* routes
`DiscordOAuth.ts`	Discord OAuth2 helper
`SpotifyOAuthService.ts`	Spotify OAuth2 flow
`UserProfileService.ts`	User profile CRUD
`LikedSongsService.ts`	Liked songs CRUD
`BotWsService.ts`	Bot-to-dashboard WebSocket bridge
`SocketBridge.ts`	Socket.IO bridge for real-time events
`AiChatService.ts`	Gemini AI chat integration
`AiChatHistoryDb.ts`	AI chat history database operations
`SessionLoginService.ts`	Session persistence store

Route Handlers (`web/route/`)

File	Purpose
`getCommands.ts`	List all bot commands
`getTopServers.ts`	Top servers by member count
`getGlobalStats.ts`	Global bot statistics
`getUserStats.ts`	User listening statistics
`getGuildStats.ts`	Guild statistics
`getUserPlaylists.ts`	User's playlists
`getUserPremium.ts`	User premium status and feature access
`guildSettings.ts`	Guild settings CRUD
`externalServices.ts`	External service integrations
`resolveDashboardAccess.ts`	Dashboard access control resolution
`adminLegacyPremium.ts`	Admin premium management
`adminBotProfile.ts`	Admin bot profile management
`adminHelpdesk.ts`	Admin helpdesk/ticket management
`premiumClaim.ts`	Premium claim/unclaim

Deployment Files

Scripts (`scripts/`)

File	Purpose
`clearSlash.js`	Remove all registered slash commands
`copyData.js`	Post-build data copy (languages, etc.)
`ecosystem.config.js`	PM2 process configuration
`getCampignId.js`	Patreon campaign ID fetcher

Additional Files (`additional-file/`)

File	Purpose
`api-domain.sh`	Nginx setup script for API domain
`ws-domain.sh`	Nginx setup script for WebServer domain
`application.yml`	Reference Lavalink configuration

Pterodactyl Eggs (`additional-file/Eggs Panel Pterodactyl/`)

File	Purpose
`egg-node-js-generic.json`	Generic Node.js egg
`egg-node-j-s--universal.json`	Universal Node.js egg
`egg-a-i-o.json`	All-in-one egg
`egg-lavalink.json`	Lavalink server egg

Frontend Source (`frontend/src/`)

File/Dir	Purpose
`App.tsx`	Root component with routing and providers
`main.tsx`	Vite entry point
`config/links.ts`	External link definitions
`config/team.json`	Team member data
`hooks/useAuth.tsx`	Authentication context
`hooks/usePlayer.ts`	Player state management
`hooks/useSocket.ts`	Socket.IO connection
`hooks/useLikedSongs.ts`	Liked songs management
`hooks/useTrackColor.ts`	Album art color extraction
`pages/`	Page components (16 pages)
`components/ui/`	Radix UI primitives
`components/dashboard/`	Dashboard-specific components
`lib/config.ts`	Runtime configuration

Troubleshooting Notes