# servusdei2018/shards architecture

> Architecture diagram of the GitHub repository servusdei2018/shards, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/servusdei2018/shards
- Repository: https://github.com/servusdei2018/shards

## Overview

##### 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).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Library Internals
    subgraph "Library Internals"
        Config["Config Loader\n(config.go)"]:::library
        Manager["Manager\n(manager.go)"]:::library
        Shard["Shard Worker\n(shards.go)"]:::library
    end

    %% User Application
    subgraph "User Application"
        Bot["Bot Application Example\n(main.go)"]:::user
        Handlers["Event Handler Registry"]:::user
    end

    %% External Systems
    Gateway[(Discord Gateway)]:::external

    %% Documentation & Dependencies
    subgraph "Documentation & Dependencies"
        GoMod["go.mod"]:::docs
        GoSum["go.sum"]:::docs
        DemoReadme["examples/pingpong/README.md"]:::docs
        ProjectReadme["README.md"]:::docs
    end

    %% Connections
    Bot -->|"imports config & creates"| Config
    Config -->|provides config| Manager
    Bot -->|"calls Manager.Run()"| Manager
    Manager -->|"spawns N shard workers"| Shard
    Shard -->|"WebSocket connect & identify"| Gateway
    Gateway -->|"events"| Shard
    Shard -->|"dispatch events"| Handlers
    Handlers -->|"invoke callbacks"| Bot
    Bot -->|"issues commands"| Manager
    Manager -->|"routes commands to"| Shard
    Manager -->|"monitors & restarts"| Shard

    %% Click Events
    click Config "https://github.com/servusdei2018/shards/blob/master/config.go"
    click Manager "https://github.com/servusdei2018/shards/blob/master/manager.go"
    click Shard "https://github.com/servusdei2018/shards/blob/master/shards.go"
    click Bot "https://github.com/servusdei2018/shards/blob/master/examples/pingpong/main.go"
    click DemoReadme "https://github.com/servusdei2018/shards/blob/master/examples/pingpong/README.md"
    click GoMod "https://github.com/servusdei2018/shards/blob/master/go.mod"
    click GoSum "https://github.com/servusdei2018/shards/blob/master/go.sum"
    click ProjectReadme "https://github.com/servusdei2018/shards/blob/master/README.md"

    %% Styles
    classDef library fill:#BBDEFB,stroke:#1E88E5,color:#0D47A1,stroke-width:1px
    classDef user fill:#C8E6C9,stroke:#388E3C,color:#1B5E20,stroke-width:1px
    classDef external fill:#FFE0B2,stroke:#F57C00,color:#E65100,stroke-width:1px
    classDef docs fill:#E0E0E0,stroke:#9E9E9E,color:#424242,stroke-width:1px
```
