# jikan-me/jikan architecture

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

- Interactive diagram: https://gitdiagram.com/jikan-me/jikan
- Repository: https://github.com/jikan-me/jikan

## Overview

##### Project Type and Purpose
- Jikan is a PHP library and API that scrapes MyAnimeList’s website to provide an unofficial API. Its purpose is to abstract the complexities of web scraping and parsing by offering easy-to-use classes to fetch and convert MyAnimeList data into PHP objects.
- This project primarily serves as a backend library, with its consumers being other applications (or even a REST API built on top of it) needing MAL data.

##### Key Components
- API Client & Request Manager:
- HTTP client layer. Highlight the “src/MyAnimeList/MalClient.php” as the central API client that issues HTTP requests.
- “src/Request” folder which is subdivided into multiple domains (Anime, Manga, Character, etc.). Each Request class (for example, AnimeRequest, MangaRequest, etc.) encapsulates how to call specific endpoints on MyAnimeList via scraping.
- Parsing Layer:
- “src/Parser” directory, which is organized into multiple subdirectories (Anime, Manga, Character, Forum, etc.). Each parser (e.g., AnimeParser, MangaParser, etc.) takes raw HTML or response data received from MyAnimeList and converts it into structured data.
- A directional flow from the Request layer to the Parser layer.
- Data Model Layer:
- “src/Model” directory. These components (like Anime, Manga, Character entities, etc.) represent the domain-specific objects that the API returns.
- That Models are the outcome of the data processed by their corresponding Parsers.
- Utility and Helper Components:
- Elements from “src/Helper” (such as Constants, Media, Parser, etc.), which provide shared utilities and common functionality across the library.
- Exception Handling:
- “src/Exception” components for managing errors (e.g., BadResponseException, ParserException).
- Third-Party Integration:
- “src/Goutte” folder (containing GoutteWrapper) to highlight its role in web scraping. This shows that Jikan leverages the Goutte library (a PHP web scraping library) to retrieve HTML data from MyAnimeList.
- Testing & Quality Assurance:

##### Architectural Relationships and Interaction Flow
- The consumer calls the API Client (MalClient), which then constructs a specific Request (e.g., AnimeRequest) based on the domain data needed.
- The Request component performs an HTTP call via GoutteWrapper, fetching raw HTML from MyAnimeList.
- Fetched HTML is passed to the appropriate Parser (e.g., AnimeParser, MangaParser) which extracts and structures the data.
- The Parser then instantiates and populates a Model object (for example, an Anime model) representing the data.
- Any errors encountered are thrown as Exceptions (BadResponseException, ParserException) and handled accordingly.
- Optionally, note the use of Helper utilities for common operations and constants that drive consistent behavior across components.

##### Design Principles and Patterns
- Layered Architecture: Clearly segment the Request, Parser, Model, and Utility layers.
- Separation of Concerns: Each directory and set of files (like Request, Parser, and Model) is responsible for a distinct aspect of the data flow.
- Modularity: The organized subdirectories (Anime, Manga, Character, etc.) show domain-driven structures that are independently extendable.
- Error Handling: Centralize error management with dedicated Exception classes.

## Diagram (Mermaid)

```mermaid
flowchart TD 
    %% Top Layer: API Consumer
    Consumer["API Consumer"]:::consumer

    %% Layer 1: API Client
    Client["MalClient (API Client)"]:::client

    %% Layer 2: Request Layer
    subgraph "Request Layer"
        Req["Request Classes (e.g., AnimeRequest, MangaRequest)"]:::request
    end

    %% Layer 3: Third-Party Integration
    Goutte["GoutteWrapper (Web Scraper)"]:::goutte

    %% Layer 4: Parsing Layer
    Parser["Parser (e.g., AnimeParser)"]:::parser

    %% Layer 5: Data Model Layer
    Model["Model (e.g., Anime Model)"]:::model

    %% Side Box: Utility & Helper Components
    Helper["Helpers & Utilities"]:::helper

    %% Side Box: Exception Handling
    Exception["Exception Handling"]:::exception

    %% Side Box: Testing & Quality Assurance
    TestSuite["Test Suite (PHPUnit, GrumPHP)"]:::tests

    %% Main Flow Connections
    Consumer -->|"calls"| Client
    Client -->|"creates_request"| Req
    Req -->|"fetches_HTML_via"| Goutte
    Goutte -->|"provides_HTML_to"| Parser
    Parser -->|"populates"| Model

    %% Utility Usage (dashed arrows)
    Client ---|"uses"| Helper
    Req ---|"uses"| Helper
    Parser ---|"uses"| Helper
    Model ---|"uses"| Helper

    %% Exception Handling (dotted arrows)
    Client -.->|"throws"| Exception
    Req -.->|"throws"| Exception
    Parser -.->|"throws"| Exception
    Goutte -.->|"throws"| Exception

    %% Testing connection (illustrative, not in main flow)
    TestSuite ---|"tests"| Client
    TestSuite ---|"tests"| Req
    TestSuite ---|"tests"| Parser
    TestSuite ---|"tests"| Model

    %% Click Events
    click Client "https://github.com/jikan-me/jikan/blob/master/src/MyAnimeList/MalClient.php"
    click Req "https://github.com/jikan-me/jikan/tree/master/src/Request"
    click Parser "https://github.com/jikan-me/jikan/tree/master/src/Parser"
    click Model "https://github.com/jikan-me/jikan/tree/master/src/Model"
    click Helper "https://github.com/jikan-me/jikan/tree/master/src/Helper"
    click Exception "https://github.com/jikan-me/jikan/tree/master/src/Exception"
    click Goutte "https://github.com/jikan-me/jikan/tree/master/src/Goutte"
    click TestSuite "https://github.com/jikan-me/jikan/tree/master/test"

    %% Styles
    classDef consumer fill:#ffebcd,stroke:#b8860b,stroke-width:2px
    classDef client fill:#add8e6,stroke:#00008b,stroke-width:2px
    classDef request fill:#87cefa,stroke:#1e90ff,stroke-width:2px
    classDef goutte fill:#dda0dd,stroke:#800080,stroke-width:2px
    classDef parser fill:#90ee90,stroke:#006400,stroke-width:2px
    classDef model fill:#ffdab9,stroke:#ff8c00,stroke-width:2px
    classDef helper fill:#d3d3d3,stroke:#696969,stroke-width:2px
    classDef exception fill:#ffcccb,stroke:#ff0000,stroke-width:2px
    classDef tests fill:#ffffe0,stroke:#ffd700,stroke-width:2px
```
