# square/retrofit architecture

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

- Interactive diagram: https://gitdiagram.com/square/retrofit
- Repository: https://github.com/square/retrofit

## Overview

##### Main Components
- Core Library (Retrofit Core): Represented by the “retrofit” directory. This is the heart of the library, providing the API for building HTTP requests, processing responses, and handling CallAdapters/Converters.
- Adapter Modules: Under “retrofit-adapters”, you have adapters for asynchronous types and platform-specific features (e.g., rxjava, rxjava2, rxjava3, java8, guava, scala). These modules extend the core to support various concurrency strategies and reactive programming styles.
- Converter Modules: Under “retrofit-converters”, you see support for different data formats and serialization tools (Gson, Jackson, JAXB, Kotlinx-serialization, Moshi, Protobuf, Scalars, SimpleXml, Wire). These modules plug into Retrofit to convert HTTP bodies to and from Java objects.
- Mock and Response-Type Keeper Modules: “retrofit-mock” (used for testing or mimicking API behavior) and “retrofit-response-type-keeper” (likely to preserve or process type information) are additional components that augment the core functionalities.
- Supporting/Documentation Modules: The “website” directory contains content that documents the API, modules, and usage examples. Also, test directories (like “android-test”, “java-test”, “kotlin-test”) illustrate how the library is validated across platforms.

##### Articulate Relationships and Interactions
- That “Mock” components depend on the Retrofit Core to simulate the behavior of real HTTP calls during testing.
- Optionally, indicate that tests, samples, and website/documentation are external (or “client”) consumers that interact with the library through the API provided by the Core.
- Gradle build system (and other config files) as the mechanism connecting all modules, ensuring consistency in versions and dependencies (such as those defined in gradle.properties and the Gradle wrapper).

##### Architectural Patterns and Design Principles
- Plugin Architecture: The Retrofit core is designed to be extensible through specific “converters” and “adapters”. Emphasize how these parts are loosely coupled and can be added or replaced by the user.
- Separation of Concerns: Distinct modules are responsible for HTTP handling (retrofit core), data binding (converter modules), asynchronous operation (adapter modules), and testing/mocking functionalities.
- Modularity: Each functional category (adapters, converters, mocks, etc.) is separated into its own module with its own build scripts, indicating a high degree of modular design.

