How servusdei2018/shards works
Project type and purpose
• This is an open-source Go library (“shards”) that provides configurable, scalable and automatic sharding for discordgo-based Discord bots. It is not a standalone service but a library you embed in your bot to manage multiple gateway connections (“shards”) transparently.
File structure
• Top-level Go files
• config.go Defines user-facing configuration structures (number of shards, intents, restart options, etc.)
• manager.go Implements the Manager component that uses config to spawn, monitor and restart shard routines
• shards.go Contains the Shard abstraction (one WebSocket client + event loop + lifecycle hooks)
• go.mod / go.sum Dependency management for Go modules
• examples/pingpong
• A small bot example demonstrating how to import shards, configure a Manager, register event handlers, and run the shard cluster
• CI / GitHub meta
• .circleci, .github/... CI and contributor workflows, not part of runtime architecture
README for additional insights
• Features: automatic scaling, zero-downtime restarts, slash-commands support
• Usage: import the package, create a Manager with your desired config, register event handlers (message create, application command create), call Manager.Run()
a. Main components
1. Your Bot Application (the user’s code that imports shards)
2. Config Loader (parses config.go structures)
3. Manager
4. Shard Workers (multiple instances)
5. Discord Gateway (external WebSocket/API endpoint)
6. Event Handler Registry (in your application)
b. Relationships & interactions
• The Bot Application passes a Config object into the Manager.
• Manager spins up N Shard Workers (goroutines/processes) according to config.
• Each Shard Worker opens a WebSocket to the Discord Gateway, performs identify/heartbeat, and maintains the session.
• Gateway sends events → Shard Worker parses them → pushes to the Event Handler Registry in the Bot Application.
• For outgoing commands (e.g., slash commands), the Bot Application calls back into Manager → the appropriate Shard Worker sends over its WebSocket.
• On zero-downtime restart: Manager gracefully spins up new Shard Workers with existing session data, drains the old ones, then shuts them down.
c. Architectural patterns & design principles
• Manager-Worker pattern (orchestrator spawns and supervises workers)
• Event-driven architecture (WebSocket events → user callbacks)
• Graceful restart logic (state handoff between worker generations)
• Concurrency via Go goroutines, channels, context cancellation
d. Key technologies & libraries
• Go lang (modules, goroutines, channels)
• discordgo (underlying Discord API & WebSocket client)
• Native Go WebSocket handling (in shards.go)
• CI/CD via CircleCI, standard Go toolchain
Detail
• Lifecycle step: initialization (config & identify), running (heartbeat loop, event dispatch), restart (spin-up new workers, drain old ones).