How m2f-kt/archer works
Project Type and Purpose
• This is an open-source, multi-platform Kotlin library (Archer) that implements a lightweight Functional Clean Architecture DSL.
• It provides core abstractions for UseCases, Repositories, DataSources (remote & local), caching strategies, mappers, and error handling.
• There is a second module (“database”) that supplies a platform-agnostic SQLDelight-based storage backend and driver factories.
File Structure Analysis
• Top-level modules:
• archer-core (the library’s core DSL and abstractions)
• database (SQLDelight-powered persistence)
• docs (Docusaurus site for documentation)
• Each module is configured as a Kotlin Multiplatform project (sources under commonMain/androidMain/jvmMain/jsMain/iosMain/nativeMain).
• archery-core contains:
• DSL builders (ice, either, nullable, raise)
• Repository & DataSource interfaces and default InMemoryDataSource implementations
• CRUD abstractions (GetRepositoryStrategy, StoreDataSource, etc.)
• Concurrency primitives (Mutex)
• Failure handling (HttpStatusHandler, Failure)
• database contains:
• DatabaseDriverFactory per platform
• SQLDelight schema under commonMain/sqldelight
• ArcherInitializer to set up the database on startup
Architecture Insights from README
• The core architecture follows the Clean Architecture flow:
UseCase → Repository → RemoteDataSource → mapping → Repository → LocalDataSource → mapping → Repository → UseCase
• Archer abstracts away interface + implementation boilerplate for Repositories/DataSources via a DSL.
• Mappers must still be provided by the developer.
Components
a. Main Components:
1. Client/UseCase Layer (application code invoking the DSL)
2. Archer DSL Layer (ice, either, nullable, raise builders)
3. Repository Layer (orchestrates data flow between datasources)
4. DataSource Layer
• RemoteDataSource (getDataSource)
• LocalDataSource (StoreDataSource – e.g., InMemoryDataSource or SQLDelight-backed)
5. Mapper Layer (param↔domain and domain↔DBO mappers)
6. Persistence Module (SQLDelight database + DatabaseDriverFactory)
7. Concurrency/Locking (Mutex implementations per platform)
8. Failure Handling (HttpStatusHandler, Failure model)
b. Relationships & Data Flow:
• DSL invokes Repository.get/put with a key
• Repository directs call to RemoteDataSource → returns raw data
• Mapper transforms raw to Domain Model → Repository
• Repository calls LocalDataSource.put (with mapped data) → Mapper maps Domain to DBO → persists
• Repository calls LocalDataSource.get → maps DBO back to Domain → returns to client DSL
• DSL returns result wrapped in Ice/Either/Nullable
c. Architectural Patterns & Principles:
• Clean Architecture (UseCase-Repository-DataSource)
• Separation of concerns: mapping, persistence, concurrency, error handling are distinct modules
• Multiplatform abstraction: single API targeting JS/JVM/Android/iOS/Native
d. Key Technologies & Frameworks:
• Kotlin Multiplatform (commonMain + platformMain source sets)
• SQLDelight (for Database module)
• Kotlinx-coroutines or custom Mutex concurrency
• Docusaurus (documentation site)