# fleet-sdk/fleet architecture

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

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

## Overview

##### Project Type and Purpose
- This is a TypeScript monorepo SDK (“Fleet SDK”) for the Ergo blockchain.
- It provides a suite of packages for transaction building, serialization, cryptography, compilation of ErgoScript, mock-chain testing utilities, blockchain data providers, wallet/key management, plus plugins for specialized protocols (AgeUSD, Babel Fees).

##### File Structure
- Top-level: a pnpm workspace orchestrates multiple packages under `/packages` and `/plugins`.
- Core sub-packages under `/packages`:
– common (shared types & utilities)
– crypto (ECDSA, hashing, coders)
– serializer (binary serializers/parsers for Ergo data structures)
– core (transaction builder, selectors, plugin context)
– wallet (mnemonics, HD keys, provers)
– compiler (ErgoScript → bytecode)
– mock-chain (in-memory testing chain & UTXO management)
– blockchain-providers (GraphQL, other providers)
- `/plugins`: each plugin extends core functionality via the plugin API.
- Top-level config: tsconfig, CI, release workflows.

##### README
- Lists each package and its role.
- Emphasizes a “fluent, flexible” off-chain/on-chain coding model.
- Mentions plugin architecture for protocol-specific extensions.

##### Main Components & Relationships
a. Core Library Layer
- @fleet-sdk/common: foundational types + utils
- @fleet-sdk/crypto: low-level crypto primitives
- @fleet-sdk/serializer: binary encoding/decoding
b. Functional Layer
- @fleet-sdk/core: transaction building, plugin host
- @fleet-sdk/wallet: key/mnemonic management + prover
- @fleet-sdk/compiler: compile ErgoScript contracts
- @fleet-sdk/mock-chain: simulate blockchain for tests
- @fleet-sdk/blockchain-providers: connect to external GraphQL or REST endpoints
c. Plugin Layer
- ageusd-plugin, babel-fees-plugin: implement protocol-specific logic via the core plugin API
d. Test-Vectors Package
- _test-vectors: shared fixtures used by multiple packages
e. CI/CD & Release
- GitHub Actions workflows orchestrate builds, tests, coverage, releases

- Data Flow & Dependencies
– Core ← common, crypto, serializer
– Wallet ← common, crypto, core (for transaction construction)
– Compiler ← common (types), serializer (output formatting)
– Mock-chain ← common, serializer, crypto (to simulate tx signatures)
– Blockchain-providers ← common (types), networking utils
– Plugins ← core (pluginContext API), may use common, serializer

