# maxswa/osrs-json-hiscores architecture

> Architecture diagram of the GitHub repository maxswa/osrs-json-hiscores, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/maxswa/osrs-json-hiscores
- Repository: https://github.com/maxswa/osrs-json-hiscores

## Overview

##### Main Components

a. External Systems:
- OSRS Official Hiscores API (CSV endpoint)
- OSRS Leaderboards Web Interface

b. Core Library Components:
- API Interface Layer
- Data Transformation Layer
- Type System
- Utility Services

##### Component Relationships

**[External Systems]**
**┌─────────────────────┐    ┌────────────────────┐**
- OSRS Hiscores API   │    │ OSRS Leaderboards  │
- (CSV Format)        │    │ (Web Interface)    │
- ┘    └────────────────────┘
- ↑                         ↑

**[OSRS JSON Hiscores Library]**
**┌─────────────────────────────────────────────┐**
- API Interface Layer                         │
- ┌─────────────────┐    ┌─────────────────┐ │
- Stats Fetcher   │    │ Leaderboard     │ │
- (hiscores.ts)   │    │ Scraper         │ │
- ┘    └─────────────────┘ │
- ↓                  ↓             │
- ┌─────────────────────────────────────────┐ │
- Data Transformation Layer        │ │
- (CSV to JSON, Data Enrichment)      │ │
- ┘ │
- ↓                  ↓             │
- ┌─────────────────────────────────────────┐ │
- Type System Layer             │ │
- (types.ts)                   │ │
- ┘ │
- ↓                  ↓             │
- ┌─────────────────────────────────────────┐ │
- Utility Services              │ │
- (constants.ts, helpers.ts)            │ │
- ┘ │
- ┘
- ↓
**┌─────────────────────────────────────────────┐**
- Client Applications               │
- (Server-side Node.js Applications)       │
- ┘

##### Important Details to Note

Annotations explaining:
- CORS limitations (why it must be used server-side)
- Data flow direction (from OSRS API → Library → Client)
- Supported game modes (main, ironman, hardcore, etc.)
- Type safety through TypeScript implementation

##### Clear separation between external services and internal processing

Keep the abstraction level focused on the architectural components while maintaining enough detail to show the data enrichment process and type safety mechanisms.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Systems
    subgraph External["External Systems"]
        OSRS[OSRS Hiscores API]:::external
        WEB[OSRS Leaderboards Web]:::external
    end

    %% Main Library
    subgraph Library["OSRS JSON Hiscores Library"]
        %% API Interface Layer
        subgraph API["API Interface Layer"]
            StatsFetcher["Stats Fetcher"]:::core
            LeaderScraper["Leaderboard Scraper"]:::core
        end

        %% Data Transformation
        subgraph Transform["Data Transformation Layer"]
            CSVtoJSON["CSV to JSON Converter"]:::transform
            DataEnrich["Data Enrichment"]:::transform
        end

        %% Type System
        subgraph Types["Type System Layer"]
            TypeDefs["Type Definitions"]:::types
            Validation["Data Validation"]:::types
        end

        %% Utility Services
        subgraph Utils["Utility Services"]
            Constants["Constants Service"]:::util
            Helpers["Helpers Service"]:::util
        end
    end

    %% Client Applications
    ClientApps["Node.js Client Applications"]:::client

    %% Relationships
    OSRS --> StatsFetcher
    WEB --> LeaderScraper
    StatsFetcher --> CSVtoJSON
    LeaderScraper --> DataEnrich
    CSVtoJSON --> DataEnrich
    DataEnrich --> TypeDefs
    TypeDefs --> Validation
    Validation --> ClientApps
    Constants --> StatsFetcher
    Constants --> LeaderScraper
    Helpers --> CSVtoJSON
    Helpers --> DataEnrich

    %% Click Events
    click StatsFetcher "https://github.com/maxswa/osrs-json-hiscores/blob/main/src/hiscores.ts"
    click TypeDefs "https://github.com/maxswa/osrs-json-hiscores/blob/main/src/types.ts"
    click Constants "https://github.com/maxswa/osrs-json-hiscores/blob/main/src/utils/constants.ts"
    click Helpers "https://github.com/maxswa/osrs-json-hiscores/blob/main/src/utils/helpers.ts"
    click Utils "https://github.com/maxswa/osrs-json-hiscores/tree/main/src/utils/"

    %% Styling
    classDef external fill:#a8d1f0,stroke:#333
    classDef core fill:#90EE90,stroke:#333
    classDef transform fill:#FFB347,stroke:#333
    classDef types fill:#FFE5B4,stroke:#333
    classDef util fill:#F0E68C,stroke:#333
    classDef client fill:#D3D3D3,stroke:#333

    %% Legend
    subgraph Legend
        L1[External Systems]:::external
        L2[Core Components]:::core
        L3[Data Transformation]:::transform
        L4[Type System]:::types
        L5[Utility Services]:::util
        L6[Client Applications]:::client
    end
```
