# minswap/sdk architecture

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

- Interactive diagram: https://gitdiagram.com/minswap/sdk
- Repository: https://github.com/minswap/sdk

## Overview

##### Project type and purpose
- This is an off-chain SDK library (NPM package) for the Minswap Cardano DEX ecosystem.
- It provides adapters for price and pool data, transaction builders for various AMM versions (V1, V2, StableSwap, LBE V2), a syncer service to populate a local data store from on-chain sources, plus utility workers like LBE V2 and expired-order monitors.

##### File structure
Top-level modules:
- src/adapters: implements `BlockfrostAdapter`, `MinswapAdapter` (backed by the syncer), `MaestroAdapter`.
- src/syncer: a standalone service that reads from on-chain (via connector) and writes to Postgres & Redis.
- src/lbe-v2-worker & src/expired-order-monitor: background workers for limit-order book events.
- src/dex, src/dex-v2, src/stableswap, src/lbe-v2: core logic for pricing, calculations, order building.
- src/utils & src/types: shared utilities and type definitions.
- examples/ & docs/: usage samples and detailed design specs.
- docker-compose.yaml, Dockerfile.syncer: infrastructure for running the syncer, database, Redis.
- prisma schema & init.sql: schema for Postgres.

##### README for additional insights
- The README emphasizes three adapter entry points (Blockfrost, Minswap/syncer, Maestro).
- Key use-cases: fetching current pools, historical data, building and submitting swap orders.
- Guidance on running the syncer via Docker Compose to power the `MinswapAdapter`.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Services
    subgraph "External Services"
        BF["Blockfrost API"]:::external
        MA["Maestro API"]:::external
        CN["Cardano Network"]:::external
    end

    %% Syncer Infrastructure
    subgraph "Syncer Infrastructure"
        direction TB
        DC["Docker Compose"]:::infra
        DF["Dockerfile.syncer"]:::infra
        SC["Syncer Connector"]:::syncer
        SYNC["Syncer Controller"]:::syncer
        PG["Postgres"]:::db
        RD["Redis"]:::db
    end

    %% SDK Library
    subgraph "SDK Library"
        direction TB
        subgraph "Adapters"
            BFAd["BlockfrostAdapter"]:::adapter
            MSAd["MinswapAdapter"]:::adapter
            MAAd["MaestroAdapter"]:::adapter
        end
        RepoReader["Repository Reader"]:::adapter
        subgraph "Core Modules"
            DEX["Dex (AMM V1)"]:::core
            DEX2["DexV2"]:::core
            SS["StableSwap"]:::core
            LBE["LBE V2 Logic"]:::core
        end
        UTIL["Utils"]:::util
        TYPES["Types"]:::util
    end

    %% Background Workers
    subgraph "Background Workers"
        direction TB
        LBW["LBE V2 Worker"]:::worker
        EXPW["Expired Order Monitor"]:::worker
    end

    %% User Application
    UserApp["User Application / examples"]:::user

    %% Connections
    BF -->|queries| BFAd
    MA -->|queries| MAAd
    SC -->|sync data| SYNC
    SYNC -->|writes| PG
    SYNC -->|writes| RD
    DC --> SYNC
    DF --> SYNC

    BFAd -->|"fetch pools"| DEX
    MSAd -->|"fetch pools"| RepoReader
    RepoReader -->|"read pool data"| DEX

    MAAd -->|"fetch pools"| DEX

    DEX -->|build tx| CN
    DEX2 -->|build tx| CN
    SS -->|build tx| CN
    LBE -->|build tx| CN

    LBW -->|monitor events| PG
    LBW -->|monitor events| RD
    LBW -->|trigger logic| LBE

    EXPW -->|monitor orders| PG
    EXPW -->|trigger logic| SS

    UserApp -->|uses| BFAd
    UserApp -->|uses| MSAd
    UserApp -->|uses| MAAd
    UserApp -->|imports| UTIL
    UserApp -->|imports| TYPES

    %% Click Events
    click BFAd "https://github.com/minswap/sdk/blob/main/src/adapters/blockfrost.ts"
    click MSAd "https://github.com/minswap/sdk/blob/main/src/adapters/minswap.ts"
    click MAAd "https://github.com/minswap/sdk/blob/main/src/adapters/maestro.ts"
    click RepoReader "https://github.com/minswap/sdk/blob/main/src/adapters/index.ts"
    click SYNC "https://github.com/minswap/sdk/blob/main/src/syncer/main.ts"
    click SC "https://github.com/minswap/sdk/blob/main/src/syncer/connector.ts"
    click SYNC "https://github.com/minswap/sdk/blob/main/src/syncer/syncer.ts"
    click PG "https://github.com/minswap/sdk/blob/main/src/syncer/repository/postgres-repository.ts"
    click RD "https://github.com/minswap/sdk/blob/main/src/syncer/repository/redis-repository.ts"
    click DF "https://github.com/minswap/sdk/blob/main/Dockerfile.syncer"
    click DC "https://github.com/minswap/sdk/blob/main/docker-compose.yaml"
    click PG "https://github.com/minswap/sdk/blob/main/src/syncer/postgres/init.sql"
    click PG "https://github.com/minswap/sdk/blob/main/src/syncer/postgres/prisma/schema.prisma"
    click DEX "https://github.com/minswap/sdk/blob/main/src/dex.ts"
    click DEX2 "https://github.com/minswap/sdk/blob/main/src/dex-v2.ts"
    click SS "https://github.com/minswap/sdk/blob/main/src/stableswap.ts"
    click LBE "https://github.com/minswap/sdk/blob/main/src/lbe-v2/lbe-v2.ts"
    click LBE "https://github.com/minswap/sdk/blob/main/src/lbe-v2/type.ts"
    click LBE "https://github.com/minswap/sdk/blob/main/src/lbe-v2/validation.ts"
    click LBW "https://github.com/minswap/sdk/blob/main/src/lbe-v2-worker/worker.ts"
    click EXPW "https://github.com/minswap/sdk/blob/main/src/expired-order-monitor.ts"
    click UTIL "https://github.com/minswap/sdk/tree/main/src/utils/"
    click TYPES "https://github.com/minswap/sdk/tree/main/src/types/"
    click UserApp "https://github.com/minswap/sdk/tree/main/examples/"

    %% Styles
    classDef external fill:#cfe2f3,stroke:#0b5394,color:#0b5394;
    classDef infra fill:#e2f0d9,stroke:#38761d,color:#38761d;
    classDef syncer fill:#d9ead3,stroke:#274e13,color:#274e13;
    classDef db fill:#d9ead3,stroke:#274e13,color:#274e13;
    classDef adapter fill:#f9cb9c,stroke:#b45f06,color:#b45f06;
    classDef core fill:#f4cccc,stroke:#a61c00,color:#a61c00;
    classDef util fill:#fff2cc,stroke:#7f6000,color:#7f6000;
    classDef worker fill:#fce5cd,stroke:#b45f06,color:#b45f06;
    classDef user fill:#d9d2e9,stroke:#674ea7,color:#674ea7;
```
