# m2f-kt/archer architecture

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

- Interactive diagram: https://gitdiagram.com/m2f-kt/archer
- Repository: https://github.com/m2f-kt/archer

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% DSL / UseCase Layer
    subgraph "DSL / UseCase Layer"
        direction TB
        ArcherRaise["ArcherRaise (ice/either/nullable/raise)"]:::dsl
        Operation["Operation (DSL builder)"]:::dsl
        Validate["Validate (DSL builder)"]:::dsl
    end

    %% Core Abstractions
    subgraph "Core Abstractions"
        direction TB
        Repository["Repository"]:::core
        GetRepo["GetRepositoryStrategy"]:::core
        StoreDS["StoreDataSource"]:::core
        MainSyncRepo["MainSyncRepository"]:::core
        SingleDSRepo["SingleDataSourceRepository"]:::core
        StoreSyncRepo["StoreSyncRepository"]:::core
    end

    %% DataSource Layer
    subgraph "DataSource Layer"
        direction TB
        DataSource["DataSource (interface)"]:::core
        InMemDS["InMemoryDataSource (common)"]:::impl
        subgraph "Platform InMemory Implementations"
            direction TB
            InMemAndroid["InMemoryDataSource.android"]:::impl
            InMemJS["InMemoryDataSource.js"]:::impl
            InMemJVM["InMemoryDataSource.jvm"]:::impl
            InMemNative["InMemoryDataSource.native"]:::impl
        end
    end

    %% Mapper & Failure Handling
    subgraph "Mapper & Failure"
        direction TB
        Bijection["Bijection"]:::mapper
        DataSourceMapper["DataSourceMapper"]:::mapper
        KleisliArrow["KleisliArrow"]:::mapper
        FailureModel["Failure"]:::failure
        HttpStatus["HttpStatusHandler"]:::failure
    end

    %% Concurrency / Locking
    subgraph "Concurrency / Mutex"
        direction TB
        MutexCommon["Mutex (common)"]:::concurrency
        MutexAndroid["Mutex.android"]:::concurrency
        MutexJS["Mutex.js"]:::concurrency
        MutexJVM["Mutex.jvm"]:::concurrency
        MutexNative["Mutex.native"]:::concurrency
    end

    %% Persistence Module
    subgraph "Persistence Module (SQLDelight)"
        direction TB
        Expiration["ExpirationRegistry.sq"]:::persistence
        DBFactoryCommon["DatabaseDriverFactory"]:::persistence
        DBFactoryAndroid["DatabaseDriverFactory.android"]:::persistence
        DBFactoryIOS["DatabaseDriverFactory.ios"]:::persistence
        DBFactoryJS["DatabaseDriverFactory.js"]:::persistence
        DBFactoryJVM["DatabaseDriverFactory.jvm"]:::persistence
        ArcherInit["ArcherInitializer"]:::persistence
    end

    %% Data Flow Arrows
    ArcherRaise -->|1.invoke DSL| Repository
    Operation -->|1.invoke DSL| Repository
    Validate -->|1.invoke DSL| Repository

    Repository -->|2.fetch remote| DataSource
    DataSource -->|3.return raw| DataSourceMapper
    DataSourceMapper -->|4.domain model| Repository

    Repository -->|5.store local| StoreDS
    StoreDS -->|6.map→DBO & persist| Expiration
    Expiration -->|7.DB write| ArcherInit
    ArcherInit -->|8.db ready| DBFactoryCommon

    StoreDS -->|9.map DBO→Domain| DataSourceMapper
    DataSourceMapper -->|10.return| Repository

    Repository -->|11.return result| ArcherRaise

    %% Extension Points
    DataSourceMapper ---|dashed| Operation
    FailureModel ---|dashed| ArcherRaise
    HttpStatus ---|dashed| DataSource

    MutexCommon ---|dashed| DataSource
    MutexAndroid ---|dashed| DataSource
    MutexJS ---|dashed| DataSource
    MutexJVM ---|dashed| DataSource
    MutexNative ---|dashed| DataSource

    %% Click Events
    click ArcherRaise "https://github.com/m2f-kt/archer/blob/main/archer-core/src/commonMain/kotlin/com/m2f/archer/crud/ArcherRaise.kt"
    click Operation "https://github.com/m2f-kt/archer/blob/main/archer-core/src/commonMain/kotlin/com/m2f/archer/crud/operation/Operation.kt"
    click Validate "https://github.com/m2f-kt/archer/blob/main/archer-core/src/commonMain/kotlin/com/m2f/archer/crud/validate/Validate.kt"

    click Repository "https://github.com/m2f-kt/archer/blob/main/archer-core/src/commonMain/kotlin/com/m2f/archer/crud/Repository.kt"
    click GetRepo "https://github.com/m2f-kt/archer/blob/main/archer-core/src/commonMain/kotlin/com/m2f/archer/crud/GetRepositoryStrategy.kt"
    click StoreDS "https://github.com/m2f-kt/archer/blob/main/archer-core/src/commonMain/kotlin/com/m2f/archer/crud/StoreDataSource.kt"
    click MainSyncRepo "https://github.com/m2f-kt/archer/blob/main/archer-core/src/commonMain/kotlin/com/m2f/archer/repository/MainSyncRepository.kt"
    click SingleDSRepo "https://github.com/m2f-kt/archer/blob/main/archer-core/src/commonMain/kotlin/com/m2f/archer/repository/SingleDataSourceRepository.kt"
    click StoreSyncRepo "https://github.com/m2f-kt/archer/blob/main/archer-core/src/commonMain/kotlin/com/m2f/archer/repository/StoreSyncRepository.kt"

    click DataSource "https://github.com/m2f-kt/archer/blob/main/archer-core/src/commonMain/kotlin/com/m2f/archer/datasource/DataSource.kt"
    click InMemDS "https://github.com/m2f-kt/archer/blob/main/archer-core/src/commonMain/kotlin/com/m2f/archer/datasource/InMemoryDataSource.kt"
    click InMemAndroid "https://github.com/m2f-kt/archer/blob/main/archer-core/src/androidMain/kotlin/com/m2f/archer/datasource/InMemoryDataSource.android.kt"
    click InMemJS "https://github.com/m2f-kt/archer/blob/main/archer-core/src/jsMain/kotlin/com/m2f/archer/datasource/InMemoryDataSource.js.kt"
    click InMemJVM "https://github.com/m2f-kt/archer/blob/main/archer-core/src/jvmMain/kotlin/com/m2f/archer/datasource/InMemoryDataSource.jvm.kt"
    click InMemNative "https://github.com/m2f-kt/archer/blob/main/archer-core/src/nativeMain/kotlin/com/m2f/archer/datasource/InMemoryDataSource.native.kt"

    click Bijection "https://github.com/m2f-kt/archer/blob/main/archer-core/src/commonMain/kotlin/com/m2f/archer/mapper/Bijection.kt"
    click DataSourceMapper "https://github.com/m2f-kt/archer/blob/main/archer-core/src/commonMain/kotlin/com/m2f/archer/mapper/DataSourceMapper.kt"
    click KleisliArrow "https://github.com/m2f-kt/archer/blob/main/archer-core/src/commonMain/kotlin/com/m2f/archer/mapper/KleisliArrow.kt"
    click FailureModel "https://github.com/m2f-kt/archer/blob/main/archer-core/src/commonMain/kotlin/com/m2f/archer/failure/Failure.kt"
    click HttpStatus "https://github.com/m2f-kt/archer/blob/main/archer-core/src/commonMain/kotlin/com/m2f/archer/failure/network/HttpStatusHandler.kt"

    click MutexCommon "https://github.com/m2f-kt/archer/blob/main/archer-core/src/commonMain/kotlin/com/m2f/archer/datasource/concurrency/Mutex.kt"
    click MutexAndroid "https://github.com/m2f-kt/archer/blob/main/archer-core/src/androidMain/kotlin/com/m2f/archer/datasource/concurrency/Mutex.android.kt"
    click MutexJS "https://github.com/m2f-kt/archer/blob/main/archer-core/src/jsMain/kotlin/com/m2f/archer/datasource/concurrency/Mutex.js.kt"
    click MutexJVM "https://github.com/m2f-kt/archer/blob/main/archer-core/src/jvmMain/kotlin/com/m2f/archer/datasource/concurrency/Mutex.jvm.kt"
    click MutexNative "https://github.com/m2f-kt/archer/blob/main/archer-core/src/nativeMain/kotlin/com/m2f/archer/datasource/concurrency/Mutex.native.kt"

    click Expiration "https://github.com/m2f-kt/archer/blob/main/database/src/commonMain/sqldelight/com/m2f/archer/ExpirationRegistry.sq"
    click DBFactoryCommon "https://github.com/m2f-kt/archer/blob/main/database/src/commonMain/kotlin/com/m2f/archer/data/storage/DatabaseDriverFactory.kt"
    click DBFactoryAndroid "https://github.com/m2f-kt/archer/blob/main/database/src/androidMain/kotlin/com/m2f/archer/data/storage/DatabaseDriverFactory.android.kt"
    click DBFactoryIOS "https://github.com/m2f-kt/archer/blob/main/database/src/iosMain/kotlin/com/m2f/archer/data/storage/DatabaseDriverFactory.ios.kt"
    click DBFactoryJS "https://github.com/m2f-kt/archer/blob/main/database/src/jsMain/kotlin/com/m2f/archer/data/storage/DatabaseDriverFactory.js.kt"
    click DBFactoryJVM "https://github.com/m2f-kt/archer/blob/main/database/src/jvmMain/kotlin/com/m2f/archer/data/storage/DatabaseDriverFactory.jvm.kt"
    click ArcherInit "https://github.com/m2f-kt/archer/blob/main/database/src/androidMain/kotlin/com/m2f/archer/startup/ArcherInitializer.kt"

    %% Styles
    classDef dsl fill:#ccffcc,stroke:#000
    classDef core fill:#cce5ff,stroke:#000
    classDef impl fill:#ffd699,stroke:#000
    classDef mapper fill:#d9b3ff,stroke:#000
    classDef failure fill:#e6e6ff,stroke:#000
    classDef concurrency fill:#e6ffe6,stroke:#000
    classDef persistence fill:#ffe0b3,stroke:#000
```
