# mineral-dart/core architecture

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

- Interactive diagram: https://gitdiagram.com/mineral-dart/core
- Repository: https://github.com/mineral-dart/core

## Overview

##### Project Type & Purpose
- Mineral is an open-source Dart framework (library/tool) for building Discord bots.
- It provides a CLI for scaffolding, a core runtime for command/event handling, HTTP API wrappers, WebSocket connectivity (including sharding), state management, dependency injection, and extensibility via modules/plugins.

##### File-Structure Analysis
- Top-level “lib/cli.dart”: entry point for the command-line interface (scaffold, build, publish).
- “lib/core/…”: public API surface (core.dart, framework.dart, exception.dart, services, builders, collectors, events).
- “lib/src/…”: implementation details
- “api/…”: high-level wrappers around Discord REST endpoints (builders, channels, guilds, interactions).
- “commands/…”: CLI “make” and compile commands plus templates.
- “internal/services/…”: core runtime services (HTTP adapters, CLI service, event dispatcher, collector service, context-menu service, package service, shared state service, debugger).
- “internal/websockets/…”: WebSocket connection, dispatcher, packet handling, sharding.
- “internal/kernel.dart”: bootstraps DI container, registers services and modules.
- Configuration: pubspec.yaml, dartdoc, analysis_options, GitHub workflows (CI/publish).

##### Key Components to Capture
a. CLI Layer
- CLI entry (lib/cli.dart)
- Commands: make, compile, help, publish
- PackageService & Template engine
b. Core Framework
- Kernel: initializes DI container
- Container/Injector (services registry)
- Public API (core.dart, framework.dart): classes for client/user code
- Builders & Collectors for constructing Discord payloads
c. HTTP API Service
- HttpService + adapters (default & Discord API adapters)
- Used by public API to make REST calls to Discord
d. WebSocket Service
- WebSockets manager, dispatcher & sharding
- Receives real-time events (JSON packets) from Discord Gateway
e. Event System
- EventEmitterService / EventService
- Publishes WebSocket events to user-defined event handlers
f. State Management
- SharedStateService / MineralState
- Intra-application stores for sharing data
g. User Code (Plugins/Modules)
- Commands, Event Handlers, Interactive Components
- Registered via DI container
h. External Dependency
- Discord REST API endpoint
- Discord Gateway (WebSocket endpoint)

##### Relationships & Data Flows
- CLI invokes Kernel → registers services & modules → user bootstrap code uses Framework API.
- At runtime:
- Kernel/Container instantiates HttpService and WebSocketService.
- WebSocketService connects to Discord Gateway → emits packets → EventService.
- EventService routes packets to user-defined MineralEvent handlers.
- Handlers use HttpService (via API wrappers) to call Discord REST API.
- State changes propagate via SharedStateService → injectable into handlers.
- Build/Compile commands (CLI) transform user code into executables or JS bundles.

##### Architectural Patterns & Principles
- Modular & layered architecture: CLI layer, Core framework layer, Transport layer (HTTP/WebSocket), User layer.
- Dependency Injection/Service Container for extensibility and testability.
- Publisher/Subscriber (EventEmitter) for decoupled event handling.
- Builder pattern in API payload construction.
- Sharding abstraction for horizontal scalability over WebSocket connections.

## Diagram (Mermaid)

