# dingo/api architecture

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

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

## Overview

##### Project type and purpose
- This is a PHP library/package (“dingo/api”) that plugs into Laravel or Lumen applications to provide a full-featured API toolkit.
- Its core goal is to add content negotiation, versioning, authentication adapters, rate limiting, response transformation, exception handling, internal requests, and documentation support to a host application.

##### File structure
- Top-level files: composer.json, config/api.php, phpunit.xml.dist, readme.md – typical of a PHP package.
- src/
- Auth: authentication managers and adapters (Basic, JWT, Authorization).
- Console: custom Artisan commands (cache, docs, routes).
- Contract: interfaces for Auth, Debug, HTTP parser, RateLimit, Request, Validator, Routing, Transformer – defines extension points.
- Dispatcher.php: orchestrates HTTP request dispatch to controllers.
- Event: domain events (RequestWasMatched, ResponseIsMorphing, ResponseWasMorphed).
- Exception: custom exception classes and a Handler.
- Facade: API and Route facades for syntactic sugar.
- Http: middleware layers (Auth, RateLimit, PrepareController, Request), request and response implementations, parsers, formatters and validators.
- Provider: service providers to bootstrap this package into Laravel, Lumen, routing, HTTP.
- Routing: adapters for Laravel or Lumen routers, resource registration, URL generation.
- Transformer: adapters (Fractal), factory, binding for resource → representation.
- tests/: extensive unit tests covering all modules.

##### README for additional insights
- Core features listed match the modules in src/: content negotiation, auth adapters, versioning, rate limiting, transformers, error handling, internal requests, docs.
- Mentions plug-in nature for Laravel and Lumen.

