# skydoves/sandwich architecture

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

- Interactive diagram: https://gitdiagram.com/skydoves/sandwich
- Repository: https://github.com/skydoves/sandwich

## Overview

Based on our analysis of both the file tree and the README, this project is a multi-module Kotlin library designed for standardized network response handling. Its purpose is to simplify how API responses are processed in Android, backend, and even Kotlin Multiplatform projects. The core idea is to wrap network (or I/O) responses into an ApiResponse abstraction (with Success, Failure.Error, and Failure.Exception) along with rich extension functions, mappers, and operators—including the unique “Operator” and “Global Operator” patterns for consistent and reusable response handling.

##### Main Components to Highlight
- Core Library Module (e.g., the “sandwich” module) – This is where the base classes, interfaces (like ApiResponse and its subtypes), extension functions (onSuccess, onError, etc.), mappers, and common operators reside.
- Integration Modules – These include submodules like “sandwich-retrofit”, “sandwich-ktor”, “sandwich-ktorfit”, “sandwich-retrofit-serialization”, “sandwich-retrofit-datasource”. They extend and integrate the core functionality with specific networking libraries (Retrofit, Ktor, etc.).
- Demo Application (the “app” module) – This acts as an example usage of the library, demonstrating how to apply global operators, data flow through network requests, and UI interactions.
- Baseline Profile Module – Used mainly for profiling and performance aspects.
- Build & CI/CD Modules – (e.g., “buildSrc”, the GitHub workflows) which manage build configurations, code quality (Spotless), and deployment pipelines.
- Documentation – The “docs” directory, along with mkdocs configuration, supports the generation of up-to-date online documentation.

##### Relationships and Interactions
- The Demo Application uses the Core Library module (and by extension, the integration components) to invoke network calls and process responses using the provided extension functions.
- The integration modules depend on the core module. They add specific adapters, interceptors, and converters that tailor the ApiResponse handling to particular networking stacks.
- Global Operator components (configured via SandwichInitializer in the demo app or within an Application class) interact with both the core and integration layers to uniformly handle errors (e.g., token refreshing) or custom error mapping across all network calls.
- The Build & CI/CD modules interface with all components via automated workflows (build, publish docs, etc.).

##### Architectural Patterns and Design Principles
- Modular Design: The project is subdivided into specific modules (core, integration, demo app, etc.) to promote separation of concerns.
- Operator Pattern: Notice the extensive use of both regular and suspend “operators” to encapsulate and reuse business logic for response handling.
- Extension Functions: The library uses Kotlin’s extension functions to add behavior (like onSuccess, onError) directly to the ApiResponse objects.
- Global Configuration: The pattern of initializing global operators via a SandwichInitializer for consistent behavior.
- Dependency Injection (as shown in the Hilt examples) to manage global operator dependencies, especially important in larger applications.

##### Relevant Technologies, Frameworks, and Libraries
- Kotlin Multiplatform and Coroutines – to support asynchronous and multi-environment usage.
- Retrofit, Ktor, and Ktorfit integrations serve as external system interfaces.
- DI frameworks such as Hilt for dependency injection as seen in the global operator examples.
- Build tools and Quality modules including Gradle/Kotlin DSL and Spotless for code formatting and automatically bundling ProGuard rules.