```mermaid
graph TD
    %% CLI Layer
    subgraph "CLI Layer"
        CLI["CLI Entry"]:::cli
        Make["Commands\n(make, compile, help, publish)"]:::cli
        PackageService["PackageService"]:::cli
        Templates["CLI Templates"]:::cli
    end

    %% Core Framework
    subgraph "Core Framework"
        Kernel["Kernel & DI Container"]:::core
        Injector["Container/Injector Mixins"]:::core
        PublicAPI["Public API Surface"]:::core
        BuildersCollectors["Builders & Collectors"]:::core
    end

    %% HTTP API Service
    subgraph "HTTP API Service"
        HttpService["HttpService & Contract"]:::http
        DefaultAdapters["Default Adapters"]:::http
        DiscordAdapters["Discord API Adapters"]:::http
        DiscordHttpService["Discord API HTTP Service"]:::http
    end

    %% WebSocket Service & Sharding
    subgraph "WebSocket Service & Sharding"
        WebSockets["WebSocket Core"]:::ws
        Dispatcher["WebSocket Dispatcher"]:::ws
        Packets["Packet Definitions"]:::ws
        EventsMapping["Gateway Event Mappings"]:::ws
        ShardManager["Shard Manager"]:::ws
    end

    %% Event System
    subgraph "Event System"
        Emitter["EventEmitterService"]:::event
        EventService["EventService"]:::event
    end

    %% State Management
    StateService["SharedStateService"]:::state

    %% Core Runtime Services
    subgraph "Core Runtime Services"
        CollectorSvc["Collector Service"]:::coreSvc
        ContextMenuSvc["Context Menu Service"]:::coreSvc
        DebuggerSvc["Debugger Service"]:::coreSvc
        IntentSvc["Intent Service"]:::coreSvc
        ConsoleSvc["Console Service & Themes"]:::coreSvc
    end

    %% User Modules & Plugins
    subgraph "User Modules & Plugins"
        UserCommands["User Commands"]:::user
        EventHandlers["Event Handlers"]:::user
        InteractiveComponents["Interactive Components"]:::user
    end

    %% External Dependencies
    ExternalREST["Discord REST API"]:::external
    ExternalGateway["Discord Gateway"]:::external

    %% Relationships
    CLI -->|invokes| Kernel
    Make -->|uses| Kernel
    Templates -->|provides| Make
    PackageService -->|used by| CLI

    Kernel --> Injector
    Kernel --> HttpService
    Kernel --> WebSockets
    Kernel --> PublicAPI
    Kernel --> CollectorSvc
    Kernel --> ContextMenuSvc
    Kernel --> DebuggerSvc
    Kernel --> IntentSvc
    Kernel --> ConsoleSvc

    PublicAPI --> BuildersCollectors
    HttpService --> DefaultAdapters
    HttpService --> DiscordAdapters
    DiscordAdapters --> DiscordHttpService
    DiscordHttpService -->|REST calls| ExternalREST

    WebSockets --> Dispatcher
    Dispatcher --> Packets
    Dispatcher --> EventsMapping
    WebSockets --> ShardManager
    WebSockets -->|connects to| ExternalGateway
    ExternalGateway -->|sends packets| WebSockets

    WebSockets -->|emits| Emitter
    Emitter --> EventService
    EventService --> EventHandlers

    EventHandlers -->|calls| HttpService
    EventHandlers -->|reads/writes| StateService
    StateService --> EventHandlers

    UserCommands -->|registered in| Kernel
    EventHandlers -->|registered in| Kernel
    InteractiveComponents -->|registered in| Kernel

    %% Click Events
    click CLI "https://github.com/mineral-dart/core/blob/main/lib/cli.dart"
    click Make "https://github.com/mineral-dart/core/tree/main/lib/src/commands"
    click Templates "https://github.com/mineral-dart/core/tree/main/lib/src/commands/templates"
    click PackageService "https://github.com/mineral-dart/core/blob/main/lib/src/internal/services/package_service.dart"
    click Kernel "https://github.com/mineral-dart/core/blob/main/lib/src/internal/kernel.dart"
    click Injector "https://github.com/mineral-dart/core/blob/main/lib/src/internal/mixins/container.dart"
    click PublicAPI "https://github.com/mineral-dart/core/blob/main/lib/core.dart"
    click BuildersCollectors "https://github.com/mineral-dart/core/blob/main/lib/core/builders.dart"
    click HttpService "https://github.com/mineral-dart/core/blob/main/lib/src/internal/services/http_service/http_service.dart"
    click DefaultAdapters "https://github.com/mineral-dart/core/tree/main/lib/src/internal/services/http_service/adapters/default"
    click DiscordAdapters "https://github.com/mineral-dart/core/tree/main/lib/src/internal/services/http_service/adapters/discord_api"
    click DiscordHttpService "https://github.com/mineral-dart/core/blob/main/lib/src/internal/services/discord_api_http_service.dart"
    click WebSockets "https://github.com/mineral-dart/core/blob/main/lib/src/internal/websockets/websockets.dart"
    click Dispatcher "https://github.com/mineral-dart/core/blob/main/lib/src/internal/websockets/websocket_dispatcher.dart"
    click Packets "https://github.com/mineral-dart/core/tree/main/lib/src/internal/websockets/packets"
    click EventsMapping "https://github.com/mineral-dart/core/tree/main/lib/src/internal/websockets/events"
    click ShardManager "https://github.com/mineral-dart/core/blob/main/lib/src/internal/websockets/sharding/shard_manager.dart"
    click Emitter "https://github.com/mineral-dart/core/blob/main/lib/src/internal/services/event_emitter_service.dart"
    click EventService "https://github.com/mineral-dart/core/blob/main/lib/src/internal/services/event_service.dart"
    click StateService "https://github.com/mineral-dart/core/blob/main/lib/src/internal/services/shared_state_service.dart"
    click CollectorSvc "https://github.com/mineral-dart/core/blob/main/lib/src/internal/services/collector_service.dart"
    click ContextMenuSvc "https://github.com/mineral-dart/core/blob/main/lib/src/internal/services/context_menu_service.dart"
    click DebuggerSvc "https://github.com/mineral-dart/core/blob/main/lib/src/internal/services/debugger_service.dart"
    click IntentSvc "https://github.com/mineral-dart/core/blob/main/lib/src/internal/services/intent_service.dart"
    click ConsoleSvc "https://github.com/mineral-dart/core/blob/main/lib/src/internal/services/console/console_service.dart"

    %% Styles
    classDef cli fill:#D0E6FF,stroke:#0366D6,color:#0366D6
    classDef core fill:#E6F4EA,stroke:#22863A,color:#22863A
    classDef http fill:#FFEFD5,stroke:#D18700,color:#D18700
    classDef ws fill:#F3E5FF,stroke:#6F42C1,color:#6F42C1
    classDef event fill:#E0F2F1,stroke:#00796B,color:#00796B
    classDef state fill:#FFF3E0,stroke:#E65100,color:#E65100
    classDef coreSvc fill:#F1F8E9,stroke:#389E0D,color:#389E0D
    classDef user fill:#F0F0F0,stroke:#6A737D,color:#6A737D
    classDef external fill:#FFEBEE,stroke:#D32F2F,color:#D32F2F
```
