# holidays-jp/api architecture

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

- Interactive diagram: https://gitdiagram.com/holidays-jp/api
- Repository: https://github.com/holidays-jp/api

## Overview

##### Project Type and Purpose
- This is a lightweight backend-only API (“Holidays JP API”) written in PHP.
- It serves Japanese holiday data in JSON or CSV format, versioned by year, and publishes a static docs site.

##### File Structure Analysis
- Top-level:
- app/holidaysJP.php – core PHP class that reads holiday data and formats output.
- main.php – HTTP entry point (routes requests to the class).
- docs/ – pre-generated JSON/CSV files plus static HTML docs for each API version.
- composer.json – dependency management; phpunit.xml and tests/ – test suite.
- .github/workflows – CI pipelines for building, testing, and updating docs site.
- Pattern: Single-service MVC-lite (“controller” in main.php, “model” in app/, “view” = formatted JSON/CSV).

##### README Insights
- Confirms it’s an MIT-licensed, publicly hosted API with published docs.
- No external microservices—pure PHP service + static hosting.

##### Main Components
a. HTTP Client (consumer) – issues GET /v{year}/{format} requests.
b. Web Server (nginx or Apache) – routes to main.php.
c. PHP Runtime – runs main.php and app/holidaysJP.php.
d. File Storage – docs/v1/{year}/{date,datetime}.json|csv (holiday data).
e. CI/CD Pipeline (GitHub Actions) – runs tests, regenerates docs, deploys to GitHub Pages.
f. Static Docs Host (GitHub Pages or CDN).

##### Relationships and Data Flow
1. Client → Web Server: HTTP GET request.
2. Web Server → main.php: passes route parameters (version, year, format).
3. main.php → holidaysJP class: invokes method to load data.
4. holidaysJP → File Storage: reads JSON/CSV file for requested year and format.
5. holidaysJP → main.php: returns array or string payload.
6. main.php → Web Server → Client: HTTP response with JSON/CSV.
7. Developer Push → GitHub Actions: checkout → composer install → phpunit tests → regenerate docs → deploy docs to GitHub Pages.

##### Architectural Patterns / Design Principles
- Single Responsibility: holidaysJP class solely handles data retrieval and formatting.
- File-Based Storage: versioned flat files avoid database complexity.
- CI/CD Automation: ensures code quality and documentation consistency.
- Separation: dynamic API vs. static docs site.

##### Technologies, Frameworks, Libraries
- PHP 7+ (native)
- Composer (package management)
- PHPUnit (testing)
- GitHub Actions (CI/CD)
- GitHub Pages or any static file host for docs

##### Detail Level
- Moving parts: API entry, processing class, file reads, test suite, CI workflows, static site.
- Don’t over-split trivial elements; focus on logical groupings.
- Enough detail so a newcomer can trace “How does a GET request become JSON?” and “How do docs get published?”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Runtime Zone
    subgraph "Dynamic API Service"
        direction TB
        Client["HTTP Client"]:::external
        WebServer["Web Server (nginx/apache)"]:::runtime
        Main["main.php"]:::runtime
        HolidaysService["holidaysJP Class"]:::runtime
        FileStorage["Holiday Data<br/>docs/v1/ JSON/CSV"]:::storage
    end

    %% Static Docs Zone
    subgraph "Static Docs Host"
        direction TB
        StaticHTML["Static Docs Site<br/>docs/index.html"]:::storage
        StaticData["HTML Docs & Data<br/>docs/v1/"]:::storage
    end

    %% CI/CD Zone
    subgraph "CI/CD Pipeline"
        direction TB
        Repo["GitHub Repo"]:::cicd
        subgraph "GitHub Actions" 
            direction TB
            BuildYml["build.yml"]:::cicd
            TouchYml["touch.yml"]:::cicd
        end
        Composer["composer.json<br/>composer.lock"]:::cicd
        TestSuite["phpunit.xml & tests/"]:::cicd
    end

    %% Runtime Flows
    Client -->|"GET /v{year}/{format}"| WebServer
    WebServer -->|"route to main.php"| Main
    Main -->|"invoke loadData()"| HolidaysService
    HolidaysService -->|"read file"| FileStorage
    HolidaysService -->|"return payload"| Main
    Main -->|"response"| WebServer
    WebServer -->|"HTTP response"| Client

    %% CI/CD Flows (dashed)
    Repo -.->|push code| BuildYml
    BuildYml -->|composer install| Composer
    BuildYml -->|run tests| TestSuite
    BuildYml -->|regenerate docs| TouchYml
    TouchYml -.->|deploy docs| StaticHTML
    TouchYml -.->|deploy data| StaticData

    %% Click Events
    click Main "https://github.com/holidays-jp/api/blob/master/main.php"
    click HolidaysService "https://github.com/holidays-jp/api/blob/master/app/holidaysJP.php"
    click FileStorage "https://github.com/holidays-jp/api/tree/master/docs/v1/"
    click StaticHTML "https://github.com/holidays-jp/api/blob/master/docs/index.html"
    click StaticData "https://github.com/holidays-jp/api/tree/master/docs/v1/"
    click BuildYml "https://github.com/holidays-jp/api/blob/master/.github/workflows/build.yml"
    click TouchYml "https://github.com/holidays-jp/api/blob/master/.github/workflows/touch.yml"
    click Composer "https://github.com/holidays-jp/api/blob/master/composer.json"
    click Composer "https://github.com/holidays-jp/api/blob/master/composer.lock"
    click TestSuite "https://github.com/holidays-jp/api/blob/master/phpunit.xml"
    click TestSuite "https://github.com/holidays-jp/api/tree/master/tests/"
    click Repo "https://github.com/holidays-jp/api/blob/master/README.md"
    click Repo "https://github.com/holidays-jp/api/tree/master/LICENCE"

    %% Styles
    classDef runtime fill:#BBE1FA,stroke:#333,stroke-width:1px
    classDef storage fill:#B2F2BB,stroke:#333,stroke-width:1px
    classDef cicd fill:#FFDEB4,stroke:#333,stroke-width:1px
    classDef external fill:#E0E0E0,stroke:#333,stroke-width:1px
```