##### Architectural Patterns & Principles
- Monorepo modularization: each concern lives in its own package.
- Plugin architecture: core exposes extension points for third-party logic.
- Clear layering: low-level (crypto, serializer) → mid-level (common) → high-level (core, wallet, compiler).
- Test-driven: each package contains its own tests and shared test-vectors.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Foundation Layer
    subgraph "Foundation Layer"
        FCommon["@fleet-sdk/common"]:::foundation
        FSerializer["@fleet-sdk/serializer"]:::foundation
        FCrypto["@fleet-sdk/crypto"]:::foundation
    end

    %% Functional Layer
    subgraph "Functional Layer"
        FCore["@fleet-sdk/core"]:::functional
        FWallet["@fleet-sdk/wallet"]:::functional
        FCompiler["@fleet-sdk/compiler"]:::functional
        FMock["@fleet-sdk/mock-chain"]:::functional
        FProviders["@fleet-sdk/blockchain-providers"]:::functional
    end

    %% Plugin Layer
    subgraph "Plugin Layer"
        PAgeusd["@fleet-sdk/ageusd-plugin"]:::plugin
        PBabel["@fleet-sdk/babel-fees-plugin"]:::plugin
    end

    %% Test Vectors
    subgraph "Test Vectors"
        TV["_test-vectors"]:::test
    end

    %% External Systems
    subgraph "External Systems"
        ENode["Ergo Node GraphQL"]:::external
        DevApp["Developer Application"]:::external
    end

    %% Configuration
    subgraph "Configuration"
        PNPM["pnpm-workspace.yaml"]:::config
        TSConfig["tsconfig.json"]:::config
        CI["CI/CD Workflows"]:::config
    end

    %% Dependencies
    FCommon -->|imports| FSerializer
    FCommon -->|imports| FCrypto

    FCore -->|imports| FCommon
    FCore -->|imports| FCrypto
    FCore -->|imports| FSerializer

    FWallet -->|imports| FCommon
    FWallet -->|imports| FCrypto
    FWallet -->|imports| FCore

    FCompiler -->|imports| FCommon
    FCompiler -->|imports| FSerializer

    FMock -->|imports| FCommon
    FMock -->|imports| FSerializer
    FMock -->|imports| FCrypto

    FProviders -->|imports| FCommon
    FProviders -->|connects to| ENode

    PAgeusd -.->|extends| FCore
    PBabel -.->|extends| FCore

    DevApp -->|uses| FCore
    DevApp -->|uses| FWallet
    DevApp -->|uses| FCompiler
    DevApp -->|uses| FProviders
    DevApp -->|uses| PAgeusd
    DevApp -->|uses| PBabel

    TV -.->|test fixtures| FCommon
    TV -.->|test fixtures| FCrypto
    TV -.->|test fixtures| FSerializer
    TV -.->|test fixtures| FCore
    TV -.->|test fixtures| FWallet
    TV -.->|test fixtures| FCompiler
    TV -.->|test fixtures| FMock
    TV -.->|test fixtures| FProviders
    TV -.->|test fixtures| PAgeusd
    TV -.->|test fixtures| PBabel

    PNPM -->|workspace config| FCommon
    PNPM -->|workspace config| FCrypto
    PNPM -->|workspace config| FSerializer
    PNPM -->|workspace config| FCore
    PNPM -->|workspace config| FWallet
    PNPM -->|workspace config| FCompiler
    PNPM -->|workspace config| FMock
    PNPM -->|workspace config| FProviders
    PNPM -->|workspace config| PAgeusd
    PNPM -->|workspace config| PBabel

    TSConfig -->|tsconfig| FCommon
    TSConfig -->|tsconfig| FCrypto
    TSConfig -->|tsconfig| FSerializer
    TSConfig -->|tsconfig| FCore
    TSConfig -->|tsconfig| FWallet
    TSConfig -->|tsconfig| FCompiler
    TSConfig -->|tsconfig| FMock
    TSConfig -->|tsconfig| FProviders
    TSConfig -->|tsconfig| PAgeusd
    TSConfig -->|tsconfig| PBabel

    CI -->|build/test/release| FCommon
    CI -->|build/test/release| FCrypto
    CI -->|build/test/release| FSerializer
    CI -->|build/test/release| FCore
    CI -->|build/test/release| FWallet
    CI -->|build/test/release| FCompiler
    CI -->|build/test/release| FMock
    CI -->|build/test/release| FProviders
    CI -->|build/test/release| PAgeusd
    CI -->|build/test/release| PBabel

    %% Click Events
    click FCommon "https://github.com/fleet-sdk/fleet/tree/master/packages/common"
    click FCrypto "https://github.com/fleet-sdk/fleet/tree/master/packages/crypto"
    click FSerializer "https://github.com/fleet-sdk/fleet/tree/master/packages/serializer"
    click FCore "https://github.com/fleet-sdk/fleet/tree/master/packages/core"
    click FWallet "https://github.com/fleet-sdk/fleet/tree/master/packages/wallet"
    click FCompiler "https://github.com/fleet-sdk/fleet/tree/master/packages/compiler"
    click FMock "https://github.com/fleet-sdk/fleet/tree/master/packages/mock-chain"
    click FProviders "https://github.com/fleet-sdk/fleet/tree/master/packages/blockchain-providers"
    click PAgeusd "https://github.com/fleet-sdk/fleet/tree/master/plugins/ageusd"
    click PBabel "https://github.com/fleet-sdk/fleet/tree/master/plugins/babel-fees"
    click TV "https://github.com/fleet-sdk/fleet/tree/master/packages/_test-vectors"
    click CI "https://github.com/fleet-sdk/fleet/blob/master/.github/workflows/ci.yml"
    click CI "https://github.com/fleet-sdk/fleet/blob/master/.github/workflows/coverage.yml"
    click CI "https://github.com/fleet-sdk/fleet/blob/master/.github/workflows/release.yml"
    click PNPM "https://github.com/fleet-sdk/fleet/blob/master/pnpm-workspace.yaml"
    click TSConfig "https://github.com/fleet-sdk/fleet/blob/master/tsconfig.json"

    %% Styles
    classDef foundation fill:#cce5ff,stroke:#004085,color:#004085
    classDef functional fill:#d4edda,stroke:#155724,color:#155724
    classDef plugin fill:#fff3cd,stroke:#856404,color:#856404
    classDef test fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef external fill:#f8d7da,stroke:#721c24,color:#721c24
    classDef config fill:#f5f5f5,stroke:#333,stroke-dasharray: 5 5,color:#333
```
