# tamong/melon-api architecture

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

- Interactive diagram: https://gitdiagram.com/tamong/melon-api
- Repository: https://github.com/tamong/melon-api

## Overview

##### Project Type and Purpose
- This project is a web API built to retrieve music data from Melon (a South Korean music streaming service), primarily via web scraping. It is built using Hono.js, TypeScript, and is designed to run on the Bun runtime with the potential for deployment on platforms like Cloudflare Workers (as indicated by the presence of wrangler.toml).
- The API exposes endpoints that serve chart, song, and album data. It incorporates features such as caching to optimize response times and a prefetching system to keep the data fresh. Additionally, it includes analytics middleware to log request data for tracking purposes.

##### Analysis of the File Structure
- Top-Level Files:
- The presence of configuration files (e.g., .env.example, tsconfig.json, wrangler.toml) and package.json indicate a structured Node.js/Bun setup.
- src/ Directory:
- index.ts: Likely the main entry point responsible for initializing the Hono server and setting up middleware/routes.
- Middleware: Contains analytics.ts, suggesting that request analytics are applied early in the request-handling pipeline.
- Routes: Multiple route files (album.ts, chart.ts, song.ts, index.ts) that segregate endpoints by functionality.
- Services: Files for album, chart, scraper, and song, which encapsulate the business logic and web scraping functions.
- Types: Provides TypeScript type definitions (charts, errors, scraper) ensuring type safety across the system.
- Utils: Includes cache, helper, and prefetch modules – these provide support functions like caching data and prefetching chart information.

##### Key Components
a. API Server Layer:
- Entry Point (src/index.ts): Initializes the Hono server.
- Hosting and Runtime: Runs on the Bun runtime (with Bun-specific configuration in bun.lock and package.json).
b. Middleware Layer:
- Analytics Middleware (src/middleware/analytics.ts): Captures and logs detailed metrics on each incoming request.
c. Routing Layer:
- API Routes (src/routes/): Includes endpoint definitions for album, chart, song, and the base endpoint.
d. Service Layer:
- Business Logic & Web Scraping Services (src/services/): Contains specific modules to fetch and process data for charts (chart.ts), songs (song.ts), albums (album.ts), and a common scraper (scraper.ts).
e. Utility and Support Components:
- Caching (src/utils/cache.ts): Manages cache storage for chart data to reduce frequent requests.
- Prefetching (src/utils/prefetch.ts): Automatically refreshes data to avoid “cold fetches.”
- Helper Functions (src/utils/helper.ts): Provides general utility functions.
f. External Dependencies:
- Melon Website: The external data source that is scraped via Cheerio.
- Cheerio Library: Used in the scraping service for parsing and extracting HTML content.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Request
    Client["Client Request"]:::client

    %% API Server Layer
    subgraph "API Layer"
        API_Server["API Server (Hono.js on Bun)"]:::api
    end

    %% Middleware Layer
    subgraph "Middleware Layer"
        Analytics_Middleware["Analytics Middleware"]:::middleware
    end

    %% Routing Layer
    subgraph "Routing Layer"
        Base_Route["Index Route"]:::routes
        Album_Route["Album Route"]:::routes
        Chart_Route["Chart Route"]:::routes
        Song_Route["Song Route"]:::routes
    end

    %% Service Layer
    subgraph "Service Layer"
        Album_Service["Album Service"]:::services
        Chart_Service["Chart Service"]:::services
        Song_Service["Song Service"]:::services
        Scraper_Service["Scraping Service (Cheerio)"]:::services
    end

    %% Utility Layer
    subgraph "Utility Layer"
        Cache_Utility["Caching Utility"]:::utilities
        Prefetch_Utility["Prefetching Utility"]:::utilities
        Helper_Utility["Helper Functions"]:::utilities
    end

    %% External Dependency
    External_Data["Melon Website"]:::external

    %% Connections
    Client -->|"sends request"| API_Server
    API_Server -->|"initializes"| Analytics_Middleware
    Analytics_Middleware -->|"routes to"| Base_Route
    Analytics_Middleware -->|"routes to"| Album_Route
    Analytics_Middleware -->|"routes to"| Chart_Route
    Analytics_Middleware -->|"routes to"| Song_Route

    Album_Route -->|"calls"| Album_Service
    Chart_Route -->|"calls"| Chart_Service
    Song_Route -->|"calls"| Song_Service

    Album_Service -->|"uses"| Scraper_Service
    Chart_Service -->|"uses"| Scraper_Service
    Song_Service -->|"uses"| Scraper_Service

    Scraper_Service -->|"fetches from"| External_Data

    Album_Service -->|"uses"| Cache_Utility
    Album_Service -->|"uses"| Prefetch_Utility
    Album_Service -->|"uses"| Helper_Utility

    Chart_Service -->|"uses"| Cache_Utility
    Chart_Service -->|"uses"| Prefetch_Utility
    Chart_Service -->|"uses"| Helper_Utility

    Song_Service -->|"uses"| Cache_Utility
    Song_Service -->|"uses"| Prefetch_Utility
    Song_Service -->|"uses"| Helper_Utility

    %% Click Events
    click API_Server "https://github.com/tamong/melon-api/blob/main/src/index.ts"
    click Analytics_Middleware "https://github.com/tamong/melon-api/blob/main/src/middleware/analytics.ts"
    click Album_Route "https://github.com/tamong/melon-api/blob/main/src/routes/album.ts"
    click Chart_Route "https://github.com/tamong/melon-api/blob/main/src/routes/chart.ts"
    click Song_Route "https://github.com/tamong/melon-api/blob/main/src/routes/song.ts"
    click Base_Route "https://github.com/tamong/melon-api/blob/main/src/routes/index.ts"
    click Album_Service "https://github.com/tamong/melon-api/blob/main/src/services/album.ts"
    click Chart_Service "https://github.com/tamong/melon-api/blob/main/src/services/chart.ts"
    click Song_Service "https://github.com/tamong/melon-api/blob/main/src/services/song.ts"
    click Scraper_Service "https://github.com/tamong/melon-api/blob/main/src/services/scraper.ts"
    click Cache_Utility "https://github.com/tamong/melon-api/blob/main/src/utils/cache.ts"
    click Prefetch_Utility "https://github.com/tamong/melon-api/blob/main/src/utils/prefetch.ts"
    click Helper_Utility "https://github.com/tamong/melon-api/blob/main/src/utils/helper.ts"

    %% Styles
    classDef api fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef middleware fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef routes fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef services fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef utilities fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef external fill:#e2e3e5,stroke:#41464b,stroke-width:2px;
    classDef client fill:#e6e6fa,stroke:#6a5acd,stroke-width:2px;
```
