# hydradevx/hypr architecture

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

- Interactive diagram: https://gitdiagram.com/hydradevx/hypr
- Repository: https://github.com/hydradevx/hypr

## Overview

##### Project type and purpose
- This is a monorepo full-stack application (built with PNPM workspaces + Turbo) comprising:
- A Node.js/TypeScript CLI “selfbot” that connects to Discord as a user account, loads commands & features modularly, and maintains internal state.
- An optional React/Vite Web UI that lets the user control the bot, view logs, edit RPC, etc.
- Purpose: provide a blazing-fast, fully-modular Discord selfbot framework with hot-reloadable config and plugin support.

##### File structure
- Top-level:
- .github CI & release workflows, lint config, scripts for cross-platform installation, Turbo and PNPM workspace configs.
- packages/selfbot: bot.ts (entry), web.ts (serves/launches Web UI), TSConfig, package.json.
- packages/selfbot/bot:
– commands/… (organized by category: activity, fun, general, moderation, raiding, tools, ui, utility).
– features/… (autoReact, invisibilityCloak).
– managers/… (state managers: afk, autoReact, raid).
– utils/… (config loader & watcher, logger, antiCrash, richPresence, updater, etc.).
- packages/web: React SPA (App.tsx, pages, components, Tailwind, theme hooks, Vite, etc.).

##### Extract key architecture notes from README
- Modular plugin & command system
- Hot-reloadable config.json
- Optional Web UI for controls & logs
- Discord RPC integration
- Cross-platform, lightning-fast setup

A. External:
- Discord Gateway & REST API (cloud)
- Discord client / user token
B. Core Selfbot (Node.js):
1. Entrypoints
– bot.ts: initializes modules, connects to Discord.
– web.ts: launches local HTTP server / WS for Web UI.
2. Config Manager (utils/config-read + watcher)
– Loads config.json → broadcasts reload events to features/managers.
3. Command Handler (bot/commands)
– Scans command directories → registers each command with Discord event listeners.
4. Feature Modules (bot/features)
– AutoReaction, Invisibility Cloak, etc.
5. State Managers (bot/managers)
– Maintain AFK state, raid status, etc.
6. Utility Modules (bot/utils)
– Logger, antiCrash, updater, richPresence (Discord RPC), usage loader, info loader…
7. Plugin Extension Points
– Hooks in command and feature loader for external plugins.
C. Optional Web UI (React SPA):
- Served by web.ts or static file server
- HTTP / WebSocket API ↔ core selfbot
– Controls endpoints (start/stop features, set prefix, etc.)
– Logs stream for Dashboard/Logs pages
– RPC editor & Settings via read/write config.json

##### Architectural patterns & design principles
- Monorepo with workspace isolation
- Command Pattern for commands
- Observer/Event-Emitter for config hot-reload & Discord events
- State Management via dedicated managers
- Modular, plugin-friendly directory structure
- MVC-style separation in Web UI (pages, components, theme store)

- Clearly distinguish synchronous (HTTP) vs. asynchronous/event flows (WebSocket, Discord events).

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "External Services"
        DiscordCloud["Discord Gateway & REST API"]:::external
        DiscordRPC["Discord RPC"]:::external
    end

    subgraph "Core Selfbot"
        subgraph "Entrypoints"
            BotTS["bot.ts"]:::entry
            WebTS["web.ts"]:::entry
        end
        ConfigRead["Config Manager (config-read.ts & config.ts)"]:::util
        CommandHandler["Command Handler"]:::core
        Features["Feature Modules"]:::core
        Managers["State Managers"]:::core
        Utils["Utility Modules"]:::util
        Plugins["Plugin Extension Points"]:::core
    end

    subgraph "Web UI (React SPA)"
        ReactApp["React App"]:::ui
        Controls["Controls Page"]:::ui
        Dashboard["Dashboard Page"]:::ui
        LogsPage["Logs Page"]:::ui
        Settings["Settings Page"]:::ui
        RpcEditor["RPC Editor Page"]:::ui
        ThemeStore["Theme & Sidebar Store"]:::ui
    end

    ConfigFile["config.json"]:::data
    PluginsFolder["plugins/"]:::data
    LogsStore["logs/"]:::data

    %% Data Flows
    ConfigFile-->|load|ConfigRead
    ConfigRead-->|reload events|Features
    ConfigRead-->|reload events|CommandHandler
    PluginsFolder-->|extension|Plugins

    %% Discord interactions
    DiscordCloud-->|READY event|BotTS
    BotTS-->|initialize|CommandHandler
    BotTS-->|initialize|Features
    BotTS-->|initialize|Managers
    BotTS-->|initialize|Utils
    BotTS-->|register hooks|Plugins
    CommandHandler-->|MessageCreate → dispatch|DiscordCloud
    Features-->|event handlers|DiscordCloud
    Managers-->|state updates|DiscordCloud
    Utils-->|richPresence|DiscordRPC

    %% Web UI interactions
    WebTS-->|HTTP/WS API|ReactApp
    BotTS-->|write logs|LogsStore
    LogsStore-->|WS: logStream|ReactApp

    ReactApp-->|render|Controls
    ReactApp-->|render|Dashboard
    ReactApp-->|render|LogsPage
    ReactApp-->|render|Settings
    ReactApp-->|render|RpcEditor
    ReactApp-->|use stores|ThemeStore

    %% External to Core
    DiscordCloud---BotTS

    %% Click Events
    click BotTS "https://github.com/hydradevx/hypr/blob/main/packages/selfbot/bot.ts"
    click WebTS "https://github.com/hydradevx/hypr/blob/main/packages/selfbot/web.ts"
    click ConfigRead "https://github.com/hydradevx/hypr/blob/main/packages/selfbot/bot/utils/config-read.ts"
    click ConfigRead "https://github.com/hydradevx/hypr/blob/main/packages/selfbot/bot/utils/config.ts"
    click CommandHandler "https://github.com/hydradevx/hypr/tree/main/packages/selfbot/bot/commands"
    click Features "https://github.com/hydradevx/hypr/tree/main/packages/selfbot/bot/features"
    click Managers "https://github.com/hydradevx/hypr/tree/main/packages/selfbot/bot/managers"
    click Utils "https://github.com/hydradevx/hypr/tree/main/packages/selfbot/bot/utils"
    click ReactApp "https://github.com/hydradevx/hypr/blob/main/packages/web/App.tsx"
    click Controls "https://github.com/hydradevx/hypr/blob/main/packages/web/pages/Controls.tsx"
    click Dashboard "https://github.com/hydradevx/hypr/blob/main/packages/web/pages/Dashboard.tsx"
    click LogsPage "https://github.com/hydradevx/hypr/blob/main/packages/web/pages/Logs.tsx"
    click RpcEditor "https://github.com/hydradevx/hypr/blob/main/packages/web/pages/RpcEditor.tsx"
    click Settings "https://github.com/hydradevx/hypr/blob/main/packages/web/pages/Settings.tsx"
    click ThemeStore "https://github.com/hydradevx/hypr/blob/main/packages/web/lib/themeContext.tsx"

    %% Styles
    classDef external fill:#E0E0FF,stroke:#888;
    classDef core fill:#D0FFD0,stroke:#0A0;
    classDef util fill:#D0E0FF,stroke:#00F;
    classDef ui fill:#FFF0B3,stroke:#CC0;
    classDef entry fill:#CFFFCF,stroke:#0A0;
    classDef data fill:#FFECB3,stroke:#CC0;
```