##### Summary
- Surround it with integration modules that extend to specific networking frameworks.
- How the Demo Application ties everything together via API calls, global operators, and error-handling flows.
- Don’t forget to include ancillary modules (build tools, docs, baseline profiling), as they are vital for the overall project architecture.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & CI/CD Modules
    subgraph "Build & CI/CD Modules"
        BuildConfig["Build Configuration"]:::build
        Workflows["CI/CD Workflows"]:::build
        BuildScripts["Additional Build Scripts"]:::build
    end

    %% Core Library Module
    subgraph "Core Library"
        CoreLibrary["Core Library Module\n(ApiResponse, Operators)"]:::core
    end

    %% Integration Modules
    subgraph "Integration Modules"
        Retrofit["Retrofit Integration"]:::integration
        Ktor["Ktor Integration"]:::integration
        Ktorfit["Ktorfit Integration"]:::integration
        RetrofitSer["Retrofit Serialization"]:::integration
        RetrofitDS["Retrofit Datasource"]:::integration
    end

    %% Demo Application
    subgraph "Demo Application"
        DemoApp["Demo Application"]:::demo
    end

    %% Baseline Profile Module
    subgraph "Baseline Profile"
        Baseline["Baseline Profile Module"]:::profile
    end

    %% Documentation
    subgraph "Documentation"
        DocsFolder["Documentation Folder"]:::docs
        Mkdocs["mkdocs.yml Configuration"]:::docs
    end

    %% Relationships
    %% Integration Modules depend on Core Library
    Retrofit -->|"depends_on"| CoreLibrary
    Ktor -->|"depends_on"| CoreLibrary
    Ktorfit -->|"depends_on"| CoreLibrary
    RetrofitSer -->|"depends_on"| CoreLibrary
    RetrofitDS -->|"depends_on"| CoreLibrary

    %% Demo Application uses Core Library and configures global operators across integrations
    DemoApp -->|"invokes"| CoreLibrary
    DemoApp -->|"configures_global_operator"| Retrofit
    DemoApp -->|"configures_global_operator"| Ktor
    DemoApp -->|"configures_global_operator"| Ktorfit
    DemoApp -->|"configures_global_operator"| RetrofitSer
    DemoApp -->|"configures_global_operator"| RetrofitDS

    %% Build & CI/CD Modules interface with key components
    BuildConfig -->|"configures"| CoreLibrary
    Workflows -->|"triggers_build"| DemoApp
    BuildScripts -->|"supports_build"| CoreLibrary

    %% Documentation is generated from Core Library and Demo Application
    CoreLibrary -->|"generates_docs"| DocsFolder
    DemoApp -->|"documented_in"| DocsFolder

    %% Baseline Profile monitors the Demo Application performance
    DemoApp -->|"monitored_by"| Baseline

    %% Click Events
    click CoreLibrary "https://github.com/skydoves/sandwich/tree/main/sandwich/src/commonMain/kotlin/com/skydoves/sandwich"
    click Retrofit "https://github.com/skydoves/sandwich/tree/main/sandwich-retrofit"
    click Ktor "https://github.com/skydoves/sandwich/tree/main/sandwich-ktor"
    click Ktorfit "https://github.com/skydoves/sandwich/tree/main/sandwich-ktorfit"
    click RetrofitDS "https://github.com/skydoves/sandwich/tree/main/sandwich-retrofit-datasource"
    click RetrofitSer "https://github.com/skydoves/sandwich/tree/main/sandwich-retrofit-serialization"
    click DemoApp "https://github.com/skydoves/sandwich/tree/main/app"
    click Baseline "https://github.com/skydoves/sandwich/tree/main/baselineprofile"
    click BuildConfig "https://github.com/skydoves/sandwich/tree/main/buildSrc"
    click Workflows "https://github.com/skydoves/sandwich/tree/main/.github/workflows"
    click BuildScripts "https://github.com/skydoves/sandwich/blob/main/scripts/publish-module.gradle.kts"
    click DocsFolder "https://github.com/skydoves/sandwich/tree/main/docs"
    click Mkdocs "https://github.com/skydoves/sandwich/blob/main/mkdocs.yml"

    %% Styles
    classDef core fill:#ffcccc,stroke:#990000,stroke-width:2px;
    classDef integration fill:#ccffcc,stroke:#006600,stroke-width:2px;
    classDef demo fill:#ccccff,stroke:#000099,stroke-width:2px;
    classDef build fill:#ffffcc,stroke:#999900,stroke-width:2px;
    classDef profile fill:#ccffff,stroke:#009999,stroke-width:2px;
    classDef docs fill:#ffccff,stroke:#990099,stroke-width:2px;
```
