How skydoves/sandwich works
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.