##### Relevant Technologies and Frameworks
- Java and Android are the primary target platforms.
- Integration with OkHttp (and rules for R8/ProGuard) is crucial, as indicated in the README.
- On the adapters side, include references to technologies like RxJava, Java8’s CompletableFuture, Guava’s ListenableFuture, and Scala if applicable.
- In converters, include reference to popular serialization libraries such as Gson, Jackson, Moshi, Protobuf, and others.
- The build system is Gradle based, so note this as the glue that connects the modules.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Consumers
    subgraph "External Consumers"
        Ext1["Website (Documentation)"]:::external
        Ext2["Test Directories"]:::external
    end

    %% Retrofit Core is the primary component
    Core["Retrofit Core"]:::core
    click Core "https://github.com/square/retrofit/tree/trunk/retrofit/src/main/java/retrofit2"

    %% Extension Modules: Adapter Modules
    subgraph "Adapter Modules"
        A1["RxJava Adapter"]:::adapter
        A2["RxJava2 Adapter"]:::adapter
        A3["RxJava3 Adapter"]:::adapter
        A4["Java8 Adapter"]:::adapter
        A5["Guava Adapter"]:::adapter
        A6["Scala Adapter"]:::adapter
    end
    click A1 "https://github.com/square/retrofit/tree/trunk/retrofit-adapters/rxjava"
    click A2 "https://github.com/square/retrofit/tree/trunk/retrofit-adapters/rxjava2"
    click A3 "https://github.com/square/retrofit/tree/trunk/retrofit-adapters/rxjava3"
    click A4 "https://github.com/square/retrofit/tree/trunk/retrofit-adapters/java8"
    click A5 "https://github.com/square/retrofit/tree/trunk/retrofit-adapters/guava"
    click A6 "https://github.com/square/retrofit/tree/trunk/retrofit-adapters/scala"

    %% Extension Modules: Converter Modules
    subgraph "Converter Modules"
        C1["Gson Converter"]:::converter
        C2["Jackson Converter"]:::converter
        C3["Moshi Converter"]:::converter
        C4["Protobuf Converter"]:::converter
        C5["Scalars Converter"]:::converter
        C6["SimpleXml Converter"]:::converter
        C7["Wire Converter"]:::converter
        C8["Kotlinx-serialization Converter"]:::converter
        C9["JAXB Converter"]:::converter
        C10["JAXB3 Converter"]:::converter
        C11["Guava Converter"]:::converter
        C12["Java8 Converter"]:::converter
    end
    click C1 "https://github.com/square/retrofit/tree/trunk/retrofit-converters/gson"
    click C2 "https://github.com/square/retrofit/tree/trunk/retrofit-converters/jackson"
    click C3 "https://github.com/square/retrofit/tree/trunk/retrofit-converters/moshi"
    click C4 "https://github.com/square/retrofit/tree/trunk/retrofit-converters/protobuf"
    click C5 "https://github.com/square/retrofit/tree/trunk/retrofit-converters/scalars"
    click C6 "https://github.com/square/retrofit/tree/trunk/retrofit-converters/simplexml"
    click C7 "https://github.com/square/retrofit/tree/trunk/retrofit-converters/wire"
    click C8 "https://github.com/square/retrofit/tree/trunk/retrofit-converters/kotlinx-serialization"
    click C9 "https://github.com/square/retrofit/tree/trunk/retrofit-converters/jaxb"
    click C10 "https://github.com/square/retrofit/tree/trunk/retrofit-converters/jaxb3"
    click C11 "https://github.com/square/retrofit/tree/trunk/retrofit-converters/guava"
    click C12 "https://github.com/square/retrofit/tree/trunk/retrofit-converters/java8"

    %% Additional Modules
    subgraph "Additional Modules"
        Mock["Mock Module"]:::additional
        Keeper["Response-Type Keeper Module"]:::additional
    end
    click Mock "https://github.com/square/retrofit/tree/trunk/retrofit-mock"
    click Keeper "https://github.com/square/retrofit/tree/trunk/retrofit-response-type-keeper"

    %% Build & Distribution Components
    subgraph "Build & Distribution"
        B1["build.gradle"]:::build
        B2["gradle.properties"]:::build
        B3["gradle (wrapper)"]:::build
        B4["settings.gradle"]:::build
        B5["gradlew"]:::build
        B6["gradlew.bat"]:::build
    end
    click B1 "https://github.com/square/retrofit/blob/trunk/build.gradle"
    click B2 "https://github.com/square/retrofit/blob/trunk/gradle.properties"
    click B3 "https://github.com/square/retrofit/tree/trunk/gradle"
    click B4 "https://github.com/square/retrofit/blob/trunk/settings.gradle"
    click B5 "https://github.com/square/retrofit/tree/trunk/gradlew"
    click B6 "https://github.com/square/retrofit/blob/trunk/gradlew.bat"

    %% Relationships

    %% External consumers use the API provided by Retrofit Core
    Ext1 -->|"consumes"| Core
    Ext2 -->|"consumes"| Core

    %% Retrofit Core delegates to extension modules (Adapters and Converters)
    Core -->|"calls"| A1
    Core -->|"calls"| A2
    Core -->|"calls"| A3
    Core -->|"calls"| A4
    Core -->|"calls"| A5
    Core -->|"calls"| A6

    Core -->|"processes"| C1
    Core -->|"processes"| C2
    Core -->|"processes"| C3
    Core -->|"processes"| C4
    Core -->|"processes"| C5
    Core -->|"processes"| C6
    Core -->|"processes"| C7
    Core -->|"processes"| C8
    Core -->|"processes"| C9
    Core -->|"processes"| C10
    Core -->|"processes"| C11
    Core -->|"processes"| C12

    %% Retrofit Core supports additional modules for testing and type preservation
    Core -->|"simulates"| Mock
    Core -->|"captures"| Keeper

    %% Build system configures core and extension modules
    B1 -->|"configures"| Core
    B1 -->|"configures"| A1
    B1 -->|"configures"| C1
    B1 -->|"configures"| Mock
    B1 -->|"configures"| Keeper

    %% Styles
    classDef core fill:#ffcccc,stroke:#333,stroke-width:2px;
    classDef adapter fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef converter fill:#ccccff,stroke:#333,stroke-width:2px;
    classDef additional fill:#ffe599,stroke:#333,stroke-width:2px;
    classDef build fill:#ffd699,stroke:#333,stroke-width:2px;
    classDef external fill:#e0e0e0,stroke:#333,stroke-width:2px;
```
