How unloopedmido/skyblockts works
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: