# valumane/hypixelapi architecture

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

- Interactive diagram: https://gitdiagram.com/valumane/hypixelapi
- Repository: https://github.com/valumane/hypixelapi

## Overview

##### Project type and purpose
- This is a lightweight full-stack “API Utilities” web project.
- Frontend: a static web UI (index.html + styles.css + /script + /texture assets) that visualizes SkyBlock data.
- Backend: a Node.js “hypixel-scraper” service that crawls Hypixel sitemaps, calls the official Hypixel API, and writes JSON data (in /gestion and /sitemap).

##### Main components
a. Browser / Client
- Loads index.html, CSS, scripts (main.js, profile.js, inventory.js, etc.) and textures.
- Renders player/guild/SkyBlock views and invokes data-fetching calls.
b. Static Assets Host
- Serves index.html, styles.css, JS files from root.
c. Scraper Service (hypixel-scraper)
- sitemap_gestion.js: retrieves sitemap.json → ndjson of all item pages.
- sitemap_process_scrapping.js: sequentially fetches each page via index.js (Hypixel API calls).
- management logic in /gestion/*.json: normalizes and merges endpoint data (e.g., bazaar.json, gemstone.json).
d. Data Store (File System)
- JSON under hypixel-scraper/gestion and sitemap.
- backup_API.json at root as fallback.
e. External Hypixel API
- Public endpoints providing real-time data on players, guilds, SkyBlock.

##### Relationships & Data Flows
- Scraper Service → External Hypixel API: calls endpoints, retrieves raw JSON.
- Scraper Service → Data Store: writes processed JSON under /gestion and /sitemap.
- Browser Frontend → Scraper Service (or direct to External API / backup_API.json): fetches JSON for display.
- Browser Frontend → Local Static Host: loads JS, CSS, images.

##### Architectural Patterns & Principles
- Client-Server separation: static SPA vs. scraping microservice.
- File-based cache/database: no traditional RDBMS—JSON files serve as datastore.
- Modular scripting: each feature (profile, inventory, bestiary) lives in its own JS file.
- Single Responsibility in scrapper: sitemap crawling, API calling, data normalization.

##### Detailed Breakdown to Capture All Elements
- Frontend:
- index.html loads /styles.css + /script/*.js
- /texture/* provides UI images
- Backend (hypixel-scraper):
- index.js is entry point
- sitemap_gestion.js builds sitemap.json → .ndjson
- sitemap_process_scrapping.js loops through URLs, invokes index.js
- /gestion/*.json hold feature-specific metadata
- Data Flow:
1. Scraper boots → reads existing sitemap.json or backup_API.json
2. Crawls new data → writes updated JSON files
3. Frontend fetches these JSONs to display up-to-date stats

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Frontend Layer"
        browser["Browser / SPA"]:::frontend
        staticserver["Static File Server"]:::frontend
        indexhtml["index.html"]:::frontend
        stylescss["styles.css"]:::frontend
        scriptfolder["script/*.js"]:::frontend
        texturefolder["texture/*"]:::frontend
    end

    subgraph "Backend Layer"
        scraper["Scraper Microservice"]:::microservice
        datastore["JSON Data Store\n(hypixel-scraper/gestion/, sitemap/)"]:::datastore
        backup["backup_API.json"]:::datastore
    end

    externalapi["Hypixel Public API"]:::external

    browser -->|GET HTML/CSS/JS/Textures| staticserver
    staticserver --> indexhtml
    staticserver --> stylescss
    staticserver --> scriptfolder
    staticserver --> texturefolder

    browser -->|"GET JSON"| scraper
    browser -->|"Fallback to backup"| backup

    scraper -->|"GET endpoints"| externalapi
    scraper -->|"Read/Write JSON"| datastore

    classDef frontend fill:#D0E8FF,stroke:#6699CC
    classDef microservice fill:#FFE5B4,stroke:#FF9933
    classDef datastore fill:#E6FFCC,stroke:#339933
    classDef external fill:#DDDDDD,stroke:#888888

    click indexhtml "https://github.com/valumane/hypixelapi/blob/main/index.html"
    click stylescss "https://github.com/valumane/hypixelapi/blob/main/styles.css"
    click scriptfolder "https://github.com/valumane/hypixelapi/tree/main/script/"
    click texturefolder "https://github.com/valumane/hypixelapi/tree/main/texture/"
    click scrindex "https://github.com/valumane/hypixelapi/blob/main/hypixel-scraper/index.js"
    click sitemgestion "https://github.com/valumane/hypixelapi/blob/main/hypixel-scraper/sitemap_gestion.js"
    click sitemapprocess "https://github.com/valumane/hypixelapi/blob/main/hypixel-scraper/sitemap_process_scrapping.js"
    click packjson "https://github.com/valumane/hypixelapi/blob/main/hypixel-scraper/package.json"
    click packlock "https://github.com/valumane/hypixelapi/blob/main/hypixel-scraper/package-lock.json"
    click gestdir "https://github.com/valumane/hypixelapi/tree/main/hypixel-scraper/gestion/"
    click sitemapdir "https://github.com/valumane/hypixelapi/tree/main/hypixel-scraper/sitemap/"
    click backup "https://github.com/valumane/hypixelapi/blob/main/backup_API.json"
```
