# unloopedmido/skyblockts architecture

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

- Interactive diagram: https://gitdiagram.com/unloopedmido/skyblockts
- Repository: https://github.com/unloopedmido/skyblockts

## Overview

##### Main System Components
From the file tree and README, the repository is a TypeScript monorepo (pnpm workspaces) containing three logical subsystems:
- @skyblock-ts/core (a zero-opinion, fully typed SkyBlock API client)
- @skyblock-ts/toolkit (high-level utilities built on top of core)
- docs (a static documentation site built with Vite + React + custom UI components)
Additionally, there’s the external Hypixel SkyBlock REST API as a remote service.

##### Relationships and Data Flows
- Consumer Code (external application or user script) imports either:
– CoreClient from @skyblock-ts/core (for direct, typed API calls), or
– ToolkitClient from @skyblock-ts/toolkit (for caching, batching, filters).
- ToolkitClient internally instantiates CoreClient and delegates raw fetches to it.
- CoreClient uses a generic fetcher utility (`packages/core/src/utils/fetcher.ts`) to make HTTP requests to the Hypixel SkyBlock API endpoints.
- CoreClient modules (Auctions, Bazaar, Profile, Data, Misc) expose typed methods that return Promise<T> of response types.
- Toolkit modules (Auctions, Bazaar, Profiles) wrap CoreClient methods, add caching (in-memory, TTL), batching and higher-level helpers.
- docs site is a static front-end; it does not invoke real API calls at runtime but demonstrates usage (through embedded code samples) and renders UI built atop React + TypeScript + shadcn-ui components.

##### Architectural Patterns and Design Principles
- Monorepo workspace (pnpm) to co-develop & version packages in lock-step.
- Strict separation of concerns:
– Core = API client only, no runtime deps.
– Toolkit = business logic (caching, filtering).
– docs = presentation layer.
- Layered architecture: Consumer → Toolkit → Core → External API.
- Interface-based design: each module exposes a well-typed interface.
- Build pipelines: tsup for bundling each package; Vite for docs site.

##### Essential Details to Capture
- Monorepo management (pnpm workspaces)
- Dependencies: toolkit → core → external API
- Build & test pipelines (tsup.config.ts, tsconfig.json, tests folder)
- The in-memory cache component inside toolkit (with TTL) and batching logic
- React component library in docs (UI layer)

Putting It All Together:

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Monorepo Root
    subgraph "Monorepo Root"
        direction TB
        Root_pnpm["pnpm-workspace.yaml"]:::tooling
        Root_tsconfig["tsconfig.json"]:::tooling
        Root_pkg["package.json"]:::tooling
        Root_gitignore[".gitignore"]:::tooling
    end

    %% Core Package
    subgraph "@skyblock-ts/core Package" 
        direction TB
        CoreClient["CoreClient"]:::internal
        CoreIndex["index.ts"]:::internal
        Fetcher["fetcher.ts"]:::internal
        ApiError["HypixelApiError.ts"]:::internal
        subgraph "Modules"
            direction TB
            AuctionMod["Auction.ts"]:::internal
            BazaarMod["Bazaar.ts"]:::internal
            DataMod["Data.ts"]:::internal
            MiscMod["Misc.ts"]:::internal
            ProfileMod["Profile.ts"]:::internal
        end
        subgraph "Types"
            direction TB
            AuctionTypes["AuctionTypes.ts"]:::internal
            BazaarTypes["BazaarTypes.ts"]:::internal
            DataTypes["DataTypes.ts"]:::internal
            MiscTypes["MiscTypes.ts"]:::internal
            ProfileTypes["ProfileTypes.ts"]:::internal
        end
        subgraph "Tests"
            direction TB
            TestAuction["auction.test.ts"]:::tooling
            TestBazaar["bazaar.test.ts"]:::tooling
            TestData["data.test.ts"]:::tooling
            TestMisc["misc.test.ts"]:::tooling
            TestProfile["profile.test.ts"]:::tooling
        end
        subgraph "Build Config"
            direction TB
            CoreTsup["tsup.config.ts"]:::tooling
            CoreTsconfig["tsconfig.json"]:::tooling
        end
    end

    %% Toolkit Package
    subgraph "@skyblock-ts/toolkit Package"
        direction TB
        ToolkitClient["ToolkitClient"]:::internal
        ToolkitIndex["index.ts"]:::internal
        subgraph "Modules"
            direction TB
            TKAuctions["Auctions.ts"]:::internal
            TKBazaar["Bazaar.ts"]:::internal
            TKProfiles["Profiles.ts"]:::internal
        end
        subgraph "Cache & Batching"
            direction TB
            Cache["Cache (in-memory, TTL)"]:::internal
            Batching["Batching Logic"]:::internal
        end
        subgraph "Build Config"
            direction TB
            TK_Tsup["tsup.config.ts"]:::tooling
            TK_Tsconfig["tsconfig.json"]:::tooling
        end
    end

    %% Docs Site
    subgraph "docs Site" 
        direction TB
        DocMain["main.tsx"]:::docs
        DocIndexHtml["index.html"]:::docs
        DocVite["vite.config.ts"]:::tooling
        DocTsconfig["tsconfig.json"]:::tooling
        subgraph "UI Components"
            direction TB
            UI_Button["button.tsx"]:::docs
            UI_Dialog["dialog.tsx"]:::docs
            UI_Dropdown["dropdown-menu.tsx"]:::docs
            UI_Input["input.tsx"]:::docs
            UI_Sheet["sheet.tsx"]:::docs
        end
        subgraph "Layout & Theme"
            direction TB
            Navbar["navbar.tsx"]:::docs
            ThemeProvider["theme-provider.tsx"]:::docs
            ThemeInit["theme-init.ts"]:::docs
        end
        subgraph "Routes"
            direction TB
            RouteIndex["index.tsx"]:::docs
            RouteAbout["about.tsx"]:::docs
        end
        subgraph "Utils & Hooks"
            direction TB
            Utils["utils.ts"]:::docs
            UseTheme["useTheme.tsx"]:::docs
        end
        subgraph "Docs Config"
            direction TB
            DocsPkg["package.json"]:::tooling
            DocsTsApp["tsconfig.app.json"]:::tooling
            DocsTsNode["tsconfig.node.json"]:::tooling
        end
    end

    %% External API
    HypixelAPI["Hypixel SkyBlock REST API"]:::external

    %% Consumer
    Consumer["Consumer Code"]:::external

    %% Relationships
    Consumer -->|"imports ToolkitClient"| ToolkitClient
    Consumer -->|"imports CoreClient"| CoreClient
    ToolkitClient -->|"runtime dependency"| CoreClient
    CoreClient -->|"HTTP requests"| HypixelAPI
    ToolkitClient -->|"delegates fetches"| CoreClient
    %% Tests and docs don't call API
    %% Docs static demonstration
    DocMain -.->|"static samples only"| HypixelAPI

    %% Click Events
    click Root_pnpm "https://github.com/unloopedmido/skyblockts/blob/main/pnpm-workspace.yaml"
    click Root_tsconfig "https://github.com/unloopedmido/skyblockts/blob/main/tsconfig.json"
    click Root_pkg "https://github.com/unloopedmido/skyblockts/blob/main/package.json"
    click Root_gitignore "https://github.com/unloopedmido/skyblockts/blob/main/.gitignore"
    click CoreClient "https://github.com/unloopedmido/skyblockts/blob/main/packages/core/src/CoreClient.ts"
    click CoreIndex "https://github.com/unloopedmido/skyblockts/blob/main/packages/core/src/index.ts"
    click Fetcher "https://github.com/unloopedmido/skyblockts/blob/main/packages/core/src/utils/fetcher.ts"
    click ApiError "https://github.com/unloopedmido/skyblockts/blob/main/packages/core/src/errors/HypixelApiError.ts"
    click AuctionMod "https://github.com/unloopedmido/skyblockts/blob/main/packages/core/src/modules/Auction.ts"
    click BazaarMod "https://github.com/unloopedmido/skyblockts/blob/main/packages/core/src/modules/Bazaar.ts"
    click DataMod "https://github.com/unloopedmido/skyblockts/blob/main/packages/core/src/modules/Data.ts"
    click MiscMod "https://github.com/unloopedmido/skyblockts/blob/main/packages/core/src/modules/Misc.ts"
    click ProfileMod "https://github.com/unloopedmido/skyblockts/blob/main/packages/core/src/modules/Profile.ts"
    click AuctionTypes "https://github.com/unloopedmido/skyblockts/blob/main/packages/core/src/types/AuctionTypes.ts"
    click BazaarTypes "https://github.com/unloopedmido/skyblockts/blob/main/packages/core/src/types/BazaarTypes.ts"
    click DataTypes "https://github.com/unloopedmido/skyblockts/blob/main/packages/core/src/types/DataTypes.ts"
    click MiscTypes "https://github.com/unloopedmido/skyblockts/blob/main/packages/core/src/types/MiscTypes.ts"
    click ProfileTypes "https://github.com/unloopedmido/skyblockts/blob/main/packages/core/src/types/ProfileTypes.ts"
    click TestAuction "https://github.com/unloopedmido/skyblockts/blob/main/packages/core/src/test/auction.test.ts"
    click TestBazaar "https://github.com/unloopedmido/skyblockts/blob/main/packages/core/src/test/bazaar.test.ts"
    click TestData "https://github.com/unloopedmido/skyblockts/blob/main/packages/core/src/test/data.test.ts"
    click TestMisc "https://github.com/unloopedmido/skyblockts/blob/main/packages/core/src/test/misc.test.ts"
    click TestProfile "https://github.com/unloopedmido/skyblockts/blob/main/packages/core/src/test/profile.test.ts"
    click CoreTsup "https://github.com/unloopedmido/skyblockts/blob/main/packages/core/tsup.config.ts"
    click CoreTsconfig "https://github.com/unloopedmido/skyblockts/blob/main/packages/core/tsconfig.json"
    click ToolkitClient "https://github.com/unloopedmido/skyblockts/blob/main/packages/toolkit/src/ToolkitClient.ts"
    click ToolkitIndex "https://github.com/unloopedmido/skyblockts/blob/main/packages/toolkit/src/index.ts"
    click TKAuctions "https://github.com/unloopedmido/skyblockts/blob/main/packages/toolkit/src/modules/Auctions.ts"
    click TKBazaar "https://github.com/unloopedmido/skyblockts/blob/main/packages/toolkit/src/modules/Bazaar.ts"
    click TKProfiles "https://github.com/unloopedmido/skyblockts/blob/main/packages/toolkit/src/modules/Profiles.ts"
    click TK_Tsup "https://github.com/unloopedmido/skyblockts/blob/main/packages/toolkit/tsup.config.ts"
    click TK_Tsconfig "https://github.com/unloopedmido/skyblockts/blob/main/packages/toolkit/tsconfig.json"
    click DocMain "https://github.com/unloopedmido/skyblockts/blob/main/docs/src/main.tsx"
    click DocIndexHtml "https://github.com/unloopedmido/skyblockts/blob/main/docs/index.html"
    click DocVite "https://github.com/unloopedmido/skyblockts/blob/main/docs/vite.config.ts"
    click DocTsconfig "https://github.com/unloopedmido/skyblockts/blob/main/docs/tsconfig.json"
    click UI_Button "https://github.com/unloopedmido/skyblockts/blob/main/docs/src/components/ui/button.tsx"
    click UI_Dialog "https://github.com/unloopedmido/skyblockts/blob/main/docs/src/components/ui/dialog.tsx"
    click UI_Dropdown "https://github.com/unloopedmido/skyblockts/blob/main/docs/src/components/ui/dropdown-menu.tsx"
    click UI_Input "https://github.com/unloopedmido/skyblockts/blob/main/docs/src/components/ui/input.tsx"
    click UI_Sheet "https://github.com/unloopedmido/skyblockts/blob/main/docs/src/components/ui/sheet.tsx"
    click Navbar "https://github.com/unloopedmido/skyblockts/blob/main/docs/src/components/navbar.tsx"
    click ThemeProvider "https://github.com/unloopedmido/skyblockts/blob/main/docs/src/components/theme-provider.tsx"
    click ThemeInit "https://github.com/unloopedmido/skyblockts/blob/main/docs/theme-init.ts"
    click RouteIndex "https://github.com/unloopedmido/skyblockts/blob/main/docs/src/routes/index.tsx"
    click RouteAbout "https://github.com/unloopedmido/skyblockts/blob/main/docs/src/routes/about.tsx"
    click Utils "https://github.com/unloopedmido/skyblockts/blob/main/docs/src/lib/utils.ts"
    click UseTheme "https://github.com/unloopedmido/skyblockts/blob/main/docs/src/hooks/useTheme.tsx"
    click DocsPkg "https://github.com/unloopedmido/skyblockts/blob/main/docs/package.json"
    click DocsTsApp "https://github.com/unloopedmido/skyblockts/blob/main/docs/tsconfig.app.json"
    click DocsTsNode "https://github.com/unloopedmido/skyblockts/blob/main/docs/tsconfig.node.json"

    %% Styles
    classDef internal fill:#D6EAF8,stroke:#21618C
    classDef external fill:#D5F5E3,stroke:#27AE60
    classDef docs fill:#FDEBD0,stroke:#E67E22
    classDef tooling fill:#E5E8E8,stroke:#566573
```
