# sapphiredev/framework architecture

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

- Interactive diagram: https://gitdiagram.com/sapphiredev/framework
- Repository: https://github.com/sapphiredev/framework

## Overview

##### Project Type and Purpose
- The README clarifies that Sapphire is a framework for building advanced Discord bots using discord.js.
- The framework is highly modular and extends discord.js by providing built-in support for commands, arguments parsing, preconditions, listeners, and plugins. It also emphasizes strong TypeScript integration.

##### Main Components
a. Framework Core:
- The core is responsible for bootstrapping the bot instance. Look at files like src/index.ts and src/lib/SapphireClient.ts which initialize and run the framework.
b. Command & Argument Handling:
- Command handling system (see src/lib/structures/CommandStore.ts, src/lib/structures/Command.ts) and the Arguments system (src/arguments/*). These components parse and process user inputs.
c. Precondition and Error Handling:
- The framework includes preconditions (src/preconditions) and detailed error classes (e.g., src/lib/errors/*) for validating user interaction and handling exceptions.
d. Event Listeners:
- Various directories under src/listeners and src/optional-listeners handle different types of Discord events (e.g., CoreInteractionCreate, CoreReady) and errors.
e. Plugins and Extensions:
- The plugin system is key to Sapphire's extensibility. Check out src/lib/plugins/Plugin.ts and PluginManager.ts to represent how additional functionality can be integrated.
f. Utility Modules:
- There are helpers for parsing (src/lib/parsers), logging (src/lib/utils/logger), and preconditions resolution (src/lib/precondition-resolvers) that support the main flows.
g. Integration with discord.js:

##### Relationships and Interactions
- Data flows from Discord to the Framework Core via the discord.js events, which are then intercepted by the Listeners.
- Listeners in turn trigger Commands, using the Command and Argument Stores.
- Prior to executing commands, the Precondition system validates the context. If validations fail, the Error Handling components get involved.
- The Plugin subsystem allows hooks to modify behavior or extend functionalities across commands, listeners, parsers, and resolvers.
- Utility modules like logging and resolvers support various parts of the framework by standardizing operations and error messaging.

##### Architectural Patterns and Design Principles
- Modularization – the system splits responsibilities into clearly defined directories (arguments, lib, listeners, preconditions, etc.).
- Store/Registry Pattern – components such as CommandStore, ArgumentStore, ListenerStore, and PreconditionStore help in dynamically registering and managing components.
- Plugin Architecture – clear separation for extension points to allow external plugins without modifying core functionality.
- Event-driven design – driven by Discord events, which are captured by listeners and passed on to the command handling pipeline.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Subgraph: Discord Source
    subgraph "Discord Source"
        A["\"Discord Events\""]
    end

    %% Subgraph: Framework Core
    subgraph "Framework Core"
        B["\"SapphireClient\""]
    end

    %% Subgraph: Listeners
    subgraph "Listeners"
        C1["\"Core Listeners\""]
        C2["\"Optional Listeners\""]
    end

    %% Subgraph: Command & Argument System
    subgraph "Command & Argument System"
        D1["\"CommandStore\""]
        D2["\"Command\""]
        D3["\"Arguments\""]
    end

    %% Subgraph: Preconditions & Error Handling
    subgraph "Preconditions & Error Handling"
        E1["\"Preconditions\""]
        E2["\"Errors\""]
    end

    %% Subgraph: Plugins & Extensions
    subgraph "Plugins & Extensions"
        F["\"Plugin Manager\""]
    end

    %% Subgraph: Utility Modules
    subgraph "Utility Modules"
        G["\"Utility Modules\""]
    end

    %% Relationships
    A -->|"triggers"| B
    B -->|"dispatches"| C1
    B -->|"dispatches"| C2
    C1 -->|"invokes"| D1
    C1 -->|"invokes"| D2
    C1 -->|"invokes"| D3
    C2 -->|"invokes"| D1
    C2 -->|"invokes"| D2
    C2 -->|"invokes"| D3
    D1 -->|"validates"| E1
    D2 -->|"validates"| E1
    D3 -->|"validates"| E1
    E1 -->|"failure"| E2
    F ---|"hooks-into"| B
    F ---|"hooks-into"| C1
    F ---|"hooks-into"| D1
    G -.-> B
    G -.-> C1
    G -.-> D1
    G -.-> E1

    %% Click Events for Component Mapping
    click B "https://github.com/sapphiredev/framework/blob/main/src/index.ts"
    click B "https://github.com/sapphiredev/framework/blob/main/src/lib/SapphireClient.ts"
    click D2 "https://github.com/sapphiredev/framework/blob/main/src/lib/structures/Command.ts"
    click D1 "https://github.com/sapphiredev/framework/blob/main/src/lib/structures/CommandStore.ts"
    click D3 "https://github.com/sapphiredev/framework/tree/main/src/arguments"
    click E1 "https://github.com/sapphiredev/framework/tree/main/src/preconditions"
    click E2 "https://github.com/sapphiredev/framework/tree/main/src/lib/errors"
    click C1 "https://github.com/sapphiredev/framework/tree/main/src/listeners"
    click C2 "https://github.com/sapphiredev/framework/tree/main/src/optional-listeners"
    click F "https://github.com/sapphiredev/framework/tree/main/src/lib/plugins"
    click G "https://github.com/sapphiredev/framework/tree/main/src/lib/utils"

    %% Styles
    classDef core fill:#ffefc6,stroke:#d48b00,stroke-width:2px;
    classDef listener fill:#d0efff,stroke:#0077cc,stroke-width:2px;
    classDef command fill:#d1ffd6,stroke:#228b22,stroke-width:2px;
    classDef precond fill:#ffd1d1,stroke:#cc0000,stroke-width:2px;
    classDef plugin fill:#fff3d1,stroke:#ffaa00,stroke-width:2px;
    classDef util fill:#e8d9ff,stroke:#6a0dad,stroke-width:2px;
    classDef external fill:#ffffff,stroke:#000000,stroke-dasharray: 5 5;

    class B core;
    class C1,C2 listener;
    class D1,D2,D3 command;
    class E1,E2 precond;
    class F plugin;
    class G util;
    class A external;
```
