How mineral-dart/core works
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.