# nextsnake/nextcore architecture

> Architecture diagram of the GitHub repository nextsnake/nextcore, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nextsnake/nextcore
- Repository: https://github.com/nextsnake/nextcore

## Overview

##### Project Type and Purpose
- Nextcore is a specialized API client library for Discord.
- Its purpose is to provide a fast, highly configurable, and modular way to interact with the Discord API; this includes both gateway (real-time, through websocket communication, sharding, etc.) and HTTP interactions (REST calls for sending messages, updating channels, etc.).

##### Break Down the File Structure into Main Components
- The core library is under the “nextcore” directory. Inside this, you have:
- The “common” module: Contains utility functions, error handling, JSON utilities, and components to manage asynchronous/coroutine behavior.
- The “gateway” module: Handles real-time communication (sharding, connection management, decompression, error handling, exponential backoff, etc.). This is where components like the shard and shard manager live.
- The “http” module: Provides HTTP client functionality, including authentication (with dedicated classes like BotAuthentication), rate limit handling (global rate limiter, bucket rate limiting), and request routing.
- The “examples” directory demonstrates how these core components are used in real scenarios (for instance, the “ping pong” example showing event handling and sending HTTP requests).
- The “tests” directory confirms the internal structure such as dispatcher functionality, JSON handling, rate limiter behavior, etc.

##### How the Components Interact
- At a high level, client code (as shown in the examples) instantiates an HTTP client and a gateway (ShardManager). The HTTP module handles RESTful interactions such as sending messages, while the gateway module handles persistent connections for receiving events.
- The common module supports both HTTP and gateway components with shared utilities, error management, and asynchronous routines.

##### Architectural Patterns and Design Principles
- Separation of Concerns: Clearly separate HTTP functionality from the gateway (real-time) functionality.
- Low-level control and speed are achieved through explicit components (e.g., fine-grained control of rate limiting, priority queuing in “times_per”, and shard management).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Code
    A["Client Code (Examples)"]:::client

    %% Common Module Subgraph
    subgraph "Common Module"
        O["Utilities & JSON Handling"]:::common
        P["Error Handling"]:::common
        Q["Async & Coroutine Utils"]:::common
    end

    %% Gateway Module Subgraph
    subgraph "Gateway Module"
        G["Shard Manager"]:::gateway
        H["Shard"]:::gateway
        I["Decompressor"]:::gateway
        J["Exponential Backoff"]:::gateway
    end

    %% HTTP Module Subgraph
    subgraph "HTTP Module"
        K["Bot Authentication"]:::http
        L["Rate Limiter (Global&Bucket)"]:::http
        M["Request Session"]:::http
        N["Route Construction"]:::http
    end

    %% External Discord APIs
    DREST["Discord REST API"]:::discord
    DWs["Discord WebSocket Gateway"]:::discord

    %% Interactions between Client Code and Nextcore Library
    A -->|"uses"| G
    A -->|"uses"| M
    A -->|"sendsCommandsTo"| N

    %% Common Module supports both Gateway and HTTP Modules
    O ---|"supports"| G
    O ---|"supports"| M
    P ---|"handlesErrorsFor"| G
    P ---|"handlesErrorsFor"| M
    Q ---|"providesAsyncFor"| G
    Q ---|"providesAsyncFor"| M

    %% Gateway Module initiates HTTP interactions when needed
    G -->|"triggersHTTP"| M

    %% HTTP Module interactions with Discord REST API
    M -->|"HTTPReqResp"| DREST

    %% Discord WebSocket sends events to Gateway Module
    DWs -->|"sendsEvents"| G

    %% Styling Classes
    classDef client fill:#ffcc99,stroke:#000,stroke-width:2px;
    classDef common fill:#cce5ff,stroke:#000,stroke-width:2px;
    classDef gateway fill:#d1f0d1,stroke:#000,stroke-width:2px;
    classDef http fill:#f9e79f,stroke:#000,stroke-width:2px;
    classDef discord fill:#ffd1dc,stroke:#000,stroke-width:2px;

    %% Click Events for Component Mapping
    click O "https://github.com/nextsnake/nextcore/tree/master/nextcore/common"
    click P "https://github.com/nextsnake/nextcore/tree/master/nextcore/common"
    click Q "https://github.com/nextsnake/nextcore/tree/master/nextcore/common"

    click G "https://github.com/nextsnake/nextcore/tree/master/nextcore/gateway"
    click H "https://github.com/nextsnake/nextcore/tree/master/nextcore/gateway"
    click I "https://github.com/nextsnake/nextcore/tree/master/nextcore/gateway"
    click J "https://github.com/nextsnake/nextcore/tree/master/nextcore/gateway"

    click K "https://github.com/nextsnake/nextcore/tree/master/nextcore/http"
    click L "https://github.com/nextsnake/nextcore/tree/master/nextcore/http"
    click M "https://github.com/nextsnake/nextcore/tree/master/nextcore/http"
    click N "https://github.com/nextsnake/nextcore/tree/master/nextcore/http"

    click A "https://github.com/nextsnake/nextcore/tree/master/examples"
```