##### Essential elements
- Notes or callouts to show where configuration & facades fit in

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Service Providers & Configuration
    subgraph "Service Providers & Configuration"
        direction TB
        SP1["DingoServiceProvider"]:::serviceProvider
        SP2["HttpServiceProvider"]:::serviceProvider
        SP3["RoutingServiceProvider"]:::serviceProvider
        SP4["LaravelServiceProvider"]:::serviceProvider
        SP5["LumenServiceProvider"]:::serviceProvider
        CFG["config/api.php"]:::serviceProvider
        F1["Facade/API"]:::serviceProvider
        F2["Facade/Route"]:::serviceProvider
    end

    %% HTTP Runtime
    subgraph "HTTP Runtime"
        direction TB
        HTTP_REQ["Incoming HTTP Request"]:::http
        DISP["Dispatcher"]:::http
        subgraph "Router Adapters"
            direction TB
            RADPT_LA["RouterAdapter/Laravel"]:::http
            RADPT_LU["RouterAdapter/Lumen"]:::http
        end
        subgraph "Middleware Pipeline"
            direction TB
            MW1["RateLimit"]:::http
            MW2["Auth"]:::http
            MW3["PrepareController"]:::http
            MW4["Request"]:::http
        end
        CTRL["Controller / Resource Handler"]:::http
    end

    %% Subsystems
    subgraph "Auth Subsystem"
        direction TB
        AUTH["Auth Manager"]:::subsystem
        AP1["Basic Provider"]:::subsystem
        AP2["JWT Provider"]:::subsystem
        AP3["Authorization Provider"]:::subsystem
    end

    subgraph "Rate Limiting Subsystem"
        direction TB
        RL_HANDLER["RateLimit Handler"]:::subsystem
        THR1["Throttle"]:::subsystem
        THR2["Authenticated Throttle"]:::subsystem
        THR3["Unauthenticated Throttle"]:::subsystem
        THR4["Route Throttle"]:::subsystem
    end

    subgraph "Request/Response Subsystem"
        direction TB
        REQ_SUB["Request Parser & Validator"]:::subsystem
        IR["InternalRequest"]:::subsystem
        RESP_FACTORY["Response Factory"]:::subsystem
        FMT1["Json Formatter"]:::subsystem
        FMT2["Jsonp Formatter"]:::subsystem
        FMT3["JsonOptionalFormatting"]:::subsystem
    end

    subgraph "Transformation Subsystem"
        direction TB
        TF_FACTORY["Transformer Factory"]:::subsystem
        TF_ADPT["Fractal Adapter"]:::subsystem
        TF_BIND["Transformer Binding"]:::subsystem
    end

    %% Events & Exception
    subgraph "Events & Exception"
        direction TB
        EVT1["RequestWasMatched"]:::event
        EVT2["ResponseIsMorphing"]:::event
        EVT3["ResponseWasMorphed"]:::event
        EXH["Exception Handler"]:::event
    end

    %% Console Commands
    subgraph "Console Commands"
        direction TB
        CMD1["Cache Command"]:::console
        CMD2["Docs Command"]:::console
        CMD3["Routes Command"]:::console
    end

    %% Flow
    HTTP_REQ --> DISP
    DISP --> RADPT_LA
    DISP --> RADPT_LU
    RADPT_LA --> EVT1
    RADPT_LU --> EVT1
    EVT1 --> MW1
    MW1 --> MW2
    MW2 --> MW3
    MW3 --> MW4
    MW4 --> CTRL
    CTRL --> IR
    CTRL --> TF_FACTORY
    TF_FACTORY --> TF_ADPT
    TF_ADPT --> TF_BIND
    TF_BIND --> EVT2
    EVT2 --> FMT1
    EVT2 --> FMT2
    EVT2 --> FMT3
    FMT1 --> EVT3
    FMT2 --> EVT3
    FMT3 --> EVT3
    EVT3 --> RESP_FACTORY
    RESP_FACTORY -->|"HTTP Response"| HTTP_REQ

    %% Exception flow
    CTRL --> EXH
    MW1 --> EXH
    MW2 --> EXH
    DISP --> EXH

    %% ServiceProvider hooks
    SP1 --> DISP
    SP2 --> HTTP_REQ
    SP3 --> RADPT_LA
    SP3 --> RADPT_LU
    SP4 --> SP1
    SP5 --> SP1

    %% Console uses subsystems
    CMD1 --> RADPT_LA
    CMD1 --> TF_FACTORY
    CMD2 --> RADPT_LA
    CMD2 --> TF_FACTORY
    CMD3 --> RADPT_LA

    %% Facades
    F1 --> DISP
    F2 --> RADPT_LA

    %% Click Events
    click SP1 "https://github.com/dingo/api/blob/master/src/Provider/DingoServiceProvider.php"
    click SP2 "https://github.com/dingo/api/blob/master/src/Provider/HttpServiceProvider.php"
    click SP3 "https://github.com/dingo/api/blob/master/src/Provider/RoutingServiceProvider.php"
    click SP4 "https://github.com/dingo/api/blob/master/src/Provider/LaravelServiceProvider.php"
    click SP5 "https://github.com/dingo/api/blob/master/src/Provider/LumenServiceProvider.php"
    click DISP "https://github.com/dingo/api/blob/master/src/Dispatcher.php"
    click RADPT_LA "https://github.com/dingo/api/blob/master/src/Routing/Adapter/Laravel.php"
    click RADPT_LU "https://github.com/dingo/api/blob/master/src/Routing/Adapter/Lumen.php"
    click MW1 "https://github.com/dingo/api/blob/master/src/Http/Middleware/RateLimit.php"
    click MW2 "https://github.com/dingo/api/blob/master/src/Http/Middleware/Auth.php"
    click MW3 "https://github.com/dingo/api/blob/master/src/Http/Middleware/PrepareController.php"
    click MW4 "https://github.com/dingo/api/blob/master/src/Http/Middleware/Request.php"
    click AUTH "https://github.com/dingo/api/blob/master/src/Auth/Auth.php"
    click AP1 "https://github.com/dingo/api/blob/master/src/Auth/Provider/Basic.php"
    click AP2 "https://github.com/dingo/api/blob/master/src/Auth/Provider/JWT.php"
    click AP3 "https://github.com/dingo/api/blob/master/src/Auth/Provider/Authorization.php"
    click RL_HANDLER "https://github.com/dingo/api/blob/master/src/Http/RateLimit/Handler.php"
    click THR1 "https://github.com/dingo/api/blob/master/src/Http/RateLimit/Throttle/Throttle.php"
    click THR2 "https://github.com/dingo/api/blob/master/src/Http/RateLimit/Throttle/Authenticated.php"
    click THR3 "https://github.com/dingo/api/blob/master/src/Http/RateLimit/Throttle/Unauthenticated.php"
    click THR4 "https://github.com/dingo/api/blob/master/src/Http/RateLimit/Throttle/Route.php"
    click IR "https://github.com/dingo/api/blob/master/src/Http/InternalRequest.php"
    click EVT1 "https://github.com/dingo/api/blob/master/src/Event/RequestWasMatched.php"
    click EVT2 "https://github.com/dingo/api/blob/master/src/Event/ResponseIsMorphing.php"
    click EVT3 "https://github.com/dingo/api/blob/master/src/Event/ResponseWasMorphed.php"
    click EXH "https://github.com/dingo/api/blob/master/src/Exception/Handler.php"
    click CMD1 "https://github.com/dingo/api/blob/master/src/Console/Command/Cache.php"
    click CMD2 "https://github.com/dingo/api/blob/master/src/Console/Command/Docs.php"
    click CMD3 "https://github.com/dingo/api/blob/master/src/Console/Command/Routes.php"
    click F1 "https://github.com/dingo/api/blob/master/src/Facade/API.php"
    click F2 "https://github.com/dingo/api/blob/master/src/Facade/Route.php"
    click CFG "https://github.com/dingo/api/blob/master/config/api.php"

    %% Styles
    classDef serviceProvider fill:#AED6F1,stroke:#2E86C1,color:#1B4F72
    classDef http fill:#A9DFBF,stroke:#27AE60,color:#145A32
    classDef subsystem fill:#F9E79F,stroke:#B7950B,color:#7D6608
    classDef event fill:#D7BDE2,stroke:#8E44AD,color:#4A235A
    classDef console fill:#D5D8DC,stroke:#7B7D7D,color:#2C3E50
```
